Understanding parameter and value references
This topic describes the usage of referenced values in parameters and xml metadata
Using value references as a parameters in API methods
- language
- resolution
- output format
- owned by
- read access
- ...
- Although the value can be provided as the label (e.g."en"), we advise you to use the element name (e.g. "VLANGUAGEEN") for performance and stability reasons.
-
Normally these parameters are only used to retrieve the object.
- In the
DocumentObj 2.5 web servicesthe parameters "language" and "resolution" are used to retrieve the language object. - The parameter "output format" in the
PublicationOutput 2.5 web servicesis used to retrieve the publication output.
- In the
-
Only the security parameters are used to update a value
- For instance, the parameters "ownedBy" and "readAccess" which can be supplied to the
Folder 2.5 web servicesare used to set the security on the folder object.
- For instance, the parameters "ownedBy" and "readAccess" which can be supplied to the
Using value references in the xml metadata
A lot of metadata fields are linked with a list of value (e.g. DOC-LANGUAGE, FRESOLUTION, FSTATUS, FREQUESTEDLANGUAGES, FSOURCELANGUAGE,...) or are referencing another object like an user (e.g. FAUTHOR), an output format (e.g. FISHOUTPUTFORMATREF) or an usergroup (e.g. FUSERGROUP).
- Don't do anything special and pass the value as you would do for all other fields. In this case, you must use the label of the value(s).
<ishfield name='FAUTHOR' level='lng'>Admin</ishfield> <ishfield name='FSTATUS' level='lng' ishoperator='in'>To be reviewed, In review</ishfield> Use the attribute
ishvaluetypeto indicate the meaning of your value.There are 2 possible values forishvaluetype:"value" which indicates that you use the label of the value(s).
<ishfield name='FAUTHOR' level='lng' ishvaluetype='value'>Admin</ishfield> <ishfield name='FSTATUS' level='lng' ishvaluetype='value' ishoperator='in'>To be reviewed, In review</ishfield>"element" which indicates that you use the element name of the value(s).
<ishfield name='FAUTHOR' level='lng' ishvaluetype='element'>VUSERADMIN</ishfield> <ishfield name='FSTATUS' level='lng' ishvaluetype='element' ishoperator='in'>VSTATUSTOBEREVIEWED, VSTATUSINREVIEW</ishfield>
- For stability reasons you should always use the element name of the value, when you are using constants or when you are caching values inside a script. Whenever somebody renames the value, the label of the value is changed while the element name remains the same.
- Not only for stability reasons, but also for performance reasons you should try to use the element name of the value