This tutorial shows how we can use a Java application to make a request to the Core API of the yuuvis® API system to retrieve the history entries of a DMS document. In addition, it briefly describes which history entries are generated for a document.

Introduction

The history of a DMS document is used to trace what happened to the document 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 events such as updating or retrieving the document.

Requirements

To work through this tutorial, the following is required:

• Set-up yuuvis® API system (see minikube setup, for example)
• A user with at least read permissions on a document type in the system (see tutorial for permissions)
• Simple Maven project

The History Entry

An entry in the history looks like this:

{
    "properties": {
        "system:objectId": {
            "value": 223439898
        },
        "system:objectTypeId": {
            "value": "system:audit"
        },
        "system:baseTypeId": {
            "value": "item"
        },
        "system:createdBy": {
            "value": "353c631e-6a61-4e89-9512-8d275c826ce5"
        },
        "system:tenant": {
            "value": "default"
        },
        "system: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"
        },
        "system:versionNumber": {
            "value": 1
        }
    }
}

The Client Application

We use a Java client to send a GET request to the Core API.

Maven Configuration

This example uses the OkHttpClient by Square, Inc. Therefore we add the following dependency to the file pom.xml:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>3.12.0</version>
</dependency>

Client Configuration

To interact with the yuuvis® API system via the Core API, we use an OkHttp3 client to send HTTP requests and read their responses.

String baseUrl = "http://127.0.0.1"; //baseUrl of gateway: "http://<host>:<port>"
String username = "clouduser";
String userpassword = "secret";
String tenant = "default";
String auth = java.util.Base64.getEncoder().encodeToString((username + ":" + userpassword).getBytes());
  
OkHttpClient.Builder builder = new OkHttpClient.Builder();
OkHttpClient client = builder.build();

For more information on setting up the OkHttp3 client with cookie handling, please refer to this Login Tutorial.

Retrieve History Entries of a Document

With a GET request to the URL /api/dms/objects/{objectId}/history we can retrieve the history of the DMS document with the object ID objectId.  The objectId serves as the unique identification number of an object and can be retrieved from the API response during import, for example (see tutorial on updating documents).

String objectId = "1234567890"; //example-objectId

Request request = new Request.Builder()
	.header("Authorization", auth)
    .header("X-ID-TENANT-NAME", tenant)
    .url(baseUrl + "/api/dms/objects/" + objectId + "/history")
    .get()
    .build();

We can now execute the above request object with the OkHttpClient instance created at the beginning. Then we let the result be displayed as a string in the command line.

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

The returned history for a DMS document is a list of all history entries.

Which History Entries Are There?

For the various actions, such as import, retrieve, update, and deletion of a DMS document, there are the following history entries:

Import:

• OBJECT_CREATED
• OBJECT_CREATED_WITH_CONTENT

The difference between these two types of import is that the first type imports only metadata and the second type imports metadata and content simultaneously.

Retrieve:

• DOCUMENT_ACCESSED
• METADATA_ACCESSED
• RENDITION_PDF_ACCESSED

Each of these types distinguishes between retrieving only metadata, content, or the PDF rendition of the content of a document.

Update:

• OBJECT_METADATA_CHANGED
• OBJECT_DOCUMENT_CHANGED

Here, a distinction is made between updating the metadata and the content of a document.

Delete:

• OBJECT_DELETED
• OBJECT_FLAGGED_FOR_DELETE

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

Summary

In this article, we used the OkHttpClient to retrieve the history of a DMS document and output the result to the command line. If you want to use a client to send several requests to the system in the same user context, we recommend a session handling, such as described here.

The full implementation of this example can be found in this git repository.