Status Change

Every time the status of a document changes the client might need to react. A status change happens for example when our classification and extraction service updates document data. Please check our full list of statuses.

Delphi Status

There are 2 options to implement this communication.

1. Delphi Status
2. Webhook notification (recommended)
   1. Format
   2. Example
   3. Configuration via our API
      1. Configuration In the WebApp
3. Polling

Webhook notification (recommended)

When configured, the WebApp sends notifications via HTTPS to a remote endpoint when changes happen to the status of documents.

The remote endpoint is expected to return the HTTP status 200. If another status is returned instead, we’ll retry to notify multiple times at increasing intervals for 24 hours.

Notification will be sent out for the following status changes.

Update to state	Notification is sent
From null to 1	Yes
From 1 to 2	Yes
From 1 to 6	Yes
From 2 to 5	Yes
From 3 to 4	Yes
From 3 to 5	Yes
From 4 to 5	Yes
From 2 to 8	Yes
From 3 to 8	Yes
From 4 to 8	Yes

Note: Notification is sent for every status change. However, when two or more events cause a change in status almost at the same time, the later takes pre-eminence and notification is sent for the later only.

Format

The notification payload is an array of objects containing data of one or more staged-documents.

Each object has the following properties:

Property	Type	Description
uuid	string	A unique identifier for the staged-document
url	string	The url to get all information about the staged-document
currentStatus	integer	The status of the staged-document after the update
previousStatus	null or integer	The status of the staged-document before the update

Example

Here’s an example of the notification payload sent to the webhook.

[
	{
	    "uuid":"1a03651a-b43f-41d5-bb75-b1e82023b902",
	    "url":"https:\/\/<FQDN>\/external-api\/staged-documents\/1a03651a-b43f-41d5-bb75-b1e82023b902",
	    "currentStatus":1,
	    "previousStatus":null
	},
	...
]

Configuration via our API

The webhook can be configured by the
POST /external-api/external-dms-configuration endpoint.

To do so, make a request sending the following JSON body:

{
    "url": "<url of remote endpoint>"
}

The url must start with https://.

Once configured, the webhook URL can be retrieved with the GET /external-api/external-dms-configuration endpoint.

Configuration In the WebApp

Administrators can configure the webhook in the WebApp.

To do so:

1. Log in into the WebApp and from the app menu, go to Administration.
2. Click on Delphi.
3. Enter the Webhook URL

Polling

When communication via webhooks can’t be implemented, a polling strategy should be considered in the remote system.

One way of achieving that in the remote system is to:

1. Keep track of the staged-document uuids returned when uploading documents
2. Regularly fetch staged-document information by using the GET /external-api/staged-documents/<uuid> endpoint.

---

Architrave GmbH - All rights reserved.
Made in Berlin, proudly international.