The metadata structure of Elvis 5

Metadata in Elvis 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

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

This file is generated during the start-up of Elvis 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 Elvis 5 .

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: Elvis 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 Elvis, 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:

<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 Elvis 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 Elvis 5.

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.

<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:

<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 Elvis 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.

Note: When adding a field to a new group, the name of this group needs to be defined in the fieldGroups section. See above.

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 Elvis 5.

<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>

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 templates of predefined metadata settings for Elvis 5.

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.

<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>

<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:

• text
• number
• decimal
• datetime

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 Elvis 5 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.

<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: The description of the Tags field.

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