1. Overview

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.

2. 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.

3. Requirements

To work through this tutorial, the following is required:

4. The History Entry

An entry in the history looks like this:

Structure of a History Entry
{
    "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
        }
    }
}

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 referencedObjectId. The referredObjectId is the object ID of the document 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 which user context the entry was created, what happened and which version number the corresponding DMS document has after the protocolled action.

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

5. The Client Application

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

6. Maven Configuration

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

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

7. 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.

OkHttp3 Client and Variables
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.

8. 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).

Retrieve History Entries of a Document
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.

Execute Request
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.

9. 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.