Documentation Center

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

The following parameters are linked with a list of value:
  • language
  • resolution
  • output format
  • owned by
  • read access
  • ...
How should these parameters be provided?
  • 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.
How are these parameters used?
  • Normally these parameters are only used to retrieve the object.
    • In the DocumentObj 2.5 web services the parameters "language" and "resolution" are used to retrieve the language object.
    • The parameter "output format" in the PublicationOutput 2.5 web services is used to retrieve the publication output.
  • 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 services are used to set the security on the folder object.

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

When you supply a value for those fields, you have 3 options:
  • 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 ishvaluetype to indicate the meaning of your value.

    There are 2 possible values for ishvaluetype:
    • "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>
Try to use the element name of the value as much as possible
  • 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
When you have no other option and you have to pass the label of the value, try to pass the label of the value case sensitive using a pick list. All methods will find the value case insensitive, but this is a fallback mechanism requiring a second (slower) query.