Shelf SharePoint Connector Guide


Document version history

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

05 Oct 2023

Expired

1.1

Shelf

The document has been updated to include the description of providing Read access to specific collections on SharePoint. New imagery and text descriptions have been added. The existing figure numbering has been updated.

23 Aug 2024

Active






















Document purpose

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.

Glossary

Prior to starting to learn about the SharePoint connector and its configuration and usage, you need to learn the terminology used by Shelf.

Shelf NextGen KMS (Next Generation Knowledge Management System) is a knowledge management platform that employs AI capabilities to create, edit, process, store, export/import, and otherwise handle various content. The platform sports multiple AI-enabled features such as Search Copilot, Analytics Copilot, Semantic Search, Content Intelligence etc., all of which are intended to optimize and centralize customer organizations’ knowledge and provide fast, accurate, and consistent answers.

The Content Integration Layer (CIL) in Shelf Knowledge Management System (Shelf NextGen KMS) is a feature that allows for the seamless integration of various types and formats of content into the system. It enables users to sync content from various sources and knowledge repositories.

A connector is an entity that defines which external Content Management System Shelf NextGen KMS needs to connect to via Content Integration Layer (e.g. the SharePoint connector is a set of API parameters to define how to connect Shelf to Microsoft SharePoint). Shelf NextGen KMS has a set of preconfigured connectors (SharePoint, Contentful, Zendesk, Confluence connectors, etc.) but also allows for creating the custom ones.

A connection profile is a feature that allows users to establish a connection to various external applications or sources. It enables seamless integration and collaboration between Shelf NextGen KMS and other platforms such as external content repositories. Using Shelf’s connection profiles, users can import and synchronize various content and generally streamline workflows between Shelf NextGen KMS and external systems. This feature enhances the overall efficiency and effectiveness of knowledge management processes by enabling easy access to relevant information from different sources within the Shelf platform.

A sync flow is a feature that is responsible for the synchronization of content from external sources to Shelf NextGen KMS. Shelf’s sync flows can work on schedule or on demand, making it a versatile tool for content synchronization and prompt knowledge delivery.


Prerequisites

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

  • Admin Panel must be accessible on your Shelf NextGen KMS account
  • All preliminary configurations must be performed for your SharePoint account
  • Content items (articles, documents, etc.) must be available on your SharePoint account
  • Docker needs to be installed and configured to set up required permissions for SharePoint via PowerShell.



Content Integration Layer and its purpose

The Content Integration Layer feature makes it possible to integrate various content types and formats into a single platform, Shelf NextGen KMS, from where users can further derive useful information to deliver accurate and relevant answers to their clients.

The Content Integration Layer ensures that content is indexed, tagged, and categorized appropriately, making it easily searchable and accessible to users within the knowledge management system. It provides capabilities for content mapping, transformation, and synchronization, enabling the consolidation and synchronization of data from multiple sources.

CIL also ensures that the latest version of content is always available to users and facilitates efficient content updating and maintenance.

Overall, the Content Integration Layer plays a crucial role in providing a centralized repository of relevant and up-to-date information, making it easier for users to find and access the knowledge they need.

The detailed information about the CIL feature can be found in the relevant chapters of the Shelf Content Integration Layer Feature User Guide.


Understanding the Content Integration Layer workflow

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 NextGen 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 NextGen KMS.

For the proper operation of the SharePoint connector to sync your content from Microsoft SharePoint into Shelf NextGen 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.



Configurations on the Microsoft SharePoint side

Before making the configurations described below, make sure you have the Microsoft SharePoint Admin permissions. If you have such a permissions level, you can expect to see the following window after logging in to your Microsoft SharePoint account.

Figure 1. Verifying the SharePoint Admin permissions

If you do not have such a role, contact your organization’s SharePoint administrators and consult with them on this matter.


Registering and configuring SharePoint application in Azure and SharePoint

The next stage of configurations on the Microsoft side is to register your SharePoint application with Azure. This step is needed not only to make your SharePoint application a trusted one but also to set up a proper authentication method Shelf NextGen KMS will use to access the Microsoft SharePoint platform and sync content from it.

To complete this stage, follow the below procedure.


1. Go to https://portal.azure.com/ and log in using credentials under which you log in to your Microsoft SharePoint account.
2. In Azure, search for App registrations by starting to enter it in the search field. Select the found menu.

Figure 2. Finding and selecting the App registrations menu in Azure


3. In the App registrations window, find and click + New registration.

Figure 3. Starting to register your SharePoint application in Azure


4. In the next window, enter the desired name for your SharePoint application and select the account type based on your organization’s configurations. In our case, we use a single tenant account type. Following that, click Register.

Figure 4. Setting the app’s name and account type

Once you see the below toast message, your application has been successfully registered with Azure but requires some additional configurations that are described below.


5. After registering the application, you are redirected to your application page. In this page, find and open the Certificates and secrets option from the left sidebar navigation menu.

Figure 5. Accessing your application’s certificates and secrets and creating new secret


6. In the new window that appears, click + New client secret to create a secret for your SharePoint application.
7. In the form that appears on the right, enter the relevant value in the Description field and set your secret expiration period. Once done, click Add.
8. Once the secret is created, you can see and copy it (from the Value column) for further use. Save it to some file.

Figure 6. Viewing and copying the secret for your SharePoint application


9. After finishing here, go to the Overview option in the navigation menu. Find and copy your Application (client) ID and Directory (tenant) ID. The latter is also identified as Realm (for the Shelf NextGen KMS purposes). Save them to some local file for further use.

Figure 7. Viewing and copying your SharePoint Application ID and Directory ID


10. After completing Step 9 you are done with Azure configurations. Now go to your SharePoint Admin page at

https://<your_domain>-admin.sharepoint.com/_layouts/15/appinv.aspx

where <your_domain> needs to be replaced with your real SharePoint domain


11. In this page, enter your Application (client) ID, which you have previously copied from Azure’s Overview page, into the respective App Id and title field. Click Lookup. The name of your application is autopopulated in the relevant - Title - field.

Figure 8. Finding your app and creating its permissions 


12. Fill in the App Domain and Redirect URL fields as shown in Figure 8 above.
13. In the App’s Permission Request XML (Field no.4 on the figure above), enter the suitable XML code:

if you want users to have read access to a specific collection only

<AppPermissionRequests AllowAppOnlyPolicy="true">  

   <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" 

    Right="Read" />

</AppPermissionRequests>


if you want users to have read access to all collections stored on the Microsoft SharePoint account

<AppPermissionRequests AllowAppOnlyPolicy="true">

  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="Read" />

</AppPermissionRequests>


14. Depending on the XML code you have entered as instructed in Step 13 above, perform the following actions:

If you want users to have read access to all Microsoft SharePoint collections, click Create and then, in the new window that appears, press Trust It to verify that you trust your SharePoint application.

Figure 9. Confirming that you trust SharePoint app - Read All collections case


If you want users to have read access to the specific collection of Microsoft SharePoint only, click Create and then, in the new window that opens, select the desired collection from the dropdown list (NB: you can select only one collection at a time; if you want to add more collections, repeat all steps starting from Step 9). Press Trust It to verify that you trust your SharePoint application.

Figure 10. Confirming that you trust SharePoint app - Read Specific Collection case

📢

It may occur that when selecting the needed collection from the dropdown list you will see instead of the correct collection names some odd ones, like shown in the figure below.

To fix this issue and see the correct names, you need to remove the -admin suffix in the URL address of your SharePoint domain.

This action will navigate you to the old design of the app creation and permission granting page.

Populate the needed fields as described above and click Create. Now the collection names in the dropdown list should have the correct look.


15. The next step is to enable custom app authentication (which is disabled by default) for your SharePoint account. The most efficient and easy way to do it is running PowerShell via Docker (which has been previously installed and configured on your local machine). Execute the following command in the terminal:

docker

docker run --rm -it m365pnp/powershell


16. After running this command, you can expect to see the below response:


17. Once you see it, enter the command responsible for allowing you to sign in to your account:

Connect-PnPOnline -PnPManagementShell


18. This command returns a response with the prompt to enter your domain URL. Enter it - https://<your_domain>-admin.sharepoint.com - and hit Enter.

19. Continue to follow and fulfill prompts you see. In particular, the prompt telling you how to sign in to your account (see the image below). Make sure to enter the proper code you are provided with.


20. After a successful sign-on, go back to PowerShell and run the following command to enable custom app authentication:

Set-PnPTenant -DisableCustomAppAuthentication $false


Once you have successfully completed all the above steps and configurations laid down in them, you are done with registering and configuring your SharePoint application in Azure and on Microsoft SharePoint platform. You can now use your SharePoint site as a source from which Shelf NextGen KMS can sync content. Make sure to add the needed content to the site.



Configurations on the Shelf side

This chapter and its subsections describe the steps you need to take to get your SharePoint connector configured and ready for use.


Accessing Content Integration Layer

From the standard workflow described above you see that to start configuring and using your SharePoint connector you need to access the Content Integration Layer feature. To do so, perform the following steps:

  1. Log into your Shelf NextGen KMS account using valid credentials.
  2. Once logged in, go to the Admin Panel by selecting the respective option in the dropdown menu.

Figure 11. Accessing Admin Panel in Shelf NextGen KMS

3. In the Admin Panel window, you can see the left sidebar panel serving as a navigation menu to browse all the necessary components and their settings. One of these components is Content Integration Layer, consisting of three modules: Connectors, Connection Profiles, and Sync Flows.

Figure 12. Accessing CIL modules in Admin Panel


Configuring SharePoint connector

In fact, no configurations are needed for your SharePoint connector. It is prebuilt and preconfigured by Shelf. You can see it in the connector list that appears once you select the Connectors option in the Content Integration Layer section.

Figure 13. Viewing the SharePoint connector in CIL

What you need to do next is to create and configure a connection profile dedicated to work with the external content source such as your Microsoft SharePoint instance.


Configuring SharePoint connection profile

The SharePoint connection profile is a feature that uses the prebuilt SharePoint connector and allows Shelf NextGen KMS to access, authenticate on Microsoft SharePoint, and communicate with it to find and sync content stored there. But to enable its proper operation, you need to create and configure it as described in the procedure below.

  1. In the Admin Panel in Shelf NextGen KMS, go to the Content Integration Layer section, find and select the Connection Profiles option.
  2. In the Connection Profiles window that appears, you see the list of available connection profiles. Neither the prebuilt nor other custom connection profiles can be used for communicating with SharePoint, so you need to create a new connection profile. Click the Create Connection Profile button to start.

Figure 14. Accessing CIL connection profiles and starting creating a new connection profile 

3. The Create Connection Profile page that opens is where you need to do all the configurations for the SharePoint connection profile you create. You need to indicate the connector - SharePoint - to be used for the profile, add some description, if needed, indicate the authentication method, and fill in other important details grouped under the Runtime Settings and Credentials sections.

Figure 15. Configuring the SharePoint connection profile in Shelf

In the Runtime Settings section, you need to enter your SharePoint Instance URL which is the address of your SharePoint site - https://<your_domain>.sharepoint.com.

In the Credentials section, there are 3 fields to be populated:

  • Client ID
  • Client Secret
  • Realm

All these details you already have on hand as you have copied Application (client) ID and Directory (tenant) ID from the Overview page and created and copied the client secret in the Certificates and secrets page in Azure.

Paste the Application (client) ID value into the Client ID field, the Directory (tenant) ID value into the Realm field, and, finally, the client secret value into the Client Secret field.

📢

Fields with the asterisk symbol (*) are mandatory. If they are left blank, you are not able to save the connection profile you are creating.


4. Once you have populated all the necessary fields in the form, click Create to save changes and finalize creating your SharePoint connection profile.


Configuring SharePoint sync flow

Now that you have configured the SharePoint connector and connection profile, you need to create and configure the SharePoint sync flow. Sync flows are basically sets of instructions telling Shelf NextGen KMS what content and when it needs to pull from external sources, in our case - SharePoint.

To create and configure the SharePoint sync flow, perform the following steps.

  1. In the Admin Panel in Shelf NextGen KMS, go to the Content Integration Layer section, find and select the Sync Flows option.

Figure 16. Starting creating SharePoint sync flow


2. In the Create Sync Flow form that appears, select the needed connection profile from the dropdown list that opens if you click in the respective field. In our case - SharePoint CP. Add some title for your sync flow, and description if needed.

Figure 17. Configuring the SharePoint sync flow

3. You also need to tell Shelf how to run content synchronization: if you want it to be a scheduled procedure, select the On-schedule checkbox, and if it needs to be a manual procedure, select the On-demand checkbox.

Figure 18. Configuring the scheduled run of SharePoint sync flow


4. Finally, you can optionally add filters to apply to the content syncing from SharePoint into Shelf NextGen KMS. To do so, click Apply Filter and then select the filter type, criterion, and value. Read more about filters in Table 3 of the Sync Flows chapter in the Shelf Content Integration Layer Feature User Guide document.

Once done, click the Create button to finish your SharePoint sync flow creation.


Running SharePoint sync job

Once you have created the SharePoint sync flow, you can either wait until it performs the content sync per schedule (if you have selected the On-schedule option for the sync flow run type), or start the sync manually at any time (if you have selected the On-demand option for the run type).

To manually start syncing your content from SharePoint into Shelf, follow the below steps.

  1. Open the newly created SharePoint sync flow, find and go to the Jobs tab in its window.
  2. In the tab window, find and click the Trigger Now button to start syncing content.

Figure 19. Manually running content syncing from SharePoint into Shelf

3. In the popup window that appears, confirm the sync start by clicking the Sync button.

Figure 20. Confirming the sync start


4. Once done, the sync job is started and becomes visible in the list of sync jobs.

Figure 21. Viewing the running SharePoint sync job

📢

The sync job can be triggered manually both for the on-schedule and on-demand sync flows, unless there is a sync job running at that time. 

In the first case, the manually triggered job overrides the schedule set for the sync flow. At the same time, the sync flow execution will resume to occur per schedule after the manually triggered sync job is finished. If you manually trigger the sync flow job, it starts immediately.

If there is a running sync job in this sync flow when you attempt to start a new job, this new job will not be created and, respectively, the content sync will not be started. In this case you will see the error message informing that the job is already running. 

If there are no other sync jobs running in this sync flow, the Jobs tab window refreshes, and a new job with the IN PROGRESS status appears in the table grid.


5. While the job is running, you can stop it by accessing its More Actions menu and selecting the Stop option in the dropdown list as shown below.

Figure 22. Stopping the sync job


Checking syncing results

Once the sync job triggered manually or on schedule is finished, you will see it to change the status to SUCCESS (if the sync was successful) or FAILED (if some issues occurred during the sync). In the latter case, check your configurations in the SharePoint connection profile and sync flow and rerun the sync job.

If the sync was successful, you can see the recently sync content directly from this window. To do so, open the Recent Sync tab and check the content items synced from SharePoint into Shelf.

Figure 23. Viewing the recently synced content from SharePoint

Note that the tab shows not more than 50 content items, so if you have synced more items, you will see them only after going back to the Shelf NextGen KMS Homepage and selecting the respective source - SharePoint.


Configuring SharePoint permissions in User Groups

Even when you successfully configured the SharePoint connector, connection profile, sync flow, run the sync job and pulled the content from your SharePoint repository, you need to add SharePoint collections to the permitted sources via Shelf’s User Groups feature. Otherwise, you will not be able to search for the synced content and otherwise manage it in Shelf NextGen KMS.

To set the mentioned collection permissions, go back to the Admin Panel where find and select the User Groups option in the left sidebar menu. Select the needed user group from the list to open it.

Figure 24. Accessing User Groups in Shelf

In the selected user group window that opens, go and select the Collection Permissions tab. Once it opens, click the Add Collection button.

Figure 25. Starting to set SharePoint collection permissions in Shelf

In the form that opens, find and select the needed SharePoint collections you want to allow.

Figure 26. Selecting SharePoint collections

Confirm your choice by clicking the Add button. Once the collections are added, they appear in the list.

Figure 27. Viewing the added SharePoint collections

Once done, you are finished with all the configurations needed to sync content from SharePoint into Shelf NextGen KMS using the SharePoint connector.



Viewing SharePoint resources in Shelf

After completing all the configurations on your SharePoint connector and associated features and options, you can now view and work with the content synced into Shelf NextGen KMS from your SharePoint repository.

Go back to Shelf NextGen KMS homepage and select SharePoint as the needed source in the navigation panel.

Figure 28. Viewing content synced from SharePoint into Shelf

Note that if you select any content item synced from SharePoint it will open in SharePoint not in Shelf NextGen KMS.

Figure 29. Viewing content item in SharePoint

Now, you can enjoy all the benefits, including the AI-enabled features such as Search and Analytics Copilots, of Shelf NextGen KMS in relation to your content synced from SharePoint.

In particular, you can filter this content using the Collections filter in Shelf NextGen KMS’s advanced search, as shown in the figure below.

Figure 30. Searching the synced content using the Collections filter in Shelf NextGen KMS search

You can also search across the articles synced from SharePoint by title, description, and content (keyword(s) or phrase(s)). Generally, you can use virtually all the capabilities of Shelf NextGen KMS in relation to searching, viewing, and managing content synced from SharePoint.

Figure 31. Viewing the search results for SharePoint articles