POST dms.request.objects.upsert.database-before (Webhook)

As of Version2021 Autumn
HTTP MethodPOST
Response FormatJSON
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 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.
  • 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.
  • 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 or updated, the properties creationDate and traceId of these tags are set or updated after the webhook.
  • 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/310Only 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 EndpointThe 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/objects100 - 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/file301 - OBJECT_DOCUMENT_CHANGED
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=true310 - OBJECT_TAG_UPDATED (since 2021 Summer)
Restart Service

REGISTRY service

HeaderAuthorization-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'])