Creating a custom metadata field in Elvis 5
Elvis Server is shipped with over 400 different metadata fields. When needed, each of these fields can be modified to better match your needs and requirements (for example by renaming an unused field that holds all or most of the properties that you are after). However, should any of these fields not allow you to store data in the way you want to, you can also create a custom metadata field from scratch.
Consider using a default metadata field
Although it may sound tempting to create a dedicated field to store your data in, be aware that creating a custom metadata field comes with a few restrictions:
- Metadata follows a particular industry standard (see Working with embedded metadata in Elvis 5), meaning that data is stored in specific fields that are defined in that standard.
Example: The Dublin Core industry standard stores copyright information in the 'Rights' field while the IPTC standard uses the 'Copyright Notice' field to store the same information.
Each application that supports that standard (such as the Elvis Desktop client or Photoshop) is able to correctly interpret the values within those fields and properly display them within the user interface.
When creating a custom metadata field however, embedding the value can only be done in one of a limited number of fields made available in a particular industry standard. Also, finding these values in the user interface of applications such as Photoshop could be less user friendly.
Example: The XMP standard contains 10 fields in which custom values can be stored. In Photoshop, finding the field may need to be done by looking at the raw metadata.
Note: All default metadata fields include support for one or more industry standards. This makes it preferable to use a default metadata field as a starting point.
- Creating a new custom metadata field involves creating the full XML structure for that field including some or all of the possible settings. Renaming an existing default metadata field and using its existing structure and settings is much quicker and leaves less room for errors.
- The value of a custom metadata field is always embedded in the index each time that asset is manipulated. This can slow down the processing time of the asset, especially when many of such assets need to be processed. For default metadata fields you can configure whether or not the value should be embedded.
It is highly recommended therefore to use a default metadata field as a starting point instead of creating a custom metadata field from scratch. For more information, see Changing the default metadata field options in Elvis 5 Server.
Before you start
Should you still want to go ahead with creating a custom metadata field, make sure that you start by creating a plan.
Be aware that:
- Once custom fields are active, they are difficult to modify without causing any data loss
- Renaming or removing a field completely removes all data already stored in the field
Decide upon the following:
- System name: The system name of the field should be unique, cannot contain any spaces or special characters and should start with "cf_"
- Display name: For better user experience, come up with a descriptive name for displaying the field in the user interface of the clients. This name may contain spaces and special characters.
Example: Company Name
- Availability. Should the field be available to all assets or only to assets of a particular type?
- Data type. Which type of data should the field hold? Choose from the following types:
- date / time
Note: Once this is defined it cannot be changed (else it will corrupt the index).
- Number of values. Should the field hold a single value or multiple values?
- Sorting. When the field holds multiple values, should these values be automatically sorted?
Note: When using a custom list, automatic sorting may not be desirable.
- Predefined values. Should the field offer one or more predefined values (either custom values or values from a taxonomy)? Should users be able to add their own value?
- Searching. Should the field be included in the general search results or should it only be possible to find the value by specifically searching on the field name?
Note: For some fields (such as the Elvis ID or folder path) it is not necessary or even logical to make appear in the general search results.
- Grouping. Each metadata field should belong to a group so that it can be correctly displayed in the clients. Should this group be an existing group or should a new group be created? When a new group is created, how should this be named? Note that the group name cannot contain any spaces or special characters.
Recommended reading: Working with metadata in Elvis 5 .
Info: Basic knowledge of XML is required.
Custom metadata fields are defined in the following XML structure:
<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>
It is essential to have a full understanding of this structure and its elements. Please make yourself familiar with the explanation in The metadata structure of Elvis 5 before defining custom metadata fields.
Adding a custom metadata field
The default settings of a metadata field are modified by 'extending' them in the custom-assetinfo.xml file as part of the
Note: For information about modifying this file, see Changing the Elvis 5 Server configuration for a running cluster.
Step 1. Access the Config properties page of a running Elvis Server instance.
Step 2. Open the custom-assetinfo.xml file.
Tip: Copy and paste the content of this file into an XML editor so that you have the benefit of line numbers and syntax highlighting. When done editing, copy and paste the changes back into the Elvis page.
Step 3. (Optional, only when introducing a new group) In the fieldGroups section, add a new field group.
Step 4. In the
<assets> section, define your custom metadata field by using the following structure:
<assetTypeBaseExt> <fields> <field> <fileFields> <fileField></fileField> </fileFields> <storage/> <compass/> <data/> </field> </fields> </assetTypeBaseExt>
See The metadata structure of Elvis 5 for details about how to define each element.
Step 5. Save the file.
Proceed as follows, depending on the version of Elvis Server:
Steps for Elvis 5.26 or higher:
Step 6. Restart the Server.
Note: For most changes — such as adding a new field or changing the compass settings for existing fields — the index will be automatically updated by Elvis Server; manually updating the index is not necessary.
However, an index update is required when changes are made to the following settings (see next step):
Step 7. (Optional, only when changes have been made to the excludeFromAll or analyzerForAll setting for an existing field) Run the Asset Processing Tool with none of the options checked. This will correct all field settings by re-indexing all assets.
Step 8. (Optional) Provide a more descriptive and user friendly name for the field. See Renaming a metadata field in Elvis 5.
Steps for Elvis 5.25 or lower:
Step 6. Restart the Server.
Note: This allows the field to be shown in the client, but with incorrect settings.
Step 7. Update the index for Elvis Server.
Step 8. (Optional) Provide a more descriptive and user friendly name for the field. See Renaming a metadata field in Elvis 5 .
The following example shows how to add a simple custom metadata field which can be searched and sorted. The field is editable and contains text. The value is not embedded in the asset.
<assets> <assetTypeBaseExt name="CommonFields"> <fields> <field name="cf_CompanyTarget" group="General"> <storage storeInMetadata="true" /> <compass index="un_tokenized" store="yes" excludeFromAll="false" /> <data editable="true" datatype="text" /> </field> </fields> </assetTypeBaseExt> </assets>
The following example shows a similar field with predefined values and the option for the users to manually add a value.
<assets> <assetTypeBaseExt name="CommonFields"> <fields> <field name="cf_CompanyStatus" group="General"> <storage storeInMetadata="true" /> <compass index="un_tokenized" store="yes" excludeFromAll="false" /> <data editable="true" datatype="text"> <predefinedValues onlyFromList="false"> <value>Idle</value> <value>New</value> </predefinedValues> </data> </field> </fields> </assetTypeBaseExt> </assets>
- 13 June 2017: Updated section 'Adding a custom metadata field' with information about updating the index for Elvis 5.26 and higher.