This document has been developed for those customers’ end users who are using Shelf Knowledge Management System (Shelf KMS) with the Content Integration Layer feature to manage and handle various content both stored in Shelf KMS and in external platforms integrated via CIL. The document’s goal is to answer the following questions: 

• What is the Shelf Content Integration Layer?

• What purposes does this feature serve?

• What is a Microsoft SharePoint Connector?

• How is it configured?

• How is it used in practice?

If you require further assistance, feel free to contact us at support@shelf.io or from the in-app chat support within the Shelf platform.

For proper operation of your SharePoint connector and successful synchronization of your content from the Microsoft SharePoint platform into Shelf KMS, the following preconditions must be met:

• OpenSSL should be installed to perform CLI operations

• Azure Portal Access should be granted to the user under which you are going to perform configurations

• Azure Active Directory Administrator (or Azure Global Administrator) permissions should be granted to the user under which you are going to perform configurations; this level is required for registering applications and granting API permissions in Azure Active Directory

• Admin panel must be accessible on your Shelf KMS account

• Content items (articles, documents, etc.) must be available on your SharePoint account.

Before proceeding to learn how you can configure and use the Shelf integration with your SharePoint resources, you need to be aware of the following content-related constraint(s) coming from the Microsoft side.

When syncing content items from your SharePoint site to Shelf, the sync job may fail with the display of the error message shown on the figure below:

This failure to sync your content occurs when the number of items in your SharePoint library or list exceeds 5,000. Shelf Content Integration Layer and its connectors are not in control of this limitation, which is caused by Microsoft’s List View Threshold (LVT) threshold that is in place to help get consistent performance across all users with queries to the back-end database.

You can read more about the LVT limit and possible solution methods in the dedicated articles created by Microsoft: 

1. Overview of large lists and libraries 

2. The number of items in this list exceeds the list view threshold" when you view lists in Microsoft 365.

If you need additional information or support on this matter, feel free to contact Shelf Support.

• Published Pages only — Draft and checked-out pages are excluded from sync.

• Standard layouts only — Single-column, two-column, three-column, one-third/two-thirds split, and full-width layouts are supported. Content in "Flexible" layout sections is skipped entirely.

• Structure preserved, styling not — Section/column structure and content hierarchy are maintained. Visual styling (colors, fonts, backgrounds, spacing) is not replicated.

• SharePoint Site, being the root of Document libraries, Lists, and Pages, is the container of the highest level and is indirectly mapped at the stage of configuring SharePoint connection profile in Shelf (the Instance URL parameter/value in the RUNTIME SETTINGS block).

• In SharePoint, the top-level containers that hold content are Document libraries, Lists, and Site Pages.

• In Shelf, the top-level container is a Collection. Each connected SharePoint Document library or List appears as a Collection in Shelf. SharePoint Pages are synced as individual Gems (one Gem per published page).

• Folders: Any folder structure inside a connected library (and inside a List where folders are enabled) is preserved as nested Folders within the corresponding Shelf Collection. This includes folders at any depth.

• Content Items:
  • Files stored in a Document library become Gems inside the corresponding Shelf Collection (and within its folders, if applicable).

  • Content Items stored in a SharePoint List become Gems inside the corresponding Shelf Collection for that List.

• Pages: SharePoint Pages are stored in the Site Pages library on each SharePoint site. Each published Page becomes an individual Gem. Pages do not follow the Collection → Folder → Gem hierarchy. Files referenced on Pages appear as links within the Gem; the underlying files are synced separately as standalone Gems from the Images & Documents libraries. 

To work with synced Pages in KMS and for Content Intelligence to process them, you must grant permissions to the Site Pages collection in User Groups > [your user group] > Collection permissions.

• Document library example

  • SharePoint: Site A / "Policies" (Document library) / HR / 2024 / Code-of-Conduct.pdf

  • Shelf: Collection "Policies" → Folder "HR" → "2024" → Gem "Code-of-Conduct.pdf"

• List example

  • SharePoint: Site A / "FAQs" (List) with an item "How do I reset my password?"

  • Shelf: Collection "FAQs" → Gem "How do I reset my password?"

• Page example

  • SharePoint: Site A / Site Pages / "Company Holiday Policy" (published Page with text, a banner, and an embedded PDF)

  • Shelf: Gem "Company Holiday Policy" (extracted page content with a link to the PDF) + Gem "Holiday-Calendar-2025.pdf" (synced separately from the Images & Documents library)

• Selection scope: Each library and each list you select in the SharePoint Connector is created as a separate Collection in Shelf.

• Folder depth: Nested folders in SharePoint remain nested folders in Shelf without changes to depth.

• Content parity: Each SharePoint file or list item maps to a single Gem in Shelf, placed according to the original SharePoint hierarchy (Collection → Folder(s) → Gem).

• Naming: Shelf Collections typically mirror the names of their source libraries/lists. Folder names and item titles/file names are also preserved.

• Pages — published only: Only Pages in the "Published" state are synced. Draft or checked-out Pages are excluded.

• Pages — web part coverage: 6 web part types are currently supported (see the supported web parts table above). Unsupported types appear as blank areas. Additional web part types will be supported in future updates.

• Pages — embedded files as links: Files on a Page appear as links in the page Gem. The files themselves are synced separately from the Images & Documents library. This is by design.

• Pages — Flexible layouts excluded: Content in "Flexible" section layouts is not synced. Use standard layouts to ensure content is captured.

• SharePoint Document library: 
  https://support.microsoft.com/en-us/office/create-a-document-library-in-sharepoint-306728fe-0325-4b28-b60d-f902e1d75939

• SharePoint Folder (in a Document library): 
  https://support.microsoft.com/en-us/office/create-a-folder-in-a-document-library-3d6a8c11-2490-4d6b-8837-f25649a69c56

• SharePoint List: 
  https://support.microsoft.com/en-us/office/create-a-list-0d397414-d95f-41eb-addd-5e6eff41b083

• SharePoint Pages (Site Pages): 
  https://support.microsoft.com/en-us/office/create-and-use-modern-pages-on-a-sharepoint-site-b3d46deb-27a6-4b1e-87b8-df851e503dec

Understanding this mapping up front makes configuration choices and the downstream behavior of the Shelf Content Integration Layer more predictable when integrating with SharePoint.

In-depth configurations and use cases of the Shelf Content Integration Layer are described in the dedicated Shelf Content Integration Layer Feature User Guide mentioned above, but the short example of the CIL workflow is as follows:

1. You access the Content Integration Layer feature in your Shelf KMS (Admin panel).

2. You select one of Shelf-preconfigured connectors or create your custom one (based on the external content repository from which you need to sync content)

3. You create a connection profile that uses the selected or created connector, and configure it: indicate credentials (username/password/API key/token/etc.) to access your external repository. All these credentials and access details can be taken from that external platform, and in the respective section below we will show you how to get them on Microsoft SharePoint.

4. You create a sync flow that uses the created connection profile and configure this sync flow to run either on some specific schedule or on demand. It is here where you can apply filters to tell CIL which exactly content needs to be synced. 

5. You run the created sync flow manually (if set to run on demand) or wait for the scheduled run, and get your content from the needed external source right in Shelf KMS.

For the proper operation of the SharePoint connector to sync your content from Microsoft SharePoint into Shelf KMS, you need to do certain actions in Microsoft SharePoint, Azure and in Shelf.  Read the chapters below to learn what exactly you need to do.

Before proceeding to creating the dedicated apps on Azure, you first need to generate a self-signed certificate that is needed to authorize your Azure apps to access Shelf and vice versa. 

To generate your certificate, complete the following steps.

1. Make sure you have OpenSSL of the latest released version installed on your computer. To do so, open a terminal or a command prompt utility and run the following command
   
   

   Shell openssl version

   
   

   If OpenSSL is installed on your computer, the command will return the version of the installed OpenSSL.
   
   

   Shell C:\Windows\system32>openssl version OpenSSL 3.4.1 11 Feb 2025 (Library: OpenSSL 3.4.1 11 Feb 2025)

   
   

2. Run the following command in your OS-specific terminal
   
   

   Shell openssl req -x509 -newkey rsa:2048 -keyout private.key -out cert.crt -days 365 -nodes -subj "/CN=ShelfConnectors"

   
   

At this step, you need to create a single PEM file by combining the previously generated self-signed certificate and its private key. To do that, run the following command in your terminal

The output should be a file named azure-cert.pem that contains both the certificate and private key. The PEM file, logically, is saved to the same location where the certificate and private key are stored.

At this stage of configurations, you need to create the Connector app in Azure. To do so, follow the below steps.

1. Log in to your account on Azure Portal using the Admin credentials.

2. In the search field on top of the page look for and navigate to App registrations.Figure 2. Finding and selecting the App registrations menu in Azure

3. On the App registrations page, find and select + New registration.
   

   Figure 3. Initiating new registration on Azure

   
   

4. In the form that appears, enter the name for the new app registration - Connector app, and click Register. No other selections/configurations are needed in this form.Figure 4. Registering Connector app on Azure

5. Once Connector app is registered, you are redirected to its page. 

1. When on the Connector app page, under the Manage menu (1) in the navigation panel, find and select the Certificates & secrets option (2). 

2. Then select the Certificates tab (3) and press Upload certificate (4).Figure 5. Accessing Connector app’s certificates and secrets menu and initiating certificate upload

3. In the panel that opens in the right part of the page, upload the previously generated cert.crt file and add some description for it. Press Add once done.Figure 6. Uploading certificate 

   
   

1. After the certificate is added to Connector app, open the API permissions option (1) in the menu, and on the Connector app’s permissions page, select + Add a permission (2).Figure 7. Accessing Connector app’s API permissions settings

2. In the pane that appears, select the SharePoint option (3).

   

   Figure 8. Selecting SharePoint for Connector app’s API permissions

3. In the window that appears in the right pane, select the Application permissions option (4) and then select the Sites.Selected checkbox (5). Click Add permissions (6) to save changes.Figure 9. Adding Sharepoint Sites.Selected permissions to Connector app

   Permission	Description
   Sites.Selected	This permission is used specifically to assign a specific SharePoint site in the next step via API (using the Manage Permissions app). It neither provides access to ALL your SharePoints sites nor grants any other permissions to the apps.

   
   

   
   

4. Now you need to get admin consent for Your Tenant on these permissions. If you have the admin level, you can do it yourself by clicking the respective button as shown below. Otherwise, contact your organization’s Azure admin and ask them to do that.

Figure 10. Granting admin consent for Your Tenant

1. Repeat Step 1 from the procedure above.

2. In the pane that appears, select the Microsoft Graph option (2).Figure 11. Selecting Microsoft Graph for Connector app’s API permissions

3. In the window that appears in the right pane, select the Application permissions option (3), in the search field (4) below look for Sites.Selected, and then expand the Sites section (5) and select the Sites.Selected checkbox (6). Click Add permissions (7) to save changes.Figure 12. Viewing added Microsoft Graph permission for Connector app

4. Now you need to get admin consent for Your Tenant on these permissions. If you have the admin level, you can do it yourself by clicking the respective button as shown below. Otherwise, contact your organization’s Azure admin and ask them to do that. Figure 13. Granting admin consent for Your Tenant for Microsoft Graph permission

The Manage Permissions app you are about to create does not share any credentials you may enter here with Shelf. The Manage Permissions app is simply sharing the connector that will be created. See more in Configurations on Microsoft SharePoint side section

1. On Azure Portal, navigate again to App registrations and add a new registration as shown in Figures 2 and 3 above.

2. In the new app registration form, enter the needed name - Manage Permissions app - and click Register. Leave other fields and checkboxes unchanged. 

   Figure 14. Initiating Manage Permissions app registration

   
   

Once the app is registered, you are redirected to its page and see the respective notification on top of the page.

Figure 15. Viewing Manage Permissions app page

Now, you need to add specific permissions to the app you have just registered, and then grant admin consent for Your Tenant for it. Follow the below steps.

1. When on the Manage Permissions app page, find and select the API permissions option in the navigation panel as shown in Figure 15 above. 

2. On the page that opens, find and select + Add a permission.

   Figure 16. Initiating permissions granting to Manage Permissions app

   
   

3. In the pane that appears, select the Microsoft Graph option and then select the Application permission option. 

   Figure 17.  Selecting Microsoft Graph

4. In the permissions list that expands below, find and select the following permissions by checking the relevant boxes as listed below. Then confirm changes by clicking Add permissions.

Application: 

• Application.Read.All

AppRoleAssignment

• AppRoleAssignment.ReadWrite.All

Sites

• Sites.FullControl.All

Figure 18. Granting Microsoft Graph permissions

Explaining permissions

Permission	Description
Application.Read.All	This permission is required because the Manage Permissions app must be able to read other applications, in our case the Connector app, for providing granular permissions to SharePoint site(s).
AppRoleAssignment.ReadWrite.All	This permission is specifically required to assign new roles/access to other applications, such as the Connector app.
Sites.FullControl.All	This permission is necessary because the Manage Permissions app must have control over sites to assign a selected site to a specific app (in our case the Connector app).

  5. Now, click + Add a permission again but this time select not Microsoft Graph but SharePoint. 

Figure 19. Selecting SharePoint for granting permissions for Manage Permissions app

  6. Then, select the Application permissions option and scroll down to find the Sites.FullControl.All permission. Select it by     checking the relevant box and confirm your selection by clicking Add permissions.Figure 20. Adding specific SharePoint permissions   7.  Once done, all the selected permissions are added. However, to allow Manage Permissions app to make use of them, you need to grant admin consent on these permissions for Your Tenant. If you have the admin level, you can do it yourself by clicking the respective button as shown below. Otherwise, contact your organization’s Azure admin and ask them to do that.

Figure 21. Viewing added permissions and adding admin consent on them for Your Tenant