API App Data elements User defined metadata

User defined metadata

App API for adding user defined metadata to data elements.

Overview

Custom metadata on data elements allows key-value pairs of metadata to be added to a data element via the API. There are dedicated endpoints for setting and retrieving these values. The data is also available in other endpoints where metadata about data elements is retrieved.

Note: This is data that users with write permissions on the data element can freely edit via the API. If you want to add metadata that cannot be edited via the apps API, you should use metadata instead. That field is not exposed via the app’s API and can only be set through calls to storage, often via custom-developed C# code.

Retrieve

Endpoint for downloading the list of custom metadata that has already been added to a data element.

GET {org}/{appname}/instances/{instanceOwnerPartyId}/{instanceGuid}/data/{dataGuid}/user-defined-metadata
Accept: application/json

Response:

{
    "userDefinedMetadata": [
        {
            "key": "TheKey",
            "value": "TheValue"
        },
        {
            "key": "AnotherKey",
            "value": "AnotherValue"
        }
    ]
}

Edit

Endpoint for editing the metadata. Submitted data will overwrite the entire list and will remove everything that is not included in the latest update.

PUT {org}/{appname}/instances/{instanceOwnerPartyId}/{instanceGuid}/data/{dataGuid}/user-defined-metadata
Content-Type: application/json

{
    "userDefinedMetadata": [
        {
            "key": "TheKey",
            "value": "TheValue"
        },
        {
            "key": "AnotherKey",
            "value": "AnotherValue"
        }
    ]
}

The response will contain the list of all key-value pairs that have been added to the data element, in the same format as the submitted data.