1. Introduction
This tutorial shows how binary content files can be imported in yuuvis® Momentum via the core API. We will develop a small Java application that implements the HTTP requests to the corresponding endpoint.
2. Requirements
To create DMS objects, you need a running yuuvis® Momentum test system with at least one appropriate user account. We also expect you to have the Maven project with the corresponding dependencies for login and request/response processing.
3. Requirements
Please work through the following tutorials to get prepared:
4. Java Library Imports
We import the following Java libraries to use them in our application.
import okhttp3.*;
import java.net.CookieManager;
import java.net.CookiePolicy;
import java.util.Base64;
import java.io.File;
import org.json.JSONObject;
5. Used Content Types
We will use JSON structures for the metadata handling und plain text as well as JPEG image files as example content files.
public static final MediaType JSON = MediaType.parse("application/json; charset=utf-8");
public static final MediaType PLAINTEXT = MediaType.parse("text/plain; charset=utf-8");
public static final MediaType JPEG = MediaType.parse("image/jpeg; charset=utf-8");
6. Login Data
To use our Java client, we need the login information. We store them in variables such that we can reuse the values later.
public static final String username = "root";
public static final String userpassword = "changeme";
public static final String auth = "Basic "+ Base64.getEncoder().encodeToString((username+":"+userpassword).getBytes());
public static final String tenant = "myfirsttenant";
public static final String baseUrl = "http://123.456.78.9:30080";
Then we create our Java client. Please note that an IOException can be thrown by the OkHttpClient. That’s why we use it always wrapped with try and catch.
try {
CookieJar cookieJar = new JavaNetCookieJar(new CookieManager(null, CookiePolicy.ACCEPT_ALL));
OkHttpClient client = new OkHttpClient.Builder().cookieJar(cookieJar).build();
} catch (Exception e) {
e.printStackTrace();
}
We can now use our client to handle the requests to the yuuvis® Momentum API.
7. Importing a Single Document
To import a document using the Java client, we need the metadata and optionally the content of the document (depending on the schema definition, there are document types that may or must have content or must not have content).
The metadata when importing a document has the following format:
{
"objects": [{
"properties": {
"objectTypeId": {
"value": "system:document"
}
},
"contentStreams": [{
"mimeType": "text/plain",
"fileName": "geislein.txt",
"cid": "cid0"
}]
}]
}
In our example, we create a DMS object that will have the general object type system:document that is available in systems. An object of this type can optionally have a binary content file assigned to itself. The content is referenced in the contentStreams section by specifying a cid (multipart content ID within the request body as shown later). In the example, the cid references a multipart content with content ID cid0.
A content file can be in different file formats. It is recommended to specify the format correctly in the metadata and in the multipart request. If the content type is not specified, it is automatically determined during the content analysis. If the content type determination is not clear or the content analysis is switched off, the content type application/octet-stream is used.
In our example we have chosen a text file (mimetype text/plain).
7.1. Request
For an import, a POST request must be sent to the endpoint /api/dms/objects with a multipart body consisting of metadata and, if applicable, content of the object to be imported. To construct such a request, we use a MultipartBody.Builder(), which allows us to build the request body from several form parts as follows.
RequestBody singleImportRequestBody = new MultipartBody
.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("data",
"metadata.json",
RequestBody.create(JSON,
new File("./src/main/resources/metadata.json")))
.addFormDataPart("cid0",
"geislein.txt",
RequestBody.create(PLAINTEXT,
new File("./src/main/resources/geislein.txt")))
.build();
We use a Request.Builder() to create a request object with the multipart body, headers, and the URL. The following headers are necessary for the import because they contain user information of the user accessing the endpoint: Authorization header that contains the Base64-coded credentials of the user and an X-ID-TENANT-NAME header that contains the tenant name of the user. If the used OkHttp client supports cookie handling, the Authorization header can be omitted after the client’s first request, since the login information is stored in a session cookie (see also Login Tutorial).
Request singleImportRequest = new Request.Builder()
.header("Authorization", auth)
.header("X-ID-TENANT-NAME", tenant)
.url(baseUrl + "/api/dms/objects")
.post(singleImportRequestBody)
.build();
7.2. Response
To display the response of the API to the console, we create an associated response object when the request is executed. Please note that an IOException can be thrown by the OkHttpClient when creating the response object.
Response response = client.newCall(singleImportRequest).execute();
String responseString = response.body().string();
System.out.println(responseString);
The response Body contains a JSON structure that contains the metadata specified in the request as well as the automatically set metadata like system:objectId.
{
"objects":[
{
"properties":{
"system:objectId":{
"value":"ecc0f6cc-7467-4e02-9903-073b893afdfd"
},
"system:baseTypeId":{
"value":"system:document"
},
"system:objectTypeId":{
"value":"system:document"
},
"system:createdBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:creationDate":{
"value":"2025-12-12T12:54:45.710Z"
},
"system:lastModifiedBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:lastModificationDate":{
"value":"2025-12-12T12:54:45.710Z"
},
"system:versionNumber":{
"value":1
},
"system:tenant":{
"value":"myfirsttenant"
},
"system:traceId":{
"value":"11bcb030b2d473dd"
}
},
"contentStreams":[
{
"contentStreamId":"7723e659-8dd1-493e-a72c-16422f7a1d47",
"archivePath":"myfirsttenant-system:document/2025/12/12/77/23/e6/",
"length":18280,
"mimeType":"text/plain",
"fileName":"geislein.txt",
"digest":"62B80FA99520837B3469ED395F6FA7E513DEEA824E20B75E665028A1F8038E88",
"repositoryId":"s3_path_tenant_date_csid"
}
]
}
]
}
If we want to retrieve our imported document from yuuvis® Momentum, we can request it by its system:objectId. The value can be extracted from the response body.
JSONObject jsonObject = new JSONObject(responseString);
String objectId = jsonObject.getJSONArray("objects")
.getJSONObject(0)
.getJSONObject("properties")
.getJSONObject("system:objectId")
.getString("value");
System.out.println(objectId);
The value in our example is ecc0f6cc-7467-4e02-9903-073b893afdfd.
8. Importing Multiple Documents in Batch Mode
If multiple documents are to be imported at the same time, this can be done using the same endpoint of the Core API. Instead of a single object, the objects list consists of several metadata records. The individual content files of the objects then each require a unique cid as the name of the form-data parts in the multipart request. This cid is referenced in the associated metadata record in the contentStreams list, which allows metadata to be uniquely assigned to content.
{
"objects": [{
"properties": {
"system:objectTypeId": {
"value": "system:document"
}
},
"contentStreams": [{
"cid": "cid1"
}]
},
{
"properties": {
"system:objectTypeId": {
"value": "system:document"
}
},
"contentStreams": [{
"cid": "cid2"
}]
}]
}
8.1. Batch Request
In the multipart body, we create a separate FormDataPart for the content of each object, whose first parameter is the content ID (cid).
RequestBody batchImportRequestBody = new MultipartBody
.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("data",
"metadataBatch.json",
RequestBody.create(JSON,
new File("./src/main/resources/metadataBatch.json")))
.addFormDataPart("cid1",
"schneiderlein.txt",
RequestBody.create(PLAINTEXT,
new File("./src/main/resources/schneiderlein.txt")))
.addFormDataPart("cid2",
"960px-Offterdinger_Das_tapfere_Schneiderlein.jpeg",
RequestBody.create(PLAINTEXT,
new File("./src/main/resources/960px-Offterdinger_Das_tapfere_Schneiderlein.jpeg")))
.build();
The assembly of the request object is identical to the normal import.
8.2. Response of Batch Request
If successful, the response object contains a multi-element objects list that contains the metadata records of all objects imported in this batch import.
{
"objects":[
{
"properties":{
"system:objectId":{
"value":"76491961-05d8-4e6f-a4d5-f6a3170c1e32"
},
"system:baseTypeId":{
"value":"system:document"
},
"system:objectTypeId":{
"value":"system:document"
},
"system:createdBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:creationDate":{
"value":"2025-12-12T14:37:43.790Z"
},
"system:lastModifiedBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:lastModificationDate":{
"value":"2025-12-12T14:37:43.790Z"
},
"system:versionNumber":{
"value":1
},
"system:tenant":{
"value":"myfirsttenant"
},
"system:traceId":{
"value":"1b7b8ad68eff7fc6"
}
},
"contentStreams":[
{
"contentStreamId":"0784bded-9551-4c76-9f9d-4bb01bfcf355",
"archivePath":"myfirsttenant-system:document/2025/12/12/07/84/bd/",
"length":18280,
"mimeType":"text/plain",
"fileName":"schneiderlein.txt",
"digest":"62B80FA99520837B3469ED395F6FA7E513DEEA824E20B75E665028A1F8038E88",
"repositoryId":"s3_path_tenant_date_csid"
}
]
},
{
"properties":{
"system:objectId":{
"value":"ccb8a457-7b0b-4f16-8882-0340f3dbe5e2"
},
"system:baseTypeId":{
"value":"system:document"
},
"system:objectTypeId":{
"value":"system:document"
},
"system:createdBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:creationDate":{
"value":"2025-12-12T14:37:43.790Z"
},
"system:lastModifiedBy":{
"value":"4d639f66-03d6-4264-a0bb-abbe9e6dee5d"
},
"system:lastModificationDate":{
"value":"2025-12-12T14:37:43.790Z"
},
"system:versionNumber":{
"value":1
},
"system:tenant":{
"value":"myfirsttenant"
},
"system:traceId":{
"value":"1b7b8ad68eff7fc6"
}
},
"contentStreams":[
{
"contentStreamId":"4e5ebba4-b2b1-44a5-9652-17f29b69c5e8",
"archivePath":"myfirsttenant-system:document/2025/12/12/4e/5e/bb/",
"length":559594,
"mimeType":"image/jpeg",
"fileName":"960px-Offterdinger_Das_tapfere_Schneiderlein.jpeg",
"digest":"35780E6A34DE10582E22651AF8A0D83FDD9FC6A42AC1615DEE8EB2BC9B8346C0",
"repositoryId":"s3_path_tenant_date_csid"
}
]
}
]
}
9. Summary
In this tutorial an OkHttpClient with Cookie Handling was used to import documents via the Core API, both in batch mode and individually. Your new objects are now retrievable via core API.
A complete code example can be found in this git repository.