SharePointAdapter-APP

SharePointAdapter-APP

 Funktionsumfang

Die App SharePointAdapter bindet deine d.velop-Plattform an Microsoft SharePoint an.

 Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle von SharePointAdapter-App für deine eigenen Entwicklungen nutzen kannst.

 Authentifizierung

Die Schnittstellen von SharePointAdapter-App benötigen eine gültige Authentifizierung der Identity provider-App.

Wie du eine solche Authentifizierung erhältst, kannst du der API-Dokumentation der Identity provider-App entnehmen. Die Erstellung erfolgt auf der Oberfläche deines d.velop cloud-Mandanten.

 Definieren eines Quellsystems

Wenn du ein System hast, das Ausgangsdaten bereitstellt (z.B. eine E-Mail-Anwendung oder ein ERP-System), musst du für das Erstellen einer Zuordnung die Elemente des Quellsystems für ein Microsoft SharePoint-Repository vorbereiten. Ein Element eines Quellsystems wird Quelle genannt. Eine Quelle enthält Quelleneigenschaften und Quellenkategorien. Indem Du eine Quelle definierst, kann die SharePointAdapter-App die Bezeichner für die Metadaten der Quelle mit den Bezeichnern für die Metadaten des Microsoft SharePoint-Repositorys verbinden.

 Vorbereitung Deiner App

Damit die SharePointAdapter-App Quellsysteme finden kann, muss deine App die entsprechende Schnittstelle bereitstellen. Die SharePointAdapter-App nutzt zum Auffinden von Apps, die als Quellsystem dienen, das Konzept einer HTTP GET-Anforderung für die Rootressource der Apps (systembaseuri-Pfad mit dem App-Namen). Es werden alle Apps abgefragt, die an dem Gateway registriert sind.

 Bereitstellen der URL zu den Quellen

Die Rootressourcen der Apps werden beim Aufruf der Zuordnungen abgerufen. Die SharePointAdapter-App prüft, ob in der Antwort (Response) die Linkrelation sources enthalten ist. Wenn diese Linkrelation enthalten ist, bietet die App als Quellsystem mindestens eine Quelle für die SharePointAdapter-App an. Die SharePointAdapter-App führt eine HTTP GET-Anforderung auf den angegeben Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200.

Request


GET /myapp
Accept: application/hal+json

Response


{
    "_links": {
        "sources": {
            "href": "/myapp/sources"
        }
    }
}

 Bereitstellen der Quellen

Nachdem die URLs der Quellen ermittelt wurden, werden die Quellen der Apps mit einer HTTP GET-Anforderung von der SharePointAdapter-App abgerufen.

Das Beispiel zeigt, wie du die HTTP-Antwort der Linkrelation sources gestaltest, um der SharePointAdapter-App die Quellen zu übermitteln.

Request


GET /myapp/sources
Accept: application/hal+json

Response


{
	"sources" : [{
		"id" : "/myapp/sources/mysource",
		"displayName" : "My Source",
		"categories": [{
			"key": "mycategory1", 
			"displayName": "My category 1"
		}, 
		{
			"key": "mycategory2", 
			"displayName": "My category 2"
		}],
		"properties" : [{
			"key" : "myprop1",
			"displayName" : "My property 1"
		}, 
		{
			"key" : "myprop2",
			"displayName" : "My property 2"
		},
		{
			"key" : "myprop3",
			"displayName" : "My property 3"
		}]
	}]
}

Struktur einer Quelle

EigenschaftEigenschaft eines enthaltenen ObjektsBeschreibung
sources-Das Quellsystem kann in diesem Array mehrere Quellen ausliefern (z.B. E-Mail, Anlagen etc.), um verschiedene Zuordnungsarten zu unterscheiden.
idGibt den eindeutigen Bezeichner der Quelle an. Die ID muss eine relative URI sein. Die relative URI sollte mit dem Namen der App beginnen, die das Quellsystem bereitstellt, damit eine Eindeutigkeit gewährleistet ist (z.B. /myapp/sources/mysource).
displayNameGibt den Anzeigenamen an, wie er auf der Administrationsoberfläche Zuordnungen im Feld Quelle angezeigt wird. Die DMSApp verwendet zur Internationalisierung den HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Quelle sprachspezifisch ausgegeben werden.
categoriesGibt das Array der Quellenkategorien an, die für die Zuordnungsverwaltung und Zuordnungsverarbeitung zur Verfügung gestellt werden.
propertiesGibt das Array der Quelleneigenschaften an, die für die Zuordnungsverwaltung und Zuordnungsverarbeitung zur Verfügung gestellt werden.

Struktur einer Quellenkategorie

EigenschaftBeschreibung
keyGibt den eindeutigen Bezeichner der Quellenkategorie an.
displayNameGibt den Anzeigenamen an, wie er auf der Administrationsoberfläche Zuordnungen im Bereich Kategorien im Feld Quelle angezeigt wird. Die DMSApp verwendet zur Internationalisierung den HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Kategorie sprachspezifisch ausgegeben werden.

Struktur einer Quelleneigenschaft

EigenschaftBeschreibung
keyGibt den eindeutigen Bezeichner der Quelleneigenschaft an.
displayNameGibt den Anzeigenamen an, wie er auf der Administrationsoberfläche Zuordnungen im Bereich Eigenschaften im Feld Quelle angezeigt wird. Die DMSApp verwendet zur Internationalisierung den HTTP-Header Accept-Language. Dieser HTTP-Header muss vom Quellsystem ausgewertet und der Anzeigename der Eigenschaft sprachspezifisch ausgegeben werden.

 Speichern einer neuen Datei (DMS-Objekt) ohne Benutzerinteraktion

Mit dieser Funktion kannst du Dateien (DMS-Objekte) in Microsoft SharePoint speichern.

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

  • Ermittele die URL zu einem Repository
  • Ermittele die Linkrelation zum Speichern eines neuen DMS-Objektes
  • Stelle die neue Datei bereit
  • Rufe die URL zum Speichern eines neuen DMS-Objektes auf

 Ermitteln der URL zu einem Repository

Für die Implementierung eigener Funktionen benötigst du immer die ID des Repositorys. Mit der SharePointAdapter-App hast du die Möglichkeit, auf mehrere Microsoft Sharepoint-Websitesammlungen zuzugreifen, wenn du mehrere Repositorys konfiguriert hast.

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

  • Ermittele die Linkrelation zum Abrufen der Liste der Repositorys
  • Rufe die Liste der Repositorys ab

 Ermitteln der Linkrelation zum Abrufen der Liste der Repositorys

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

Request


GET /sharepointadapter
Accept: application/hal+json

Response


{
    "_links": {
        "repo": {
            "href": "/sharepointadapter/r/{repositoryid}",
            "templated": true
        }
    }
}

 Abrufen der Liste der Repositorys

Um Repository-spezifische Funktionen aufrufen zu können, benötigst du die Repository-ID.

Ersetze den Platzhalter {repositoryid} in der URL /sharepointadapter/r/{repositoryid} mit der Repository-ID. Wenn du die Repository-ID nicht kennst, rufe die URL wie folgt auf:

Request


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

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

Response


{
    "repositories":[
        {
            "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
            "name": "MyCompany SharePoint - ExampleSite",
            "host": "https://mycompany.sharepoint.com",
            "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
            "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
            "siteCollection": {
                "title": "ExampleSite",
                "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
                "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
            }
        },
        ...
    ]
}

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

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
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 /sharepointadapter/r.

Response


{
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
    "name": "MyCompany SharePoint - ExampleSite",
    "host": "https://mycompany.sharepoint.com",
    "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
    "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
    "siteCollection": {
        "title": "ExampleSite",
        "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
        "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
    }
}

 Ermitteln der Linkrelation zum Speichern eines neuen DMS-Objektes

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "dmsobjectwithmapping": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
    "name": "MyCompany SharePoint - ExampleSite",
    "host": "https://mycompany.sharepoint.com",
    "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
    "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
    "siteCollection": {
        "title": "ExampleSite",
        "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
        "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
    }
}

 Bereitstellen der zu speichernden Datei

Wenn du deine Datei nicht mit einer vorsignierten URL bereitstellen kannst, kannst du die Datei temporär mit der SharePointAdapter-App bereitstellen. Mit der URL zur temporär hochgeladenen Datei kannst du dann das DMS-Objekt speichern.

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

  • Ermittele die URL zu einem Repository
  • Ermittele die Linkrelation zum temporären Hochladen der Datei
  • Rufe die URL zum temporären Hochladen der Datei auf
  • Lade die temporäre Datei hoch

Hinweis

Ein temporäres Hochladen einer Datei ist nur mit der Angabe einer ID zu einem Repository möglich.

 Ermitteln der URL zu einem Repository

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

Request


GET /sharepointadapter
Accept: application/hal+json

Response


{
    "_links": {
        "repo": {
            "href": "/sharepointadapter/r/{repositoryid}",
            "templated": true
        }
    }
}

 Ermitteln der Linkrelation zum temporären Hochladen der Datei

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "filecache": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d"
}

 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 /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache
Origin: https://baseuri

Response


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

Der Link wird für den anschließenden Upload der temporären Datei und als URI für die Ablage eines neuen DMS-Objektes benötigt. 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 /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "contentUri": "https://your.presigned.URL.to.the.file",
    "filename": "UploadedFile.txt",
    "sourceId": "/myapp/sources/mysource",
    "sourceCategory": "mycategory1",
    "sourceProperties": {
        "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 SharePointAdapter-App die Datei herunterlädt.Ja
filenameStringGibt den Namen der zu speichernden Datei mit der Dateierweiterung an.Ja
sourceIdStringLegt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceProperties angewendet werden.Ja
sourceCategoryStringGibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Gib bei dieser Eigenschaft die ID der Quellenkategorie an.Ja
sourcePropertiesStringGibt ein JSON-Array mit Quelleneigenschaften an, die für die Zuordnungsverarbeitung verwendet werden.Ja
sourceProperties.properties.keyStringGibt die ID der Quelleneigenschaft an. Es werden nur Eigenschaften berücksichtigt, die von dir angegeben und vom Administrator in der Zuordnung konfiguriert wurden.Ja
sourceProperties.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: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<DMS-Object-ID>

 Aufrufen der URL zur Ablage eines neuen DMS-Objektes ohne Mapping

Du hast die Möglichkeit, auch ohne konfiguriertes Mapping einen Upload durchzuführen. Dabei gibst du die im Mapping angegebenen Informationen direkt in der Anforderung mit.

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

Request


POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "contentUri": "https://your.presigned.URL.to.the.file",
    "filename": "UploadedFile.txt",
    "sourceCategory": "mycategory1",
    "sourceProperties": {
        "properties": [{
                "key": "myprop1",
				"values": ["Please verify the XYZ invoice"]
            },
			{
				"key": "myprop2",
				"values": ["Name1@contoso.com","Name2@samplecompany.de"]
			}
        ]
    },
    "destination": {
        "Source": "SourceName",
        "DestinationSite": {
            "Path": "https://url.of.the.sharepoint/site"
        },
        "DestinationLibrary": {
            "Id": "Library Guid",
            "Type": 1,
            "IsCheckOutRequired": false
        },
        "DestinationContentType": {
            "Id": "ContentType Id",            
        }
    }
}
EigenschaftTypBeschreibungPflicht
contentUriStringGibt die URL an, unter der die SharePointAdapter-App die Datei herunterlädt.Ja
filenameStringGibt den Namen der zu speichernden Datei mit der Dateierweiterung an.Ja
sourceIdStringLegt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceProperties angewendet werden.Ja
sourceCategoryStringGibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Gib bei dieser Eigenschaft die ID der Quellenkategorie an.Ja
sourcePropertiesStringGibt ein JSON-Array mit Quelleneigenschaften an, die für die Zuordnungsverarbeitung verwendet werden.Ja
sourceProperties.properties.keyStringGibt die ID der Quelleneigenschaft an. Es werden nur Eigenschaften berücksichtigt, die von dir angegeben und vom Administrator in der Zuordnung konfiguriert wurden.Ja
sourceProperties.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
destinationStringGibt ein JSON-Array mit weiteren Informationen zum Ablageort an.Ja
destination.SourceStringGibt den Namen des Quelltyps an, bspw. SalesOrderConfirmationJa
destination.DestinationSiteStringGibt ein JSON-Array mit weiteren Informationen zur Microsoft SharePoint-Website an, in die das Dokument hochgeladen werden soll.Ja
destination.DestinationSite.PathStringGibt die URL zur Microsoft SharePoint-Website an, bspw. https://url.of.the.sharepoint/siteJa
destination.DestinationLibraryStringGibt ein JSON-Array mit weiteren Informationen zur Microsoft SharePoint-Dokumentbibliothek an, in die das Dokument hochgeladen werden soll.Ja
destination.DestinationLibrary.IdStringGibt die Microsoft SharePoint-GUID der zu verwendenden Microsoft SharePoint-Dokumentenbibliothek an.Ja
destination.DestinationLibrary.TypeStringGibt den Typen der Dokumentenbibliothek an.Ja
destination.DestinationLibrary.IsCheckOutRequiredStringGibt an, ob ein CheckOut-Vorgang durchgeführt werden soll.Ja
destination.DestinationContentTypeStringGibt ein JSON-Array mit weiteren Informationen zum Microsoft SharePoint-ContentType an.Ja
destination.DestinationContentType.IdStringGibt die ID des zu verwendenden Microsoft SharePoint-ContentTypes an.Ja

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

Response


HTTP/1.1 201 Created
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<DMS-Object-ID>

 Erstellen eines neuen Listenelements

Mit dieser Funktion kannst du ein Listenelement in SharePoint erstellen.

Führe dazu folgende Schritte aus:

 Ermitteln der Linkrelation für das Erstellen eines neuen Listenelements

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "dmsobjectwithmapping": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
    "name": "MyCompany SharePoint - ExampleSite",
    "host": "https://mycompany.sharepoint.com",
    "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
    "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
    "siteCollection": {
        "title": "ExampleSite",
        "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
        "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
    }
}

 Aufrufen der URL zum Erstellen eines Listenelements

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

Request


POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "sourceId": "/myapp/sources/mysource",
    "sourceCategory": "mycategory1",
    "sourceProperties": {
        "properties": [
            {
                "key": "myprop1",
		        "values": ["Please verify the XYZ invoice"]
            },
			{
				"key": "myprop2",
				"values": ["Name1@contoso.com","Name2@samplecompany.de"]
			}
        ]
    }
}
EigenschaftTypBeschreibungPflicht
sourceIdStringLegt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceProperties angewendet werden.Ja
sourceCategoryStringGibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Gib bei dieser Eigenschaft die ID der Quellenkategorie an.Ja
sourcePropertiesStringGibt ein JSON-Array mit Quelleneigenschaften an, die für die Zuordnungsverarbeitung verwendet werden.Ja
sourceProperties.properties.keyStringGibt die ID der Quelleneigenschaft an. Es werden nur Eigenschaften berücksichtigt, die von dir angegeben und vom Administrator in der Zuordnung konfiguriert wurden.Ja
sourceProperties.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 erstellen Listenelement im Location-Header:

Response


HTTP/1.1 201 Created
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>

 Aktualisieren eines bestehenden Elements

Mit dieser Funktion kannst du ein DMS-Objekt, das schon in Microsoft SharePoint existiert, aktualisieren und Metadaten nachträglich anpassen.

 Aufrufen der URL zum Anpassen eines bestehenden Elements

Führe eine HTTP-PUT- Anforderung mit den benötigten Eigenschaften als Body auf folgende URL aus. Du erhältst die URL im Location-Header der Antwort beim Erstellen eines DMS-Objektes.

Request


PUT /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "sourceId": "/myapp/sources/mysource",
    "sourceCategory": "mycategory1",
    "sourceProperties": {
        "properties": [
            {
                "key": "myprop1",
		        "values": ["Please verify the XYZ invoice"]
            },
			{
				"key": "myprop2",
				"values": ["Name1@contoso.com","Name2@samplecompany.de"]
			}
        ]
    }
}
EigenschaftTypBeschreibungPflicht
sourceIdStringLegt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceProperties angewendet werden.Ja
sourceCategoryStringGibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Gib bei dieser Eigenschaft die ID der Quellenkategorie an.Ja
sourcePropertiesStringGibt ein JSON-Array mit Quelleneigenschaften an, die für die Zuordnungsverarbeitung verwendet werden.Ja
sourceProperties.properties.keyStringGibt die ID der Quelleneigenschaft an. Es werden nur Eigenschaften berücksichtigt, die von dir angegeben und vom Administrator in der Zuordnung konfiguriert wurden.Ja
sourceProperties.properties.keyStringGibt 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 angepassten DMS-Objekt im Location-Header sowie den Status 200:

Response


HTTP/1.1 204 OK
Location: /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<List-Item-ID>

 Speichern einer neuen Datei (DMS-Objekt) mit Benutzerinteraktion

Mit dieser Funktion kannst du Dateien (DMS-Objekte) in Microsoft Sharepoint mit einem Ablagedialog speichern.

Führe dazu folgende Schritte aus:

  • Ermittle die URL zu einem Repository
  • Ermittle die Linkrelation für den Ablagedialog
  • Stelle die neue Datei bereit
  • Erstelle einen Ablagedialog mit definierten Eigenschaften und Dateien
  • Zeige den Ablagedialog mit definierten Eigenschaften und Dateien an
  • Führe weitere Aktionen nach dem Speichern aus (optional)

 Ermitteln der URL zu einem Repository

Für die Implementierung eigener Funktionen benötigst du immer die ID des Repositorys. Mit der SharePointAdapter-App hast du die Möglichkeit, auf mehrere Microsoft Sharepoint-Websitesammlungen zuzugreifen, wenn du mehrere Repositorys konfiguriert hast.

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

  • Ermittele die Linkrelation zum Abrufen der Liste der Repositorys
  • Rufe die Liste der Repositorys ab

 Ermitteln der Linkrelation zum Abrufen der Liste der Repositorys

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

Request


GET /sharepointadapter
Accept: application/hal+json

Response


{
    "_links": {
        "repo": {
            "href": "/sharepointadapter/r/{repositoryid}",
            "templated": true
        }
    }
}

 Ermitteln der Linkrelation für den Ablagedialog

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "new": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/new",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
    "name": "MyCompany SharePoint - ExampleSite",
    "host": "https://mycompany.sharepoint.com",
    "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
    "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
    "siteCollection": {
        "title": "ExampleSite",
        "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
        "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
    }
}

 Bereitstellen der zu speichernden Datei

Wenn du deine Datei nicht mit einer vorsignierten URL bereitstellen kannst, kannst du die Datei temporär mit der SharePointAdapter-App bereitstellen. Mit der URL zur temporär hochgeladenen Datei kannst du dann das DMS-Objekt speichern.

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

  • Ermittele die URL zu einem Repository
  • Ermittele die Linkrelation zum temporären Hochladen der Datei
  • Rufe die URL zum temporären Hochladen der Datei auf
  • Lade die temporäre Datei hoch

Hinweis

Ein temporäres Hochladen einer Datei ist nur mit der Angabe einer ID zu einem Repository möglich.

 Ermitteln der URL zu einem Repository

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

Request


GET /sharepointadapter
Accept: application/hal+json

Response


{
    "_links": {
        "repo": {
            "href": "/sharepointadapter/r/{repositoryid}",
            "templated": true
        }
    }
}

 Ermitteln der Linkrelation zum temporären Hochladen der Datei

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "filecache": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d"
}

 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 /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/cache
Origin: https://baseuri

Response


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

Der Link wird für den anschließenden Upload der temporären Datei und als URI für die Ablage eines neuen DMS-Objektes benötigt. 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.

 Erstellen einen Ablagedialogs mit definierten Eigenschaften und Dateien

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

Request


POST /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/new
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "storeObjects": [{
        "displayValue": "Please verify the XYZ invoice",
        "filename": "UploadedFile.txt",
        "contentUri": "https://your.presigned.URL.to.the.file",
        "sourceId": "/myapp/sources/mysource",
        "sourceCategory": "mycategory1",
        "sourceProperties":{
            "properties": [{
                "key": "myprop1",
                "values": ["Please verify the XYZ invoice"]
            },{
                "key": "myprop2",
                "values": ["Name1@contoso.com","Name2@samplecompany.de"]
            }],
            "userdata": [{
                "key": "postProcessingOption",
                "display": "My post processing options",
                "values": [
                    {"value":"1", "display": "Action 1", "default":"false"},
                    {"value":"2", "display": "Default action 2", "default":"true"},
                    {"value":"3", "display": "Action 3", "default":"false"}
                ]
            }],
        }
        "successCallbackUri": "/myapp/sources/mysource/success/myfile"
    },
    {
        ...
    }]
}

Die Eigenschaft storeObjects gibt das Array der Elementeigenschaften und Dateien an, mit denen der Ablagedialog definiert werden soll.

Den Aufbau eines storeObjects siehst du in der folgenden Tabelle:

EigenschaftTypBeschreibung
displayValueStringGibt den Anzeigenamen des Elements an, das gespeichert wird. Der Anzeigename wird im Ablagedialog für den Anwender sichtbar. Dieser Parameter ist optional.
filenameStringGibt den Namen der zu speichernden Datei mit der Dateierweiterung an.
contentUriStringGibt die URL an, unter der die SharePointAdapter-App die Datei herunterlädt.
sourceIdStringLegt fest, zu welcher Quelle die Zuordnung gehört, die zum Speichern verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceProperties angewendet werden.
sourceCategoryStringGibt an, welche Kategorie für die Zuordnungsverarbeitung beim Speichern verwendet werden soll. Gib bei dieser Eigenschaft die ID der Quellenkategorie an.
sourcePropertiesObjectGibt ein JSON-Array mit Quelleneigenschaften an, die für die Zuordnungsverarbeitung verwendet werden.
sourceProperties.propertiesObject-ArrayGibt ein Array der Quelleigenschaften an, die für die Zuordnungsverarbeitung bereitgestellt werden. Es werden nur diejenigen Eigenschaften beim Speichern berücksichtigt, die vom Administrator in der Zuordnung konfiguriert wurden.
sourceProperties.properties.keyStringGibt die ID der Quelleneigenschaft an. Es werden nur diejenigen Eigenschaften berücksichtigt, die von dir angegeben und die vom Administrator in der Zuordnung konfiguriert wurden.
sourceProperties.properties.valuesString-ArrayGibt 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.
sourceProperties.userdataObjectGibt ein Array von Optionen an, die zusätzlich im Ablagedialog angezeigt werden sollen. Das Angeben dieser Eigenschaft ist optional.
sourceProperties.userdata.keyStringGibt die ID der Option an, die im Ablagedialog angezeigt werden soll.
sourceProperties.userdata.displayStringGibt den Text an, der zu der Option im Ablagedialog angezeigt werden soll.
sourceProperties.userdata.valuesObject-ArrayGibt einen Array mit Auswahlwerten für die Optionen im Ablagedialog an.
sourceProperties.userdata.values.valueStringGibt den Wert der Option an.
sourceProperties.userdata.values.displayStringGibt den Text der Option an.
sourceProperties.userdata.values.defaultStringGibt an, ob die Option vorausgewählt sein soll. Dies ist nur für eine Option des Arrays möglich.
successCallbackUriStringGibt die URL an, die über HTTP POST aufgerufen wird, wenn der Ablagevorgang erfolgreich durchgeführt wurde. Die URL muss relativ sein.

Als Antwort erhältst du die URL zum erstellten Ablagedialog im Location-Header:

Response


HTTP/1.1 201 Created
Location: /sharepointadapter/inbound/<DMS-Object-ID>?repoId=d7f0a5a2-72d5-439d-8ea4-92958d77ba4d

 Zeige den Ablagedialog mit definierten Eigenschaften und Dateien an

Um dem Anwender den erstellten Ablagedialog anzuzeigen rufe die URL aus dem Location-Header im Browser auf.

 Führe weitere Aktionen nach dem Speichern aus (optional)

Wurde beim Erstellen des Ablagedialogs der Parameter successCallbackUri angegeben und hat der Anwender das Speichern erfolgreich abgeschlossen, so erhältst du eine HTTP-POST-Anforderung für diese URL mit einem JSON-Objekt in der Anforderung.

Request


POST /myapp/sources/mysource/myfile/success
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "_links": {
        "dmsobjectwithmapping": { 
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m"
        }
    },
    "userdata": [{
        "postProcessingOption": ["2"]
    }]
}
EigenschaftBeschreibung
_linksEnthält die Linkrelation dmsobjectwithmapping. Die Linkrelation ist eine relative URL zu den Details des gespeicherten DMS-Objektes.
userdataGibt das Array mit den Ergebnissen, welche Optionen ein Anwender ausgewählt hat, als Name-Wert-Paare (Key-Value) an. Die Eigenschaft userdata existiert nur, wenn dem Anwender Optionen bereitgestellt wurden.

Gib als Antwort auf die Anforderung der SharePoint-App einen entsprechenden HTTP-Statuscode zurück. Anhand deines Statuscods zeigt der Ablagedialog eine entsprechende Erfolgs- oder Fehlermeldung an.

 Abrufen der Ergebnisse eines Suchvorgangs (DMS-Objekt)

Beim Abrufen von Ergebnissen eines Suchvorgangs kannst du die Ergebnismenge durch Angabe einer bestimmten Quelle sowie der zugehörigen Quellenkategorien und Quelleneigenschaften eingrenzen. Du kannst auch einen Volltextsuchbegriff zur Einschränkung des Suchergebnisses verwenden.

Um die Ergebnisse eines Suchvorgangs abzurufen, führe folgende Schritte durch:

  • Ermittele die URL zu einem Repository
  • Ermittele die Linkrelation zum Abrufen der Ergebnisse eines Suchvorgangs
  • Gib verhaltenssteuernde Parametern an
  • Rufe die URL für die Ergebnisse eines Suchvorgangs auf

 Ermitteln der Linkrelation zum Abrufen der Ergebnisse eines Suchvorgangs

Rufe die URL zu einem Repository wie folgt auf:

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d
Accept: application/hal+json

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

Response


{
    "_links": {
        "searchresultwithmapping": {
            "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm",
            "templated": false
        }
    },
    "id": "d7f0a5a2-72d5-439d-8ea4-92958d77ba4d",
    "name": "MyCompany SharePoint - ExampleSite",
    "host": "https://mycompany.sharepoint.com",
    "clientId": "e5a8e525-febf-4c88-bdb5-f67a680cd424",
    "tenantId": "3324857c-429f-4aa1-bea3-a53d6d199b4a",
    "siteCollection": {
        "title": "ExampleSite",
        "path": "https://mycompany.sharepoint.com/sites/ExampleSite",
        "siteName": "https://mycompany.sharepoint.com/sites/ExampleSite"
    }
}

 Angeben von verhaltenssteuernden Parametern

Führe eine HTTP GET-Anforderung auf diese URL mit den benötigten Parametern aus.

Request


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?sourceid=/myapp/sources/mysource&sourceproperties={"myprop1":["Test E-Mail 1"]}&sourcecategories=["mycategory1"]&sourcepropertysort=myprop1&ascending=true&fulltext=test&page=1&pagesize=50
Accept: application/hal+json
ParameterTypBeschreibungPflicht
sourceidStringLegt fest, zu welcher Quelle die Zuordnung gehört, die für die Suche verwendet werden soll. Die Quelle muss existieren, damit die Eigenschaften unter sourceproperties angewendet werden.Ja
sourcePropertiesStringGibt eine Sucheinschränkung nach Eigenschaften aus Sicht der Quelle an. Sucheinschränkungen werden als JSON-Objekt erwartet. Gib die ID der zugeordneten Quelleneigenschaften an, um einen Suchvorgang auf beliebig viele Kriterien zu beschränken.
Beispiel: sourceproperties={"<ID_ source proptery1>":["<search refiner 1>", "<search refiner 2>"],"<ID_source proptery2>":["search refiner 3"]}
Nein
sourcecategoriesStringGibt ein JSON-Array mit Quellenkategorien an, in denen gesucht werden soll.
Beispiel: sourcecategories=["mycategory1","mycategory2"]
Nein
sourcepropertysortStringGibt die ID der zugeordneten Quelleneigenschaft an, nach der sortiert wird. Ist keine Sortiereigenschaft angegeben, erfolgt die Sortierung gemäß Standardsortierung anhand des Sortierkriteriums Geändert am.Nein
ascendingBoolGibt die Richtung der Sortierreihenfolge an.

ascending=true bewirkt eine aufsteigende Sortierung (von klein nach groß (A-Z) und von alt nach neu).

ascending=false: bewirkt eine absteigende Sortierung (von groß nach klein (Z-A) und von neu nach alt).

Wenn du keinen ascending-Parameter angibst, ist die Sortierung absteigend.
Nein
fulltextString Gibt einen Volltextsuchbegriff an.Nein
pageGanzzahlGibt an, welche Seite der Ergebnisliste angefordert wird. Wenn du keinen Parameter übermittelst, wird die Seite 1 angefordert.Nein
pagesizeGanzzahlGibt an, wie viele Elemente pro Seite angezeigt werden. Wenn du keinen Parameter übermittelst, werden 100 Elemente pro Seite angefordert.Nein

Als Ergebnis wird folgendes JSON-Objekt zurückgegeben: Response


{
  "_links": {
    "next": {
      "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?...page=2"
    },
    "self": {
      "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/srm?...page=1"
    }
  },
  "page": 1,
  "items": [
    {
      "_links": {
        "self": { "href": "/sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/o2m/<DMS-Object-ID>" }
      },
      "id": "<DMS-Object-ID>",
      "sourceProperties": [
        {
          "key": "myprop1",
          "value": "Test E-Mail 1",
          "isMultiValue": false
        },
        {
          "key": "myprop2",
          "value": "John Smith",
          "isMultiValue": false
        },
        "..."
      ],
      "sourceCategories": [ "mycategory1" ]
    },
    "..."
  ]
}
EigenschaftBeschreibung
_linksEnthält die Linkrelationen zum Element.

self: Self-Link.

next: Relative URL zum Abrufen der nächsten Seite der Ergebnisliste. Wird nur angegeben, wenn es weitere Ergebnisse gibt.

prev: Relative URL zum Abrufen der vorherigen Seite der Ergebnisliste. Wird nur angegeben, wenn es vorherige Ergebnisse gibt.
pageGibt die Seitennummer der Ergebnisliste an.
itemsGibt das Array mit Elementen der Ergebnisse für den Suchvorgang für die angeforderte Seite an.

 Struktur eines Elementes der Ergebnisliste

EigenschaftBeschreibung
_linksEnthält die Linkrelationen zu dem Element.

self: Self-Link.
idGibt die DMS-Object-ID des Elements an.
sourcePropertiesGibt das Array mit Quelleneigenschaften an, die für das Element vorhanden sind.

Wenn dieselbe Quelleneigenschaft mehreren SharePoint-Eigenschaften zugeordnet wurde, und das Element diese Eigenschaften besitzt, wird die Quelleneigenschaft mehrfach mit den jeweiligen Werten der SharePoint-Eigenschaft zurückgegeben.
sourceCategoriesGibt das Array mit den IDs der Quellenkategorien an, die für das Element zur Verfügung stehen. Es werden nur dann mehrere Kategorien zurückgegeben, wenn mehrere Quellenkategorien dem Inhaltstyp des Elements zugeordnet wurden.

 Struktur einer Quelleneigenschaft

EigenschaftBeschreibung
key Gibt den eindeutigen Bezeichner der Quelleneigenschaft an.
valueGibt den Wert der zugeordneten Eigenschaft an.
isMultiValueGibt an, ob die zugeordnete Sharepoint-Eigenschaft eine Mehrfacheigenschaft ist.

 Aufrufen der URL für die Details eines DMS-Objektes (JSON-Repräsentation)

Wenn Du erfolgreich ein DMS-Objekt angelegt hast, dann können die Details des DMS-Objektes wie folgt abgerufen werden:


GET /sharepointadapter/r/d7f0a5a2-72d5-439d-8ea4-92958d77ba4d/<DMS-Object-ID>?sourceid=/myapp/sources/mysource
Accept: application/json

Als Ergebnis wird folgendes JSON-Objekt zurückgegeben:


{
    "id": "<DMS-Object-ID>",
    "sourceCategories": [
        "mycategory1"
    ],
    sourceProperties: [
        {
            "key": "myprop1",
            "value": "Please verify the XYZ invoice"
        },
        {
            "key": "myprop2",
            "value": "Name1@contoso.com"
        }
    ]
}
EigenschaftBeschreibung
idGibt die Dokument-ID des DMS-Objektes an.
sourceCategoriesGibt das Array mit den IDs der Quellkategorien an, die für das angeforderte DMS-Objekt in Frage kommen.

Es werden dann mehrere Kategorien zurückgegeben, wenn für das DMS-Objekt mehrere Quellkategorien ausgewählt wurden.
sourcePropertiesGibt das Array mit den Quelleigenschaften an, die für das angeforderte DMS-Objekt vorhanden sind.

 Struktur einer Quelleigenschaft

EigenschaftBeschreibung
keyGibt den eindeutigen Bezeichner der Quelleigenschaft an.
valueGibt den Wert der zugeordneten SharePoint-Eigenschaft an.