Setup

Before we can use the Document ADM on to retrieve documents from SharePoint we must setup an app registration in Azure and configure settings in the profiles.

Note

The current version of the Document ADM on Graph is only supported on SharePoint Online. If you are using on-premise the Document ADM is not supported as the Graph API is used.

1. App Registration

The first step is setting up or updating your existing app registration. The Document ADM executes actions to SharePoint on behalf of users so we must update the existing app registration used for the Microsoft provider. This means we're setting up delegated permissions so they run on behalf of the user and the user can only do actions according to their permissions in SharePoint.

Warning

Using another app than the Microsoft provider app registration will not work for the on behalf flow.

Adding New API Permission

To be able to execute actions to SharePoint on behalf of the current user, you'll need to set an extra permission named Sites.ReadWrite.All on the existing app registration.

1. Identity the app registration which is configured in the Microsoft Provider of the Ometa Business Connector.

   

2. Click on the API permissions in the navigation tree on the left of the application registration

3. Click on Add a permission

4. Click on the tile Microsoft Graph

5. Choose Delegated permissions as permission type

6. Choose Sites.ReadWrite.All and click Add permissions

   

7. Grant admin consent to the new API permission.

   

2. Filling in the Profile

The next step is to fill in the REST and OData profiles used by the Document ADM.

Important

If you would like to use the new recycle bin view, this is currently only supported in the beta version of the Graph API. Update the Service Url / Url field in the profiles from 'https://graph.microsoft.com/v1.0' to 'https://graph.microsoft.com/beta'.

REST - Graph - On Behalf Of

Fill in the REST - Graph - On Behalf Of profile, this profile is used to do the Graph API calls using the REST interface.

1. Fill in the OAuth Client ID field, replace {client ID} with the application (client) ID and replace {tenant ID} with the directory (tenant) ID. You can find those ID's on the overview page of the app registration.
2. Fill in the Certificate PEM Path with the subject of your certificate used for the authentication.

OData - Graph - On Behalf Of

Fill in the OData - Graph - On Behalf Of profile, this profile is used to do the Graph API calls using the OData interface.

SharePoint Building Blocks - On Behalf Of

This profile is used to upload documents using the Graph API. Fill in this profile to ensure proper handling of custom DLL calls.

Important

Make sure the ClientID has the client ID and tenant ID in the following format: clientID@tenantID.

1. Fill in the Client ID field, replace {client ID} with the application (client) ID and replace {tenant ID} with the directory (tenant) ID.
2. Fill in the SharePointOnlineAzureADCertificate with the subject of your certificate used for the authentication.
3. Change the SharePointOnline field to True.

3. Setting Up the SharePoint Document Library

The document ADM works with a SharePoint document library. By default the document ADM will work with some custom fields that needs to be added to the library. The following fields should be added:

• Document Type: choice field to specify the type of the document, can be set to multi value.
• Document Tag: a text field to set the tag of the document.
• Year: the year of the document.

Warning

If you are using other fields you can modify your custom document ADM object. Make sure to also create those fields on the SharePoint document library itself. The method Update Item Properties should also be modified, this interface script contains a body with the fields to update. The internal name should be used.

You can use the standard building block Ensure Generic Document Library in the object SharePoint.BuildingBlocks.Lists.

Configure this method on your lifecycle or execute this method to create the generic list.

Troubleshooting

Configuration Issue Authentication

A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details. Original exception: AADSTS700027: The certificate with identifier used to sign the client assertion is not registered on application.

This error is triggered because the app used in the profiles is different from the app registration used for the Microsoft provider.

The specified list was not found

If you're having trouble with the error "The specified list was not found" even though the title is correct, this means your user doesn't have permission to retrieve the list. Make sure the permissions on the app are properly set as specified in this article and verify if admin consent is granted. Also check if you're using the correct app in the profile.

If everything is set properly it may be an old token is cached before you set the correct permissions. Remove the token in the ident.userTokens to clear the cache. Execute the following SQL script in Ometa Framework database to clear the token, modify the profile if you changed the profile on the views on the object:

DELETE FROM [ident].[UserTokens]
WHERE [ProfileName] = 'REST - Graph - On Behalf Of' OR [ProfileName] = 'OData - Graph - On Behalf Of'

After you've cleared the user token, you can refresh the page with the document ADM and it should work now.

Excessive Paging Error

Excessive paging requests (currently 100) were blocked by the REST interface. Increase the page size to reduce the total number of requests going back and forth.

This error is raised by Ometa to prevent reading too much data causing performance issues. It only occurs on SharePoint lists with more than 10.000 items: 100 pages x 100 documents. And only when the all records are required: most commonly when sorting a column in ADM.

Because the Graph API does not support filtering and sorting on all columns, Ometa does this locally and may have to fetch far more data than is just shown on the view. Due to this, it will start to slow down with more items in the list.

When configuring an object, Ometa doesn't know how many items exist in the list. It assumes fewer than 10,000 items and leaves filtering and sorting enabled by default. We recommend disabling filtering and sorting on large lists / folders (5.000+) if the excessive paging error occurs or significant slow down is happening.

See REST interface paging for more details on the safeguard.