Dynamics 365 Adapter-APP

Dynamics 365 Adapter-APP

 Funktionsumfang

Die App Dynamics 365 Adapter bindet deine d.velop-Plattform an Microsoft Dynamics 365 an.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der Dynamics 365 Adapter-App für deine eigenen Entwicklungen nutzen kannst.

 Authentifizierung

Die Schnittstellen der Dynamics 365 Adapter-App benötigen eine gültige Authentifizierung der Identityprovider-App.

Wie du eine solche Authentifizierung erhältst, kannst du der API-Dokumentation der Identityprovider-App entnehmen. Du stellst die Authentifizierung in deinem d.velop cloud-Mandanten ein.

 Vorbereitung Deiner App

Damit du die Dienste der Dynamics 365 Adapter-App nutzen kannst, musst du die App entsprechend in deinem d.velop cloud-Mandanten bereitstellen und konfigurieren. Das bedeutet, du legst in der App Dokumentarten an, die du anschließend über die bereitgestellten Dienste anliefern kannst. Außerdem legst du fest, in welchem Zielsystem die angelieferten Belege abgelegt werden.

 Speichern einer neuen Datei (DMS-Objekt)

Mit dieser Funktion kannst du Dateien (DMS-Objekte) an den Dynamics 365-Adapter für die weitere Verarbeitung übergeben. Für die weitere Verarbeitung durch die Dynamics 365 Adapter-App musst du ein Exportsystem definieren. Ein Exportsystem kannst du unter Konfiguration anlegen und verwalten.

Führe folgende Schritte aus, um ein neues DMS-Objekt zu speichern:

  • Ermittle die URL zu einem Exportsystem.
  • Ermittle die Linkrelation zum Speichern eines neuen DMS-Objektes.
  • Stelle die Datei bereit, die du speichern möchtest.
  • Rufe die URL zum Speichern eines neuen DMS-Objektes auf.

 Ermitteln der URL zu einem Exportsystem

Für die Implementierung eigener Funktionen benötigst du immer die ID des Exportsystems. Mit der Dynamics 365 Adapter-App hast du die Möglichkeit, in mehrere Exportsysteme zu exportieren, wenn du mehrere Exportsysteme konfiguriert hast.

Führe folgende Schritte aus, um zu ermitteln, welche Exportsysteme eingerichtet sind:

 Ermitteln der Linkrelation zum Abrufen der Exportsysteme

Die URL für ein Exportsystem ist als Linkrelation in der Antwort (Response) der HTTP GET-Anforderung verfügbar.

Request


GET /d365adapter
Accept: application/hal+json

Response


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

 Abrufen der Liste der Exportsysteme

Um Exportsystem-spezifische Funktionen aufrufen zu können, benötigst du die Exportsystem-ID. Ersetze den Platzhalter {exportsystemid} in der URL /d365adapter/r/{exportsystemid} mit der Exportsystem-ID. Wenn du die Exportsystem-ID nicht kennst, rufe die URL wie folgt auf:

Request


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

In der Antwort erhältst du ein Array an Exportsystemen, bei dem jeweils die Exportsystem-ID als Eigenschaft id und der Anzeigename des Exportsystems als Eigenschaft name aufgeführt ist. Zudem erhältst du noch ein paar weitere Informationen zum eingerichteten Exportsystem.

Response


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

Wenn du die Exportsystem-ID bereits kennst, kannst du den Platzhalter {exportsystemid} in der URL /d365adapter/export/{exportsystemid} mit der Exportsystem-ID ersetzen. Wenn du die URL mit der Exportsystem-ID aufrufst, erhältst du folgendes Ergebnis:

Request


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

Das JSON-Objekt in der Antwort ist dasselbe Objekt, wie in der Liste der JSON-Objekte aus der Anforderung zur 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",
}

 Ermitteln der Linkrelation zum Speichern eines neuen DMS-Objektes

Rufe die URL zu einem Exportsystem wie folgt auf:

Request


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

Das JSON-Objekt zu einem Repository enthält die Linkrelation 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",
}

 Bereitstellen der zu speichernden Datei

Wenn du deine Datei nicht mit einer vorsignierten URL bereitstellen kannst, kannst du die Datei temporär mit der Dynamics 365 Adapter-App bereitstellen. Mit der URL zur temporär hochgeladenen Datei kannst du das DMS-Objekt übergeben.

Um eine Datei temporär hochzuladen, führe folgende Schritte aus:

  • Ermittle die Linkrelation zum temporären Hochladen der Datei.
  • Rufe die URL zum temporären Hochladen der Datei auf.
  • Lade die temporären Datei hoch.

 Ermitteln der Linkrelation zum temporären Hochladen der Datei

Rufe die URL zu einem Repository wie folgt auf:

Request


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

Das JSON-Objekt zu einem Repository enthält die Linkrelation 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",
]

 Aufrufen der URL zum temporären Hochladen der Datei

Führe eine HTTP POST-Anforderung auf die URL aus, die du in der Linkrelation filecache erhalten hast. Wenn der Vorgang erfolgreich war, erhältst du den HTTP-Statuscode 201 und die URL (contentLocationUri) im 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>

Den Link benötigst du für den anschließenden Upload der temporären Datei und als URI für die Ablage eines neuen DMS-Objektes. Der Link ist 15 Minuten gültig. Nach Ablauf dieser Zeit ist ein Upload zu der angegebenen URL nicht mehr möglich.

 Hochladen der temporären Datei

Führe eine HTTP PUT-Anforderung mit den Binärdaten als Body auf die URL aus, die du als Location erhalten hast. Wenn der Vorgang erfolgreich war, erhältst du den HTTP-Statuscode 200.

Request


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

<binary content>

Response


HTTP/1.1 200 OK

Bei der HTTP PUT-Anforderung werden alle Inhalte des Bodys als Binärdaten der hochzuladenden Datei behandelt. Ein Upload mit der Methode multipart/form-data ist derzeit nicht möglich.

 Aufrufen der URL zur Ablage eines neuen DMS-Objektes

Führe eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf diese URL aus.

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"]
        }
    ]
    
}
EigenschaftTypBeschreibungPflicht
contentUriStringGibt die URL an, unter der die Dynamics 365-App die Datei herunterlädt.Ja
filenameStringGibt den Namen der zu speichernden Datei mit der Dateierweiterung an.Ja
typeStringLegt fest, welche Dokumentart das DMS-Objekt hat. Die Dokumentart muss in der Dynamics 365 Adapter-App definiert worden sein.Ja
propertiesStringGibt ein JSON-Array mit Eigenschaften an. Hier können nur Eigenschaften übergeben werden, die auch für die Dokumentart definiert worden sind.Ja
properties.keyStringGibt die ID der Eigenschaft an.Ja
properties.valuesStringGibt ein Array mit den zugehörigen Werten der Elementeigenschaft an. Auch wenn du nur einen Wert übergeben möchtest, musst du diesen Wert als JSON-Array übergeben.Ja

Als Antwort erhältst du den Link zum erstellten DMS-Objekt im Location-Header:

Response


HTTP/1.1 201 Created
Location: <DMS-Object-URL>