This tutorial demonstrates how to update documents in yuuvis® API with the Core API. The following example will result in a short Java application that implements the HTTP requests for updating a document. 

Check out our graphical overview of the architecture which describes the basic use case flow for updating content or metadata.

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

Maven Configuration

Our Java client will submit its requests to the Core API using OkHttp 3.12 by Square, Inc. Therefore, the following block must be added to the Maven dependencies in the pom.xml of the project:

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

The example client, which is created in this tutorial, is intended to exemplarily implement the possibilities of the DMS API for updating existing objects. For this purpose, the client needs the object ID of the existing object to be updated. We will update metadata and content of an object via the Core API and access older versions of the object.

Determining the Object ID after Import

The object ID of an object in the system remains consistent across all updates, so it is possible to pass the object ID of an existing object to the client. In our code example the client initially imports an object (tutorial here) to the system and extracts the objectId of the newly created object from the response. The Java library org.json can accomplish this and will be used in this example, so it needs to be added to dependencies of the maven project:

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
</dependency>

The extraction of the objectId from the answer can be realized with org.json as follows:

public static String parseObjectIdFromJsonResponse(String responseJson){
    JSONObject jsonObject = new JSONObject(responseJson);
    return jsonObject.getJSONArray("objects")
            .getJSONObject(0)
            .getJSONObject("properties")
            .getJSONObject("system:objectId")
            .getString("value");
}

Updating Documents

Update Metadata

Post Update Metadata (overwrite all)

To update the metadata of an existing object, a POST request containing the new metadata in the body must be sent to the endpoint (POST /api/dms/objects/{objectId}). Instead of using a multipart body, the new metadata is passed to the body as a string and designated as media type JSON.

Request updateMetadataRequest = new Request.Builder()
        .header("Authorization", "Basic "+ auth)
        .header("X-ID-TENANT-NAME", tenant)
        .url(baseUrl + "/api/dms/objects/" + objectId)
        .post(RequestBody.create(MediaType.parse("application/json; charset=utf-8"),
			new File("./src/main/resources/metaData2.json")))
        .build();

The response returns the full, modified metadata with a new version number.

Patch Update Metadata (only provided properties)

Since a regular POST update overwrites all properties of an object type and can end up removing attributes if they are not resupplied, an alternative option for updating metadata is provided in the PATCH endpoint (PATCH /api/dms/objects/{objectId}). It allows users to update or add only those properties provided in the request body. Properties can also be removed using the Patch endpoint by setting the value of an existing property to null.

Request patchMetadataRequest = new Request.Builder()
         .header("Authorization", auth)
         .header("X-ID-TENANT-NAME", tenant)
         .url(baseUrl + "/api/dms/objects/" + objectId)
         .patch(RequestBody.create(MediaType.parse("application/json; charset=utf-8"),
			 new File("./src/main/resources/metadataPatch.json")))
         .build();

Update Content

To update the content of an existing object, a POST request must be sent to the endpoint /api/dms/objects/{objectId}/contents/file with the new content as a file in the body. The file name of the content file can be specified via the Content-Disposition header.

Request updateContentRequest = new Request.Builder()
        .header("Authorization", "Basic "+ auth)
        .header("X-ID-TENANT-NAME", "default")
        .header("Content-Disposition", "attachment; filename=\"test2.txt\"")
        .url(baseUrl + "/api/dms/objects/" + objectId + "/contents/file")	//baseUrl: "http://<host>:<port>"
        .post(RequestBody.create(MediaType.parse("text/plain; charset=utf-8"), 
			new File("./src/main/resources/test2.txt")))
        .build();

Versioning

When updating content or metadata, a new version of the object is created each time. The endpoints for fetching metadata (/api/dms/objects/{objectId}) and content (/api/dms/objects/{objectId}/contents/file)

) always return the current version of an object. It is also possible to get an older version of the object. How to do this is described in the next section.

Retrieving Version-Related Metadata

To retrieve metadata of a version, a GET request must be sent to the endpoint /api/dms/objects/{objectId}/versions/{versionNr}. The version number for each object starts at 1 and is incremented with each update.

Request versionMetadataRequest = new Request.Builder()
        .header("Authorization", "Basic "+ auth)
        .header("X-ID-TENANT-NAME", "default")
        .url(baseUrl+ "/api/dms/objects/" + objectId + "/versions/1")
        .get().build();

Retrieving Version-Related Content

To retrieve the content of a version, a GET request must be sent to the endpoint /api/dms/objects/{objectId}/versions/{versionNr}/contents/file.

Request versionContentRequest = new Request.Builder()
        .header("Authorization", "Basic "+ auth)
        .header("X-ID-TENANT-NAME", "default")
        .url(baseUrl+ "/api/dms/objects/" + objectId + "/versions/2/contents/file")
        .get().build();

Summary

In this tutorial, we used an OkHttpClient with cookie handling to import an object, to update its metadata and content, and finally retrieve the revised versions via the version-related endpoints.

The complete code example can be found in the Git repository.