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

1. After logging in to your Intercom developer account, go to the Your Apps tab.

Figure 1. Accessing the App Building feature in Intercom

Figure 2. Starting your app creation in Intercom

Figure 3. Creating Shelf app in Intercom

Your Shelf app is now created and you can see it in the list of apps on the Your apps page.

Figure 4. Viewing the 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 5. 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, 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 6. Accessing your workspaces in Intercom

Select the needed workspace to open it.

On the workspace page that opens, find and select the Articles option in the navigation panel.

Figure 7. Accessing the Articles feature in Intercom

You are taken to the Articles page where you can see your content and work with it. For instance, you can access your collections from here. A collection is a library in Shelf KMS terminology.

Figure 8. Viewing the Articles page and accessing the Intercom collections

To access your collections, select the respective option in the sidebar panel.

On the Collections page that opens, you can view and manage the available collections and create the new ones if needed.

Figure 9. Viewing the available collections and creating a new collection in Intercom

Click the Add collection button to start creating a new collection. In the new field that appears at the bottom of the collections list, enter a desired name for your new collection.

Figure 10. Entering the new collection name

Following that, your new collection is created and displayed in the list.

Figure 11. Viewing the newly created collection

If needed, you can delete any collection from this page. Select the collection and then click the delete icon that appears next to it.

In addition to managing and creating collections in your Intercom workspace, you can also create folders. Folders are nested collections. To do so, click the +Add button next to the collection in which you want to create a folder.

Figure 12. Creating folders inside Intercom collections

Enter the name for your new folder to finish creation of the folder. The folder will appear on the list.

Figure 13. Adding the name to the folder

Figure 14. Viewing the newly created folder

To create a content item (or an article in the Intercom terminology), go to the All articles menu in the sidebar panel, and click +New article button.

Figure 15. Creating articles in Intercom

On the Article page, enter a title for your article, some description (if needed), and its content.

Figure 16. Adding content for the article in Intercom

Once done with adding the needed data to your article click Publish on top of the page to save and publish the article.

❗Note:

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

When the article is created and published, you can add it to your Intercom collection and/or folder. Click the No Collection link button on the Article page and then select the needed collection/folder in the dropdown menu that appears in the Article Settings panel. Once done, click Save settings, and your article will be added to the selected collection/folder.

Figure 17. Adding articles to collection/folder 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 18. Accessing Admin Panel in Shelf KMS

Figure 19. 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 Connectors option in the Content Integration Layer section.

Figure 20. Viewing the 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 21. Accessing CIL connection profiles and starting creating a new connection profile 

Figure 22. Configuring the 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 23. Viewing the created Intercom connection profile in the list

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.

Figure 24. Starting creating Intercom sync flow

Figure 25. Configuring the Intercom sync flow

Figure 26. Configuring the scheduled run of Intercom sync flow

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

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, 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 Intercom into Shelf

Figure 28. Confirming the sync start

Figure 29. Viewing the running and finished Intercom sync jobs

❗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 Intercom 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 Intercom into Shelf.

Figure 31. Viewing the recently synced content from Intercom

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 - 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 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 Intercom collection permissions in Shelf

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

Figure 34. Selecting Intercom collections

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

Figure 35. Viewing the 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.