Metadata API

Item metadata can be both fetched and updated via Portal”s metadata API.

Batch metadata update API

Portal provides an API with which metadata can be updated for several items at once. The actual metadata update will be performed in the background after the call has returned.

Query parameters

• item_ids - A list of item ids to update

• collection_id - A collection id. All the items in the collection will be updated

• search_id - A search id. All the items matching the search will be updated.

• ignore_list - A list of item ids to exclude from the update if collection_id or search_id is given.

• batch_update_mode - replace or append. If mode is replace then all values of provided fields will be replaced. If append then string and textarea fields will be string-appended and multiple-choice fields will have the value appended to the existing set of values. All other fields types will be replaced. The default value is replace.

Body

The body of the request is a JSON structure of the metadata update. An example of a document is:

{
    "metadata": {
        "group_name": "Demo",
        "fields": [
            {
                "name": "portal_mf899660",
                "value": "1"
            },
            {
                "name": "portal_mf876225",
                "value": ["many1", "many2"]
            }
        ]
    }
}

This will set the value of the field portal_mf899660 to 1 and the field portal_mf876225 will have the two values many1 and many2. The item”s metadata group will be set to Demo if no group is set.

Items which are associated with a different metadata group than the one given will be ignored.

Subgroups

Metadata subgroups can be modified with the batch metadata upgrade. The following is an example of a document updating a subgroup Broadcast Date:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "fields": [
                    {
                        "name": "portal_mf11039",
                        "value": "Channel 1"
                    },
                    {
                        "name": "portal_mf144943",
                        "value": "2018-11-15T15:33:12.123456+10:00"
                    }
                ]
            }
        ]
    }
}

The exact behavior depends on the number of instances of the subgroup on a given item. If the item does not already have any instances of the Broadcast Date subgroup then a new instance will be created with the given values. If the item has one instance then the values of that instance are updated (and the values of other fields are kept). If there are more than two instances of the subgroup on the given item then Vidispine does not know which instance to update and will fail with an “Ambigous path” error. In this case you will have to provide instructions on which instance to update.

This can be done by specifying the uuid of the subgroup instance:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "uuid": "72dec5c0-6157-4022-adf2-60334933d72a",
                "fields": [
                    {
                        "name": "portal_mf11039",
                        "value": "Channel 1"
                    },
                    {
                        "name": "portal_mf144943",
                        "value": "2018-11-15T15:33:12.123456+10:00"
                    }
                ]
            }
        ]
    }
}

You can also use the mode operator to specify if you want the metadata to be added as a new instance, or if you want to remove an existing instance. The following will make sure to always add a new instance of Broadcast Date:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "mode": "add",
                "fields": [
                    {
                        "name": "portal_mf11039",
                        "value": "Channel 1"
                    },
                    {
                        "name": "portal_mf144943",
                        "value": "2018-11-15T15:33:12.123456+10:00"
                    }
                ]
            }
        ]
    }
}

The following will remove the metadata group instance with the given uuid:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "mode": "remove",
                "uuid": "72dec5c0-6157-4022-adf2-60334933d72a"
            }
        ]
    }
}

If the uuid for a specific instance is left out then all instances of the metadata group will be removed:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "mode": "remove",
            }
        ]
    }
}

These operations can also be combined so that the following will remove all existing Broadcast Date instances and then replace them with the newly provided instance:

{
    "metadata": {
        "group_name": "Demo",
        "groups": [
            {
                "name": "Broadcast Date",
                "mode": "remove",
            },
            {
                "name": "Broadcast Date",
                "mode": "add",
                "fields": [

                    {
                        "name": "portal_mf11039",
                        "value": "Channel 1"
                    },
                    {
                        "name": "portal_mf144943",
                        "value": "2018-11-15T15:33:12.123456+10:00"
                    }
                ]
            }
        ]
    }
}