• What is the Shelf Content Integration Layer?
• What purposes does this feature serve?
• What is an Intercom connector?
• How is it configured?
• How is it used in practice?

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

• Admin Panel must be accessible on your Shelf KMS account
• Intercom developer account must be created and configured
• Content items (articles, documents, etc.) must be available in your Intercom repository.

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

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 Intercom connector to sync your content from Intercom into Shelf KMS, you need to do certain actions both in Intercom and in Shelf.  Read the chapters below to learn what exactly you need to do.

To create a dedicated App for your Intercom Shelf integration, follow the below steps:

Figure 1.  Accessing apps and starting building new app in Intercom

Figure 2. Creating Shelf app in Intercom

Figure 3. Viewing created Shelf app in Intercom

Once you click the Create app button (see Figure 3 above), you are redirected to the Authentication page where you can find and copy the access token for further use. You will need it when performing configurations on the Shelf side.Figure 4. Finding and copying access token for your Intercom workspace

After copying and saving the access token for your Intercom workspace, you can access that workspace to check and prepare your content for proper syncing with Shelf KMS. 

To do so, perform the following steps.

1) Go to the Test and publish menu in the navigation panel. You are redirected to the Your workspaces page where you can see your Intercom workspaces. 

Figure 5. Accessing your workspaces in Intercom

Figure 6. Accessing Knowledge feature in Intercom 

Figure 8. Viewing Knowledge Sources page and accessing content on Intercom

Figure 9. Accessing articles 

Figure 10. Viewing articles

Figure 11. Viewing content collections

Or you can access this page by selecting the Content option in the navigation panel (see Figure 10 above).

Figure 12. Managing collections and their content in Intercom 

In addition to managing and creating parent collections in your Intercom workspace, you can also create nested collections or folders. To do so, follow the below steps.

1. Find a parent collection in which you want to create nested collection(s). Open its context menu by clicking on the  respective menu button. Select the Add collection option from the dropdown menu.Figure 15. Creating nested collections/folders inside Intercom collections

2) In the modal window that opens, enter the name and description for your new nested collection. Once done, click Create collection. The created nested collection will appear on the list under its respective parent collection.

Figure 16. Adding nested collection/folder name and description

Figure 17. Verifying nested collection is created

You can delete both parent and nested collections (folders) if you no longer need them.

To do so, perform the following steps.

Figure 18. Deleting parent collection

Figure 19. Confirming parent collection deletion

Once done, the parent collection is deleted and no longer displayed in the collection list.

For deleting a nested collection/folder, follow the same method: open the nested collection’s context menu and select the Delete option there. Then confirm the deletion in the popup modal window. The nested collection will be deleted from the list.

Figure 20. Deleting nested collection/folder

You can create a content item (or an article in the Intercom terminology) in Intercom in multiple ways.

Method 1. From the Knowledge>Sources page

When on the Knowledge>Sources page, click the + New content button in the upper right corner of the window and then select the needed content/article option in the modal window that opens.Figure 21. Starting to create content from Knowledge>Sources page

Method 2. From the Knowledge>Content page

When on the Knowledge>Content page, click the + New content button in the upper right corner of the window and then select the needed content/article option in the modal window that opens.

Figure 22. Starting to create content from Knowledge>Content page

Method 3. From parent collection context menu

Open the context menu of a parent collection where you want to create content and select the Add articles option in the dropdown list that opens.

Figure 23. Starting to create content within parent collection

Method 4a. From nested collection context menu

Open the context menu of a nested collection where you want to create content and select the Add articles option in the dropdown list that opens.

Figure 23. Starting to create content within nested collection - method A

Method 4b. From nested collection directly

Expand the nested collection in which you want to create some content and click + New article underneath. 

Figure 24. Starting to create content within nested collection - method B

All the methods mentioned above will direct you to the Article page, where you can:

1. Enter a title for your article

2. Add description to it

3. Enter content of the article, that is text, images, links etc.

4. Use basic rich text editing tools

5. Check the article details such as type, status, Id, language, author, creation date, contributor, last update date, and version history

6. Enable the article for use by AI agents

7. Set the article audience

8. Set the article’s collection from the available or create a new collection for the article

9. Save the article as draft

10. Publish the article

11. Cancel the article creation that is delete it.

Figure 24. Creating article in Intercom

If needed, you can also create and add tags to the article and check reports on it, by scrolling down the Details pane. 

Once done with the populating and configuring the article, click Publish to save and make it available to the public. After saving, the article becomes available both on the Knowledge>Content page and on the Help Center page. In the latter case, you can see that the newly created article is exactly where you have pointed it to - in the Cars collection.

Figure 25. Verifying article is created and published for general use

If needed, you can later edit, relocate (move between parent and/or nested collection(s)), or delete the article(s).

❗Note:  
   Only the published articles are synced to Shelf KMS, so make sure to publish the content items you have in Intercom.

Now when you have properly configured your Intercom workspace, saved the access token for it, and learned how to manage/create content in Intercom, you can proceed to configurations on the Shelf side.

From the standard workflow described above you see that to start configuring and using your Intercom 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 26. Accessing Admin panel in Shelf KMS

Figure 27. Accessing CIL modules in Admin panel

In fact, no configurations are needed for your Intercom 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 28. Viewing Intercom 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 Intercom workspace.

The Intercom connection profile is a feature that uses the prebuilt Intercom connector and allows Shelf KMS to access, authenticate on Intercom, 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 Intercom, so you need to create a new connection profile. Click the Create connection profile button to start.Figure 29. Accessing CIL connection profiles and starting creating new connection profile 

3) The CREATE CONNECTION PROFILE page that opens is where you need to do all the configurations for the Intercom connection profile you create. You need to indicate the connector (1) — Intercom — to be used for the profile, add a name (2) and, if desired, some description (3) for your connection profile, and, finally, fill in the CREDENTIALS section (4).

Figure 30. Configuring Intercom connection profile in Shelf

In the CREDENTIALS section, the Access token field, you need to enter the access token value you have previously found and copied when configuring your Shelf integration in Intercom. 

❗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 31. Verifying Intercom connection profile is available

Now that you have configured the Intercom connector and connection profile, you need to create and configure the Intercom 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—Intercom.

To create and configure the Intercom 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. Then, on the SYNC FLOWS page that opens, click Create sync flow.Figure 32. Starting creating Intercom sync flow

2) In the CREATE SYNC FLOW form that appears, select the needed connection profile from the dropdown list (1) that opens if you click in the respective field. In our case—Intercom Content Sync Profile. Add some title (2) for your sync flow, and description (3) if needed. Figure 33. Configuring Intercom sync flow

3) You also need to tell Shelf how to run content synchronization (4): 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 34. Configuring scheduled run of Intercom sync flow4) Finally, you can optionally add filters to apply to the content syncing from Intercom into Shelf KMS. To do so, click ADD FILTER (5) and then select the filter type, criterion, and value. Note that Intercom connector currently supports only one filter—Updated At. 

Figure 34.1. Adding filter to streamline content sync from Intercom to Shelf

Figure 35. Verifying Intercom sync flow is created and available

Once you have created the Intercom 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 Intercom into Shelf, follow the below steps.

1) Open the newly created Intercom sync flow (Figure 35 above), find and go to the Jobs tab in its window.

Figure 36. Manually running content syncing from Intercom into Shelf

Figure 37. Confirming sync job start

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

Figure 38. Viewing sync job running

❗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 40. Viewing the recently synced content from Intercom

Even when you successfully configured the Intercom connector, connection profile, sync flow, run the sync job and pulled the content from your Intercom repository, you need to add Intercom 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 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 41. 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 collections button. 

Figure 42. Starting to set Intercom collection permissions in Shelf

Figure 43. Selecting Intercom collections

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

Figure 44. Viewing added Intercom collections

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