Understanding ishvaluetype
Use ishvaluetype to specify what type of value you want to retrieve from a metadata field: its unique numerical identifier, its unique string identifier, its actual value or its label. Not all metadata fields have all these types of values, but all metadata fields have at least a value.
The
ishvaluetype attribute can have the following values:
ishvaluetype attribute value | Description |
|---|---|
value | The value of the metadata field. If you omit the ishvaluetype attribute, the setting defaults to the value value. |
id | The unique numerical identifier of the metadata field. If the metadata field has no unique numerical identifier, a warning is raised, and the item's value is returned, as if ishvaluetype had been set to value. |
element | The unique string identifier of the metadata field. If the metadata field has no unique string identifier, a warning is raised, and the item's value is returned, as if ishvaluetype had been set to value. |
label | The non-unique label or title of the metadata field. For users, this returns the display name of the user. For objects with a title field (FTITLE), this returns the value of FTITLE (that is, the title of the object). For all other items, a warning is raised, and the item's value is returned, as if ishvaluetype had been set to value. This value is only supported when retrieving metadata; if you use this value when filtering or setting metadata, an exception is thrown. |
We can distinguish the following types of metadata fields:
- Fields that are linked to an external source via the metadata binding section of the XML Extension Settings. This type of field has a unique numerical identifier, a unique string identifier and a value.
- Fields that contain a value or a list of values (like, say,
FSTATUSorDOC-LANGUAGE), or that are a reference to another object (like, say,FAUTHOR). This type of field has a unique numerical identifier, a unique string identifier, a unique value and a non-unique label or title. - All other metadata fields. This type of field only has a value, so the only
ishvaluetypevalue you can use for these fields isvalue.
Using ishvaluetype inside requested metadata
If the field you are examining is linked to an external source via the metadata binding section of the XML Extension Settings, you can use
ishvaluetype to indicate if you want to get the ID or element name of the external system, which is saved inside the Content Manager database, or the resolved label from the external system. Examples:
-
Retrieve the values of the field by omitting
ishvaluetype - Request:
<ishfield name="FCOUNTRIES" level="logical"/> -
Retrieve the values of the field by explicitly setting
ishvaluetypetovalue - Request:
<ishfield name="FCOUNTRIES" level="logical" ishvaluetype="value"/> -
Retrieve the unique string identifiers of the field by setting
ishvaluetypetoelement - Request:
<ishfield name="FCOUNTRIES" level="logical" ishvaluetype="element"/>
If the field contains a value or a list of values (a field like, say,
FSTATUS or DOC-LANGUAGE), or if the field is a reference to another object (a field like FAUTHOR), you can use ishvaluetype to get the unique numerical identifier (value id), the unique string identifier (value element), the label or title of the object (value label), or its value (value value). Examples:
-
Retrieve the values of the fields by explicitly setting
ishvaluetypetovalue - Request:
<ishfield name="FSTATUS" level="lng" ishvaluetype="value"/> <ishfield name="FAUTHOR" level="lng" ishvaluetype="value"/> -
Retrieve the unique string identifiers of the fields by setting
ishvaluetypetoelement - Request:
<ishfield name="FSTATUS" level="lng" ishvaluetype="element"/> <ishfield name="FAUTHOR" level="lng" ishvaluetype="element"/> -
Retrieve the unique numerical identifiers of the fields by setting
ishvaluetypetoid - Request:
<ishfield name="FSTATUS" level="lng" ishvaluetype="id"/> <ishfield name="FAUTHOR" level="lng" ishvaluetype="id"/> -
Retrieve the non-unique label or title of the field by setting
ishvaluetypetolabel - Request:
<ishfield name="FSTATUS" level="lng" ishvaluetype="label"/> <ishfield name="FAUTHOR" level="lng" ishvaluetype="label"/>
All other metadata fields have only a value. They have no unique identifiers or labels, so setting
ishvaluetype to any other value than value results in a warning, and the return value you get back is the value of the metadata field, as if you had set ishvaluetype to value. Examples:
-
Retrieve the values of the fields by omitting
ishvaluetype - Request:
<ishfield name="FTITLE" level="logical"/> <ishfield name="MODIFIED-ON" level="lng"/> -
Retrieve the values of the fields by explicitly setting
ishvaluetypetovalue - Request:
<ishfield name="FTITLE" level="logical" ishvaluetype="value"/> <ishfield name="MODIFIED-ON" level="lng" ishvaluetype="value"/> -
Attempt to retrieve the unique string identifier of a field by setting
ishvaluetypetoelement - Request:
<ishfield name="MODIFIED-ON" level="lng" ishvaluetype="element"/>
Using ishvaluetype inside metadata for creating or updating an object
If the field is linked to an external source via the metadata binding section of the XML Extension Settings, you must set
ishvaluetype to id or element, to uniquely identify the value that needs to be saved in the Content Manager database. Examples:
- Provide a value for the unique string identifier of the field
-
<ishfield name="FCOUNTRIES" level="logical" ishvaluetype="element">BE, FR, GB</ishfield> - Attempt to provide a value for the value of the field
-
<ishfield name="FCOUNTRIES" level="logical" ishvaluetype="value">Belgium, France, United Kingdom</ishfield>
If the field contains a value or a list of values (a field like, say,
FSTATUS or DOC-LANGUAGE), or if the field is a reference to another object (a field like FAUTHOR), you must set ishvaluetype to id, element or value, to uniquely identify the value that needs to be saved in the Content Manager database (any of these three is unique). You cannot set ishvaluetype to label, because that value cannot be used while setting metadata. Examples:
- Update fields using unique values
-
<ishfield name="FSTATUS" level="lng" ishvaluetype="value">Draft</ishfield> <ishfield name="FAUTHOR" level="lng" ishvaluetype="value">MacGyver</ishfield> - Update fields using unique string identifiers
-
<ishfield name="FSTATUS" level="lng" ishvaluetype="element">VSTATUSDRAFT</ishfield> <ishfield name="FAUTHOR" level="lng" ishvaluetype="element">VUSERMACGYVER</ishfield> - Update fields using unique numerical identifiers
-
<ishfield name="FSTATUS" level="lng" ishvaluetype="id">315</ishfield> <ishfield name="FAUTHOR" level="lng" ishvaluetype="id">1200</ishfield>
All other metadata fields have only a value. They have no unique identifiers or labels, so setting
ishvaluetype to any other value than value results in a warning and will continue as if you had set ishvaluetype to value. Example:
<ishfield name="FTITLE" level="logical" ishvaluetype="element">FOO</ishfield>
The above request makes no sense, because the
FTITLE field only has a value, no identifiers. As a result, a warning is logged:
Field 'FTITLE' only supports ishvaluetype 'value'. The ishvaluetype 'element' will be ignored.
Additionally, the value of FTITLE would be set to FOO in this example.
Using ishvaluetype inside a metadata filter
If the field is linked to an external source via the metadata binding section of the XML Extension Settings, you must set
ishvaluetype to id or element, to uniquely identify the value that needs to be saved in the Content Manager database. In the following example, the metadata filter retrieves all logical objects whose FCOUNTRIES metadata field has one of the unique string identifiers BE, FR or GB:
<ishfield name="FCOUNTRIES" level="logical" ishvaluetype="element" ishoperator="in">BE, FR, GB</ishfield>
Setting
ishvaluetype to value doesn't work, and results in the following message in the log:
Value type "value" is not allowed on field "FCOUNTRIES". Field has configured metadata binding and it's value type can only be 'id' or 'element'
Setting ishvaluetype to label doesn't work, because this value is not allowed in metadata filters, and results in an exception being thrown.
If the field contains a value or a list of values (a field like, say,
FSTATUS or DOC-LANGUAGE), or if the field is a reference to another object (a field like FAUTHOR), you must set ishvaluetype to id, element or value, to uniquely identify the value that needs to be saved in the Content Manager database (any of these three is unique). Do note that if you set ishvaluetype to id, you cannot use the like operator. You cannot set ishvaluetype to label, because that value is not allowed when filtering metadata. Examples:
-
Retrieve objects whose status is "Draft" using the
FSTATUSfield's unique string identifier -
<ishfield name="FSTATUS" level="lng" ishvaluetype="element">VSTATUSDRAFT</ishfield> -
Retrieve objects whose status is "Draft" using the
FSTATUSfield's unique value -
<ishfield name="FSTATUS" level="lng" ishvaluetype="value" ishoperator="equal">Draft</ishfield>
All other metadata fields have only a value, so the only meaningful value for
ishvaluetype is value. If you try to use a filter that sets ishvaluetype to another value for these kinds of metadata fields, the following warnings appears in the log:
Field 'MODIFIED-ON' only supports ishvaluetype 'value'. The ishvaluetype 'element' will be ignored.