Document version history
Version number | Modified by | Modifications made | Date modified | Status |
1.0 | Shelf | Initial release of the document. | 12 Feb 2024 | Active |
Document purpose
- What is the Shelf Content Integration Layer?
- What purposes does this feature serve?
- What is a ServiceNow connector?
- How is it configured?
- How is it used in practice?
Glossary
Prior to starting to learn about the ServiceNow connector and its configuration and usage, you need to learn the terminology used by Shelf.
Shelf KMS (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 KMS) is a feature that allows for the seamless integration of various types and formats of content into the system. It enables users to import and organize content from various sources and knowledge repositories.
A connector is an entity that defines which external Content Management System Shelf KMS needs to connect to via Content Integration Layer (e.g. the ServiceNow connector is a set of API parameters to define how to connect Shelf to ServiceNow). Shelf KMS has a set of preconfigured connectors (Contentful, Zendesk, Sharepoint, ServiceNow, ServiceNow 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 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 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 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 ServiceNow connector and successful synchronization of your content from the ServiceNow platform into Shelf KMS, the following preconditions must be met:
- You must have a developer account with the ServiceNow platform
- Knowledge base and articles in it must be available in your ServiceNow instance. If you have no knowledge base in your ServiceNow, jump to the respective section below to learn how you can create it
- You must have the Admin level permissions on your Shelf KMS account
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 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:
- You access the Content Integration Layer feature in your Shelf KMS (Admin Panel).
- 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)
- You create a connection profile that uses the selected or created connector, and configure it: indicate credentials (username/password/security 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 ServiceNow.
- 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.
- 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 ServiceNow connector to sync your content from ServiceNow into Shelf KMS, you need to do certain actions both in ServiceNow and in Shelf. Read the chapters below to learn what exactly you need to do.
Configurations on the ServiceNow side
This chapter walks you through configurations you need to make on your ServiceNow account.
Installing Knowledge API plugin
Once you have logged in to your ServiceNow developer instance and got to the app and experience building environment, you need to install the Knowledge API plugin. This plugin enables searching, viewing, and fetching lists of most-viewed and featured knowledge articles from ServiceNow to external applications/systems.
To install the plugin, perform the following steps.
- Go to the Plugins module in your ServiceNow instance.
Figure 1. Accessing the Plugins module in ServiceNow
Figure 2. Finding and installing Knowledge API plugin
Figure 3. Installing the plugin
Obtaining Client ID and Secret
Client ID and Client Secret are the important credentials needed to access your ServiceNow instance from external applications and systems. You need to obtain them for enabling the proper operation of your Shelf ServiceNow connector.
To get these values, perform the following steps.
- Once in your ServiceNow instance, navigate to the Application Registry page of the System OAuth module.
Figure 4. Accessing the App Registry in ServiceNow
Figure 5. Creating the new app registry entry for Shelf ServiceNow connector configuration
Figure 6. Filling in the application registry creation form
Figure 7. Viewing and saving Client ID and Client Secret in ServiceNow
Obtaining Instance URL, username, and password
In addition to Client ID and Client Secret, you also need your ServiceNow Instance URL, as well as username and password used to access your instance. These values are needed at the stage of configuring your ServiceNow connector on the Shelf side.
To get the values mentioned above, perform the following steps.
- Go to the ServiceNow Developers page and log in using your credentials.
- Once logged in, go to your profile menu and find and select the Manage instance password option there.
Figure 8. Accessing the instance credentials page
Figure 9. Copying ServiceNow Instance URL, username, and password
Now, you have all the needed credentials: Instance URL, username, password, Client ID, and Client Secret.
Creating content in ServiceNow
For the purpose of this document we assume you have a blank instance with no Knowledge Bases and articles (content). So, in order to be able to use the Shelf ServiceNow connector for its intended purpose—syncing content from ServiceNow—you need to create at least one Knowledge Base and an article. Read the sections below to learn how you can do it.
Creating knowledge bases in ServiceNow
For creating a Knowledge Base in your ServiceNow instance, perform the following procedure.
- Once in your ServiceNow developer instance and in the app and experience building environment, go to the Knowledge module and select the Knowledge Bases option under it.
Figure 10. Accessing the Knowledge module and Knowledge Bases in ServiceNow
Figure 11. Creating a new Knowledge Base in ServiceNow
Figure 12. Creating and viewing Knowledge Base in ServiceNow
Creating articles in ServiceNow
After creating a Knowledge Base, you need to add some content to it. In ServiceNow, content is a knowledge article. Perform the steps laid down below to create an article.
- In the Knowledge module, search for Articles. When found, select the All option under it.
Figure 13. Accessing Articles in ServiceNow
Figure 14. Creating a new article in ServiceNow
Figure 15. Adding content to the article
Figure 16. Viewing the added article
Figure 17. Publishing the article in ServiceNow
Now that you have added the needed Knowledge Base and content to it and finished other actions mentioned in the sections above, your configurations on the ServiceNow side are done and you can proceed to the configurations on the Shelf side.
Configurations on the Shelf side
This chapter and its subsections describe the steps you need to take to get your ServiceNow 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 ServiceNow connector you need to access the Content Integration Layer feature. To do so, perform the following steps:
- Log into your Shelf KMS account using valid credentials.
- Once logged in, go to the Admin Panel by selecting the respective option in the dropdown menu.
Figure 18. Accessing Admin Panel in Shelf KMS
Figure 19. Accessing CIL modules in Admin Panel
Configuring ServiceNow connector
In fact, no configurations are needed for your ServiceNow connector. It is prebuilt and preconfigured by Shelf. You can see it in the connector list that appears once you select the Custom Connectors option in the Content Integration Layer section.
Figure 20. Viewing the ServiceNow 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 ServiceNow instance.
Configuring ServiceNow connection profile
The ServiceNow connection profile is a feature that uses the prebuilt ServiceNow connector and allows Shelf KMS to access, authenticate on ServiceNow, 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.
- In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Connection Profiles option.
- 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 ServiceNow, so you need to create a new connection profile. Click the Create Connection Profile button to start.
Figure 21. Accessing CIL connection profiles and starting creating a new connection profile
Figure 22. Configuring the ServiceNow connection profile in Shelf
In the Runtime Settings section, you need to indicate the URL of your ServiceNow instance, i.e. the storage where your content is kept in the Knowledge Bases. You have already obtained this URL as described in the respective section above.
Under the Runtime Settings header, you must also enter your Client ID and User Name, which you have saved as described in the respective sections - Obtaining Client ID and Secret and Obtaining Instance URL, username, and password.
In the Credentials section, the Client Secret field, enter the respective Client Secret you have obtained from your ServiceNow instance.
In the Password field, respectively, you need to enter the password you use to access your ServiceNow developer instance.
❗Note:
Fields with the asterisk symbol (*) are mandatory. If they are left blank, you are not able to save the connection profile you are creating.
Figure 23. Viewing the ServiceNow connection profile in the connection profiles list
Configuring ServiceNow sync flow
Now that you have configured the ServiceNow connector and connection profile, you need to create and configure the ServiceNow sync flow. Sync flows are basically sets of instructions telling Shelf KMS what content and when it needs to pull from external sources, in our case - ServiceNow.
To create and configure the ServiceNow sync flow, perform the following steps.
- In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Sync Flows option.
Figure 24. Starting creating ServiceNow sync flow
❗Note:
Fields with the asterisk symbol (*) are mandatory. If they are left blank, you are not able to save the connection profile you are creating.
Figure 25. Configuring the ServiceNow sync flow
Figure 26. Configuring the scheduled run of ServiceNow sync flow
Once done, click the Create button to finish your ServiceNow sync flow creation.
Running ServiceNow sync job
Once you have created the ServiceNow 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 ServiceNow into Shelf, follow the below steps.
- Open the newly created ServiceNow sync flow, find and go to the Jobs tab in its window.
- In the tab window, find and click the Trigger Now button to start syncing content.
Figure 27. Manually running content syncing from ServiceNow into Shelf
Figure 28. Confirming the sync start
Figure 29. Viewing the running ServiceNow sync job
❗Note:
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.
Figure 30. 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 ServiceNow 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 ServiceNow into Shelf.
Figure 31. Viewing the recently synced content from ServiceNow
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 KMS homepage and selecting the respective source - ServiceNow.
Configuring ServiceNow permissions in User Groups
Even when you successfully configured the ServiceNow connector, connection profile, sync flow, run the sync job and pulled the content from your ServiceNow repository, you need to add ServiceNow collections to the permitted sources via Shelf’s User Groups feature. Otherwise, you will not be able to search for the synced content in Shelf 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 32. 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 33. Starting to set ServiceNow collection permissions in Shelf
In the form that opens, find and select the needed ServiceNow collections you want to allow.
Figure 34. Selecting ServiceNow collections
Confirm your choice by clicking the Add button. Once the collections are added, they appear in the list.
Figure 35. Viewing the added ServiceNow collections
Viewing ServiceNow resources in Shelf
After completing all the configurations on your ServiceNow connector and associated features and options, you can now view and work with the content synced into Shelf KMS from your ServiceNow repository.
Go back to Shelf KMS homepage and select ServiceNow as the needed source in the navigation panel.
Figure 36. Viewing content synced from ServiceNow into Shelf
Note that if you select any content item synced from ServiceNow it will open in ServiceNow not in Shelf KMS.
Figure 37. Viewing content item in ServiceNow
Now, you can enjoy all the benefits, including the AI-enabled features such as Search and Analytics Copilots, of Shelf KMS in relation to your content synced from ServiceNow.
In particular, you can filter this content using the Collections filter in Shelf KMS’s advanced search, as shown in the figure below.
Figure 38. Searching the synced content using the Collections filter in Shelf KMS search
You can also search across the articles synced from ServiceNow by title, description, and content (keyword(s) or phrase(s)). Generally, you can use virtually all the capabilities of Shelf KMS in relation to searching, viewing, and managing content synced from ServiceNow.
Figure 39. Viewing the search results for ServiceNow articles