Setting metadata in REST

Metadata in Claromentis is quite a complex structure. Its values can be inherited from a parent object, they can be repeatable and can contain different data types. Because of this, it's very important to correctly format JSON requests when setting metadata for new objects or when updating existing objects.

Within a JSON request, a metadata field can be specified in the form of:

Setting single metadata value
- For simple types of metadata, just give the new value as a string/number. Simple types are:
  - String/text, from a single-line to a large textarea
  - Integer
  - Checkbox
  - Single value select (options) - radiobutton, dropdown list
  - Indicator (text with image)
- More complex values are passed as objects (arrays). These types are:
  - Multiple value select - checkboxes, multiple select list
  - Date, Date with time
  - Hyperlink
  - Address
  - User
  - Reference to document
  - File upload metadata is not supported
Setting repeatable metadata values
- If metadata field is repeatable its value must always be given as an array
- Each element in the given array has the same format as for setting single non-repatable metadata
Inheriting metadata from parent
- To delete the value belonging to an object and inherit it from parent instead specify value as associative array that has a key _inherit with value true or 1

Metadata types

Simple types

Simple types are ones that have a value that can only be represented as a simple text string. In REST request such values are set as simple key/value pair. For example:

    "metadata": {
        "usr_phone": "123 456 789",
        "description": "This is a document about something"
      }

The metadata types that can be set this way are listed above. All are pretty obvious except for the "indicator" and "checkbox" types. The "Indicator" metadata type is like a traffic light and has values like "Red,/images/default/red.gif". For REST requests the value to set should be just "Red" - the text before comma. For a "checkbox", the value should be passed as boolean or integer 0/1.

Multiple select

Multiple select values are stored as a single string with comma-separated values. When passing a metadata value of this type it should be either array or a single string.

Example:

    "metadata": {
        "mult_select": [
            "Red",
            "Green"
          ],
        "mult_select_2": "Red,Green",
        "checkboxes": [
            "One",
            "Two"
          ]
        "checkboxes_2": "One,Two"
      }

Date and Datetime

The passed value should be an associative array (object) with the following keys:

date - A 14-digit (20171130234500) or 8-digit value (20171130) OR
date_str_set - string representation of date in the format specified as "long_date" in the main Claromentis config file
time_str_set - string representation of time. Supported formats are quite flexible: 20:45, 2045, 8:45pm, 08 45 pm. Not needed for Date metadata type
timezone - string, timezone name, such as "Europe/London". If not given, the time is assumed to be in current user's timezone

It's also acceptable to set just the value instead of array if date is specified as 14-digit or 8-digit number. So similar to simple types described above.

Example:

    "metadata": {
        "datetime_field": {
            "date_str_set": "2011-09-30",
            "time_str_set": "17:21",
            "timezone": "Asia/Novosibirsk"
          },
        "datetime_field_2": {
            "date": "20110930112134"
          },
        "datetime_field_3": "20110930112134",

        "dateonly_field": {
            "date_str_set": "2011-09-30"
          },
        "dateonly_field_2": "20110930"
      }

Hyperlink

A hyperlink consists of URL and a link title. These two parts can be passed either as an array (object) with keys:

url
title

Or as a single string where the URL and title are separated with linebreak symbol (hexadecimal code 0xA).

Example:

    "metadata": {
        "hyperlink": {
            "url": "http://www.claromentis.com/",
            "title": "Claromentis website"
          },
        "hyperlink_2": "http://www.claromentis.com/\nClaromentis website"
      }

Note: \n in example above is a symbol with hexadecimal code 0xA, not the literal "\n". See this ascii table for more information.

Address

An address should be passed as associative array (object) with the following keys:

entry	type	description
line1	string	Address line 1
line2	string	Address line 2
city	string	Town/city
state	string	County/State/Province
code	string	Postal or zip code
country	string	Country

Example:

    "metadata": {
        "home_address": {
            "line1": "Flat 17",
            "line2": "35 Chapel Lane",
            "city": "Skipton",
            "state": "North Yorkshire",
            "code": "BD23 5BS",
            "country": "United Kingdom"
          }
      }

User

A user is identified by an ID, so the passed value can just be a number. Alternatively it can be an array with key "name", which contains a user name in default format (according to the $cfg_name_format in the Claromentis config file). If user with a given name is not found or the wrong user id passed, the metadata is set to an empty value.

Example:

    "metadata": {
        "manager": "12",
        "manager_2": {
            "id": 12
          },
        "director": {
            "name": "John Smith"
          }
      }

Reference to document

References to documents are a document ID (doc_id). The passed value can be either a simple number or an associative array (object) with the keys "doc_id" and "parent_id". If an incorrect doc_id is given, the metadata is set to an empty value.

Example:

    "metadata": {
        "related_document": 4512,
        "related_document_2": {
            "doc_id": 4512,
            "parent_id": 140
          }
      }

Repeatable metadata

If a metadata type is marked as repeatable, the passed value must be an array or an associative array. Each of the array elements must contain a value in the format as described above for setting single metadata value.

"metadata": {
    "repeatable_field": [
        {.. value 1 ..},
        {.. value 2 ..},
        {.. value 3 ..}
      ]
  }

If the given value is a simple array (as in the example above), the entire metadata field is replaced by the new elements. But it's also possible to update an existing value instead of writing a new one. This is generally more efficient and faster, especially if this metadata field is inherited by multiple objects (documents and folders) below the current one:

"metadata": {
    "repeatable_field": {
        "3451": {.. update value 1 ..},
        "3452": {.. update value 2 ..},
        "-1": {.. new value 3 ..}
      }
  }

Keys on the left side are elements IDs of individual metadata values. Elements with existing IDs matching those defined will be updated. Elements with new IDs will be added. Note that metadata elements that are not listed will be deleted from the metadata field, so when updating repeatable metadata fields all values that need to exist must be passed, even if some of them are unchanged.

Inheriting metadata

If a passed metadata value is an array and it has the key _inherit with a value true or 1, then the value of the metadata field on this particular object is deleted and the value of the parent object is inherited instead. If the metadata field is not inheritable, the value is just deleted.

This works for both single and repeatable metadata fields. But not for individual values inside a repeatable metadata field. With repeatable fields, either the entire field is inherited, or it isn't.

If the inherit flag is set, everything else in this metadata field value is ignored

"metadata": {
    "description": {
        "_inherit": true
      },
    "repeatable_field": {
        "_inherit": true
      },
    "repeatable_field_2": {
        // value is inherited from parent and given elements are ignored
        "_inherit": 1,
        "3451": {.. update value 1 ..},
        "3452": {.. update value 2 ..},
        "-1": {.. new value 3 ..}
      },
    "repeatable_field_3": {
        // THIS IS WRONG! Only entire metadata field can be inherited, not individual values
        "3451": {
            "_inherit": 1,   // WRONG!
        },
        "3452": {.. update value 2 ..},
        "-1": {.. new value 3 ..}
      }
  }