Conditional Metadata Setup

Conditional metadata provides relationships between values of different metadata fields. This applies within a single metadata group. Valid field types for conditions are:

  • Dropdown
  • Checkbox
  • Lookup
  • Radio

A condition limits the values that can be selected for fields, based on the currently selected values in the form. They are applied when editing or creating metadata on an item or a collection in the Portal UI.

The REST API for administrating metadata conditions can be found at /API/v2/metadata-schema/groups/{name}/conditions/ and it can be tested from the Portal UI via Help > REST API Reference. This API includes creating, deleting, and modifying conditions.

Each Condition consists of a list of fields, and allowed values for each.

As a very simple example, we can limit the Language entry on the default Film so that if Finnish is selected, the only other options are English and Swedish. This is accomplished with the following JSON:

{
    "fields": [
        {
            "keys": [
                "fi",
                "en",
                "sv"
            ],
            "field_name": "portal_mf257027"
        }
    ]
}

It can be applied with PUT to /API/v2/metadata-schema/groups/Film/conditions/LanguageTest. This creates a condition on the metadata group Film, called LanguageTest, which limits the “portal_mf257027” values, when one of the matching values here is selected, to “fi”, “en”, and “sv”.

Now after a user has selected Finnish in the a metadata form (e.g. creating a Placeholder, or editing Metadata), the only other allowed options are Swedish and English. The same applies if any other of the three languages is selected first.

Note that the “keys” of the condition are the keys of the lookup, not the display values.

The following example assumes the system has a metadata group FilmDemo, with Dropdown type of fields with field identifiers portal_movie_title, portal_directors and portal_actors.

Using the endpoint POST /API/v2/metadata-schema/groups/FilmDemo/conditions/ we can create multiple conditions efficiently in a single call:

[
    {
        "fields": [
            {
                "field_name": "portal_movie_title",
                "keys": [
                    "dirty-harry"
                ]
            },
            {
                "field_name": "portal_directors",
                "keys": [
                    "robert-rubin"
                ]
            },
            {
                "field_name": "portal_actors",
                "keys": [
                    "clint-eastwood",
                    "harry-guardino"
                ]
            }
        ],
        "external_id": "dirty-harry-1234"
    },    {
        "fields": [
            {
                "field_name": "portal_movie_title",
                "keys": [
                    "the-bridges-of-madison-county"
                ]
            },
            {
                "field_name": "portal_directors",
                "keys": [
                    "clint-eastwood"
                ]
            },
            {
                "field_name": "portal_actors",
                "keys": [
                    "clint-eastwood",
                    "meryl-streep"
                ]
            }
        ],
        "external_id": "the-bridges-of-madison-county-1235"
    }
]

This assumes e.g. that the dropdown portal_movie_title has a choice with key = dirty-harry, Display value = Dirty Harry.

Now if “Dirty Harry” is selected for Movie Title, director choices is limited to “Robert Rubin”, and actor choices are limited to “Clint Eastwood” and “Harry Guardino”.

However if user selects “Clint Eastwood” as an actor, “portal_movie_title” would allow both “Dirty Harry” and “The Bridges of Madison County” - since Clint Eastwood in actor matches both of these conditions.

Practical Example

For a related practical usage example of conditional metadata, see the Conditional metadata -section in the User Documentation.

Notes about conditions

  • Conditions can be setup before or after the metadata group is created - when creating conditions the metadata group name, field names, and keys are not validated against current metadata schema
  • Therefore care must be taken to ensure the same field identifiers and keys are used in the metadata schema and the conditions, if these don’t match the conditions are not applied
  • Conditions only apply to the listed fields, other fields in the same group are not affected
  • Empty list “keys”: [] can be used to denote that some field does not allow any value when a condition is met