POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true

Owned by Technische Redaktion
Last updated: Feb 16, 2023
As of Versionproduct version 2020 Summer | component version 2020 Summer
Request MethodPOST
Response FormatJSON
Required Permissionaction write and read
>> Roles and Role Sets
Description

To update the state for an existing tag of a DMS object, send the request with the ID of the DMS object as objectId and the tag's name together with the new value for the tag's state. In contrast to adding a tag, the update is characterized by adding the query parameter overwrite=true.

Furthermore, there is the possibility to set a traceid by means of the HTTP header: X-B3-TraceId. If not specified, a random traceid will be set. 

The method throws an exception, if the specified tag name does not exist.

In addition to the tag name, by means of the query parameter traceIdMustMatch=true, it is possible to define a second transition condition. The tag is modified only if the traceid indicated in the request matches the current traceid for the specified tag. Example (2) demonstrates the use of this extra feature, that provides the possibility to tune the update permissions for the tag. Only if the traceid is known, the tag can be modified. In this case, the traceid of the updated tag will be the same as before.

Any successful tag update changes the value for the state and the creationDate is set to the current time automatically. The traceid remains the same only if it is specified in the request and the query contains traceIdMustMatch=true parameter.

Any successful tag update will be added to the audit trail.

Tags are independent of an object's version and thus are always available at the current version. For version-specific information, metadata provide the suitable options.

Request Example

(1) /api/dms/objects/insert-objectid-here/tags/tag1/state/9999?overwrite=true

(2) /api/dms/objects/insert-objectid-here/tags/tag1/state/9999?overwrite=true&traceIdMustMatch=true
      X-B3-TraceId: 1234567887654321

Result Example

The result is a JSON structure containing the current value entries of the updated tag: name, state, creationDate and traceid.

successful tag update
{
  "objects": [
    {
      "properties": {
        "system:tags": {
          "value": [
            [
              "tag1",
              9999,
              "2020-02-20T02:20:20.220Z",
              "1234567887654321"
            ]
          ]
        }
      }
    }
  ]
}