Overview of the features of the "Microsoft SharePoint Graph-API" module

In this article, you will learn about the special features and characteristics of the Microsoft SharePoint (Graph-API) (ID=spog) module in edoc content services. This module is designed for communication with SharePoint instances that are hosted in Microsoft Azure.

Authentication method used in the "Microsoft SharePoint (Graph-API)" module

The SharePoint Graph API supports the Open Authorization 2 protocol (OAuth2) as authentication.

To enable edoc content services to access the Microsoft Graph API, you must register an app in the Azure Active Directory in the Azure Portal. After registration, you will receive the parameters TenantId and ClientId required for the connection string (ConnectionString).

You must also create a client secret in the Azure portal under Certificates & Secrets. Then enter the value for the client secret as the value for the ClientSecret parameter in the connection string.

Necessary permissions in the Azure portal for the "Microsoft SharePoint (Graph-API)" module

To enable edoc content services to access the SharePoint documents via the Microsoft Graph API, you must grant the corresponding API permissions in the Azure portal.

You have the option of granting edoc content services access to all SharePoint sites or only to certain SharePoint sites

You must grant the following application permissions if you want to access all SharePoint sites:

• API name: SharePoint

  • Permission name: Sites.ReadWrite.All

It is essential that you grant administrator approval for the application authorizations. This gives edoc content services access to all SharePoint pages of the client (tenant).

You can also grant access only to certain SharePoint sites.

You must grant the following application permissions if you only want access to certain SharePoint pages:

• API name: Microsoft Graph

  • Permission name: Sites.Selected

You must then grant the permission on the respective SharePoint page.

Here's how

1. Call up the corresponding page in the browser and add the following to the URL of the page: /_layouts/15/AppInv.aspx.

2. Enter the app ID of the created Azure AD app (client ID) on the page.

3. Click on Lookup so that the title is filled automatically.

4. Enter the app domain and the redirect URL in the corresponding fields.

5. Enter the following code in the Permission Request XML field:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope=http://sharepoint/content/sitecollection Right="FullControl" />
</AppPermissionRequests>

6. Click on Create.

Function of the ConnectionString parameter "ListId"

You can create lists and document libraries in Microsoft SharePoint.

You use the ConnectionString parameter ListId to tell edoc content services which of these lists or document libraries you want to connect to. In Microsoft SharePoint, lists and document libraries are technically the same, so the ListId parameter is used for both.

How to find the ID of a list or document library in SharePoint:

1. Call up the list or document library in the browser.

2. Click on Settings (the gear icon).

3. Click on the List settings or Library settings option. If you click on Library settings, you must also click on More library settings.

4. Copy the ID from the URL of the settings page from the address field of the browser.

In the Internet address of this settings page, the ID you are looking for is located between the curly brackets at the end of the URL.

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

The value for ListId in the example is e6748c56-669e-4b21-b4f6-a31b2f54c936.

Further information on encoded and masked characters in a URL can be found on the Internet.

What happens during the "ConnectionTest" action?

If you call the GET /ConnectionTest endpoint, the following is performed:

• The login to SharePoint is carried out.

• The technical properties of the specified list or document library are returned to edoc content services.

This ensures that both the user and password parameters and the ListId parameter are correct.

What are categories in the module?

Use the GET /Categories endpoint to retrieve the structure of a list or document library. A category in the context of the module in edoc content services represents a list or document library and the respective columns in Microsoft SharePoint.

How are content types taken into account?

If you call the GET /Categories endpoint, the content types are returned in addition to the structure of the list or document library. You can recognize the content types by the ID and the name. The ID and the name of the list or document library contain the ID and the name of the content type separated by a pipe character (|).

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

Important note on the handling of file names

The file name of a file that is uploaded to SharePoint with edoc content services changes for two reasons:

• The file name must be unique within a document library. In practice, however, it often happens that there are file names with the same name. For example, if you archive file attachments from e-mails, many attachments may simply be called Invoice.pdf. To ensure that the attachments can be clearly identified, a timestamp (time the file was uploaded) is added to the file name as a prefix. The file name Invoice.pdf becomes 2022-10-07-12-40-05-877517_Invoice.pdf.

• In SharePoint, a number of characters are not allowed in file names. Some of the invalid characters in SharePoint are valid characters for a file name in most operating systems. If these characters, which are invalid in SharePoint, are contained in the file name, they are replaced by an underscore (_). Invoice-smith&sons.pdf becomes invice-smith_sons.pdf. The following characters are replaced by default: ', #, ~, \, %, &, *, :, <, >, ?, /, {, }, |, ". A dot (.) in the file name is also replaced, unless it is the separator between the file name and the file extension.

Upload a new file version including changing the document properties

You can upload a new version of the file to an existing document in the module with the endpoint POST /Documents/{documentId} and change the properties of this document at the same time.

Search for documents

You can search for documents with the POST /Documents/search endpoint by specifying several properties and values as search criteria. The documents searched for must contain the specified value in the specified property.

For example, if you enter several search criteria, the search is linked with AND. In the following example, all documents are returned that have the vendor number 1234 and have entered Invoice as the type and that have been paid.

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

Unique document across the boundaries of a document library (ecmDocumentGuid)

Whenever you create a new document in a document library in SharePoint, the document is automatically assigned an ID. These IDs start with 1 and are incremented continuously. In practice, you may want to move documents from one document library to another. Moving a document is technically possible in principle, but the moved document receives a new ID from SharePoint, as the IDs in a document library must always be unique. With a new ID, however, you lose the reference in external systems.

edoc content services offers a mechanism to circumvent this problem:

In SharePoint, add the column ecmDocumentGuid (must be named exactly like this) to the document libraries. This column is recognized by edoc content services.

As soon as you create a new document, this column is automatically filled with a newly generated GUID (Globally Unique Identifier). The new GUID is always unique, regardless of which document library you move the document to.

The ID of a document in the ecmDocumentGuid column then looks like this: 53D67D38-F9AE-42A9-8360-24AE59DA55F0.

Special features of "NewDocuments" for reading new documents

You have two different options for retrieving new documents in an ECM system:

• You can use the POST /Documents/newDocuments endpoint to read new documents in the ECM system. You must specify the ID of the last document in the lastDocumentIndex property in the endpoint. edoc content services then searches for all documents whose ID is greater than lastDocumentIndex.

• If the document library has the column ecmDocumentGuid, lastDocumentIndex must be filled with the value from ecmDocumentGuid. If documents are found without a value in the ecmDocumentGuid column, a process is automatically executed by edoc content services in which this column is filled. Once the process is complete, all documents in the ecmDocumentGuid column have a corresponding value.

Further information on checking new documents can be found under: Check whether new documents are available in the destination system

What does "file" (folder) mean in the module?

In the context of Microsoft SharePoint, ECM files are always entries in a separate list. ECM files (folders) can never be entries in a document library in SharePoint.

The entries in the SharePoint list can contain data from an ECM file, such as the vendor number. You implement the logic of which data is stored in which relation in the application with which edoc content services is called up.

For more information about ECM files, see: Functions for managing files (folders)