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

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

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.

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

Figure 2. Finding and installing Knowledge API plugin

Figure 3. Installing the plugin

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

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

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

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.

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

Figure 11. Creating a new Knowledge Base in ServiceNow

Figure 12. Creating and viewing Knowledge Base 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

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.

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

Figure 19. Accessing CIL modules in Admin Panel

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.

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 

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

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

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

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

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

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.

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