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 Verbindungsdaten definieren. Verbindungsdaten kannst du unter Konfiguration anlegen und verwalten.

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

  • Ermittle die URL zu den Verbindungsdaten.
  • 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 den Verbindungsdaten

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

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

 Ermitteln der Linkrelation zum Abrufen der Verbindungsdaten

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

Request


GET /d365adapter
Accept: application/hal+json

Response


{
   "_links": {
       "repositories": {
           "href": "/d365adapter/r/{repositoryid}",
           "templated": true
       }
   }
}

 Abrufen der Liste der Verbindungsdaten

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

Request


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

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

Response


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

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

Request


GET /d365adapter/r/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/r.

Response


{
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example 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 Verbindungsdaten wie folgt auf:

Request


GET /d365adapter/r/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/r/d446375d-6968-4565-8579-d41e77c81039/o",
            "templated": false
        }
    },
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example 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/r
Accept: application/hal+json

Das JSON-Objekt zu einem Repository enthält die Linkrelation filecache.

Response


[
    "_links": {
        "filecache": {
            "href": "/d365adapter/r/d446375d-6968-4565-8579-d41e77c81039/cache",
            "templated": false
        }
    },
    "id": "d446375d-6968-4565-8579-d41e77c81039",
    "name": "Example 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/r/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/r/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>