How to Retrieve the History Entries of a Document

→ "Try it out - API Component "YADB""
→ check GitHub Python calls | Java Script calls | Java calls | Postman collection


This "How to" describes how to retrieve information on actions which have taken place around a document (object). Each action will be provided as single history entry for a stored document (object). In addition, the "How to" briefly describes which history entries are generated for a document (object) in general and what the structure looks like.

You can use the history of a stored document (object) to trace what actions happened from the creation of the document in the system, meaning the import, to the disappearance of the document from the system, the deletion. This also includes actions such as updating or retrieving the document (object).

Structure of a History Entry

How does the structure looks like
{
    "properties": {
        "enaio:objectId": {
            "value": 223439898
        },
        "enaio:objectTypeId": {
            "value": "enaio:audit"
        },
        "enaio:baseTypeId": {
            "value": "item"
        },
        "enaio:createdBy": {
            "value": "353c631e-6a61-4e89-9512-8d275c826ce5"
        },
        "enaio:tenant": {
            "value": "default"
        },
        "enaio:creationDate": {
            "value": "2018-12-21T12:23:34.510Z"
        },
        "description": {
            "value": ""
        },
        "action": {
            "value": 101
        },
        "detail": {
            "value": "CREATE_METADATA_WITH_CONTENT"
        },
        "referredObjectId": {
            "value": "d3241d76-0652-4ac8-ba6d-892d719a2a6d"
        },
        "traceId": {
            "value": "b279402aa9a2073b"
        },
        "enaio:versionNumber": {
            "value": 1
        }
    }
}

A history entry is structured like a map, i.e. the entry consists of key-value pairs, whereby a value can also be a key-value pair.

Each history entry has an objectId and a referredObjectId.
The referredObjectId is the object ID of the document (object) for which the entry was written and the objectId is the object ID of the entry itself.

Furthermore there are properties like createdBy, detail or versionNumber, which indicate in what user context the entry was created, what happened and which version number the corresponding document has after the logged action.

The time of the action (creationDate) and the associated trace ID (traceId) are also saved to ensure traceability.

Retrieving History Entries of a Document

To retrieve the entire history of a stored document (object), you send a GET request to the URL /dms-core/objects/{objectId}/history with the objectId ("GET operation for a list of history entries by ID") endpoint).

Retrieving History Entries of a Document
String objectId = "1234567890"; //example-objectId
Request request = new Request.Builder()
	.header("Ocp-Apim-Subscription-Key", key)
    .url(baseUrl + "/dms-core/objects/" + objectId + "/history")
    .get()
    .build();

If you execute the request, using an OkHttpClient instance, you can display the result as a string in the command line.

Executing the Request
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

The returned history for a stored document (object) is a list of all history entries.

Responses

Status Code Meaning
200 OK
401 Unauthorized
404 Not Found

History Entry Types

For the various actions, such as import, retrieve, update, and delete, there are the following history entries (action field values):

Import

  • 100 - CREATE_METADATA (only metadata - document without document file - imported)
  • 101 - CREATE_METADATA_WITH_CONTENT (document including metadata and content simultaneously imported)

Delete

  • 201 - DELETE (content file was deleted)
  • 202 - MARKED_FOR_DELETION

Update

  • 300 - UPDATE_METADATA (metadata has been updated)
  • 301 - UPDATE_CONTENT (content file has been updated)
  • 302 - UPDATE_METADATA_WITH_CONTENT (metadata and content file have been updated)

Retrieve

  • 400 - GET_CONTENT (content file retrieved)
  • 401 - GET_METADATA (metadata retrieved)
  • 402 - GET_TEXT_RENDITION (text preview retrieved)
  • 403 - GET_PDF_RENDITION (PDF rendition of the content file retrieved)
  • 404 - GET_THUMBNAIL_RENDITION (Thumbnail preview has been retrieved)

If a deletion action is triggered, the document to be deleted is first marked as deleted so that it can no longer be found. Only then are metadata and content file actually deleted, and a corresponding entry is made in the history of the document.