Dynamics 365 Adapter app

Scope of functions

The Dynamics 365 Adapter app connects your d.velop platform to Microsoft Dynamics 365.

Using the API functions

Below, you will learn how you can use the Dynamics 365 Adapter app programming interface for your own developments.

Authentication

The Dynamics 365 Adapter app interfaces require valid authentication from the identity provider app.

For information about obtaining such authentication, see the API documentation for the identity provider app. You configure the authentication in your d.velop cloud tenants.

To use the Dynamics 365 Adapter app services, you must prepare and configure the app appropriately in your d.velop cloud tenants. This involves creating document types in the app that you can then deliver using the services provided. You also choose the target system in which the delivered documents are stored.

Saving a new file (DMS object)

You can use this function to transfer files (DMS objects) to the Dynamics 365 Adapter for further processing. You must define an export system for further processing by the Dynamics 365 Adapter app. You can create and manage an export system in the configuration.

Perform the following steps to save a new DMS object:

Determine the URL for an export system.
Determine the link relation for storing the new DMS object.
Prepare the file that you want to save.
Call the URL for storing the new DMS object.

Determining the URL for an export system

To implement your own functions, you always require the ID of the export system. The Dynamics 365 Adapter app lets you export to multiple export systems if you have configured several export systems.

Perform the following steps to determine which export systems are configured:

Determining the link relation for retrieving the export systems

The URL for an export system is available as a link relation in the response of the HTTP GET request.

Request

GET /d365adapter
Accept: application/hal+json

Response

{
   "_links": {
       "exportsystems": {
           "href": "/d365adapter/export/{exportsystemid}",
           "templated": true
       }
   }
}

Retrieving the list of export systems

To call export system-specific functions, you require the export system ID. Replace the placeholder {exportsystemid} in the URL /d365adapter/r/{exportsystemid} with the export system ID. If you do not know the export system ID, call the URL as follows:

Request

GET /d365adapter/export
Accept: application/hal+json

In the response, you receive an array of export systems that lists the export system ID as the property id and the export system display name as the property name. You also receive some additional information about the configured export system.

Response

{
    "exportsystems":[
        {
            "id": "d446375d-6968-4565-8579-d41e77c81039",
            "name": "Example export system",
            "systemName": "sharepointadapter",
            "repoId": "5cdc40e2-f380-4c4e-9ba8-5026bae20dfd",
            "repoName": "Beispiel SharePoint Webseitensammlung",
        },
        ...
    ]
}

If you already know the export system ID, you can replace the placeholder {exportsystemid} in the URL /d365adapter/export/{exportsystemid} with the export system ID. When you call the URL with the export system ID, you receive the following result:

Request

GET /d365adapter/export/d446375d-6968-4565-8579-d41e77c81039
Accept: application/hal+json

The JSON object in the response is the same object as the one in the list of JSON objects from the request for the URL /d365adapter/export.

Response

{
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example export system",
    "systemName": "sharepointadapter",
    "repoId": "5cdc40e2-f380-4c4e-9ba8-5026bae20dfd",
    "repoName": "Beispiel SharePoint Webseitensammlung",
}

Determining the link relation for storing a new DMS object

You call the URL for an export system as follows:

Request

GET /d365adapter/export/d446375d-6968-4565-8579-d41e77c81039
Accept: application/hal+json

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

Response

{
    "_links": {
        "dmsobject": {
            "href": "/d365adapter/export/d446375d-6968-4565-8579-d41e77c81039/o",
            "templated": false
        }
    },
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example export system",
    "systemName": "sharepointadapter",
    "repoId": "5cdc40e2-f380-4c4e-9ba8-5026bae20dfd",
    "repoName": "Beispiel SharePoint Webseitensammlung",
}

Preparing the file to be saved

If you cannot provide your file with a presigned URL, you can provide the file temporarily using the Dynamics 365 Adapter app. You can use the URL for the temporarily uploaded file to transfer the DMS object.

To temporarily upload a file, perform the following steps:

Determine the link relation for temporarily uploading the file.
Open the URL for temporarily uploading the file.
Upload the temporary file.

Determining the link relation for temporarily uploading the file

You call the URL for a repository as follows:

Request

GET /d365adapter/export
Accept: application/hal+json

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

Response

[
    "_links": {
        "filecache": {
            "href": "/d365adapter/export/d446375d-6968-4565-8579-d41e77c81039/cache",
            "templated": false
        }
    },
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example export system",
    "systemName": "sharepointadapter",
    "repoId": "5cdc40e2-f380-4c4e-9ba8-5026bae20dfd",
    "repoName": "Beispiel SharePoint Webseitensammlung",
]

Opening the URL for temporarily uploading the file

Execute an HTTP POST request for the URL that you received in the link relation filecache. If the process was successful, you receive the HTTP status code 201 and the URL (contentLocationUri) in the HTTP header Location.

Request

POST /d365adapter/export/d446375d-6968-4565-8579-d41e77c81039/cache
Origin: https://baseuri

Response

HTTP/1.1 201 Created
Location: <Presigned-URL from AWS S3>

You require the link for the subsequent upload of the temporary file and as the URI for storing a new DMS object. The link is valid for 15 minutes. Once this time passes, it is no longer possible to upload to the specified URL.

Uploading the temporary file

Execute an HTTP PUT request with the binary data as the body for the URL that you received as the location. If the process was successful, you receive the HTTP status code 200.

Request

PUT <Presigned-URL from AWS S3>
Origin: https://baseuri

<binary content>

Response

HTTP/1.1 200 OK

In the HTTP PUT request, all the content of the body is handled as the binary data for the file to be uploaded. Uploading using the method multipart/form-data is currently not possible.

Calling the URL for storing a new DMS object

Execute an HTTP POST request for this URL with the required properties as the body.

Request

POST /d365adapter/export/d446375d-6968-4565-8579-d41e77c81039/o
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "contentUri": "https://your.presigned.URL.to.the.file",
    "filename": "UploadedFile.txt",
    "type": "myDocumentType",
    "properties": [{
            "key": "myprop1",
            "values": ["Please verify the XYZ invoice"]
        },
        {
            "key": "myprop2",
            "values": ["Name1@contoso.com","Name2@samplecompany.de"]
        }
    ]
    
}

Property	Type	Description	Required
contentUri	String	Indicates the URL from which the Dynamics 365 app downloads the file.	Yes
filename	String	Indicates the name of the file to be saved, with the file extension.	Yes
type	String	Specifies the document type of the DMS object. The document type must have been defined in the Dynamics 365 Adapter app.	Yes
properties	String	Indicates a JSON array with properties. Only properties that have also been defined for the document type can be transferred here.	Yes
properties.key	String	Indicates the ID of the property.	Yes
properties.values	String	Indicates an array with the corresponding values of the element property. Even if you want to transfer only one value, you must transfer this value as a JSON array.	Yes

As the response, you receive the link to the created DMS object in the location header:

Response

HTTP/1.1 201 Created
Location: <Base-URI>/d365adapter/r/<Repository-ID>/o/<DMS-Object-ID>

Update a DMS-Object with Location as URL

Execute an HTTP PUT request for this URL with the required properties as the body.

Request

PUT d365adapter/r/d446375d-6968-4565-8579-d41e77c81039/o/aHR0cHM6Ly9kLXZlbG9wLmRlfA==

Origin: https://baseuri
Accept: */*
Content-Type: application/json

{
    "Filename": "UploadedFile.png",
    "Type": "myDocumentType",
    "ContentUri": "https://your.presigned.URL.to.the.file",
    "AlterationText": "reason for update",
    "Properties": [
        {
            "Key": "myprop1",
            "Values": [
                "myprop1Value"
            ]
        },
        {
            "Key": "myprop2",
            "Values": [
                "myprop2Value"
            ]
        }
       
    ]
}

Property	Type	Description	Required
Filename	String	Indicates the name of the file to be saved, with the file extension.	No
Type	String	Specifies the document type of the DMS object. The document type must have been defined in the Dynamics 365 Adapter app.	Yes
ContentUri	String	Indicates the URL from which the Dynamics 365 app downloads the file.	NO
AlterationText	String	Indicates the reason of the Update. If it has been configured as a mandatory field in the DMS, it must be specified.	Nein
Properties	String	Indicates a JSON array with properties. Only properties that have also been defined for the document type can be transferred here.	No
Properties.Key	String	Indicates the ID of the property.	No
Properties.Values	String	Indicates an array with the corresponding values of the element property. Even if you want to transfer only one value, you must transfer this value as a JSON array.	No

Response

HTTP/1.1 200 OK

Update of a DMS-Object with the Location in the Body

Make an HTTP PUT request with the required properties to the native location URL of the DMS system. This update option is required if the DMS object was not created by the app itself.

Request

PUT d365adapter/r/d446375d-6968-4565-8579-d41e77c81039/o

Origin: https://baseuri
Accept: */*
Content-Type: application/json

{ 
    "LocationUri": "https://tenant.d-velop.cloud/dms/r/4ddb13ae-3e49-4c3c-a158-b5457f39f0bb/o2m/PL00039211?sourceid=%2fd365adapter%2fsources%2fQuotation",
    "UpdateObject": {
        "Filename": "UploadedFile.png",
        "Type": "myDocumentType",
        "ContentUri": "https://your.presigned.URL.to.the.file",
        "AlterationText": "reason for update",
        "Properties": [
            {
                "Key": "myprop1",
                "Values": [
                    "myprop1Value"
                ]
            },
            {
                "Key": "myprop2",
                "Values": [
                    "myprop2Value"
                ]
            }
        ]
    }
}

Property	Type	Description	Required
LocationUri	String	Specifies the location of the object.	Yes
UpdateObject	String	Specifies a JSON array with properties. Contains all properties of the object.	Yes
UpdateObject.Filename	String	Specifies the name of the file to be saved with the file extension. Can be left empty during an update. In diesem Fall bleibt der Filename bestehen.	No
UpdateObject.Type	String	Defines, which document type the DMS-Object has. The document type must have been defined before.	Yes
UpdateObject.ContentUri	String	Indicates where the file can be found. Can be left empty. In this case the file will not be overwritten.	No
UpdateObject.AlterationText	String	Indicates the reason for the update. If it has been configured as a mandatory field in the DMS, it must be specified.	No
UpdateObject.Properties	String	Specifies a JSON array with properties. Only properties that have also been defined for the document type can be passed here. Can also be left empty. In this case, no properties will be overwritten.	No
UpdateObject.Properties.Key	String	Specifies the ID of the property.	No
UpdateObject.Properties.Values	String	Specifies an array with the associated values of the element property. Even if you want to pass only one value, you must pass that value as a JSON array.	No

Response

HTTP/1.1 200 OK

Get the Properties of a DMS-Object

Execute an HTTP GET request for this URL.

Request

GET d365adapter/r/d446375d-6968-4565-8579-d41e77c81039/o/aHR0cHM6Ly9kLXZlbG9wLmRlfA==

Origin: https://baseuri
Accept: application/json

In response you get a link relation and the specified properties.

Response

{
    "_links": {
        "self": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "update": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "move": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "mainblobcontent": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "openInLocation": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "preview": {
            "href": "<link>",
            "icon": "",
            "templated": false
        },
        "edit": {
            "href": "<link>",
            "icon": "",
            "templated": false
        }
    },
    "id": "aHR0cHM6Ly9kLXZlbG9wLmRlfA==",
    "sourceCategories": [
        "mySourceCategorie"
    ],
    "sourceProperties": [
          {
            "Key": "myprop1",
            "Values": [
              "myprop1Value"
            ]
          },
          {
            "Key": "myprop2",
            "Values": [
              "myprop2Value"
            ]
          }

    ],
    "destinationRelativeUrl": "my.Document.png"
}