Dynamics 365 Adapter-APP

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.

 Preparing your app

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"]
        }
    ]
    
}
PropertyTypeDescriptionRequired
contentUriStringIndicates the URL from which the Dynamics 365 app downloads the file.Yes
filenameStringIndicates the name of the file to be saved, with the file extension.Yes
typeStringSpecifies the document type of the DMS object. The document type must have been defined in the Dynamics 365 Adapter app.Yes
propertiesStringIndicates a JSON array with properties. Only properties that have also been defined for the document type can be transferred here.Yes
properties.keyStringIndicates the ID of the property.Yes
properties.valuesStringIndicates 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: <DMS-Object-URL>