Document version history
Version number | Modified by | Modifications made | Date modified | Status |
1.0 | Shelf | Initial release of the document. | 19 Jan 2024 | Active |
Document purpose
- 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?
Glossary
Prior to starting to learn about the Intercom connector and its configuration and usage, you need to learn the terminology used by Shelf.
Intercom (https://intercom.com) is an automated customer support platform that offers AI-enabled content management capabilities for their customers. For the purpose of this document, Intercom is identified as an external content storage.
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 Intercom connector is a set of API parameters to define how to connect Shelf to Intercom). Shelf KMS has a set of preconfigured connectors (Intercom, Zendesk, Sharepoint, Confluence 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.
Credentials is a set of unique identifiers—such as a username and password—that enables a user to verify identity in order to log in to an online account.
Access token is a unique identifier used to authenticate REST API requests submitted to Intercom by external platforms, systems, and applications. For the purpose of this document, access token is a unique identifier that allows Shelf KMS to access Intercom for content retrieval and synchronization.
Prerequisites
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.
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/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.
- 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 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.
Configurations on the Intercom side
Configurations you need to perform in Intercom mostly relate to creating a dedicated app for your Intercom Shelf integration, obtaining the access token for that integration, accessing your Intercom workspace, and, finally, managing your content there.
Before proceeding with the mentioned configuration procedure, make sure to log in to your Intercom developer account where you have previously created the relevant workspace.
Creating Shelf app in Intercom
To create a dedicated App for your Intercom Shelf integration, follow the below steps:
- 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
Obtaining access token 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
Managing content in Intercom
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
Creating collections
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.
Creating folders
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
Creating or adding content
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.
Configurations on the Shelf side
This chapter and its subsections describe the steps you need to take to get your Intercom 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 Intercom 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 Intercom connector
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.
Configuring Intercom connection profile
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.
- 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 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
Configuring Intercom sync flow
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.
- 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.
Running Intercom sync job
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.
- Open the newly created Intercom 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 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
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 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.
Configuring Intercom permissions in User Groups
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.
Viewing Intercom resources in Shelf
After completing all the configurations on your Intercom connector and associated features and options, you can now view and work with the content synced into Shelf KMS from your Intercom repository.
Go back to Shelf KMS homepage and select Intercom as the needed source in the navigation panel.
Figure 36. Viewing content synced from Intercom into Shelf
Note that if you select any content item synced from Intercom it will open in Intercom not in Shelf KMS.
Figure 37. Viewing content item in Intercom
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 Intercom.
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 Intercom 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 Intercom.
Figure 39. Viewing the search results for Intercom articles