This tutorial shows how to change your basic schema for individual instances of an object type during the entire lifecycle of a document. Classify objects at a later point in time, add or remove property groups at runtime by defining and referencing "floating" secondary object types.

Table of Contents

Introduction

It is no small thing to manage, store and track all of your business content in a fast-changing world. To be able to optimize and adapt your working business processes constantly is one of the keys to your success. To cater your needs yuuvis® offers the flexibility to change the metadata structure of your basic schema at runtime, and - most important - for your already stored instances of an object type. Whether the newly added property groups are used to classify and add values to your objects, to provide additional search options or to support further business processes - the system goes with the flow. The functionality of adding or removing property groups including metadata values of referenced "floating" secondary object types provides all you need to make your schema changes happen.

Requirements

To work through this tutorial, the following is required:

Set-up yuuvis® API system (see Installation Guide)
A user with read and write permissions on a document type in the system (see tutorial for permissions)

Example Use Case for a "Schema Flow"

Since a high variety of customized business processes can be set up for managing content, this tutorial shows one basic example to give you a better understanding of the idea behind the provided functionality. Let us imagine the following initial situation: we want to import documents and do not know the content types yet. At a later point in time, if the content type is known, we would like to add the needed group of properties for invoice, delivery slip and supplier metadata by using floating secondary object types.

The definition of the referenced properties is not explicitly mentioned in this example use case. For details please refer to "Schema - Defining Object Types, "Property Definitions"".

Defining Document Object Types

Add a new document object type definition ("document") with a single property ("DateOfReceipt") to your schema to enable the import in general. To store objects with content, the objects' type must be a document type and the contentStreamAllowed attribute must specify that this type can or must have content (allowed or required).

schema.xml (document object types)

...
    <typeDocumentDefinition>
        <id>appSot:document</id>
        <baseId>system:document</baseId>
        <contentStreamAllowed>allowed</contentStreamAllowed>
        <propertyReference>appSot:DateOfReceipt</propertyReference>
    </typeDocumentDefinition>
...

Define Secondary Object Types

Add three new secondary object types to your schema - each representing a group of properties used for specifying the content type in detail ("INV" invoice, "DEL" delivery slip and "SUP" supplier). At this point, it does not matter whether the secondary object type will be used later on by a document object type as static or floating.

schema.xml (secondary object types)

...   
    <typeSecondaryDefinition>
        <id>appSot:INV</id>
        <baseId>system:secondary</baseId>
        <propertyReference>appSot:invoiceNo</propertyReference>
    </typeSecondaryDefinition>

    <typeSecondaryDefinition>
        <id>appSot:DEL</id>
        <baseId>system:secondary</baseId>
        <propertyReference>appSot:deliverySlipNo</propertyReference>
    </typeSecondaryDefinition>

    <typeSecondaryDefinition>
        <id>appSot:SUP</id>
        <baseId>system:secondary</baseId>
        <propertyReference>appSot:name</propertyReference>
        <propertyReference>appSot:address</propertyReference>
        <propertyReference>appSot:phone</propertyReference>
    </typeSecondaryDefinition>
...

Adding References to Secondary Object Types

Now, add three references to the secondary object types for your defined document object type ("document"). All three are "floating" references (static=false), since they should only be used if the content type is known and the properties are useful and necessary.

schema.xml (add reference)

...
    <typeDocumentDefinition>
        <id>appSot:document</id>
        <baseId>system:document</baseId>
        <contentStreamAllowed>allowed</contentStreamAllowed>
        <secondaryObjectTypeId static="false">appSot:INV</secondaryObjectTypeId>
        <secondaryObjectTypeId static="false">appSot:DEL</secondaryObjectTypeId>
        <secondaryObjectTypeId static="false">appSot:SUP</secondaryObjectTypeId>
    </typeDocumentDefinition>
...

Importing New Documents

First of all, import your documents as a simple instance of "document" including the values for the "date of receipt" using the "POST /api/dms/objects" endpoint.
>> Importing Documents via Core API

metadata.json (import)

{
	"objects": [{
		"properties": {
			"system:objectTypeId": {
				"value": "appSot:document"
			}
            "appSot:DateOfReceipt": {
                "value": "2020-10-07"
            }
		}
	}]
}

Adding Secondary Object Types

During the Lifecycle

If the content type is known, you update the schema for the object type's instance and add the necessary secondary object types (POST /api/dms/objects/{objectId} or PATCH /api/dms/objects/{objectId}). Use the keyword "add": for a single secondary object type, or "value:" with a comma separated list, e.g., ["INV","SUP"] for multiple ones. Note that by using the keyword "value":, the list of "floating" secondary object types transferred will replace all existing ones. This includes the related properties and metadata values. If you want to keep the existing "floating" secondary object types, you have to list them as well.

metadata.json (add single)

{
	"objects": [{
		"properties": {
			"system:secondaryObjecttypeIds": {
				"add": "INV"
			},
			"appSot:invoiceNo": {
				"value": "K0815-2020-1894834"
			}
		}
	}]
}

metadata.json (add multiple)

{
	"objects": [{
		"properties": {
			"system:secondaryObjecttypeIds": {
				"value": ["INV","SUP"]
			},
			"appSot:invoiceNo": {
				"value": "K0815-2020-1894834"
			},
			"appSot:name": {
				"value": "Supplier Smith"
			},
			"appSot:address": {
				"value": "7 Main Street, London"
			},
			"appSot:phone": {
				"value": "004420834029390"
			}
		}
	}]
}

Right at the Start of the Lifecycle (Import)

If you already know what content type you are going to import (e.g., an invoice), you can add one or more "floating" secondary object types right away. Use the keyword "value": with a comma separated list, e.g., ["INV","SUP"] ("POST /api/dms/objects" endpoint).

metadata.json (import multiple)

{
	"objects": [{
		"properties": {
			"system:objectTypeId": {
				"value": "appSot:document"
			}
            "system:secondaryObjectTypeIds": {
                "value": ["INV","SUP"]
            }
            "appSot:DateOfReceipt": {
                "value": "2020-10-07"
            }
		}
	}]
}

Removing Secondary Object Types

When a "floating" secondary object type is not needed any longer, you remove it from the object type's instance using the update endpoints (POST /api/dms/objects/{objectId} or PATCH /api/dms/objects/{objectId}). All related properties and metadata values will be removed as well.

metadata.json (remove)

{
	"objects": [{
		"properties": {
			"system:secondaryobjecttypeids": {
				"remove": "INV"
			}
		}
	}]
}

Searching for Objects

You search for objects that use secondary object types by explicitly specifying them in the FROM clause: select * from appSot:INV. The search result delivers the entire object and not only the properties of the specified secondary object type.

Summary

In this tutorial, we provided an example use case to give you a better understanding of how you can change the basic schema structure for individual instances of an object type at runtime. You understand the concept of floating secondary object types and based on this knowledge you are able to discuss and define your custom schema flows.

Read on

Managing the Schema

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

Schema - Defining Object Types

Define properties and reference them in object type definitions for the entire system, for individual tenants or for a specific app. Keep reading

DMS Endpoints

To update the instance of an object type with the property group of a floating secondary object type as well as specific values use one of the two endpoints for updating metadata. Keep reading

Browser not supported