1. Overview

This tutorial shows how to use the Core API to get the tenant-specific schema of the system, how to validate a schema, and how to bring in a new schema.

2. Introduction

The schema consists of the tenant-specific schema, the unchangeable system properties, and the global schema. It determines the attributes and properties that objects must or may have in the system. You can find out more about the structure of the schema here.

This tutorial deals with the administration of tenant-specific schemas. The global schema remains unchanged from the endpoints presented below.

A user can only manage the schema that belongs to the client to which he or she belongs. It is not possible to manage schemas of other clients. A user also requires the role 'YUUVIS_TENANT_ADMIN'.

The endpoints presented in the following example provide or expect a schema in XML format.

3. Requirements

To work through this tutorial, the following is required:

  • Set-up yuuvis® API system (see Installation Guide)

  • A user with read and delete permissions on a document type in the system (see Roles)

  • Simple Maven project

4. Maven Configuration

This example uses the OkHttpClient of the open source portal Square Open Source. For this, 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>

5. 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 the Login to the Core API tutorial.

6. Retrieving the Schema

The active schema can be retrieved with a GET request to the URL /api/admin/schema. This schema contains only the tenant-specific, user-defined object types, properties, and so on. It does not contain any system types, meaning you can upload it as it is without the system behaving differently afterwards. Only the version number of the schema and the modification date would change. Underneath the tenant-specific schema lies a preconfigured global schema which can be altered only by authorized administrators via the URL /api/system/schema. To retrieve a complete schema consisting of the global schema and the additions specific to the tenant of the user that requests it, use /api/dms/schema.

Retrieving the Schema
Request getSchemaRequest = new Request.Builder()
        .header("Authorization", "Basic " + auth)
        .header("X-ID-TENANT-NAME", tenant)
        .url(baseUrl + "/api/admin/schema")
        .get()
        .build();

The OkHttpClient instance now makes it easy to write the schema to a file.

Write the Schema to a File
try(FileOutputStream fos = new FileOutputStream("activeSchema.xml")) {
    Response activeSchemaResponse = client.newCall(getSchemaRequest).execute();
    byte[] bytes = activeSchemaResponse.body().bytes();
    fos.write(bytes);
}

7. Validating a Schema

A POST request for the URL /api/admin/schema/validate can be used to verify that a schema is valid. This requires a schema; in the example, under the path ./schemaToValidate.xml. The schema is sent as a multi-part in the body of the request.

Validating a Schema
String filename = "./schemaToValidate.xml";

RequestBody requestBody = new MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("file", "schema.xml", RequestBody.create(MediaType.parse("application/xml; charset=utf-8"), new File(filename)))
        .build();

Request validateSchemaRequest = new Request.Builder()
        .header("Authorization", "Basic " + auth)
        .header("X-ID-TENANT-NAME", tenant)
        .url(baseUrl + "/api/admin/schema/validate")
        .post(requestBody)
        .build();

The response to this request contains an HTTP status code and the validation result in JSON format. You can simply output this to the console after the request was called using an OkHttpClient instance.

Console Output of the Validation Result
Response validationResponse = client.newCall(validateSchemaRequest).execute();
System.out.println(validationResponse.code());
String validationResponseAsString = validationResponse.body().string();
System.out.println(validationResponseAsString);

In the case of a valid schema, the response contains the HTTP status code 200 and the validation result is an empty list, meaning it does not contain any validation errors.

Result of a Successful Validation
{
    "validationErrors": []
}

If, however, the schema is not valid, the response contains the HTTP status code 422 and there is at least one validation error.

Result of an Unsuccessful Validation
{
    "validationErrors": [{
        "message": "Invalid property reference 'name' in type definition 'email'."
    }]
}

8. Importing a New Schema

A new schema can be imported with the POST request to the URL /api/admin/schema. The endpoint behaves similar to the validation endpoint, meaning the HTTP status code of the answer tells you if the schema is valid and the answer contains a validation result. The difference is that if the validation is successful, the schema is stored and activated in the system.

Importing a Schema
String filename = "./schemaToImport.xml";

RequestBody requestBody = new MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("file", "schema.xml", RequestBody.create(MediaType.parse("application/xml; charset=utf-8"), new File(filename)))
        .build();

Request validateSchemaRequest = new Request.Builder()
    .header("Authorization", "Basic " + auth)
        .header("X-ID-TENANT-NAME", tenant)
        .url(baseUrl + "/api/admin/schema")
        .post(requestBody)
        .build();

The further use of the request is analogous to the validation of a schema described in the previous section.

9. Changing the Schema

Typically, you rarely want to import a completely new schema. Often you only want to extend the active schema with object types or properties or make small changes. This can be done with the help of the three preset endpoints:

  1. Fetch the schema to be changed and save it locally in an XML file.

  2. Make the desired changes to the XML file and verify with the validation endpoint whether the new version of the schema is still valid.

  3. Import the changed, valid schema

10. Summary

This tutorial showed how to get the tenant-specific schema in XML format for editing, how to validate any schema and how to import a new schema.

The full implementations of these examples can be found in this Git repository.

For more information about creating your own Schema, please refer to the Schema concepts article.