d.velop connect for Microsoft Dynamics 365-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"]
        }
    ]
    
}

Eigenschaft	Typ	Beschreibung	Pflicht
contentUri	String	Gibt die URL an, unter der die Dynamics 365-App die Datei herunterlädt. Für eine Aktenerstellung muss dieser Wert leer gelassen werden.	Ja
filename	String	Gibt den Namen der zu speichernden Datei mit der Dateierweiterung an. Für eine Aktenerstellung muss dieser Wert leer gelassen werden.	Ja
type	String	Legt fest, welche Dokumentart das DMS-Objekt hat. Die Dokumentart muss in der Dynamics 365 Adapter-App definiert worden sein.	Ja
properties	String	Gibt ein JSON-Array mit Eigenschaften an. Hier können nur Eigenschaften übergeben werden, die auch für die Dokumentart definiert worden sind.	Ja
properties.key	String	Gibt die ID der Eigenschaft an.	Ja
properties.values	String	Gibt 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: <Base-URI>/d365adapter/r/<Repository-ID>/o/<DMS-Object-ID>

Aktualisierung eines DMS-Objektes auf die Location URL des DMS-Objekts

Führe eine HTTP PUT-Anforderung mit den benötigten Eigenschaften als Body auf die Location-URL des DMS-Objektes aus.

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"
            ]
        }
       
    ]
}

Eigenschaft	Typ	Beschreibung	Pflicht
Filename	String	Gibt den Namen der zu speichernden Datei mit der Dateierweiterung an. Kann bei einem Update leer gelassen werden. In diesem Fall bleibt der Filename bestehen.	Nein
Type	String	Legt fest, welche Dokumentart das DMS-Objekt hat. Die Dokumentart muss vorher definiert worden sein.	Ja
ContentUri	String	Gibt an, wo die Datei zu finden ist. Kann leer gelassen werden. In diesem Fall wird die Datei nicht überschrieben.	Nein
AlterationText	String	Gibt den Änderungsgrund für die Aktualisierung eines DMS-Objektes an. Kann angegeben werden, wenn das DMS-System diese Information erfordert.	Nein
Properties	String	Gibt ein JSON-Array mit Eigenschaften an. Hier können nur Eigenschaften übergeben werden, die auch für die Dokumentart definiert worden sind. Kann auch leer gelassen werden. In diesem Fall werden keine Properties überschrieben.	Nein
Properties.Key	String	Gibt die ID der Eigenschaft an.	Nein
Properties.Values	String	Gibt 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.	Nein

Response


HTTP/1.1 200 OK

Aktualisierung eines DMS-Objektes durch die native Location-URL des DMS-Systems

Führe eine HTTP PUT-Anforderung mit den benötigten Eigenschaften auf die native Location-URL des DMS-Systems aus. Diese Möglichkeit der Aktualisierung ist erforderlich, wenn das DMS-Objekt nicht durch die App selbst erzeugt wurde.

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"
                ]
            }
        ]
    }
}

Eigenschaft	Typ	Beschreibung	Pflicht
LocationUri	String	Gibt die Speicherort des Objektes an.	Ja
UpdateObject	String	Gibt ein JSON-Array mit Eigenschaften an. Beinhaltet alle Eigenschaften des Objektes.	Ja
UpdateObject.Filename	String	Gibt den Namen der zu speichernden Datei mit der Dateierweiterung an. Kann bei einem Update leer gelassen werden. In diesem Fall bleibt der Filename bestehen.	Nein
UpdateObject.Type	String	Legt fest, welche Dokumentart das DMS-Objekt hat. Die Dokumentart muss vorher definiert worden sein.	Ja
UpdateObject.ContentUri	String	Gibt an, wo die Datei zu finden ist. Kann leer gelassen werden. In diesem Fall wird die Datei nicht überschrieben.	Nein
UpdateObject.AlterationText	String	Gibt den Änderungsgrund für die Aktualisierung eines DMS-Objektes an. Kann angegeben werden, wenn das DMS-System diese Information erfordert.	Nein
UpdateObject.Properties	String	Gibt ein JSON-Array mit Eigenschaften an. Hier können nur Eigenschaften übergeben werden, die auch für die Dokumentart definiert worden sind. Kann auch leer gelassen werden. In diesem Fall werden keine Properties überschrieben.	Nein
UpdateObject.Properties.Key	String	Gibt die ID der Eigenschaft an.	Nein
UpdateObject.Properties.Values	String	Gibt 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.	Nein

Response


HTTP/1.1 200 OK

Abrufen der Daten eines DMS-Objektes

Führe eine HTTP GET-Anforderung auf die Location URL aus.

Request


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

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

Als Antwort erhältst du eine Linkrelation und die Angegebenen Eigenschaften.

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"
}

X close

Impressum

Alle bisherigen Dokumentationen zur d.velop connect for Microsoft Dynamics 365-App verlieren mit der Veröffentlichung der aktuellen Version ihre Gültigkeit.

Die in dieser Dokumentation enthaltenen Informationen sind mit größter Sorgfalt erstellt und durch unsere Qualitätssicherung nach dem allgemeinen Stand der erprobten Technik geprüft. Dennoch sind Fehler nicht auszuschließen. Aus diesem Grund stellen die in der vorliegenden Dokumentation enthaltenen Informationen keine Verpflichtung, zugesicherte Eigenschaft oder Garantie dar. Die d.velop AG übernimmt auf Basis dieser Dokumentation keine Haftung oder Gewährleistung. Ansprüche nach dem Produkthaftungsgesetz sowie nach Deliktsrecht bleiben unberührt, sofern sie nicht individualvertraglich ausgeschlossen wurden.
Aussagen über gesetzliche, rechtliche und steuerliche Vorschriften und deren Auswirkungen haben nur für die Bundesrepublik Deutschland Gültigkeit.
Die d.velop AG behält sich vor, in ihrer Software vorhandene Komponenten von Drittanbietern durch funktionsadäquate Komponenten anderer Hersteller zu ersetzen. Die d.velop AG behält sich in Ausübung Ihrer jeweils gültigen Releasepolitik vor, Produktfeatures und einzelne Softwareprodukte nicht mehr durch Softwarepflege- und Supportleistungen zu unterstützen. Näheres dazu finden Sie im Supportlebenszyklus des d.velop-Service-Portals unter https://portal.d-velop.de.

Die Verwendung der Texte, Bilder, Grafiken sowie deren Arrangements, auch auszugsweise, sind ohne vorherige Zustimmung der d.velop AG nicht erlaubt.
Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Warenzeichen der jeweiligen Hersteller/Inhaber, die diese zur Verfügung gestellt haben.

Sofern Teile oder einzelne Formulierungen dieser Dokumentation der geltenden Rechtslage nicht, nicht mehr oder nicht vollständig entsprechen sollen, bleiben die übrigen Teile der Dokumentation in ihrem Inhalt und ihrer Gültigkeit davon unberührt.
In der Dokumentation können Sie über Links zu externen Internetseiten gelangen, die nicht von uns betrieben werden. Derartige Links werden von uns entweder eindeutig gekennzeichnet oder sind durch einen Wechsel in der Adresszeile Ihres Browsers erkennbar. Für die Inhalte dieser externen Internetseiten sind wir nicht verantwortlich.

Kontakt
d.velop AG
Schildarpstraße 6-8
48712 Gescher, Deutschland

Fon +49 2542 9307-0
d-velop.de oder info@d-velop.de

Vertreten durch den Vorstand: Christoph Pliete (Vorsitzender), Mario Dönnebrink
Vorsitzender des Aufsichtsrates: Dr. Helmut Bäumer
Handelsregister beim Amtsgericht Coesfeld, Nr. HRB 4903
Umsatzsteueridentifikationsnummer: DE 813062165

d.velop connect for Microsoft Dynamics 365-App

Dynamics 365 Adapter-App

Funktionsumfang

Verwenden der API-Funktionen

Authentifizierung

Vorbereitung Deiner App

Speichern einer neuen Datei (DMS-Objekt)

Ermitteln der URL zu den Verbindungsdaten

Ermitteln der Linkrelation zum Abrufen der Verbindungsdaten

Abrufen der Liste der Verbindungsdaten

Ermitteln der Linkrelation zum Speichern eines neuen DMS-Objektes

Bereitstellen der zu speichernden Datei

Ermitteln der Linkrelation zum temporären Hochladen der Datei

Aufrufen der URL zum temporären Hochladen der Datei

Hochladen der temporären Datei

Aufrufen der URL zur Ablage eines neuen DMS-Objektes

Aktualisierung eines DMS-Objektes auf die Location URL des DMS-Objekts

Aktualisierung eines DMS-Objektes durch die native Location-URL des DMS-Systems

Abrufen der Daten eines DMS-Objektes

Impressum

Code on this page