The metadata structure of Assets Server

Metadata in Assets Server is organized in XML format with the following tree structure:

<fullAssetsInfo>

   <assetsInfo>
   ... //settings for default metadata fields
   </assetsInfo>  
   
  <assetsInfoExt>
	
		<fieldGroups>
		... //group definitions
		</fieldGroups>
		
		<assets>
		... //custom metadata fields
		</assets>
	    
		<fieldExtensions>
		... //extensions to default metadata fields
		</fieldExtensions>
   
   </assetsInfoExt>
   
</fullAssetsInfo>

Viewing the structure

Info: Performing the described step requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

The full XML structure can be viewed in the full_assetinfo.xml file.

The location of this file is:

<Assets Server location>/Elvis Hot Data/elvis-data/assetInfo

This file is generated during the start-up of Assets Server and combines a central file containing the settings for the default metadata fields with a configuration file containing settings that overrule the default metadata field settings and settings for custom metadata fields.

Settings of the central file are listed first, followed by those of the configuration file.

For more information, see Working with metadata in Assets Server.

Default settings

The settings for the default fields are defined at the start of the file between the <assetsInfo></assetsInfo> tags.

Extended settings

Settings that overrule the default metadata field settings and settings for custom metadata fields are defined between the <assetsInfoExt></assetsInfoExt> tags, where 'Ext' stands for 'Extension'.

<assetsInfoExt>
    <fieldGroups>
        <fieldGroup/>
    </fieldGroups>
    <assets>
        <assetTypeBaseExt>
            <fields>
                <field>
                    <fileFields>
                        <fileField></fileField>
                    </fileFields>				
                    <storage/>
                    <compass/>
                    <data>
                        <predefinedValues/>
                        <taxonomy/>
                    </data>
                    <userInterface/>
                    <description/>
                </field>
            </fields>
        </assetTypeBaseExt>
    </assets>
</assetsInfoExt>

Each element is explained below.

Note: Assets Server works on the principle that when a setting is not defined, the default setting is used. Even when a setting may not be present in the custom configuration, a default setting is still active for it.

Example: When no analyzer is defined in the compass setting, the default analyzer is used.

assetsInfoExt

The assetsInfoExt element defines the settings as an extension (which is what 'Ext' stands for) to the default settings.

fieldGroups

In Assets Server, a metadata field always needs to be part of a group. This is done by defining the group name in the 'field' element (see below).

When you want to use a new group name, it has to be defined here in the following format:

<fieldGroup name="name" />

<fieldGroups>
	<fieldGroup name="CompanyData" />
	<fieldGroup name="Collections" />
	<fieldGroup name="PDFs" />
</fieldGroups>

<fieldGroups>
	<fieldGroup name="CompanyData" />
</fieldGroups>

<assets>
	<assetTypeBaseExt name="CommonFields">
		<fields>
			<field name="cf_companyName" group="CompanyData">
			<storage storeInMetadata="true"/>
			<compass index="tokenized" analyzer="pureLowerCase" 
			store="yes" excludeFromAll="false" />
			<data editable="true" datatype="text" />
			</field>
		</fields>
	</assetTypeBaseExt>
</assets>

assets

This is the location where the custom metadata fields are defined.

Each field uses the following structure:

Copy the code

<assetTypeBaseExt>
	<fields>
		<field>
			<fileFields>
				<fileField></fileField>
			</fileFields>	
			<storage/>
			<compass/>
			<data/>
		</field>
	</fields>
</assetTypeBaseExt>

See the examples at the end of this article.

assetTypeBaseExt

Metadata fields can be made available to all assets within Assets Server or can be restricted to specific assets only. This is done by making the metadata field part of a particular level within a hierarchical structure.

This structure is referred to as the 'Asset Type Base' structure and is shown below.

For a full explanation about how this structure works, see Controlling metadata field availability in Assets Server.

In short, a metadata field is assigned to one of the levels in the structure. Assets that are part of that level will be able to use that metadata field as well as all metadata fields in the levels above it. Any metadata fields that are part of the levels below it will not be available to the asset.

This makes it possible to make a particular metadata field available to a specific file type.

Example: An audio file has access to all metadata fields that are assigned to 'AudioFields' as well as all metadata fields that are defined in all levels above it in the structure (from 'RootSystemFields' to 'ImageAndVideoFields') but any fields that are defined in 'VideoFields' and 'FlashFields' are not accessible for audio files.

When creating a custom metadata field, it also needs to be assigned to a level in the 'Asset Type Base' structure.

This is done by 'extending' the default Asset Type Base with a new configuration which will overrule the default configuration.

In the following example, 'CollectionFields' is extended (by using the element assetTypeBaseExt) and a custom metadata field is defined for it.

Copy the code

<assetTypeBaseExt name="CollectionFields">
   <fields>	
      <field name="cf_CustomCollection" group="Collections" >
	...
	</field>
   </fields>
</assetTypeBaseExt>

fields

Fields that all make use of the same assetTypeBaseExt definition can be defined between the <fields></fields> tags.

field

The actual definition of a custom metadata field is defined here.

The basic structure for a field is as follows:

Copy the code

<field name="field name" group="group name" requiredFor="*" embed="true|false" keepOnPromote="true|false">
    <storage/>
    <compass/>
    <data/>
    <userInterface/>
    <description/>
</field>

field name

The field name should be unique in the system, start with "cf_" and cannot contain any spaces or special characters.

Example: name="cf_companyName"

Tip: A more descriptive name can be provided for the user by substituting the default name with another name.

group name

Each metadata field in Assets Server needs to be part of a group. This could either be an existing group or a new group. The name of this group is added here.

The names of the default groups are as follows:

• Essentials. (Requires Assets Server 6.62 or higher) Add fields to this group to always show at the top of the Metadata panel.
• File. Typical file information, such as file size.
• Dimensions. Information about the file dimension such as size and resolution.
• General. General file information, such as a description or tags.
• Approval. Information related to file approval such as state and comment.
• Utility. General fields for marking assets to be hidden, ignored, prevented from cleaning up.
• Rights. Information about the usage rights of the content.
• Subject. Information describing the subject of the content.
• Publication. General publication information, such as ISBN number and word count
• Product. General product information such as the product name.
• Creator. Information about the creator of the content.
• Licensor. Information about the licensor of the content.
• Licensee. Information about the licensee of the content.
• Location. Information about the location of the content, either subject location and creation location.
• GPS. GPS information.
• OpenCalais. Information extracted by Open Calais.
• EXIF. EXIF information such as camera model or exposure time.
• ImageInfo. Image specific information such as bit depth and color mode.
• VideoInfo. Video specific information such as duration and frame rate.
• AudioInfo. Audio specific information such as artist and lyrics.
• DocumentInfo. Document specific information such as number of pages.
• PdfInfo. PDF specific information such as PDF version or creation software.
• FlashInfo. Adobe Flash specific information such as Flash version and frame count.
• Enterprise. Information related to WoodWing Studio Server such as 'Studio ID' and 'Modified in Studio by'.
• XMPID. XMP information.
• Etags. ETags contain unique numbers that are incremented each time an asset is modified. They are used internally in the system.
• Version. Information related to the version of the asset such as Version Comment and Version Number.
• System. Internal Assets Server information such as Elvis ID.
• Analytics. Information related to analytics such as View Count and Download Count.

keepOnCheckIn

Info: This feature requires Assets Server 6.107 or higher.

When Assets users check in a checked-out file or when they replace a file, the original file is replaced by either the edited version of the file or by a completely different file.

During this process, users can choose if the metadata values of the original file should be kept, or if the metadata values of the original file should be replaced by the metadata values of the checked-in file.

When the option to keep the original metadata is chosen, the metadata values of the original file are left intact and not replaced by the metadata values of the file that is checked in.

In certain scenarios though, it could be necessary to replace specific metadata values of the original file with values from the file that is checked in (such as the copyright information of the file that is checked in).

For these scenarios, the 'keepOnCheckIn' option for that metadata field can be set to 'false' in the custom-assetinfo.xml file.

This way, the metadata value in the original file for that field is replaced by the metadata value of the file that is checked in, even though the user has chosen to keep the original metadata.

For more information, see Controlling metadata values when checking in or replacing a file in Assets Server.

<?xml version="1.0" encoding="UTF-8"?>
<assetsInfoExt>
	<fieldExtensions>
        <fieldExt name="copyright" keepOnCheckIn="false"></fieldExt>
	</fieldExtensions>
</assetsInfoExt>

requiredFor

Makes input for a metadata field required. Three levels can be used:

1. Loose (default): Users are notified and encouraged to add a value but they are not forced to do so (meaning that they can continue without entering the 'required' data).

2. Strict: Users cannot import assets manually unless they add a value. When users remove the value for an existing asset, they are notified. When users leave the field blank, the original value is automatically put back when they exit the asset.

3. Enforced: Assets are not allowed to be imported without the required metadata. When users remove the value for an existing asset, they are notified. When users leave the field blank, the original value is automatically put back when they exit the asset.

Input can be made required for specific asset types or a range of types.

For more information, see Making metadata input required in Assets Server.

<fieldExt name="copyright" group="Rights" requiredFor="assetDomain:image" />

embed

When the value needs to be embedded in the asset, set this value to "true".

Note: The field to embed the value in needs to be defined in the fileFields setting, see below.

<field name="cf_companyName" group="General" embed="true">
	<fileFields>
		<fileField>XMP-plus:Custom1</fileField>
	</fileFields>
	<storage storeInMetadata="true" />
	<compass index="un_tokenized" store="yes" excludeFromAll="false" />
	<data editable="true" datatype="text" />
</field>

technical

Defines that the field contains technical data, typically not relevant for end-users to see.

Fields with technical="true" set can only be seen by users with super user status (including when accessing the data through an API).

<fieldExt name="..." group="..." embed="true|false" technical="true|false">

keepOnPromote

When set to true, the value of the field is maintained when the asset itself is promoted to be the current version.

Example: An asset has 3 older versions, each with a different value in the downloadCount field. When one of the older versions of the asset is promoted and keepOnPromote is set to true for the downloadCount field, the value of that field is not reset.

fileFields

Fields to embed the value in are defined here between the <fileField></fileField> tags.

Note: For this to work, the embed setting (see above), needs to be set to "true".

fileField

Use the fields of a particular industry standard that are available for that purpose. Add the setting by using the following syntax:

name of the standard used:name of the field

<field name="cf_companyName" group="General" embed="true">
	<fileFields>
		<fileField>XMP-plus:Custom1</fileField>
	</fileFields>
	<storage storeInMetadata="true" />
	<compass index="un_tokenized" store="yes" excludeFromAll="false" />
	<data editable="true" datatype="text" />
</field>

Storage

The storage setting defines if the value of the field should be added to the index (when an asset is imported or when an existing asset is manipulated).

Note: For custom metadata fields, this setting needs to be set to "true".

<storage storeInMetadata="true"/>

Compass

The compass element defines how the value of the metadata field should be stored in the search index. It consists of the following settings: 'index', 'store', 'analyzer', 'analyzerForAll, and 'excludeFromAll'.

<compass index="un_tokenized" store="yes" excludeFromAll="false" analyzerForAll="default" analyzer="pureLowerCase"/>

Tip: For ease of use, several 'templates' of these compass definitions are made available that can be directly applied to various field types. For more information, see Custom metadata templates in Assets Server.

Note: For information about how to configure custom metadata fields in such a way that they are searchable by the Log usage stats API, see Searchable custom stats metadata in Assets Server.)

index

The index setting controls how the value is stored in the index. Use one of the following settings:

• un_tokenized. The value of the field is stored in full, without spaces or without dividing it up in separate words.

Note: This setting is typically used for fields with exact or non-string values.

Example: creation dates, ratings, file types.

• tokenized. Each word is separately stored.

Note: This setting is typically used for descriptions and other fields with long text.

Example: 'lorem ipsum' is stored as 'lorem' and 'ipsum'.

• no. The value will not be stored in the search index and users will not be able to search on this field.

store

The store setting defines if the field should be displayed in the search results. Enter 'yes' or 'no'.

excludeFromAll

The excludeFromAll setting defines whether or not a user can search on the value as a general search term. Possible values are "true" or "false".

Set it to "true" when users should only be able to search on the value by specifically searching on the field.

Example: The default metadata field that stores the folder path (folderPath) is typically not a field of which its value should appear in a general search result. However, users should still be able to search on the field when they want to. Therefore, the 'store' setting is set to 'yes' while 'excludeFromAll' is set to 'true'.

analyzer

This setting defines which analyzer should be used for breaking up the metadata field value into tokens.

Note: Obviously, analyzers are only used by tokenized fields (fields with setting index="tokenized").

Choose from the following analyzers:

• default. The standard analyzer used by Lucene to produce search tokens.
• pureLowerCase. Produces one token of the entire value in lower case.
• alphaNumeric. Creates tokens by splitting the value by word space.

For more information about analyzers, please read the Lucene documentation.

analyzerForAll

Users can search on a value as a general search term or by searching in a specific field.

By default, the 'analyzer' setting (see above) is used when using both search methods.

When a different analyzer needs to be used for each search method, the analyzerForAll setting can be used when a general search is performed, while the 'analyzer' setting is then used when a search on a specific field is performed.

Choose from the following analyzers:

• default. The standard analyzer used by Lucene to produce search tokens.
• pureLowerCase. Produces one token of the entire value in lower case.
• alphaNumeric. Creates tokens by splitting the value by word space.

For more information about analyzers, please read the Lucene documentation.

Examples

• Search for exact value, case sensitive:

<compass index="un_tokenized" />

• Search for exact value, case insensitive:

<compass index="tokenized" analyzer="pureLowerCase" />

• Search for individual or combinations of words, case insensitive:

<compass index="tokenized"/>

Data

The data setting defines settings specific to the value of the metadata field: whether the field can be edited, if it can hold only one value or multiple value, the type of data that is stored and if predefined values should be available.

Copy the code

<data>
	<predefinedValues onlyFromList="false">
		<value flagIcon="bullet_ball_glass_blue.png">New</value>
		<value flagIcon="bullet_ball_glass_blue.png">Draft</value>
		<value flagIcon="bullet_ball_glass_yellow.png">Production</value>
		<value flagIcon="bullet_ball_glass_grey.png">Review</value>
		<value flagIcon="bullet_ball_glass_red.png">Correction</value>
		<value flagIcon="bullet_ball_glass_green.png">Final</value>
	</predefinedValues>
</data>

Copy the code

<data editable="true" multivalue="false" datatype="text">
    <taxonomy source="keyword-list.txt" onlyFromList="false" sort="false/>
</data>

editable

Defines if the value can be edited. Possible settings: "true" or "false".

multivalue

Defines if the field can hold multiple values. (The 'tags' field is a good example of a field that holds multiple values.)

Possible settings are "true" or "false". When not specified, "false" is used.

This setting can only be used for fields of the following data types:

• text
• number

Note: Fields that have the multivalue setting set to "true" cannot be sorted.

datatype

Defines the type of data that is stored in the field. Choose from the following options:

predefinedValues

Define a list of values by adding each value between the <value></value> tags.

The flagIcon setting can be used for displaying a flag in the user interface for this field. See Highlighting metadata in Assets Server by using icons.

taxonomy

A taxonomy is a list of restricted, predefined, related terms that follow a controlled hierarchy. They are also known as 'controlled vocabularies'.

Taxonomy lists greatly streamline the correct and consistent entry of metadata values among users. For more information, see .

Note: To be able to sort on a field, it has to be either un_tokenized or tokenized with a pureLowerCase analyzer and it cannot be multivalue.

User interface

The user interface settings define how the field is displayed in the user interface of the clients.

Copy the code

<userInterface
    filterUI="forDataType|checkBoxes|tagCloud"
    filterValuesSource="usedTerms"
    flagPosition="unique order number" flagIconWhenNotEmpty="icon name" />

filterUI

The filterUI setting defines which control is used for the field. Choose from the following settings:

• forDataType. Uses the standard control for the field data type. This is the default if left empty.

Example: A text box is shown for a field of data type 'text; a date picker is shown for a field of type 'datetime', and so on.

• checkBoxes. Shows a check box for each value. It works as an OR filter on the current search results.

• tagCloud. Use in combination with filterValuesSource="usedTerms" to create a tag cloud filter.

<field name="tags" group="General" embed="true">
	<storage storeInMetadata="true"/>
	<compass index="tokenized" analyzer="pureLowerCase" store="yes" 
	excludeFromAll="false" analyzerForAll="default"/>
	<data editable="true" datatype="text" multivalue="true"/>
	<userInterface filterUI="tagCloud" filterValuesSource="usedTerms"/>
	<description>
	...
	</description>
</field>

Note: The checkBoxes and tagCloud settings can only be used for fields that are un_tokenized or tokenized with a pureLowerCase analyzer.

Description

Users can choose which metadata fields they want to work with in the Metadata panel by enabling or disabling fields from a list of all available fields.

To help users choose which fields to select, a description can be added about the purpose and use of the field.

Figure: Viewing a description of a metadata field.

Add this description to the description element. Markdown can be used for formatting the text.