Link relation aa:update-multi-value-attribute

New in MC | Cloud UX 2021.3

Overview

Update a multi-value attribute of an asset.

This link rel is only available for MediaCentral | Asset Management.

HTTP method

PATCH

URI template variables

-

Query parameters

-

Request body

JSON Patch

The body contains a JSON Patch document (RFC 6902). It contains an array of JSON patch operations.

Example:

[
  {
    "op": "replace",
    "path": "/rows/0/NOTE/value",
    "value": "New text"
  }
]

This sets the value of the sub attribute NOTE in row 0 to "New text".

For a detailed list of supported JSON Patch commands, see below.

HTTP response

204 No Content

400 Bad Request

The format of a value is unexpected.

404 Not Found

Response body

-

Available in

Description

Multi-value JSON format

The JSON patch operations are applied on the JSON format of the aa:multi-value-attribute resource.

Example for a multi-value compound CONTRIBUTORS with two rows:

#

REAL_NAME

ROLE (thesaurus)

ROLE_NAME

0

Gary Cooper

488 "Actor"

Marshal Will Kane

1

Grace Kelly

488 "Actor"

Amy Fowler Kane

The sub attributes REAL_NAME and ROLE_NAME are text attributes, ROLE is a thesaurus attribute (with 488 as thesaurus ID and "Actor" as English label).

Then, the property rows contains the following JSON, when queried with ?lang=en:

Multi-value JSON: 
 
"rows": [
  {
    "REAL_NAME": {
      "value": "Gary Cooper"
    },
    "ROLE": {
      "type": "thesaurus",
      "value": "488",
      "value-labels": {
        "en": "Actor"
      },
      "taxonomyid": "THEBU_ROLE_CODE"
    },
    "ROLE_NAME": {
      "value": "Marshal Will Kane"
    }
  },
  {
    "REAL_NAME": {
      "value": "Grace Kelly"
    },
    "ROLE": {
      "type": "thesaurus",
      "value": "488",
      "value-labels": {
        "en": "Actor"
      },
      "taxonomyid": "THEBU_ROLE_CODE"
    },
    "ROLE_NAME": {
      "value": "Amy Fowler Kane"
    }
  }
]

Relation to "index" in aa:attributes

As explained in the description of the aa:multi-value-attribute resource, the JSON format here hides the MC|AM internal order index value for rows. Instead, the rows are returned as a simple array that contains the rows in the correct order.

The row index used in the path property all following JSON patch operations always addresses row numbers in this array and not the MC|AM order index value.

Multiple operations

You can send a JSON Patch command with an arbitrary amount of JSON patch operations. The operations are applied in the order they appear in the request body. This means that each operation is applied using the track numbers as they are after applying all previous operations. For example, let’s say you have a multi-value attribute with 3 rows:

#

REAL_NAME

ROLE_NAME

0

Gary Cooper

Marshal Will Kane

1

Grace Kelly

Amy Fowler Kane

2

Lloyd Bridges

Deputy Marshal Harvey Pell

Now, you want to delete the Gary Cooper row (currently row 0) and set the role name for Lloyd Bridges (currently row 2) to "Harvey Pell" . Then the operations will look like this:

[
  {
    "op": "remove",
    "path": "/rows/0"
  },
  {
    "op": "replace",
    "path": "/rows/1/ROLE_NAME",
    "value": "Harvey Pell"
  }
]

After removing the Cary Cooper row 0, all remaining rows shift by one. To change the Lloyd Bridges row (previously row 2), you now hove to use index 1.

JSON patch operations

The following chapters contain typical JSON patch operations. There are other operations available that may have the same effect. The examples here just show recommended ways to achieve the intended changes.

JSON patch structure

A JSON patch request always consists of an array of JSON patch operations.

In general, a JSON patch operation consists of:

  • An operation op: one of add, replace, remove, move, copy and test.

  • A JSON pointer path that references a location within the target document (see RFC-6901).

  • Other properties, depending on the operation.

Overview of the operations:

Operation Description

add

Takes the JSON node addressed by the path property:

  • If it references an index in a JSON array, the given value property is inserted at that index.

    • If the index is "-", the given value property is added to the end of the array.

  • If it references a JSON property:

    • If the property exists, the value of the property is replaced by the given value property.

    • If not, the property is added with the given value property as value.

replace

Replaces the node given in the path property with the given value.

remove

Removes the node given in the path property.

move

Removes the node given in the from property and adds it to the given path property. It is functionally identical to a "remove" operation, followed by an "add" operation with the removed value.

copy

Copies the node given in the from property and adds it to the given path property. It is functionally identical to an "add" operation with the value of the node given in the from property.

test

Tests a given condition. Aborts the JSON patch operation if the condition is not fulfilled.

The test command is not supported here.

For more details, see RFC 6902.

Changing sub attribute values

The following table shows typical JSON operations that change the value of a sub attribute in a row.

Description Operation

Set the value of an attribute in a row.

Example: Set the value of the sub attribute NOTE to "New text" in row 0.

 
[
  {
    "op": "replace",
    "path": "/rows/0/NOTE/value",
    "value": "New text"
  }
]

This works with all attribute types.

Example: Set the value of the thesaurus attribute ROLE to "488".

 
[
  {
    "op": "replace",
    "path": "/rows/0/ROLE/value",
    "value": "488"
  }
]

Clear the value of an attribute in a row.

Example: Clear the value of the sub attribute NOTE in row 0.

 
[
  {
    "op": "remove",
    "path": "/rows/0/NOTE/value"
  }
]

Set an attribute in a row with all properties, especially with a "unit" property for timecode and duration attributes. The "value" property of the JSON patch operation must be a complete attribute definition.

Example: Set the sub attribute SUB_TIMECODE to 20000 milliseconds (unit "ms") in row 2.

 
[
  {
    "op": "replace",
    "path": "/rows/2/SUB_TIMECODE",
    "value": {
      "unit": "ms",
      "value": 20000
    }
  }
]

Changing individual rows

The following table shows typical JSON operations that modify entire rows.

Description Operation

Append an empty row.

The "-" in the path property means: at the end.

 
[
  {
    "op": "add",
    "path": "/rows/-"
  }
]

Insert an empty row.

Example: Insert a row in front of row 2.

 
[
  {
    "op": "add",
    "path": "/rows/2"
  }
]

Append a row with given values.

Example: append a row with

  • REAL_NAME "Lloyd Bridges"

  • ROLE_NAME "Deputy Marshal Harvey Pell"

The "-" in the path property means: at the end.

 
[
  {
    "op": "add",
    "path": "/rows/-",
    "value": {
      "REAL_NAME": {
        "value": "Lloyd Bridges"
      },
      "ROLE_NAME": {
        "value": "Deputy Marshal Harvey Pell"
      }
    }
  }
]

Insert a row with given values.

Example: insert a row with

  • REAL_NAME "Lloyd Bridges"

  • ROLE_NAME "Deputy Marshal Harvey Pell"

in front of row 2.

 
[
  {
    "op": "add",
    "path": "/rows/2",
    "value": {
      "REAL_NAME": {
        "value": "Lloyd Bridges"
      },
      "ROLE_NAME": {
        "value": "Deputy Marshal Harvey Pell"
      }
    }
  }
]

Remove a row.

Example: remove row 2.

 
[
  {
    "op": "remove",
    "path": "/rows/2"
  }
]

Replace a row.

Example: replace all values in row 2 with the values:

  • REAL_NAME "Lloyd Bridges"

  • ROLE_NAME "Deputy Marshal Harvey Pell"

 
[
  {
    "op": "replace",
    "path": "/rows/2",
    "value": {
      "REAL_NAME": {
        "value": "Lloyd Bridges"
      },
      "ROLE_NAME": {
        "value": "Deputy Marshal Harvey Pell"
      }
    }
  }
]

Move a row.

Example: move row 3 in front of row 1.

 
[
  {
    "op": "move",
    "from": "/rows/3",
    "path": "/rows/1"
  }
]

Copy a row.

Example: copy row 3 and place the copy in front of row 1.

 
[
  {
    "op": "copy",
    "from": "/rows/3",
    "path": "/rows/1"
  }
]

Changing all rows

The following table shows typical JSON operations that modify the entire set of rows.

Description Operation

Remove all rows.

 
[
  {
    "op": "replace",
    "path": "/rows",
    "value": []
  }
]

Replace all rows with a given set of rows.

Example: Remove all existing rows and replace them with two new rows:

REAL_NAME

ROLE_NAME

ROLE (thesaurus)

Gary Cooper

Marshal Will Kane

488 "Actor"

Grace Kelly

Amy Fowler Kane

488 "Actor"

 
[
  {
    "op": "replace",
    "path": "/rows",
    "value": [
      {
        "REAL_NAME": {
          "value": "Gary Cooper"
        },
        "ROLE_NAME": {
          "value": "Marshal Will Kane"
        },
        "ROLE": {
          "value": "488"
        }
      },
      {
        "REAL_NAME": {
          "value": "Grace Kelly"
        },
        "ROLE_NAME": {
          "value": "Amy Fowler Kane"
        },
        "ROLE": {
          "value": "488"
        }
      }
    ]
  }
]