As of Version 2021 Autumn

HTTP Method POST

Response Format JSON

Description

This webhook can be triggered by

an object import,
an update of the content,
an update or the metadata,
or a tag update.

The webhook receives the completed objects just before they are indexed. This means that the objects are already enriched with system properties and default values (wherever necessary), normalized and validated.

In version 2021 Autumn, if there are invalid objects, the entry point of this webhook type is not reached. A validation exception is thrown before.

As of version 2021 Winter, the following behavior is implemented:

Each object is still validated before the entry point of the webhook, but a validation exception is thrown after the webhook entry point. Thus, webhooks of this type can be triggered even in case of an invalid object.
Those objects contain the corresponding validation errors in their options (see example below). Hence, it is possible to, e.g., add required properties to the original request body subsequently via a webhook.
The object validation is performed again after the webhook. Only if there still are validation errors, a validation exception is thrown.
If multiple webhooks of this type are configured, a validation is performed between every triggered webhook and its succeding webhook. Especially if objects have validation errors that were corrected by one webhook, the succeeding webhook gets the valid objects without validation errors in their options. If there are still invalid objects after the last webhook, then a validation exception is thrown.

As of version 2021 Winter: example validation errors that will be included in the 'options' of an invalid object

{
	...
	"options": {
		"action": 300,
		"detail": "OBJECT_METADATA_CHANGED",
		"validationErrors": [
			{
				"message": "Illegal property. An object of type 'appEmail:email' cannot have a property named 'decSingle'.",
				"serviceErrorCode": 2607
			},
			{
				"message": "A required property is missing. property='appEmail:from'",
				"serviceErrorCode": 2300
			}
		]
		...
	}
}

The predicate is applied to every single object in the list. The webhook is triggered for the whole object list as soon as one object satisfies the predicate.

The objects returned by the webhook are normalized and validated again before the interrupted processing chain will be continued. Hence, by means of this webhook, it is not possible to introduce invalid objects into the system. Furthermore, the object list in the original request body cannot be completely overwritten. The following rules apply:

It is not allowed to change the number of objects in the object list. An error will be thrown.
It is not allowed to modify the value of the system:objectId property. An error will be thrown.
System properties that are set by the system as well as content stream properties cannot be changed. An error will be thrown.
Especially, the values for system:lastModificationDate (and system:creationDate in case of an import process) are set before and are not updated due to any manipulations via webhook.
The expiration date cannot be removed or replaced by an earlier one.
If the value for system:parentId is changed, the new parent must be visible for the user who sent the original request.
As of version 2022 Autumn: If the webhook removes a secondary object type (SOT) from an object, all properties that were provided by the SOT are automatically removed from that object as well.
As of version 2022 Autumn: If the webhook adds an SOT to an object, all properties provided by the SOT can be added to that object by the webhook as well. If those properties are not added by the webhook, they will be automatically added with their default values afterwards (if available).
Data in the options section are read-only for the webhook. Changes will be ignored and the original values will be used. An error will not be thrown.
If tags are added by webhook during an import or metadata update, the values of system:lastModificationDate and system:traceId are used forcreationDate and traceId of these tags.
If tags are added/updated by an import or metadata update and manipulated by webhook, the value of system:lastModificationDate is used for the tags' creationDate.
If tags are added or updated during a pure tag operation, creationDate is set according to the original request.

In general any changes of the object applied by the webhook must match the action specified in the options section. Otherwise, the original request will result in an error. Consider the restrictions for these specific action codes in particular:

Value for 'action' Restriction

301

A webhook cannot change custom properties, retention properties or the system:secondaryObjectTypeIds property. However, as an exception, it is possible to add, update, or remove tags. Non-resistant tags are already removed from the object at this stage. A webhook can add resistant and non-resistant tags. All of them will be assigned to the final object. Further removals of non-resistant tags are not applied after the webhook.

110/210/310 Only changes to the system:tags property matching the individual action are allowed.

Considering the action code, the webhook might be allowed to change tags. In the audit trail, the tagging-related entry will be the same if the tag modification was specified in the original request or by means of the webhook, e.g.:

If an update adds a tag and a webhook removes this tag within the same update request, no audit entries are created.
If an update adds a tag and a webhook changes the state of this tag within the same update request, only one audit entry (OBJECT_TAG_CREATED) is created.

Requirements for External Endpoint The target URL must be a POST endpoint accepting and returning a list of objects.

Affected API Requests and Action Codes/History Codes

POST /api/dms/objects	100 - OBJECT_CREATED 101 - OBJECT_CREATED_WITH_CONTENT
POST /api/dms/objects/{objectId} PATCH /api/dms/objects/{objectId}	300 - OBJECT_METADATA_CHANGED
POST /api/dms/objects/{objectId}/contents/file	301 - OBJECT_DOCUMENT_CHANGED
POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore (as of 2022 Spring)	325 - OBJECT_RESTORED_FROM_VERSION
POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>	110 - OBJECT_TAG_CREATED (since 2021 Summer) 310 - OBJECT_TAG_UPDATED (since 2021 Summer)
DELETE /api/dms/objects/{objectId}/tags/{name}	210 - OBJECT_TAG_DELETED (since 2021 Summer)
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}	110 - OBJECT_TAG_CREATED (since 2021 Summer)
POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true	310 - OBJECT_TAG_UPDATED (since 2021 Summer)

Called by Service

REGISTRY service

Header Authorization-Header

Example Request Body

{
  "objects" : [ {
    "properties" : {
      "system:objectId" : {
        "value" : "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
      },
      "system:baseTypeId" : {
        "value" : "system:document"
      },
      "system:objectTypeId" : {
        "value" : "smallDocument"
      },
      "system:createdBy" : {
        "value" : "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
      },
      "system:creationDate" : {
        "value" : "2021-07-22T15:30:05.020Z"
      },
      "system:lastModifiedBy" : {
        "value" : "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
      },
      "system:lastModificationDate" : {
        "value" : "2021-07-22T15:30:21.520Z"
      },
      "system:versionNumber" : {
        "value" : 2
      },
      "system:tenant" : {
        "value" : "tenant1"
      },
      "system:traceId" : {
        "value" : "97a35859dbb4c435"
      },
      "Name" : {
        "value" : "exampledocument-without-content after update"
      }
    },
    "options" : {
      "action" : 300,
      "detail" : "OBJECT_METADATA_CHANGED",
      "tenant" : "tenant1",
      "user" : "root",
      "authorities" : [ "YUUVIS_SYSTEM_INTEGRATOR", "YUUVIS_TENANT_ADMIN" ],
      "inputVersion" : {
        "properties" : {
          "system:objectId" : {
            "value" : "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
          },
          "system:objectTypeId" : {
            "value" : "smallDocument"
          },
          "Name" : {
            "value" : "exampledocument-without-content after update"
          }
        }
      },
      "currentVersion" : {
        "properties" : {
          "system:objectId" : {
            "value" : "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
          },
          "system:baseTypeId" : {
            "value" : "system:document"
          },
          "system:objectTypeId" : {
            "value" : "smallDocument"
          },
          "system:createdBy" : {
            "value" : "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
          },
          "system:creationDate" : {
            "value" : "2021-07-22T15:30:05.020Z"
          },
          "system:lastModifiedBy" : {
            "value" : "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
          },
          "system:lastModificationDate" : {
            "value" : "2021-07-22T15:30:21.520Z"
          },
          "system:versionNumber" : {
            "value" : 1
          },
          "system:tenant" : {
            "value" : "tenant1"
          },
          "system:traceId" : {
            "value" : "672c49b7070ebd21"
          },
          "Name" : {
            "value" : "exampledocument-without-content"
          }
        }
      }
    }
  } ]
}

Example Predicate

Check if the object type is appEmail:email:

spel:'appEmail:email'.equals(properties['system:objectTypeId']['value'])

Browser not supported