Overview of the features of the "Microsoft SharePoint" module

In this article, you will learn about the special features and characteristics of the Microsoft SharePoint (OData, REST-API v.1) module in edoc content services. The Microsoft SharePoint (OData, REST-API v.1) module uses the SharePoint REST-API from 2013, which communicates with a Microsoft SharePoint server.

If you use an on-premises server with Microsoft SharePoint, you must use this module.

Authentication method used in the "Microsoft SharePoint (OData, REST-API v.1)" module

The SharePoint REST-API only supports the standard authentication Basic Auth (Basic Authentication), i.e. a login with user name and password.

If you want to use the open authorization OAuth2 (Open Authorization 2), you must use the Microsoft SharePoint (Graph API) module. For more information, see: Overview of the features of the "Microsoft SharePoint Graph-API" module

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)