Shelf ServiceNow Connector Overview Guide


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

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 ServiceNow 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 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:

  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/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.
  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 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.

  1. Go to the Plugins module in your ServiceNow instance.

Figure 1. Accessing the Plugins module in ServiceNow

2. When in the Plugins module, search for the Knowledge API plugin. Once it is found, click the Install button next to it to start its installation.

Figure 2. Finding and installing Knowledge API plugin

3. Confirm your choice in the popup window and wait for the installation procedure to complete.

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.

  1. Once in your ServiceNow instance, navigate to the Application Registry page of the System OAuth module.

Figure 4. Accessing the App Registry in ServiceNow


2. In the Application Registry window, find and click the New button in the top right corner. In the next window, select the generic type for your OAuth application API endpoint.

Figure 5. Creating the new app registry entry for Shelf ServiceNow connector configuration


3. In the dedicated application registry window, enter the name for your application registry. The Client ID field is autopopulated by the system. Leave the Client Secret field blank - the system generates it automatically. Once done, click Submit.

Figure 6. Filling in the application registry creation form


4. Once the success notification is displayed, your application registry is created and displayed in the list. Open it again to find and save the Client ID and Client Secret values.

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.

  1. Go to the ServiceNow Developers page and log in using your credentials.
  2. 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


3. In the popup window that appears, find and copy your Instance URL, username, and password. In this window, you can also reset the instance password if needed. The new password is displayed as soon as it is generated. Once you have copied the needed values, close the window.

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.

  1. 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


2. On the Knowledge Bases page that opens, find and click the New button.

Figure 11. Creating a new Knowledge Base in ServiceNow


3. In the new window that appears, enter the name for your new Knowledge Base and click Submit. Your Knowledge Base is created and visible in the Knowledge Bases list.

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.

  1. In the Knowledge module, search for Articles. When found, select the All option under it.

Figure 13. Accessing Articles in ServiceNow

2. In the window that opens, click the New button in the top right corner.

Figure 14. Creating a new article in ServiceNow


3. In the next window, select the Knowledge Base, a category to which you want to assign the new article. Then add the article’s content as needed. Once done, click Submit.

Figure 15. Adding content to the article


4. The article is added to the selected Knowledge Base and is displayed in the articles list.

Figure 16. Viewing the added article


5. The article is now submitted but not yet published. To finish its addition to the Knowledge Base, open the article again and click Publish.

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:

  1. Log into your Shelf KMS account using valid credentials.
  2. 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

2. 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: Custom Connectors, Connection Profiles, and Sync Flows.

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.

  1. In the Admin Panel in Shelf 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 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 


3. The Create Connection Profile page that opens is where you need to do all the configurations for the ServiceNow connection profile you create. You need to indicate the connector - ServiceNow - to be used for the profile, enter a desired name for the connection profile, and fill in the important details grouped under the Runtime Settings and Credentials sections. You can also add some description for your new ServiceNow connection profile in the respective field.

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.


4. Once you have populated all the necessary fields in the form, click Create to save changes and finalize creating your ServiceNow connection profile. When the system finishes creating the connection profile, you are redirected to the Connection Profiles page where you can see your newly created ServiceNow connection profile in the list.

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.

  1. 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

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 - ServiceNow CP. Add some title for your sync flow, and description if needed.

❗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

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 26. Configuring the scheduled run of ServiceNow sync flow


4. Finally, you can optionally add filters to apply to the content syncing from ServiceNow into Shelf 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 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.

  1. Open the newly created ServiceNow 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 27. Manually running content syncing from ServiceNow into Shelf

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

Figure 28. Confirming the sync start

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

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.


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 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

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




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