POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

Add or update the tag with the name and state specified in the request URL of the first available object matching the query. The JSON response body is an object list containing the updated object as single entry or an empty objects list if no processable object was found to match the query.

Optionally, there is the possibility to set a traceid by means of the HTTP header X-B3-TraceId. In case of a tag update, the previous traceId remains unchanged. If a new tag is added, the traceId specified in the header is used.

If an object was found to match the query and is processable, the following behavior is triggered:

• If the selected object already has a tag with a name, the current state value is replaced by the new one. Otherwise a tag with a name and state is added.
• In both cases, update or addition, the tag's creationDate will be updated.
• Any successful tag creation or update is added to the audit trail, as well as any retrieval of the metadata.

Internally, the endpoint retrieves a result list of up to 40 objects matching the specified query. The tag update/addition is applied to the first match. However, if the tag update/addition is not possible, it will be applied to the next result. In case there is no matching object left, an empty list will be returned.
Objects might be not processable for different reasons, e.g., they could be under processing by another service running in parallel. As the endpoint internally handles those situations, it is easily possible to operate multiple service instances calling this tagging endpoint at the same time. Even if those services sent the exact same request, they would retrieve different objects to which the described tag update/addition was applied.

Especially other calls of the /api/dms/objects/tags/{name}/state/{state}?query=<SQL> endpoint cannot retrieve or access an object that is currently processed via the same endpoint. An object under such processing is locked during the time of updating the database AND an additional timeout for updating the index of the search engine. This additional timeout can be configured in the API gateway configuration via the tagging-lock-visibility-timeout parameter (integer value in milliseconds, default 4000). It can be set, e.g., via the environment or via a profile configuration like api-prod.yml.

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

As of 2022 Autumn, the optional query parameter waitForSearchConsistency can be added to the request URL. If not specified, the default value true is used.

POST /api/dms/objects/tags/tag1/state/100?query=SELECT * FROM document WHERE system:tags[tag1] IS NULL AND system:creationDate=TODAY()

The query searches for objects of type document which were created today and do not have a tag with the name tag1. To the first match, a new tag tag1 will be added with the state 100.

The return is a JSON structure containing the information on existing tags and metadata dedicated to the modified object.

{
  "objects": [
    {
      "properties": {
        "system:objectId": {
          "value": "insert-objectid-here"
        },
        "system:tags": { 
          "value": [ [ "tag1", 100, "2020-02-20T02:22:20.220Z", "1234567887654321" ] ] 
        },
        "system:baseTypeId": {
          "value": "system:document"
        },
        "system:objectTypeId": {
          "value": "document"
        },
        "system:secondaryObjectTypeIds": {
          "value": [
            "system:rmDestructionRetention"
          ]
        },
        "system:createdBy": {
          "value": "this-id-indicates-the-user"
        },
        "system:creationDate": {
          "value": "2020-02-20T02:02:20.220Z"
        },
        "system:lastModifiedBy": {
          "value": "this-id-indicates-another-user"
        },
        "system:lastModificationDate": {
          "value": "2020-02-20T02:20:22.220Z"
        },
        "system:versionNumber": {
          "value": 1
        },
        "system:tenant": {
          "value": "default"
        },
        "system:traceId": {
          "value": "abcdef123456"
        },      
        "Name": {
          "value": "Email"
        },
        "date": {
          "value": "2002-02-20T02:20:00.220Z"
        }
      },
      "contentStreams": [
        {
          "contentStreamId": "0B469DD0-AA6F-11EA-A7FE-DD3E0B230EEB",
          "archivePath": "default/DOCUMENT/B4/69/D/",
          "length": 200001,
          "mimeType": "application/pdf",
          "fileName": "exchange-doku-jar.pdf",
          "digest": "334A9337CFEFC4B1D25C9CC0289205B3133DA4CDE8086C6A9D2FF61CC3205F55",
          "repositoryId": "repo252"
        }
      ]
    }
  ]
}