Übersicht über die Eigenheiten des SharePoint-Moduls

In diesem Artikel lernen Sie die Besonderheiten und Eigenheiten des Moduls SharePoint in edoc content services kennen. Das Modul SharePoint verwendet die SharePoint REST-API aus dem Jahr 2013, die mit einem Microsoft SharePoint-Server kommuniziert.

Wenn Sie einen On-Premises-Server mit Microsoft SharePoint verwenden, müssen Sie dieses Modul verwenden.

Verwendete Authentifizierungsmethode im SharePoint-Modul

Die SharePoint REST-API unterstützt lediglich die Standardauthentifizierung Basic Auth (Basic Authentication), also eine Anmeldung mit Benutzernamen und Passwort.

Unterschiede bei der Legacyauthentifizierung und den modernen Authentifizierung

Wenn bei den Aufrufen zu einem Microsoft SharePoint-Server der HTTP-Status “502 Bad Gateway” mit einer Meldung zurückgesendet wird, die www-authenticate header enthält, prüfen Sie die Zugriffssteuerung in SharePoint. Im Abschnitt Apps, die keine moderne Authentifizierung verwenden muss die Option Zugriff zulassen aktiviert sein.

Möchten Sie die offene Autorisierung OAuth2 (Open Authorization 2) verwenden, müssen Sie das Modul SharePoint Graph-API verwenden. Weitere Informationen finden Sie unter: Übersicht über die Eigenheiten des SharePoint Graph-API-Moduls

Funktion des ConnectionString-Parameters “ListId“

Sie können in Microsoft SharePoint Listen und Dokumentbibliotheken erstellen.

Mit dem ConnectionString-Parameter ListId teilen Sie edoc content services mit, zu welche dieser Listen oder Dokumentbibliotheken Sie eine Verbindung herstellen möchten. In Microsoft SharePoint werden Listen und Dokumentbibliotheken technisch gleich, sodass der Parameter ListId für beides verwendet wird.

So finden Sie die ID einer Liste oder Dokumentbibliothek in SharePoint:

Rufen Sie Liste oder Dokumentbibliothek im Browser auf.
Klicken Sie auf Einstellungen (das Zahnradsymbol).
Klicken Sie auf die Option Listeneinstellungen bzw. Bibliothekseinstellungen. Wenn Sie auf Bibliothekseinstellungen klicken, müssen Sie noch zusätzlich auf Weitere Bibliothekseinstellungen klicken.
Kopieren Sie aus dem Adressfeld des Browsers die ID aus der URL der Einstellungsseite.

In der Internetadresse dieser Einstellungsseite befindet sich die gesuchte ID zwischen den geschweiften Klammern am Ende der URL.

https://myTenant.sharepoint.com/_layouts/15/listedit.aspx?List={e6748c56-669e-4b21-b4f6-a31b2f54c936}

Der Wert für ListId lautet im Beispiel e6748c56-669e-4b21-b4f6-a31b2f54c936.

Gut zu wissen

Wenn Sie die gesamte URL aus der Adressleiste des Browsers kopieren und woanders einfügen, werden Sie keine geschweiften Klammern finden. Bestimmte Zeichen (z.B. Leerzeichen, runde Klammern, geschweifte Klammern) werden in der URL maskiert. Geschweifte Klammern werden mit der Zeichenfolge %7D maskiert, sodass die URL im Beispiel so aussieht: https://myTenant.sharepoint.com/_layouts/15/listedit.aspx?List=%7De6748c56-669e-4b21-b4f6-a31b2f54c936%7D

Der Wert für ListId befindet sich zwischen den beiden Zeichenfolgen %7D.

Weitere Informationen zu encodierten und maskierten Zeichen in einer URL finden Sie im Internet.

Was passiert bei der Aktion “ConnectionTest”?

Wenn Sie den Endpunkt GET /ConnectionTest aufrufen, wird Folgendes durchgeführt:

Die Anmeldung in SharePoint wird durchgeführt.
Die technischen Eigenschaften der angegebenen Liste oder Dokumentbibliothek werden an edoc content services zurückgegeben.

Auf diese Weise wird sichergestellt, dass sowohl die Parameter user und password als auch der Parameter ListId korrekt sind.

Was sind Kategorien im Modul?

Mit dem Endpunkt GET /Categories rufen Sie die Struktur einer Liste oder einer Dokumentbibliothek ab. Eine Kategorie im Kontext des Moduls in edoc content services repräsentiert eine Liste oder Dokumentbibliothek und die jeweiligen Spalten in Microsoft SharePoint.

Wie werden Inhaltstypen (Content types) berücksichtigt?

Wenn Sie den Endpunkt GET /Categories abrufen, werden zusätzlich zur Struktur der Liste oder Dokumentbibliothek auch die Inhaltstypen zurückgeliefert. Sie erkennen die Inhaltstypen an der ID und dem Namen. In der ID und im Namen der Liste oder der Dokumentbibliothek befinden sich die ID und der Name des Inhaltstyps getrennt durch ein Pipe-Zeichen (|).

JSON

[
  {
    "properties": [
      {
        "id": "Title",
        "name": "Title",
        "type": "Text",
        "isRequired": false,
        "alias": "Title"
      },
      {
        "id": "invoice_x0020_number",
        "name": "invoice number",
        "type": "Text",
        "isRequired": false,
        "alias": "invoice number"
      },
    ],
    "id": "e6748c56-669e-4b21-b4f6-a31b2f54c936",
    "name": "invoice library"
  },
  {
    "properties": [
      {
        "id": "Title",
        "name": "Title",
        "type": "Text",
        "isRequired": false,
        "alias": "Title"
      },
      {
        "id": "invoice_x0020_date",
        "name": "invoice date",
        "type": "DateTime",
        "isRequired": false,
        "alias": "invoice date"
      }
    ],
    "id": "e6748c56-669e-4b21-b4f6-a31b2f54c936|0x01010082946529B238E9498A2926B1E7699B6F",
    "name": "invoice library|document"
  }
]

Besonderheiten bei der Behandlung von Dateinamen

Der Dateiname einer Datei, die mit edoc content services in SharePoint hochgeladen wird, ändert sich aus zwei Gründen:

Innerhalb einer Dokumentbibliothek muss der Dateiname eindeutig sein. In der Praxis kommt es aber oft vor, dass es gleichlautende Dateinamen gibt. Wenn Sie z.B. Dateianhänge von E-Mails archivieren, können viele Anhänge einfach nur Rechnung.pdf heißen. Damit die Anhänge eindeutig identifiziert werden können, wird ein Zeitstempel (Zeitpunkt des Uploads der Datei) als Präfix in den Dateinamen eingefügt. Aus dem Dateinamen Rechnung.pdf wird 2022-10-07-12-40-05-877517_Rechnung.pdf.
In SharePoint sind eine Reihe von Zeichen in Dateinamen unzulässig. Einige der unzulässigen Zeichen in SharePoint sind in den meisten Betriebssystemen gültige Zeichen für einen Dateinamen. Wenn diese in SharePoint ungültigen Zeichen im Dateinamen enthalten sind, werden sie durch einen Unterstrich (_) ersetzt. Aus invoice-smith&sons.pdf wird invice-smith_sons.pdf. Folgende Zeichen werden standardmäßig ersetzt: ', #, ~, \, %, &, *, :, <, >, ?, /, {, }, |, “. Ein Punkt (.) im Dateinamen wird ebenfalls ersetzt, außer es handelt sich um das Trennzeichen zwischen Dateiname und Dateierweiterung.

Hochladen einer neuen Dateiversion inklusive Ändern der Dokumenteneigenschaften

Sie können im Modul mit dem Endpunkt POST /Documents/{documentId} eine neue Version der Datei in ein vorhandenes Dokument hochladen und gleichzeitig die Eigenschaften dieses Dokuments ändern.

Suchen nach Dokumenten

Sie können mit dem Endpunkt POST /Documents/search nach Dokumenten suchen, indem Sie mehrere Eigenschaften und Werte als Suchkriterium angeben. Die gesuchten Dokumente müssen den angegebenen Wert in der angegebenen Eigenschaft enthalten.

Wenn Sie z.B. mehrere Suchkriterien werden bei der Suche mit UND verknüpft. Im folgenden Beispiel werden alle Dokumente zurückgeliefert, die die Lieferantennummer 1234 haben und als Typ Rechnung eingetragen haben und die bezahlt sind.

JSON

{
  "vendor number": "1234",
  "type": "invoice",
  "paid": "false"
}

Eindeutiges Dokument über die Grenzen einer Dokumentbibliothek hinweg (ecmDocumentGuid)

Immer wenn Sie ein neues Dokument in einer Dokumentbibliothek in SharePoint erstellen, erhält das Dokument automatisch eine ID. Diese IDs beginnen mit 1 und werden fortlaufend hochgezählt. In der Praxis kommt es vor, dass Sie Dokumente von einer Dokumentbibliothek in eine andere Dokumentbibliothek verschieben möchten. Das Verschieben eines Dokuments ist prinzipiell technisch möglich, aber verschobene Dokument erhält von SharePoint eine neue ID, da die IDs in einer Dokumentbibliothek immer eindeutig sein müssen. Mit einer neuen ID verlieren Sie jedoch die Referenz in externen Systemen.

edoc content services bietet einen Mechanismus, um dieses Problem zu umgehen:

Fügen Sie in SharePoint in den Dokumentbibliotheken die Spalte ecmDocumentGuid (muss exakt so heißen) ein. Diese Spalte wird von edoc content services erkannt.

Sobald Sie ein neues Dokument erstellen, wird diese Spalte automatisch mit einer neu generierten GUID (Globally Unique Identifier) gefüllt. Die neue GUID ist immer eindeutig, ganz gleich in welche Dokumentbibliothek Sie das Dokument verschieben.

Die ID eines Dokuments in der Spalte ecmDocumentGuid sieht dann so aus: 53D67D38-F9AE-42A9-8360-24AE59DA55F0.

Besonderheiten von “NewDocuments” zum Auslesen neuer Dokumente

Sie haben zwei unterschiedliche Optionen, neue Dokumente in einem ECM-System abzurufen:

Mit dem Endpunkt POST /Documents/newDocuments können Sie im ECM-System neue Dokumente auslesen. Sie müssen im Endpunkt in der Eigenschaft lastDocumentIndex die ID des letzten Dokuments angeben. edoc content services sucht dann nach allen Dokumenten deren ID größer als lastDocumentIndex ist.
Wenn die Dokumentbibliothek die Spalte ecmDocumentGuid hat, muss lastDocumentIndex mit dem Wert aus ecmDocumentGuid gefüllt werden. Wenn Dokumente ohne Wert in der Spalte ecmDocumentGuid gefunden werden, wird automatisch ein Prozess von edoc content services ausgeführt, bei dem diese Spalte gefüllt wird. Nach Abschluss des Prozesses haben alle Dokumente in der Spalte ecmDocumentGuid einen entsprechenden Wert.

Weitere Informationen zum Prüfen von neuen Dokumenten finden Sie unter: Prüfen, ob neue Dokumente im Zielsystem vorhanden sind

Was bedeutet “Akte” (Folder) im Modul?

Im Kontext von Microsoft SharePoint sind ECM-Akten immer Einträge in einer separaten Liste. ECM-Akten (Folder) können in SharePoint niemals Einträge in einer Dokumentbibliothek sein.

Die Einträge in der SharePoint-Liste können Daten einer ECM-Akte enthalten, wie z.B. die Lieferantennummer. Sie implementieren die Logik, welche Daten in welcher Relation gespeichert werden, in der Anwendung, mit der edoc content services aufgerufen wird.

Weitere Informationen zu ECM-Akten finden Sie unter: Funktionen zum Verwalten von Akten (Folders)