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
- What is the Shelf Content Integration Layer?
- What purposes does this feature serve?
- What is a Salesforce Knowledge connector?
- How is it configured?
- How is it used in practice?
Glossary
Prior to starting to learn about the Salesforce Knowledge 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 Salesforce Knowledge connector is a set of API parameters to define how to connect Shelf to Salesforce Knowledge). Shelf KMS has a set of preconfigured connectors (Contentful, Zendesk, Sharepoint, Salesforce Knowledge 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.
A security token is a case-sensitive alphanumeric code that you append to your password or enter in a separate field in a client application. It is needed for you to login when you access Salesforce from an IP address that’s outside your company’s trusted IP range using a desktop client or the API. For the purpose of this document, the security token is a unique identifier that allows Shelf KMS to access Salesforce Knowledge for content retrieval and synchronization.
Prerequisites
For proper operation of your Salesforce Knowledge connector and successful synchronization of your content from the Salesforce platform into Shelf KMS, the following preconditions must be met:
- The Salesforce organization your user belongs to must have the Connected App package and the Shelf Integration package of the latest versions installed and configured. Contact your organization’s administrator(s) for more details
- The user under which you log in to and work in your Salesforce account must have the role not worse than Salesforce Read Only and be assigned the Shelf CIL Knowledge Access permission set. Contact your organization’s administrator(s) for more details
- The user under which you log in to and work in your Salesforce account must have the Knowledge User license. To check if your user has this license, once logged in to your Salesforce account, go to your user settings as shown below.
Figure 1. Accessing user settings in Salesforce
When in the Personal Information window, select the Advanced User Details option in the sidebar menu.
Figure 2. Accessing advanced user details in Salesforce
In the window that opens, find and see if the Knowledge User checkbox is selected.
Figure 3. Checking the Knowledge User license availability
If the checkbox is selected, you are good to go. If it is not, click the Edit button and then select the Knowledge User checkbox. Save your changes by clicking SAVE.
- Knowledge articles must be available on your Salesforce account. To check if you have content in your Salesforce storage, once on the homepage, search for and then navigate to the Knowledge app.
Figure 4. Finding and accessing the Knowledge app in Salesforce
Whe in the app, access the articles view menu by clicking the respective expand icon and select either the Published Articles or Recently Viewed (Pinned list) option.
Figure 5. Accessing articles in the Knowledge app in Salesforce
If this action directs you to the list displaying the knowledge articles, it means that you have content in your Salesforce storage and this content can be synced to Shelf KMS via the CIL feature.
Figure 6. Viewing articles in the Knowledge app in Salesforce
- Admin Panel must be accessible 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:
- 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/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 Salesforce.
- 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 Salesforce Knowledge connector to sync your content from Salesforce into Shelf KMS, you need to do certain actions both in Salesforce and in Shelf. Read the chapters below to learn what exactly you need to do.
Configurations on the Salesforce side
There are not many configurations you need to make on your Salesforce account. However, there is one important thing you need to do - obtain your security token without which Shelf KMS is not able to connect to and, respectively, sync content from, Salesforce Knowledge repository.
Obtaining security token in Salesforce
❗Note:
The Salesforce security token is a case-sensitive alphanumeric code that you append to your password or enter in a separate field in a client application. It is needed for you to login when you access Salesforce from an IP address that’s outside your company’s trusted IP range using a desktop client or the API.
This token is not displayed in your settings or profile, so to obtain it, you need to basically create a new one by resetting the existing token.
For obtaining the security token for your Salesforce repository, perform the following steps.
Figure 7. Accessing user settings in Salesforce
Figure 8. Resetting security token in Salesforce
Figure 9. Viewing new security token sent by email
After you have reset your security token and obtained and saved the new one, your configurations on the Salesforce side are basically completed 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 Salesforce Knowledge 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 Salesforce Knowledge 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 10. Accessing Admin Panel in Shelf KMS
Figure 11. Accessing CIL modules in Admin Panel
Configuring Salesforce Knowledge connector
In fact, no configurations are needed for your Salesforce Knowledge 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 12. Viewing the Salesforce Knowledge 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 Salesforce Knowledge instance.
Configuring Salesforce Knowledge connection profile
The Salesforce Knowledge connection profile is a feature that uses the prebuilt Salesforce Knowledge connector and allows Shelf KMS to access, authenticate on Salesforce Knowledge, 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 Salesforce Knowledge, so you need to create a new connection profile. Click the Create Connection Profile button to start.
Figure 13. Accessing CIL connection profiles and starting creating a new connection profile
Figure 14. Configuring the Salesforce Knowledge connection profile in Shelf
In the Runtime Settings section, you need to indicate the URL of your Salesforce instance, i.e. the storage where your content is kept. For Instance URL use my.salesforce.com (e.g. https://companyname.my.salesforce.com).
In the Credentials section, the Email field, enter the email address you use to access your Salesforce instance.
In the Password field, respectively, you need to enter the combination of the password you use to access your Salesforce instance and the security token you have previously obtained via email. For example, the value to be entered in the Password field must look as follows: MyPasswordABCDEFG123456789 where MyPassword is your Salesforce account password, and ABCDEFG123456789 is your security token.
❗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 15. Viewing the Salesforce connection profile in the connection profiles list
Configuring Salesforce sync flow
Now that you have configured the Salesforce Knowledge connector and connection profile, you need to create and configure the Salesforce 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 - Salesforce.
To create and configure the Salesforce 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 16. Starting creating Salesforce 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 17. Configuring the Salesforce sync flow
Figure 18. Configuring the scheduled run of Salesforce sync flow
Once done, click the Create button to finish your Salesforce sync flow creation.
Running Salesforce sync job
Once you have created the Salesforce 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 Salesforce into Shelf, follow the below steps.
- Open the newly created Salesforce 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 19. Manually running content syncing from Salesforce into Shelf
Figure 20. Confirming the sync start
Figure 21. Viewing the running Salesforce Knowledge 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 22. 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 Salesforce 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 Salesforce into Shelf.
Figure 23. Viewing the recently synced content from Salesforce
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 - Salesforce.
Configuring Salesforce permissions in User Groups
Even when you successfully configured the Salesforce Knowledge connector, connection profile, sync flow, run the sync job and pulled the content from your Salesforce Knowledge repository, you need to add Salesforce 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 24. 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 25. Starting to set Salesforce collection permissions in Shelf
In the form that opens, find and select the needed Salesforce collections you want to allow.
Figure 26. Selecting Salesforce collections
Confirm your choice by clicking the Add button. Once the collections are added, they appear in the list.
Figure 27. Viewing the added Salesforce collections
📌Important!
There is one Salesforce collection that needs to be added via User Groups in all cases: without adding this collection, users from this User Group cannot view any content from Salesforce. This collection is root.
Make sure to add it by yourself or request your organization’s administrator(s) to add this collection.
Once done, you are finished with all the configurations needed to sync content from Salesforce into Shelf KMS using the Salesforce Knowledge connector.
Viewing Salesforce Knowledge resources in Shelf
After completing all the configurations on your Salesforce Knowledge connector and associated features and options, you can now view and work with the content synced into Shelf KMS from your Salesforce repository.
Go back to Shelf KMS homepage and select Salesforce Knowledge as the needed source in the navigation panel.
Figure 28. Viewing content synced from Salesforce Knowledge into Shelf
Note that if you select any content item synced from Salesforce Knowledge it will open in Salesforce not in Shelf KMS.
Figure 29. Viewing content item in Salesforce
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 Salesforce.
In particular, you can filter this content using the Collections filter in Shelf KMS’s advanced search, as shown in the figure below.
Figure 30. Searching the synced content using the Collections filter in Shelf KMS search
You can also search across the articles synced from Salesforce 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 Salesforce.
Figure 31. Viewing the search results for Salesforce Knowledge articles