DMS API for configuring d.3 repositories

Using the API functions

Below, you will learn how to use the programming interface of the DMS app to configure d.3 repositories for your own developments.

This API is a RESTful HTTP API with JSON representations. In particular, we use JSON Hypertext Application Language to create links between various resources in JSON format.

You can find information about getting started with the configuration of repositories at the route /dms. You can use the link relation repoconfig to access the list of configurable repositories. From there, you can find additional link relations for the various configuration options.

Determining the link for the repository configuration

Call the link for the repository configuration using an HTTP GET request.

Request

GET /dms
Accept: application/hal+json

Among other things, the response to the HTTP GET request contains the link relation for the configuration.

Response

{
  "_links": {
    "repoconfig": {
      "href": "<URI to repository list>"
    },
    ...
  }
}

Basic information about general status codes

While you are using the functions of this API, the app may output the following general status codes. More specific status codes are explained in the corresponding sections.

Status code

• 401: The user has not been authenticated.
• 403: The origin header is missing or the user does not have administrator rights. Only tenant administrators are authorized to apply configurations to the repository.
• 406: The requested resource is not available in the desired form. Please change the accept header.
• 500: Server error.

Basic information on supported languages

You can define specific property values in multiple languages according to ISO 639-1 and RFC-3066 within this API. The following languages are supported:

The language ID de-DE is also supported for backwards compatibility. When using writing HTTP requests (POST, PUT), you can use the language ID de-DE synonymously to the language ID de (for categories and properties) or x-original (for datasets). We recommend using the IDs de or x-original.

Basic information about sequential and parallel requests to this API

Please use only sequential requests for this API. Parallel requests to this API can lead to errors and are therefore not supported.

Configuring resources

The API for configuring d.3 repositories contains the following resources. The sections below describe the resources and their configuration options in detail.

Repositories

Represents a list of repository resources.

Displaying all the administrable repositories

Use an HTTP GET request to display all the administrable repositories.

Request

GET <URI to repositories resource>
Accept: application/hal+json

In the response, you receive an array of repositories within the object _embedded.

Response

{
  "_links": { ... },
  "_embedded": {
    "repositories": [ ... ]
  }
}

Status code

• 200: The repositories were determined successfully.
• 404: The administrable repositories could not be determined.

Structure of a “repositories” resource

The repositories resource always contains the following elements.

Embedded (embedded resources)

Repository

Represents a d.3 repository. To configure a repository, you can follow its corresponding link relations in the repository resources. For the configuration, you require administration authorizations in the respective repositories.

Below you can learn how to configure a d.3 repository.

Displaying an administrable repository

Use an HTTP GET request to display an administrable repository.

Request

GET <URI to repository resource>
Accept: application/hal+json

After opening the URI, you receive the link relations that reference the specific functions of the repository in the response to the HTTP GET request. You can now use these functions to configure the repository.

Response

{
  "id": "723199c4-4f0c-5993-8b04-d5f72cd37b3d",
  "name": "repository name",
  "_links": {
    "categories": {
      "href": "<URI to category list>"
    },
    "properties": {
      "href": "<URI to property list>"
    },
    "datasets": {
      "href": "<URI to dataset list>"
    },
    "permissions": {
      "href": "<URI to permission list>"
    },
    "structures": {
      "href": "<URI to struturerule list>"
    },
    "events": {
      "href": "<URI to event list>"
    },
    "packages": {
      "href": "<URI to packages resouce>"
    }
  }
}

Status code

• 200: The repository was determined successfully.
• 404: The repository with the specified ID could not be determined.

Structure of a “repository” resource

The repository resource always contains the following elements.

Links

Categories

Represents a list of category resources.

Retrieving a list of all the categories

Use an HTTP GET request to retrieve a list of all the categories.

Request

GET <URI to categories resource>
Accept: application/hal+json

In the response, you receive an array of categories within the object _embedded.

Response

{
  "_links": { ... },
  "_embedded": {
    "categories": [ ... ]
   }
}

Status code

• 200: The categories were determined successfully.

Structure of a “categories” resource

The categories resource always contains the following elements.

Embedded (embedded resources)

Creating a category

You need at least one available property to create a new category. If no property has been configured yet for your repository, this section will help you: Creating a property.

If the required properties have already been configured for your repository, you can create a category using the POST method:

While executing the POST method as the request body, transfer a category resource.

Request

POST <URI to categories resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
 "name": {
    "en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS",
    "basedOn": "LAST_EDITING"
  },
  "propertyRefs": [
    {
      "propertyId": "1",
      "required": false,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    }
  ],
  "titleRefs": [
    {
      "propertyId": "1"
    }
  ],
  "protection": {
    "preventDeletion": true,
    "preventDeletionChangeReason": ""
  }
}

You cannot specify an ID when you create a category. This is generated automatically by the system. After a category has been created, you can find the URI of the new category in the location header.

Response

location: <URI of the created category resource>

Status code

• 201: The category was created successfully.
• 400: Invalid data was transferred or the category already exists in the repository.

Category

Represents a category within a d.3 repository. A category comprises the items dossier type and document type. You can equip any category with different properties to describe this type in more detail. For example, you can store your documents under different document types and conduct a targeted search in a specific dossier or for a desired document type.

Below you can learn how to configure a category.

Retrieving a category

If you want to display the configuration of an existing category, you can apply the GET method to the URI of the category resource.

Request

GET <URI to category resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified category:

Response

{
  "id": "BILL",
  "name": {
    "en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS",
    "basedOn": "LAST_EDITING"
  },
  "propertyRefs": [{
    "propertyId": "1",
    "required": false,
    "showInFacets": true,
    "showInSearch": true,
    "showInImport": true,
    "showInResult": true
  },
  {
    "propertyId": "DOCUMENT_ID"
  },
  ...
  ],
  "titleRefs": [{
    "propertyId": "1",
    "delimiter": ""
  },
  {
    "propertyId": "DOCUMENT_ID",
    "delimiter": "-"
  }],
  "protection": {
    "preventDeletion": true,
    "preventDeletionChangeReason": ""
  },
  "_links": { ... },
  "_embedded": { ... }
}

Status code

• 200: The category was determined successfully.
• 404: The category with the specified ID could not be determined.

Structure of a “category” resource

The category resource always contains the following elements.

PropertyRef

A PropertyRef object describes the reference of this category to its assigned property. The propertyId is used to assign the property to the category.

The remaining parameters of the PropertyRef object describe the behavior of the assigned property within this exact category. For example, the property can be defined as a required field for this category using the required parameter.

TitleRef

A TitleRef object describes a property that is used as a title field in this category. The title of a document is automatically formed using the TitleRef configuration for its category and is displayed in the search match list, for example.

Retention

A retention object describes the length of time that documents in this category are to be stored in the d.3 repository.

Protection

A Protection object controls the extended protection of items of this type.

Links

Embedded (embedded resources)

Changing a category

If you want to make changes to an existing category, you can apply the PUT method to the URI of the category resource.

Request

PUT <URI to category resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
 "name": {
    "en": "Bill"
  },
  "type": "DOCUMENT_TYPE",
  "readOnly": false,
  "retention": {
    "period": 50,
    "unit": "YEARS"
  },
  "propertyRefs": [
    {
      "propertyId": "1",
      "required": false,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    },
    {
      "propertyId": "2",
      "required": true,
      "showInFacets": true,
      "showInSearch": true,
      "showInImport": true,
      "showInResult": true
    }
  ],
  "titleRefs": [
    {
      "propertyId": "1"
    }
  ]
}

Response

location: <URI of the changed category resource>

Status code

• 200: The category was changed successfully.
• 400: Invalid data was transferred.
• 404: The category with the specified ID could not be determined.

Deleting a category

You can delete a category that is no longer required from the repository by applying the DELETE method to the URI of the category resource. A category can only be deleted if it is no longer assigned to any permission and if it has not been predefined by the system (readOnly=true).

Request

DELETE <URI to category resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The category was deleted successfully.
• 404: The category with the specified ID could not be determined.

Properties

Represents a list of property resources.

Retrieving a list of all the properties

Use an HTTP GET request to retrieve a list of all the properties.

Request

GET <URI to properties resource>
Accept: application/hal+json

In the response, you receive an array of properties in the section _embedded.

Response

{
  "_links": { ... },
  "_embedded": {
    "properties": [ ... ]
   }
}

Status code

• 200: The properties were determined successfully.

Structure of a “properties” resource

The properties resource always contains the following elements.

Embedded (embedded resources)

Creating a property

Use the POST method to create a property.

Optionally, you can link a property with a dataset to enable the DMS user to choose from a predefined set of values. In case you want to create a property with a dataset not already contained in the repository, you need to create it before the property. This chapter provides further assistance in doing so: Creating a dataset.

While executing the POST method as the request body, transfer a property resource.

Request

POST <URI to properties resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": {
    "en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": false,
  "isMultiValue": false,
  "validationRegEx": "(?<=\s)\d{13}(?=\s)",
  "dataSetId": "1"
}

You cannot specify an ID when you create a property. This is generated automatically by the system. After a property has been created, you can find the URI of the new property in the location header.

Response

location: <URI of the created property resource>

Status code

• 201: The property was created successfully.
• 400: Invalid data was transferred or the property already exists in the repository.

Property

Represents a property within a d.3 repository. A property is a feature providing a compact description of a document or a dossier. You can assign the available properties when you create or change a category.

Below, you can learn how to configure a property.

Viewing the configuration of a property

If you want to display the configuration of an existing property, you can apply the GET method to the URI of the property resource.

Request

GET <URI to property resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified property:

Response

{
  "id": "1",
  "name": {
    "en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": false,
  "readOnly": false,
  "isMultiValue": false,
  "validationRegEx": "",
  "dataSetId": "1",
  "_links": { ... }
}

Status code

• 200: The property was determined successfully.
• 404: The property with the specified ID could not be determined.

Structure of a property resource

The property resource always contains the following elements.

Links

Embedded (embedded resources)

Using predefined properties

Some properties already exist in the repository without having been created by you. These properties cannot be assigned to any category since they are automatically a part of each category. However, you can use these properties to assign permissions and to assign the title of a category. You cannot modify this type of property. This means you cannot change or delete its values. All these properties are marked with the property isSystemProperty=true.

Changing a property

If you want to make changes to an existing property, you can apply the PUT method to the URI of the property resource.

Request

PUT <URI to property resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": {
    "en": "Supplier"
  },
  "dataType": "STRING",
  "isSystemProperty": "false",
  "isMultiValue": false,
  "validationRegEx": "",
  "dataSetId": "2"
}

Response

location: <URI of the changed property resource>

Status code

• 200: The property was changed successfully.
• 400: Invalid data was transferred.
• 404: The property with the specified ID could not be determined.

Deleting a property

You can delete a property that is no longer required from the repository by applying the DELETE method to the URI of the property resource. A property can only be deleted if it is no longer assigned to any category and if it has not been predefined by the system (readOnly=true).

Request

DELETE <URI to property resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The property was deleted successfully.
• 400: The property is still assigned to at least one category or has been predefined by the system.
• 404: The property with the specified ID could not be determined.

Datasets

Represents a list of dataset resources.

Retrieving a list of all the datasets

Use an HTTP GET request to retrieve a list of all the datasets.

Request

GET <URI to datasets resource>
Accept: application/hal+json

In the response, you receive an array of datasets within the object _embedded.

Response

{
  "_links": { ... },
  "_embedded": {
    "datasets": [ ... ]
   }
}

Status code

• 200: The datasets were determined successfully.

Structure of a “datasets” resource

The datasets resource always contains the following elements.

Embedded (embedded resources)

Creating a dataset

You can use the POST method to create a dataset.

While executing the POST method as the request body, transfer a dataset resource.

Request

POST <URI to datasets resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "Supplier names",
  "dataType": "STRING",
  "values": [
    {
      "x-original": "SUPPLIER_1",
      "en": "Supplier 1"
    },
    {
      "x-original": "SUPPLIER_2",
      "en": "Supplier 2"
    }
  ]
}

You cannot specify an ID when you create a dataset. This is generated automatically by the system. After a dataset has been successfully created, you can find the URI of the new data in the location header.

Response

location: <URI of the created dataset resource>

Status code

• 201: The dataset was created successfully.
• 400: Invalid data was transferred or the dataset already exists in the repository.

Dataset

Represents a dataset within a d.3 repository. A dataset is an inventory of values a user can choose as a property for a category. This applies both for the search and for the storage of new documents.

Below, you can learn how to configure a dataset.

Viewing the configuration of a dataset

If you want to display the configuration of an existing dataset, you can apply the GET method to the URI of the dataset resource.

Request

GET <URI to dataset resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified dataset:

Response

{
  "id": "1",
  "name": "Supplier names",
  "dataType": "STRING",
  "readOnly": false,
  "values": [
      {
        "x-original": "SUPPLIER_1",
        "en": "Supplier 1"
      },
      {
        "x-original": "SUPPLIER_2",
        "en": "Supplier 2"
      }
    ],
  "_links": { ... }
}

Status code

• 200: The dataset was determined successfully.
• 404: The dataset with the specified ID could not be determined.

Structure of a “dataset” resource

The dataset resource always contains the following elements.

Value

A value object describes a value that is available for the DMS user to select in this dataset. A value object is structured in different ways depending on the data type of the dataset:

Links

Using predefined datasets

Some datasets already exist in the repository without having been created by you. These datasets can contain dynamic values and are composed of the data inventory in the repository. You can assign these datasets to a property using the following IDs. You cannot modify this type of dataset. This means you cannot add any values to it or change its name and data type. All these datasets are marked with the property readOnly=true.

Changing a dataset

If you want to make changes to an existing dataset, you can apply the PUT method to the URI of the dataset resource.

Request

PUT <URI to dataset resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "Supplier names",
  "dataType": "STRING",
  "values": [
    {
      "x-original": "SUPPLIER_1",
      "en": "Supplier 1"
    },
    {
      "x-original": "SUPPLIER_2",
      "en": "Supplier 2"
    },
    {
      "x-original": "SUPPLIER_3",
      "en": "Supplier 3"
    }
  ]
}

Response

location: <URI of the changed dataset resource>

Status code

• 200: The dataset was changed successfully.
• 400: Invalid data was transferred.
• 404: The dataset with the specified ID could not be determined.

Deleting a dataset

You can delete a dataset that is no longer required from the repository by applying the DELETE method to the URI of the dataset resource. A dataset can only be deleted if it is no longer assigned to any property and if it has not been predefined by the system (readOnly=true).

Request

DELETE <URI to dataset resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The dataset was deleted successfully.
• 400: The dataset is still assigned to at least one property or has been predefined by the system.
• 404: The dataset with the specified ID could not be determined.

Permissions

Represents a list of permission resources.

Retrieving a list of all the permissions

Use an HTTP GET request to retrieve a list of all the permissions.

Request

GET <URI to permissions resource>
Accept: application/hal+json

In the response, you receive an array of permissions within the object _embedded.

Response

{
  "_links": { ... },
  "_embedded": {
    "permissions": [ ... ]
   }
}

Status code

• 200: The permissions were determined successfully.

Structure of a “permissions” resource

The permissions resource always contains the following elements.

Links

Embedded (embedded resources)

Creating a permission

Creating a permission using the POST method.

While executing the POST method as the request body, transfer a permission resource.

Request

POST <URI to permissions resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    }
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "type": "GROUP",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    }
  ]
}

You cannot specify an ID when you create a permission. This is generated automatically by the system. After the permission has been successfully created, you can find the URI of the new permission in the location header.

Response

location: <URI of the created permission resource>

Status code

• 201: The permission was created successfully.
• 400: Invalid data was transferred or a permission with the name already exists.

Assignments

The assignments resource provides a view of your system permissions from a different perspective. It focuses on the groups and applications. The resource shows which permissions with which rights have been assigned to each group or application.

Viewing all mappings of permissions to the groups and applications

If you want to display all the mappings of existing permissions to groups and applications, you can apply the GET method to the URI of the assignments resource of the permissions resource.

Request

GET <URI to permissions assignments resource>
Accept: application/hal+json

In the response to the HTTP GET request, you then receive the requested information:

Response

{
  "subjects": [
    {
      "id": "1f99afff-9335-4525-8d76-5fd882acaa00",
      "type": "GROUP"
      "assignments": [
        {
          "permissionId": "d7bfa38f-e44d-44dc-be87-b1ae488e7ba1",
          "read": "ALLOWED",
          "write": "INHERITED",
          "delete": "INHERITED"
        }
      ]
    }
  ],
  "_links": { ... }
}

Status code

• 200: The mappings were determined successfully.

Structure of an "assignments" resource

The permission resource always contains the following elements.

Notes on the "type" property

The property can receive one of the following values:

Assignment

An assignment object describes a group or application that contains permissions and their corresponding rights.

Notes on the properties "read", "write" and "delete"

Each of the three properties can take one of these values:

If the property read contains the value DENIED, the properties write and delete also need to contain the value DENIED. If the properties write or delete contain the value ALLOWED, the property read also needs to contain the value ALLOWED.

Links

Mapping of permissions to groups and applications

If you want to quickly map or remove a large number of existing permissions to existing groups and applications, you can apply the PATCH method to the URI of the assignments resource of the permissions resource.

Request

PATCH <URI to permissions assignments resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "subjects": [
    {
      "id": "1f99afff-9335-4525-8d76-5fd882acaa00",
      "type": "GROUP",
      "assignments": [
        {
          "permissionId": "d7bfa38f-e44d-44dc-be87-b1ae488e7ba1",
          "read": "ALLOWED",
          "write": "INHERITED",
          "delete": "INHERITED"
        },
        {
          "permissionId": "56269a85-8377-4197-bae2-4855781b5d99",
          "read": "ALLOWED",
          "write": "INHERITED",
          "delete": "DENIED"
        }
      ]
    }
  ],
  "_links": { ... }
}

Response

Status code

• 200: The mappings was successfully updated.
• 400: Invalid data was transferred.

Permission

Represents a permission within a d.3 repository. Within a d.3 repository, you can assign different permissions for the categories you have created. You can use this to limit the visibility and access options of different user groups and applications. The configuration of permissions is always done based on a repository.

Below, you can learn how to configure a permission.

Viewing the configuration of a permission

If you want to display the configuration of an existing permission, you can apply the GET method to the URI of the permission resource.

Request

GET <URI to permission resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified permission:

Response

{
  "id": "1",
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    },
    ...
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "type": "GROUP",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    },
    ...
  ],
  "_links": { ... }
}

Status code

• 200: The permission was determined successfully.
• 404: No permission with the entered ID could be determined.

Structure of a “permission” resource

The permission resource always contains the following elements.

Restriction

The restriction object describes a filter that defines the documents and dossiers to which this permission applies.

PermissionAssignment

A PermissionAssignment object describes a group or application that contains permissions and their corresponding rights.

Notes on the "type" property

The property can receive one of the following values:

Notes on the properties "read", "write" and "delete"

Each of the three properties can take one of these values:

If the property read contains the value DENIED, the properties write and delete also need to contain the value DENIED. If the properties write or delete contain the value ALLOWED, the property read also needs to contain the value ALLOWED.

Links

Changing a permission

If you want to make changes to an existing permission, you can apply the PUT method to the URI of the permission resource.

Request

PUT <URI to permission resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "name": "All bills",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    },
    {
      "key": "9",
      "value": "|-1000"
    }
  ],
  "assignments": [
    {
      "subject": "89e6cbd9-af7f-46c8-9c86-2c12602476fe",
      "type": "GROUP",
      "read": "INHERITED",
      "write": "DENIED",
      "delete": "DENIED"
    }
  ]
}

Response

location: <URI of the changed permission resource>

Status code

• 200: The permission was updated successfully.
• 400: Invalid data was transferred or another permission with the name already exists.

Deleting a permission

You can delete a permission that is no longer required from the repository by applying the DELETE method to the URI of the permission resource.

Request

DELETE <URI to permission resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The permission was deleted successfully.
• 404: No permission with the specified ID could be determined.

Restriction Sets

Restriction sets allow you to dynamically grant a user authorization for documents. You can define values for each group within a restriction set. You can define a restriction set via a placeholder for a Permission in the Restriction. The authorization is dynamic in that a list of values is calculated based on the user's group membership. The user receives the configured authorization if the value of the property containing the placeholder is included in this list.

Retrieving a list of all the restriction sets

Use an HTTP GET request to retrieve a list of all restriction sets.

Request

GET <URI to restrictionSets resource>
Accept: application/hal+json

In the response, you receive an array of restriction sets.

Response

{
  "restrictionsSets": [ ... ]   
}

Status code

• 200: The restriction sets were determined successfully.

Structure of a “restriction sets” resource

The restriction sets resource always contains the following elements:

Creating a restriction set

To create a restriction set, you need at least one name. This name must be unique and not empty.

While executing the POST method as the request body, transfer a restriction set resource.

Request

POST <URI to restrictionSets resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
 "caption": "My New Set"
}

You cannot enter an ID when creating a restriction set. This ID is created automatically by the system. After a restriction set has been created, you will find the URI of the new restriction set in the Location header.

Response

location: <URI of the created restrictionSet resource>

Status code

• 201: The restriction set was created successfully.
• 400: Invalid data was transmitted, e.g. an empty caption.
• 409: Another restriction set with the caption already exists.

Restriction Set

Represents a restriction set within a d.3 repository. A restriction set allows you to dynamically grant a user authorization for a document. Authorization is granted by calculating a list of values. This list results from the user's group membership. If a restriction set is assigned to a property within a permission, the user receives the configured authorization if the value is contained in the calculated list.

Below, you learn how to configure a restriction set.

Viewing the configuration of a restriction set

If you want to display the configuration of an existing restriction set, you can apply the GET method to the URI of the restrictionSet resource.

Request

GET <URI to restrictionSet resource>/<id>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified restriction set:

Response

{
  "id": "7e74ff4b-8fb0-4748-a516-22414c940dce",
  "caption": "My New Set"
}

Status code

• 200: The restriction set was determined successfully.
• 404: No restriction set with the entered ID could be determined.

Structure of a "restrictionSet" resource

The restrictionSet resource always contains the following elements:

Changing a restriction set

If you want to make changes to an existing restriction set, you can apply the PUT method to the URI of the restriction set resource.

Request

PUT <URI to restrictionSets resource>/<id>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "caption": "Changed Set"
}

Status code

• 201: The restriction set was updated successfully.
• 400: Invalid data was transmitted, e.g. an empty caption.
• 409: Another restriction set with the caption already exists.

Deleting a restriction set

You can delete a restriction set that is no longer required from the repository by applying the DELETE method to the URI of the restriction set resource.

A restriction set can only be deleted if it is no longer assigned to any permission.

Request

DELETE <URI to restrictionSets resource>/<id>
Origin: <Base-URI of the tenant>

Status code

• 204: The restriction set was deleted successfully.
• 404: No restriction set with the specified ID could be determined.
• 409: The restriction set is assigned to a permission. The Ids of the affected permission can be found in the response.

Response 409

{
   "additionalInfo": {
      "permissions": [
         "bd0f7ca7-7ccf-4b89-aa41-052c1867ec9e",
         "52ad0156-c4f7-4cbf-a25c-eaad85a05cfd",
         ...
      ]
   },
   "message": "Restriction set is still in use."
}

Assign values to Restriction sets

The values of a restriction set are calculated dynamically based on the user's group membership. You can define individual values for each group. You can also define values that apply to all groups.

Retrieving a list of all restriction set assignments

Use an HTTP GET request to retrieve a list of all restriction set assignments.

Request

GET <URI to restrictionSet resource>/assignments/
Accept: application/hal+json

In the response, you will receive an array of restriction set assignments in the assignments section.

Response

{
  "assignments": [
      { "type": "GROUP",    
        "id": "f5b1ce00-7c24-40e7-8ae8-7efa4e44d302"
      }
   ]   
}

Status code

• 200: The restriction set assignments were determined successfully.

Structure of a "assignments" resource

The assignments resource always contains the following elements:

Creating a restriction set assignment

Creating a restriction set assignment using the POST method. While executing the POST method as the request body, transfer a assignment resource.

Request

POST <URI to restrictionSet resource>/assignments/
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "type": "GROUP",
  "id": "df2d4c8c-90de-47c8-a5f6-ba2324966407"
  "values": [
        "Value A",
        "Value B",
        "Value C",
        "Value D"
 ]
}

The type descript the kind of assignment. If an assignment refers to a specific group, enter "GROUP" as type. To specify the group, enter the id field with the group ID of the identity provider app. If you want to specify values for all groups, enter "NO_ASSIGNMENT" as type.

ATTENTION: type with the value "NO_ASSIGNMENT" also contains groups that were created after the configuration.

After a assignment has been created, you will find the URI of the new assignment in the Location header.

Response

location: <URI of the created assignment resource>

Statuscode

• 201: The assignment was created successfully.
• 400: Invalid data was transmitted.
• 409: An assignment with this group already exists.
• 422: An assignment contains invalid values.

Structure of a restriction set assignment

The assignment resource always contains the following elements:

Changing a restriction set assignment

If you want to make changes to an existing restriction set assignment, you can apply the PUT method to the URI of the restriction set assignment resource.

Request

PUT <URI to assignment resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "type": "GROUP",
  "id": "df2d4c8c-90de-47c8-a5f6-ba2324966407"
  "values": [
        "Value A",
        "Value B",
        "Value C",
        "Value D"
 ]
}

Response

location: <URI of the changed assignment resource>

Statuscode

• 200: The assignment was updated successfully.
• 400: Invalid data was transmitted.
• 422: The assignment contains invalid values.

Delete a restriction set assignment

You can delete a restriction set assignment that is no longer required from the repository by applying the DELETE method to the URI of the assignments resource.

Request

DELETE <URI to assignment resource>
Origin: <Base-URI of the tenant>

Statuscode

• 204: The assignment was deleted successfully.
• 404: No assignment set with the specified ID could be determined.

Defining values for an assignment

You can define values for each assignment. These values serve as a filter for the assigned property of a given permission. If the value of the property is contained in this list of values, the user receives the configured authorization.

ATTENTION: If the list of filter values is empty, the user receives the corresponding authorization.

Load all values of a restriction set assignment

Use an HTTP GET request to retrieve a list of all values of a restriction set assignment.

Request

GET <URI to assignment resource>/values/
Accept: application/hal+json

In the response, you will receive an array of string values.

Response

{
  "values": ["Val1","Val2"]
}

Response

location: <URI of the created assignment resource>

Statuscode

• 200: The values of a restriction set assignment were determined successfully.

Changing the values of a restriction set assignment

Apply the PUT or PATCH method to the URI of the Values resource if you want to replace or add values of an existing assignment. You will always find the Values resource under the Assignment resource.
PUT replaces the list of values with the trasmitted list.
PATCH appends the transmitted list to the existing values.

Request

PUT/PATCH <URI to assignment-resource/values>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "values": [
    "Value A",
    "Value B",
    "Value C",
    "Value D",
 ]
}

Response

location: <URI of the changed values resource>

Statuscode

• 200: The values was updated successfully.
• 400: Invalid data was transmitted.
• 422: The array contains invalid values.

Structures

Represents a list of structurerule resources.

Retrieving a list of all the structure rules

Use an HTTP GET request to retrieve a list of all the structure rules.

Request

GET <URI to structures resource>
Accept: application/hal+json

You will receive an array of individual structure rules within the object _embedded in the response.

Response

{
  "_links": { ... },
  "_embedded": {
    "structures": [ ... ]
  }
}

Status code

• 200: The structure rules were determined successfully.

Structure of a “structures” resource

The structures resource always contains the following elements.

Embedded (embedded resources)

Creating a structure rule

Creating a structure rule using the POST method.

You can create a structure rule with the following function. While executing the POST method as the request body, transfer a structurerule resource.

Request

POST <URI to structures resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "",
      "parentId": "1",
      "childId": "2"
    }
  ],
  "inheritance": [
    {
      "propertyId": "3"
    }
  ]
}

You cannot specify an ID when you create a structure rule. This is generated automatically by the system. After the structure rule has been successfully created, you can find the URI of the new structure rule in the location header.

Response

location: <URI of the created structurerule resource>

Status code

• 201: The structure rule was created successfully.
• 400: Invalid data was transferred or a structure rule with the specified parent and child already exists.

Structurerule

Represents a structure rule within a d.3 repository. Within a d.3 repository, you can use structure rules to provide a pre-configured dossier structure for your users. The structure rules are used to automatically link elements that your users save in dossiers or with documents. You can choose which properties are used to identify the parent element. You can also define properties that the element automatically applies for the child document. You can use the configuration of structures to define which categories are linked to each other under which conditions.

Below you can learn how to configure a structure rule.

Viewing the configuration of a structure rule

If you want to display the configuration of an existing structure rule, you can apply the GET method to the URI of the structurerule resource.

Request

GET <URI to structurerule resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified structure rule:

Response

{
  "id": "1",
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "",
      "parentId": "1",
      "childId": "2"
    }
  ],
  "inheritance": [
    {
      "propertyId": "3"
    }
  ],
  "_links": { ... }
}

Status code

• 200: The structure rule was determined successfully.
• 404: No structure rule with the entered ID could be determined.

Structure of a “structurerule” resource

The structurerule resource always contains the following elements.

Recognition

A Recognition object describes a property or combination of properties that is used to link the parent to child. It is not necessary for this property to exist in both the parent and child categories. Different properties can be combined with each other. If the value of these properties is identical in both objects, a corresponding structure is created in the system.

Inheritance

An inheritance object describes a property that is inherited during a link. If a link is made using a recognition property, the values of the properties specified under Inheritance are inherited from the parent object to the child object.

Links

Changing a structure rule

If you want to make changes to an existing structure rule, you can apply the PUT method to the URI of the structurerule resource.

Request

PUT <URI to structurerule resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "parent": "CUST",
  "child": "BILL",
  "createSiblingDossiers": true,
  "recognition": [
    {
      "propertyId": "",
      "parentId": "1",
      "childId": "2"
    }
  ],
  "inheritance": [
    {
      "propertyId": "2"
    }
  ]
}

Response

location: <URI of the changed structurerule resource>

Status code

• 201: The structure rule was updated successfully.
• 400: Invalid data was transferred.

Deleting a structure rule

You can delete a structure rule that is no longer required from the repository by applying the DELETE method to the URI of the structurerule resource.

Request

DELETE <URI to structurerule resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The structure rule was deleted successfully.
• 404: No structure rule with the specified ID could be determined.

Events

Represents a list of event resources.

Retrieving a list of all the events

Use an HTTP GET request to retrieve a list of all the events.

Request

GET <URI to events resource>
Accept: application/hal+json

In the response, you receive a list of all the available events in the object _links and the individual events in the object _embedded.

Response

{
  "_links": {
    "presearch": { ... },
    "postsearch": { ... },
  },
  "_embedded": {
    "presearch": { ... },
    "postsearch": { ... },
    ...
  }
}

Status code

• 200: The events were determined successfully.

Structure of an "events" resource

The events resource always contains the following elements.

Embedded (embedded resources)

Event

Represents a d.3 repository event. Events run during specific processes. All the specified webhooks in an event are then activated in the specified order. You find details on the individual events, such as execution times, in the webhook documentation.

Viewing the configuration of an event

If you want to display the configuration of an event, you can apply the GET method to the URI of the event resource.

Request

GET <URI to event resource>/<Eventname>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified event:

Response

{
  "order": [
    "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
    "1D7341B4-547C-4FFD-A309-68B871959CD8",
    "E5FE04F2-6432-469F-9191-8C1DCCEE3752"
  ],
  "_links": { ... },
  "_embedded": {
    "webhooks": [ ... ]
  }
}

Status code

• 200: The event was determined successfully.
• 404: The specified event does not exist.

Structure of an "Event" resource

The event resource always contains the following elements.

Links

Embedded (embedded resources)

Creating a webhook

If you want to set up a webhook for an event, you can use the POST method. While executing the POST method as the request body, transfer a webhook resource.

Request

POST <URI to event resource>/<Eventname>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "uri": "https://my-company.com/webhooks",
  "description": "This is a description of my webhook.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
}

You cannot specify an ID when you create a webhook. The ID is generated automatically by the system. After a webhook has been created, you can find the URI of the new webhook in the location header.

Response

location: <URI of the created webhook resource>

Status code

• 201: The webhook was created successfully.
• 400: Invalid data was transferred.

Changing the calling sequence within an event

If you want to make changes to an event, you can apply the PUT method to the URI of the event resource. However, you can only change the order of the webhooks. To make changes to a webhook, you must use the webhook resource.

Request

PUT <URI to event resource>/<Eventname>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "order": [
    "E5FE04F2-6432-469F-9191-8C1DCCEE3752",
    "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
    "1D7341B4-547C-4FFD-A309-68B871959CD8"
  ]
}

Status code

• 201: The event was updated successfully.
• 400: Invalid data was transferred.

Webhook

Represents a user-defined function that is defined for an event within a d.3 repository. With the aid of a webhook, you can use a URI to define a function that can control the standard DMS behavior or other subsequent actions.

Below, you can learn how to configure a webhook.

Viewing the configuration of a webhook

If you want to display the configuration of an existing webhook, you can apply the GET method to the URI of the webhook resource.

Request

GET <URI to webhook resource>
Accept: application/hal+json

In the response to the HTTP GET request, you receive the detailed information about the specified webhook:

Response

{
  "id": "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
  "uri": "https://my-company.com/webhooks",
  "description": "Webhook for the validation of invoices.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
  "_links": { ... }
}

Status code

• 200: The webhook was determined successfully.
• 404: No webhook with the entered ID could be determined.

Structure of a "webhook" resource

The webhook resource always contains the following elements.

Restriction

The restriction object describes a filter that defines the documents and dossiers for which this webhook is to be executed.

Links

Changing a webhook

If you want to make changes to an existing webhook, you can apply the PUT method to the URI of the webhook resource.

Request

PUT <URI to webhook resource>
Content-Type: application/hal+json
Origin: <Base-URI of the tenant>

{
  "uri": "https://my-company.com/webhooks",
  "description": "Webhook for the validation of invoices.",
  "enabled": true,
  "handleResponse": "STATUS_AND_BODY",
  "timeout": 300,
  "apiKey": "key",
  "restrictions": [
    {
      "key": "CATEGORY",
      "value": "BILL"
    }
  ]
}

Response

location: <URI of the changed webhook resource>

Status code

• 201: The webhook was updated successfully.
• 400: Invalid data was transferred.

Deleting a webhook

You can delete a webhook that is no longer required from the repository by applying the DELETE method to the URI of the webhook resource.

Request

DELETE <URI to webhook resource>
Origin: <Base-URI of the tenant>

Status code

• 204: The webhook was deleted successfully.
• 404: No webhook with the specified ID could be determined.

Packages

You can use packages to enhance your d.3 repository by adding predefined repository configurations. You may have created these configurations yourself, but they can also have been deployed for you. A package can contain metadata (categories, properties, datasets), structures, authorizations, and webhooks.

Installing a package

If you would like to install a package from a package file, you can apply the method POST to the URI in the link relation installation. You get this link relation by requesting the "packages" resource using the "repository" resource.

The package is installed asynchronously. This means that the POST only creates a job to install the package. The response to the HTTP POST request will contain a "Job" resource and a URI to query the current status of the job. If the job was completed successfully, the package was also installed completely and successfully.

Request

POST <URI to installation package resource>
Content-Type: application/octet-stream

<Package file stream>

Response

location: <URI of created job resource>

{
  "id": "05F3AC34-EF06-43CE-81B6-11CA7E5E4C9E",
  "status": "CREATED"
  "_links": { ... }
}

Status code

• 202: The job to install the package was created successfully.

Job

The Job object describes the status of an asynchronously running process.

Links