Released: Extension point

If you have an system that provides output data (e.g. an e-mail application or an ERP system), you must prepare the items of the d.3 repository source system for the creation of mapping. An item in a source system is referred to as a source. A source contains source properties and source categories. By defining a source, you give DMSApp the opportunity to connect the identifier for the source metadata to the identifiers for the d.3 repository metadata.

Preparing your app

To ensure that DMSApp can find source systems, your app must provide this user interface. To find apps that act as source systems, DMSApp uses the concept of an HTTP GET request for the root resource (systemBaseUri path with the app name) for the apps. All apps registered to the d.ecs http gateway will be requested. Make sure that the administrator did not actively exclude your app.

Providing the URL for the sources

The root resources for the apps are requested cyclically. The response of an app is then checked to determine whether a link relation with the name sources is included. This link relation serves as the signal that the app, acting as the source system, offers at least one source for DMSApp. DMSApp executes an HTTP GET request to the specified link and waits for a standardized JSON object with the HTTP status code 200 from the responding app.

Request

GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links" : {
        "sources" : {
            "href" : "/myapp/sources"
        }
    }
}

Providing sources

Once the URLs of the sources (sources) have been determined, DMSApp opens the sources of the apps using HTTP GET.

The example shows how to arrange the HTTP response of the sources link relation in order to identify sources for DMSApp.

Request

GET https://host/myapp/sources HTTP/1.1
Accept: application/hal+json

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
        "sources" : [{
                "id" : "/myapp/sources/mysource",
                "displayName" : "My Source",
                "categories": [{
                        "key": "mycategory1_ID", 
                        "displayName": "My category 1"
                }, 
                {
                        "key": "mycategory2_ID", 
                        "displayName": "My category 2"
                }],
                "properties" : [{
                        "key" : "myprop1_ID",
                        "displayName" : "My property 1"
                }, 
                {
                        "key" : "myprop2_ID",
                        "displayName" : "My property 2"
                },
                {
                        "key" : "myprop3_ID",
                        "displayName" : "My property 3"
                }]
        }]
}

Structure of a source

Structure of a source category

Structure of a source property

Released: JSON representation

The default source system is a predefined source system for each d.3 repository which is provided by default by the DMS app. When you provide an extension to DMS functions and do not want to define your own source system, you can use the properties and categories of the d.3 repository with the default source system.

The definition of a default source system and the associated mappings are set by the DMS app. You cannot change mappings for a default source system.

This chapter explains how to retrieve the source system definition for each d.3 repository.

To retrieve the source system definition of a d.3 repository, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determine the link relation for retrieving the source system definition of a d.3 repository

The JSON object for a d.3 repository contains the link relation source which you can use to retrieve the source system definition of the d.3 repository.

Response

{
        "_links": {
                "source": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Open the URL for the source system definition of a d.3 repository

You need to ensure that you can authenticate yourself for the d.3 repository. Only then you can retrieve the URL. The default source system contains all categories and properties of the d.3 repository regardless of the permissions of the user.

Retrieve the source system definition of the d.3 repository with the previously determined URL as follows:

Request

GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source HTTP/1.1
Accept: application/hal+json

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
        "id": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
        "displayName": "D3RepositoryName",
        "properties": [
                {
                        "key": "Key0",
                        "type": "String",
                        "displayName": "Sample property1"
                }
        ],
        "categories":[
                {
                        "key": "mycategory1_ID",
                        "displayName": "Sample category1"
                }
        ]
}

Structure of a source

Structure of a category

Structure of a property

Released: JSON representation, HTML page

When retrieving and viewing the results of a search operation, you can restrict the number of results displayed to you by specifying a particular source plus the associated source categories and source properties. You can also restrict your search results using a full-text search term. The Defining a source system chapter explains how to create a source for mapping.

To retrieve or display only the results of a search operation, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determining the link relation for retrieving or viewing the results of a search operation

You open the URL for a repository as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object for the repository contains the searchresultwithmapping link relation with placeholders for the values used to retrieve or view the results of the search operation.

Response

{
        _links: {
                searchresultwithmapping: {
                        href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm{?sourceid,sourceproperties,sourcecategories,sourcepropertysort,ascending,fulltext,page,pagesize}",
                        templated: true
                }
        },
        id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Specifying response control parameters

Use the following parameters to control the system response when retrieving or viewing the results of a search operation: You must encode the URL parameters (e.g. spaces in %20). The length of the encoded query parameter is limited to 2000 characters.

Opening the URL for the results of a search operation (JSON representation)

Once you have created a URL, you can then open the results of the search operation as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/json

The following JSON object will then be returned as a result:

Response

{
  "_links": {
    "next": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=2"
    },
    "self": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?...page=1"
    }
  },
  "page": 1,
  "items": [
    {
      "_links": {
        "self": { "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123" },
                "previewReadonly": { href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/preview?isReadonly=true" }
      },
      "id": "D000000123",
      "sourceProperties": [
        {
          "key": "myprop1_ID",
          "value": "Test E-Mail 1",
          "isMultiValue": false
        },
        {
          "key": "myprop2_ID",
          "value": "Max Mustermann",
          "isMultiValue": true
        },
        "..."
      ],
      "sourceCategories": [ "mycategory1_ID" ]
    },
    "..."
  ]
}

Structure of an item in the result list

Structure of a source property

Opening the URL for the results of a search operation (HTML page)

If you want to open the HTML view of the results, you must create the URL in the same way as described for retrieving the JSON representation. Enter the URL in the browser to view the HTML page. This HTML page contains the identifiers for the d.3 properties and d.3 categories.

Examples (not encoded):

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1_ID":["Test E-Mail 1"]}&sourcecategories=["mycategory1_ID"]&sourcepropertysort=myprop1_ID&ascending=true&fulltext=test&page=1&pagesize=50
Accept: text/html

Released: JSON representation, HTML page

You can retrieve the details of a DMS object as a JSON representation or view the detail view for a DMS object. When retrieving the details as a JSON representation, you can enter a specific source from a source system to define which source properties and source categories are determined. If you do not specify a source, only the ID and the link relation for the DMS object will be returned. The Defining a source system chapter explains how to create a source.

To retrieve or display the details of a DMS object, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determining the link relation for retrieving or viewing the details of a DMS object

You open the URL for a repository as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object for the repository contains the dmsobjectwithmapping link relation with placeholders for the values used to retrieve or view the details of the DMS object.

Response

{
        _links: {
                dmsobjectwithmapping: {
                        href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
                        templated: true
                }
        },
        id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Specifying response control parameters

Use the following parameters to control the system response when retrieving or viewing the details of a DMS object:

Opening the URL for the details of a DMS object (JSON representation)

Once you have created a URL, you can then retrieve the details of the DMS object as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123?sourceid=/myapp/sources/mysource
Accept: application/json

The following JSON object will then be returned as a result:

Response

{
  "_links": {
    "self": { 
                "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123"
     },
    "mainblobcontent": {
        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/main/c"
     },
     "editinoffice": {
           "href": "{ms-word:ofe|u|{+clientOrigin}/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/dav/D000000123%20(D000000123).DOCX}",
       "templated": true
     },
         "pdfblobcontent": {
       "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/current/b/p1/c"
     },
         "notes":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
         },
         "children":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/srm/?children_of=D000000123"
         },
         "versions":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/"
         }
  },
  "id": "D000000123",
  "sourceProperties": [
    {
      "key": "myprop1_ID",
      "value": "value of property 1"
    },
    {
      "key": "myprop2_ID",
      "value": "value of property 2 in row 2",
      "values": {                                                 
            "2": "value of property 2 in row 2",
        "4": "value of property 2 in row 4"
          }
    }
  ],
  "sourceCategories": ["mycategory2_ID"]
}

Structure of a source property

Opening the URL for the details of a DMS object (HTML page)

If you want to open the HTML view of the results, you must create the URL in the same way as described for querying the JSON representation. Enter the URL in the browser to view the HTML page. This HTML page contains the identifiers for the d.3 properties and d.3 categories.

Example:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123
Accept: text/html

When storing DMS objects, you can determine the storage metadata by specifying a particular source plus the associated source categories and source properties. The Defining a source system chapter explains how to create a source for mapping. In the Basic information about mapping chapter, you can find general information for helping you to create mappings.

In this topic, you will learn how to store data from a source using the DMSApp.

Please note the following limitations (only applies to the d.velop documents cloud offer):

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

{
        "_links": {
                "dmsobjectwithmapping": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{dmsobjectid}{?sourceid}",
                        "templated":true
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
        "filename": "myfile.txt",
        "sourceCategory": "mycategory1_ID",
        "sourceId": "/myapp/sources/mysource",
        "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
        "sourceProperties": {
                "properties": [{
                                "key": "myprop1_ID",
                                "values": ["Please verify the XYZ invoice"]
                        },
                        {
                                "key": "myprop2_ID",
                                "values": ["Name1@contoso.com","Name2@samplecompany.de"]
                        }
                ],
        }
}

HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D0001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc

{
        "reason": "You do not have the right to link the document with the dossier manually.
Nevertheless, the document was successfully saved. The document may be automatically linked on the server."
        "severity": 1
}

PUT /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
        "filename": "myfile.txt",
        "alterationText": "updated file",
        "sourceCategory": "mycategory1_ID",
        "sourceId": "/myapp/sources/mysource",
        "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
        "sourceProperties": {
                "properties": [{
                                "key": "myprop1_ID",
                                "values": ["Please verify the XYZ invoice"]
                        },
                        {
                                "key": "myprop2_ID",
                                "values": ["Name1@contoso.com","Name2@samplecompany.de"]
                        }
                ]
        }
}

HTTP/1.1 200 OK

GET /dms
Accept: application/hal+json

{
    "_links": {
        "new": {
            "href": "/dms/new/"
        }
    }
}

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

{
        "_links": {
                "new": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "displayValue": "Please verify the XYZ invoice",
        "filename": "myfile.txt",
        "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
        "sourceId": "/myapp/sources/mysourcel",
                "sourceCategory": "mycategory1",
                "sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
                "successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
    },
    {
        ...
    }]
}

HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

{
        "_links": {
                "new": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "dmsObjectId": "D123456789",
        "displayValue": "Please verify the XYZ invoice",
        "filename": "myfile.txt",
        "contentLocationUri": "/dms/blob/chunk/2016-May-24-14-20-26-393-1720.part",
        "sourceId": "/myapp/sources/mysourcel",
        "sourcePropertiesUri": "/myapp/sources/mysourcel/properties/myfile.haljson",
        "successCallbackUri": "/myapp/sources/mysourcel/success/myfile"
    },
    {
        ...
    }]
}

HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/new/a09dd457-5a21-4b90-8134-e562092b50ea

PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json  

{
   "sourceId": "/myapp/sources/mysource",
   "sourceProperties": {
      "properties": [
         {
            "key": "myprop1_ID",
            "values": [
               "Processing"
            ]
         },
         {
            "key": "myprop2_ID",
            "values": [
               "97273358-d124-497c-97ce-977f72b32a33"
            ]
         }
      ]
   }
}

HTTP/1.1 200 OK

PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
   "sourceId": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
   "sourceProperties": {
      "properties": [
         {
            "key": "property_state",
            "values": [
               "Processing"
            ]
         },
         {
            "key": " property_editor",
            "values": [
               "97273358-d124-497c-97ce-977f72b32a33"
            ]
         }
      ]
   }
}

HTTP/1.1 200 OK

PUT/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001/v/current
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json 

{
   "sourceId": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/source",
   "alterationText": "updated file",
   "sourceProperties": {
      "properties": [
         {
            "key": "property_state",
            "values": [
               "Release"
            ]
         }
      ]
   }
}

HTTP/1.1 200 OK

HASHALGORITHM:base64encode(hashfunction(PAYLOAD))

SHA512:xrCRnH/mKK6QVpksSpF+XcA1qWFdSX9usr0UBj6q0+ZQjvyGgv7IKCPKPz3jEYaKcpkJRhZkKfAbOPnzPZymEA==

private string CreateM5Hash(string filename)
{
   using (var md5 = MD5.Create())
   {
       using (var stream = File.OpenRead(filename))
       {
             var retVal = md5.ComputeHash(stream);
                         //Bytes in retVal für eine Datei mit dem Inhalt "Example": 
                 //45 155 209 108 21 173 26 160 179 111 217 119 62 110 20 172

             return $"MD5:{Convert.ToBase64String(retVal)}"; 
                 //Hash base64-encodiert:   
                         //MD5:ClJzBZf7T/oB/BF9nnHjqQ==        
                }
   }
}

private string CreateSHA256Hash(string filename)
{
    using (var sha256 = SHA256.Create())
    {
        using (var stream = File.OpenRead(filename))
        {
            var retVal = sha256.ComputeHash(stream);
                    //Bytes in retVal für eine Datei mit dem Inhalt "Example":  
                        //53 239 154 101 221 213 246 176 70 65 37 206 150 167 54 152 
                        //63 65 154 140 96 227 200 169 71 112 149 213 153 156 17 27

            return $"SHA256:{Convert.ToBase64String(retVal)}";
                    //Hash base64-encodiert: 
                        //SHA256:0Cn4fj2A+P2bG+Z8dCa0zB/0e0qdCoRhyCalnYxets0= 
        }
    }
}

private string CreateSHA512Hash(string filename)
{
    using (var sha512 = SHA512.Create())
    {
        using (var stream = File.OpenRead(filename))
        {
            var retVal = sha512.ComputeHash(stream);
                        //Bytes in retVal für eine Datei mit dem Inhalt "Example":   
                        //72 237 177 122 242 252 39 57 63 98 44 167 119 228 162 20 106 
                        //147 201 76 246 223 209 126 97 224 198 30 40 137 121 216 147 
                        //21 15 16 1 103 84 101 60 241 95 82 14 126 211 137 170 235 180 
                        //206 18 112 247 228 229 185 208 62 192 244 131 41

            return $"SHA512:{Convert.ToBase64String(retVal)}";
                //Hash base64-encodiert:  
                        //SHA512:xrCRnH/mKK6QVpksSpF+XcA1qWFdSX9usr0UBj6q0+ZQjvyGgv7IKCPKPz3jEYaKcpkJRhZkKfAbOPnzPZymEA== 
        }
    }
}

{
    "filename": "myfile.txt",
        "alterationText": "updated file",
    "sourceCategory": "mycategory1_ID",
    "sourceId": "/myapp/sources/mysource",  
    "contentUri": "/myapp/sources/mysource/myfile.txt",
    "sourcePropertiesUri": "/myapp/sources/mysource/myfile.haljson"    
}

{
    "displayValue": "Please verify the XYZ invoice",
    "filename": "myfile.txt",
        "alterationText": "updated file",
    "sourceCategory": "mycategory1_ID",
    "sourceId": "/myapp/sources/mysource",
    "parentId": "P123456789",
    "contentLocationUri": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43",
    "successCallbackUri": "/myapp/sources/mysource/myfile/success",
    "sourceProperties": {
        "properties": [{
                "key": "myprop1_ID",
                "values": ["Please verify the XYZ invoice"]
            },
            {
                "key": "myprop2_ID",
                "values": ["Name1@contoso.com","Name2@samplecompany.de"]
            }
        ],
                "userdata": [{
                    "key": "postProcessingOption",
                        "display": "My post processing options",
                "values": [
                        {"value":"1", "display": "Action 1", "default":"false"},
                        {"value":"2", "display": "Default action 2", "default":"true"},
                        {"value":"3", "display": "Action 3", "default":"false"}
                ]
                }
        ],
                "uniqueTag": "123456789",
                "checkHash": "MD5:ClJzBZf7T/oB/BF9nnHjqQ=="
    }
}

GET /myapp/sources/mysource/myfile.txt
Accept: application/octet-stream, */*
AuthSessionID: SampleAuthsessionId

HTTP/1.1 200 OK
Content-Length: 3495

<binary content>

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

{
        "_links": {
                "chunkedupload": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/
Origin: https://baseuri
Content-Type: application/octet-stream

<binary content>

HTTP/1.1 201 Created
Location: /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43

POST /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/blob/chunk/2018-01-01_temp_master_file_user1_44f7-95a6-58b8400ecf43
Content-Type: application/octet-stream

<binary content for chunk>

HTTP/1.1 200 OK

HTTP/1.1 400 BadRequest
  
{
    "reason": "10019: Missing value for a mandatory property.",
    "severity": 1,
    "errorCode": 10019
}

Success = 0,
Information = 1,
Warning = 2,
Error = 3

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-IgnoredNotModifiableDestinationProperty",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'myprop1_ID' was ignored because the mapped destination property with the ID '5' ('Name') is not modifiable. The current value for the property is 'Value of Name' and is not overwritten by the given value 'Value for myprop1'.",
            "hint": "Please adjust the d.3 configuration if you still want to write the values or contact your administrator.",
            "data": {
                "sourceItemId": "myprop1_ID",
                "sourceItemValue": "Value for myprop1",
                "destinationItemId": "5",
                "destinationItemValue": "Value of Name"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-NoMappingFoundForSourceCategory",
            "title": "Ignored source category",
            "detail": "The source category with the ID 'CAT1' was ignored because no mapping to a destination category was found.",
            "hint": "Please configure a mapping for the given source category or contact your administrator.",
            "data": {
                "sourceItemId": "CAT1"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [     
        {
            "code": "DmsApp-Mapping-IgnoredDestinationSystemPropertyDueToUpdateMode",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'PROP2' was ignored because the mapped destination property with the ID 'property_document_number', which is a system property, cannot be changed in update mode.",
            "data": {
                "sourceItemId": "PROP2",
                "destinationItemId": "property_document_number"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-MappingForSourceNotFound",
            "title": "Mapping configuration not found",
            "detail": "No mapping configuration was found for the source with the ID '/myapp/sources/mysourcex'. For this reason, no mapping is applied and any given values for properties or categories are ignored.",
            "hint": "Please configure a mapping for the given source or contact your administrator.",
            "data": {
                "sourceItemId": "/myapp/sources/mysourcex"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-NoDestinationCategoryFoundWithDestinationProperty",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'myprop1_ID' was ignored because the mapped destination property with the ID '5' was not found in any destination category.",
            "data": {
                "sourceItemId": "myprop1_ID",
                "destinationItemId": "5"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-NoMappingFoundForSourceProperty",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'PROP3' was ignored because no mapping to a destination property was found.",
            "hint": "Please configure a mapping for the given source property or contact your administrator.",
            "data": {
                "sourceItemId": "PROP3"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-NoSourceProperties",
            "title": "No source properties given",
            "detail": "No source properties were given that could be mapped."
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-NoValuesGivenForSourceProperty",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'myprop1_ID' was ignored because no values were given.",
            "data": {
                "sourceItemId": "myprop1_ID"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-PropertyStatusIgnored",
            "title": "Ignored source property",
            "detail": "The source property with the ID 'myprop1_ID' was ignored because it is mapped to the destination property 'status' (ID: 'property_state') and other source properties were given. A status transfer is only possible if no other properties are changed.",
            "hint": "For a status transfer please send only the property ‘status’. Change the other properties in another request.",
            "data": {
                "sourceItemId": "myprop1_ID",
                "destinationItemId": "property_state"
            }
        }
    ]
}

HTTP/1.1 200 OK
 
{
    "responseDetails": [
        {
            "code": "DmsApp-Mapping-UnknownDestinationCategory",
            "title": "Ignored source category",
            "detail": "The source category with the ID 'mycat1_ID' was ignored because the mapped destination category with the id 'destcat1_ID' is unknown or the user does not have permission for the category.",          
            "data": {
                "sourceItemId": "mycat1_ID",
                "destinationItemId": "destcat1_ID"
            }
        }
    ]
}

{
    "properties": [ 
       ...
    ],
        "userdata": [{
       "key": "postProcessingOption",
       "display": "My post processing options",
       "values": [
                    {"value":"1", "display": "Action 1", "default":"false"},
                    {"value":"2", "display": "Default action 2", "default":"true"},
                    {"value":"3", "display": "Action 3", "default":"false"}
                 ]
    }]
}

POST /myapp/sources/mysource/myfile/success
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "_links": {
        "dmsobjectwithmapping": { 
            "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000001234?sourceId=%2Fmyapp%2Fsources%2Fmysourc" 
        }
    },
        "userdata": [
        {
            "postProcessingOption": ["2"]
        }
    ]
}

HTTP/1.1 400 BadRequest
  
{
    "reason": "My error message",
    "severity": 3
}

Success = 0,
Information = 1,
Warning = 2,
Error = 3

Released: JSON representation

You can delete the current version of an existing DMS object in a d.3 repository without the need for action by the user.

To delete the current version of a DMS object, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determine the link relation for the existing DMS object

To determine a URL for an existing DMS object, perform a search and evaluate the self link relation for an item in the result list. The chapter Retrieving and viewing the results of a search operation provides you with more information about performing a search and the description of a result list item.

Determining the link relation for deleting the current version of the existing DMS object

To determine the URL for deleting the current version of the DMS object, evaluate the delete and deleteWithReason link relations for an item in the result list. If it is essential for a reason for deletion to be specified, for example, when deleting a version that has already been released, the deleteWithReason link relation is available. Otherwise, the delete link relation contains the URL for deletion. If both link relations are missing, please check the authorizations for deleting the version of the DMS object. If the existing DMS object is being processed, the authenticated user must be the one processing the DMS object.

Open the URL to delete the current version of the DMS object

Send an HTTP DELETErequest for the delete or deleteWithReason link relations determined for the existing DMS object. If you want to a reason for deletion to be communicated, this must be entered in the body of the request. The reason for deletion must contain at least 3 characters and have a maximum of 80 characters.

Request

DELETE /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{"reason":"Created accidentally."}

If the call is successful, HTTP 200 OK is returned: If the body is empty, the entire DMS object was deleted. If the DMS object contains more versions, the body contains additional link relations. If it contains the self link relation, it means there are more versions for the DMS object and you can call up more details for the DMS object using this URL. You can delete the next version of the DMS object using the delete or deleteWithReason link relations. If these link relations are not available, it means that the user is not authorized to delete the next version.

Response

HTTP/1.1 200 OK

{
        "_links": {
        "self": {
                "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
        },
                "delete": {
                "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/A00000001"
        }
        }
}

If deletion of the version fails, an appropriate response is displayed. For more information, see Overview of formats for errors.

The exclusive processing of a DMS object is required so users in Microsoft Office 365 can process an element. If processing via Office 365 is not complete, the request fails, and you receive the status code 403 Forbidden with the corresponding error information as the response. Please repeat the request at a later time.

Released: JSON representation

In this chapter, you can learn how to create and manage mapping for properties and for the categories of a source system (for instance, an e-mail application) for a d.3 repository. This mapping is used for storage, for retrieving the details of an element and for retrieving and displaying the results of searches in d.3one integrations. When saving a mapping, you choose which external data (for instance, the properties of an e-mail) is assigned to which d.3 document property.

There can only be one unique mapping for each source in a source system.

The Defining a source system chapter explains how to create a source for mapping. In the Basic information about mapping chapter, you can find general information for helping you to create mappings. For useful information about write access, see Basic information about write access.

Determining the link relation for managing mapping

In the chapter Determining a repository, you can learn how to determine the URL for a repository. Then, execute an HTTP Get request for the REST resource for a repository as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object for a repository contains the link relation mappingconfig.

Response

{
        "_links": {
                "mappingconfig": {
                        "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/"
                }
        },
        "id": "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27"
}

Storing mapping

Send an HTTP POST request with the mapping for your source system as the Body for the URL that you received in the mappingconfig link relation. If the mapping is stored successfully, you receive the HTTP status code 201 Created.

Request

POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
        name: "My Source",
        sourceId: "/myapp/sources/mysource",
        mappingItems: [{
                destination: "RECH",
                source: "mycategory1_ID",
                type: 1
        },
        {
                destination: "3",
                source: "myprop1_ID",
                type: 0
        },
        {
                destination: "property_caption",
                source: "myprop2_ID",
                type: 0
        }]
}

The JSON object that is transferred to POST is described as follows:

Retrieving stored mapping

To retrieve the mapping, execute an HTTP GET request for the URL /dms/r/<RepositoryID>/m?sourceId=<SourceID>. The value of the sourceID property indicates the unique identifier of the source (for example, /myapp/sources/mysource).

Request

GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m?sourceId=%2Fmyapp%2Fsources%2Fmysource HTTP/1.1
Accept: application/hal+json

As the response, you receive the object with the stored mapping.

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
        mappings: [{
                _links: {
                        self: {
                                href: "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID>"
                        }
                }
                name: "My Source",
                sourceId: "/myapp/sources/mysource",
                mappingItems: [{
                        destination: "RECH",
                        source: "mycategory1_ID",
                        type: 1
                },
                {
                        destination: "3",
                        source: "myprop1_ID",
                        type: 0
                },
                {
                        destination: "property_caption",
                        source: "myprop2_ID",
                        type: 0
                }]
        }]
}

The properties of the objects are the same properties as when the mappings are stored.

Deleting stored mapping

When you retrieve mapping for your source, you receive a link relation for each stored mapping (_links.self.href). For this URL, you can execute an HTTP Delete request to delete the mapping.

Request

DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json

Editing stored mapping

When you retrieve mapping for your source, you receive a link relation for each stored mapping (_links.self.href). For this URL, you can execute an HTTP PUT request to update the map. The object that you transfer is the same as the object for storing mapping.

Request

PUT https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/m/<MappingContainerID> HTTP/1.1
Origin: https://host
Accept: application/hal+json
Content-Type: application/hal+json

{
        name: "My Source",
        sourceId: "/myapp/sources/mysource",
        mappingItems: [{
                destination: "RECH",
                source: "mycategory1_ID",
                type: 1
        },
        {
                destination: "3",
                source: "myprop1_ID",
                type: 0
        },
        {
                destination: "property_caption",
                source: "myprop2_ID",
                type: 0
        }]
}

Released: JSON representation

This chapter explains how to retrieve and save the notes of a DMS object.

To retrieve or save the notes of a DMS object, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determine and open the link relation for retrieving the details of a DMS object

In the chapter Retrieving and viewing the details of a DMS object, you can learn how to determine and open the URL for retrieving the details of a DMS object.

Determine the link relation for retrieving the notes of a DMS object

The JSON object for the details of a DMS object contains the link relation notes, which you can use to retrieve the notes of the DMS object.

Response

{
  "_links": {    
         "notes":{
           "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
         }
  },
  "id": "D000000123"  
}

Retrieving the notes of a DMS object

Retrieve the notes of the DMS object with the previously determined URL as follows:

Request

GET https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n HTTP/1.1
Accept: application/hal+json

As the response, you receive the object with the notes of the DMS object:

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links": {
        "self": {
            "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n"
        }
    },
    "notes":[{
            "creator" : {
                "id": "MargaS"
                "displayName": "Marga Schilling"
            },
            "text": "This is a sample text."
            "created": "2019-09-03T09:09:09.453+02:00"
        }
    ]
}

Structure of a note element

Structure of a creator object

Saving the notes of a DMS object

With a HTTP POST request for the previously determined URL you can create a note for a DMS object. If you want to create multiple notes, repeat the process. Save a note as follows:

Request

POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/n HTTP/1.1
Content-Type: application/json
Content-Length: 42

{
    "text": "This is a sample text."
}

Response

HTTP/1.1 200 OK

Structure of the note object

Released: JSON representation, HTML page

You can retrieve the versions of a DMS object as JSON representations or display the versions of a DMS object.

To retrieve or display the versions of a DMS object, you must perform the following steps:

Determine the link relation for retrieving and displaying the versions of a DMS object

In the chapter Retrieving and viewing the details of a DMS object, you can learn how to determine the link relation for the versions of a DMS object.

Retrieving and displaying the versions of a DMS object (JSON representation)

Once you have the URL of the versions from the link relation, then you can retrieve the versions of a DMS object as follows:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/
Accept: application/json
Accept-Language: en

The following JSON object will then be returned as a result:

Response

{
  "_links": {
    "self": {
      "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/"
    }
  },
  "versions": [{ 
      "_links": { 
        "mainblobcontent": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/6_3/b/main/c" 
        },
        "pdfblobcontent": {
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/6_3/b/p1/c"
        },
        "self": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/6_3"
        }
      },
      "alterationText": "",
      "caption": "3 Processing",
      "creationDate":"2019-10-25T12:22:56.000+02:00",
      "id": "6_3",
      "mimeType":"application/msword",
      "state":"Processing"
    },
    {
      "_links": { 
        "mainblobcontent": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/3_2/b/main/c" 
        },
        "pdfblobcontent": {
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/3_2/b/p1/c"
        },
        "self": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/3_2"
        }
      },
      "alterationText": "Reasons for changes",
      "caption": "2 Release",
      "creationDate":"2019-10-22T16:29:32.000+02:00",
      "id": "3_2",
      "mimeType":"application/msword",
      "state":"Released"
    },
    {
      "_links": { 
        "mainblobcontent": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/1_1/b/main/c" 
        },
        "pdfblobcontent": {
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2/D000000123/v/1_1/b/p1/c"
        },
        "self": { 
          "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/1_1"
        }
      },
      "alterationText": "Reasons for changes",
      "caption": "1 Archive",
      "creationDate":"2019-10-12T11:49:41.000+02:00",
      "id": "1_1",
      "mimeType":"application/msword",
      "state":"Archived"
    }
  ]
}

Structure of a version

Retrieving and displaying the versions of a DMS object (HTML page)

If you want to call the HTML view of the versions, determine the link relation for the versions of a DMS object. Enter the URL in the browser to view the HTML page. This HTML page contains the list of the versions of a DMS object.

Example:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/v/
Accept: text/html

Released: JSON representation

In this chapter, you can learn how to link DMS objects with other DMS objects hierarchically independent from their type.

To link DMS objects to each other, perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determine and open the link relation for retrieving the details of a DMS object

In the chapter Retrieving and viewing the details of a DMS object, you can learn how to determine and open the URL for retrieving the details of a DMS object.

Determine the link relation for linking DMS objects

The JSON object for the details of a DMS object contains the link relation linkDmsObjects, which you can use to link DMS objects.

Response

{ 
    "_links": {   
        "linkDmsObjects":{
            "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children"
        }
    },
    "id": "D000000123" 
}

Linking DMS objects

To link a DMS object to the transferred DMS objects, execute an HTTP POST request with the list of IDs of the DMS objects to be linked as the body to the URL determined above as follows:

Request

POST https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children HTTP/1.1
Accept: application/hal+json

Content-Type: application/hal+json

{
    "dmsObjectIds": [
        "D000000089",
        "D000000127",
        "D000004567",
    ]
}

The JSON object that is transferred to POST is described as follows:

As the response, you receive the HTTP status code 200 (OK) if the link was successful. If the link was not successful or was successful only for individual DMS objects, you receive the HTTP status code 207 (multi-status) and a list with detailed information about the individual link operations.

Example of a response to a partly failed request:

Response

HTTP/1.1 207 Multi-Status
Content-Type: application/hal+json
 
{
 "requestId": "XyErwIKPhyGaMg9dxcGksgAAA@A",
 "linkDocumentErrorPageModels": [
   {
     "dmsObjectId": "D000000089",
     "errorPageModel": {
       "reason": "These documents are already linked to each other! [0000071] ",
       "severity": 1,
       "errorCode": 71
     }
   },
   {
     "dmsObjectId": "D000000127",
     "errorPageModel": {
       "reason": "These documents are already linked to each other! [0000071] ",
       "severity": 1,
       "errorCode": 71
     }
   },
   {
     "dmsObjectId": "D000004567",
     "errorPageModel": {
       "reason": "These documents are already linked to each other! [0000071] ",
       "severity": 1,
       "errorCode": 71
     }
   }
 ]
}

Description of parameters for response upon a failed request:

Structure of a response object for a link operation

Response format for errors

Success = 0,
Information = 1,
Warning = 2,
Error = 3

This function is available only for on-premises installations.

Released: JSON representation

This chapter explains how to remove the link between two DMS objects. You can only remove links of DMS objects individually.

To remove the link between two DMS objects, you must perform the following steps:

Determining the URL for a repository

In the chapter Determining a repository, you can learn how to determine the URL for a repository.

Determine and open the link relation for retrieving the details of a DMS object

In the chapter Retrieving and viewing the details of a DMS object, you can learn how to determine and open the URL for retrieving the details of a DMS object.

Determine the link relation for removing the link between two DMS objects

The JSON object for the details of a DMS object contains the link relation unlinkDmsObject with a placeholder for the ID of the parent DMS object for which you want to remove the link to the dossier.

Response

{ 
    "_links": {    
        "unlinkDmsObject": { 
            "href": "/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/{parentDmsObjectId}/children/D000004567" 
        } 
    }, 
    "id": "D000000123" 
}

Open the URL for removing the link between two DMS objects

Execute an HTTP DELETE request with the ID of the DMS object as a parameter in the URL determined above as follows to remove the link between the DMS object and the dossier:

Request

DELETE https://host/dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27/o2m/D000000123/children/D000004567 HTTP/1.1 
Accept: application/hal+json

As the response, you receive the HTTP status code 200 (OK) if the removal of the link was successful. If the removal of the link was unsuccessful, you receive the HTTP status code 400 (bad request) and detailed information about the error.

Example for a response upon a failed request:

Response

HTTP/1.1 400 Bad Request 
Content-Type: application/hal+json 

{
  "reason": "These two documents are not linked with each other. [0000073] ",
  "severity": 1,
  "errorCode": 73,
  "requestId": "XyEWT4KPhyGaMg9dxcGNiAAAA@c"
}

If you want to remove multiple DMS objects, repeat this step.

Description of parameters for response upon a failed request:

Response format for errors

Success = 0,
Information = 1,
Warning = 2,
Error = 3