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 Installation Guide)
• 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. All history codes available in yuuvis® Momentum are listed and explained in the concept article on the Audit Trail.

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.