Shelf Salesforce Knowledge Connector Overview Guide


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

This document has been developed for those customers’ end users who are using Shelf Knowledge Management System (Shelf KMS) with the Content Integration Layer feature to manage and handle various content both stored in Shelf KMS and in external platforms integrated via CIL. The document’s goal is to answer the following questions:
  • 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?
If you require further assistance, feel free to contact us at support@shelf.io or from the in-app chat support within the Shelf platform.

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:

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


1. Once logged in to your Salesforce account, go to your user settings.

Figure 7. Accessing user settings in Salesforce


2. In the window that appears next, find and select the Reset My Security Token option in the My Personal Information menu in the left sidebar panel. On the next page, click the Reset Security Token button and confirm your choice.

Figure 8. Resetting security token in Salesforce


3. Once done, the new security token is sent to your email address assigned to your user. Check your inbox and copy and save the security token you have received.

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:

  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 10. Accessing Admin Panel in Shelf KMS


3. In the Admin Panel window, you can see the left sidebar panel serving as a navigation menu to browse all the necessary components and their settings. One of these components is Content Integration Layer, consisting of three modules: Custom Connectors, Connection Profiles, and Sync Flows.

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.

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


3. The Create Connection Profile page that opens is where you need to do all the configurations for the Salesforce Knowledge connection profile you create. You need to indicate the connector - Salesforce Knowledge - to be used for the profile, enter a desired name for the connection profile, and fill in the important details grouped under the Runtime Settings and Credentials sections. You can also add some description for your new Salesforce Knowledge connection profile in the respective field.

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.


4. Once you have populated all the necessary fields in the form, click Create to save changes and finalize creating your Salesforce connection profile. When the system finishes creating the connection profile, you are redirected to the Connection Profiles page where you can see your newly created Salesforce connection profile in the list.

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.

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


2. In the Create Sync Flow form that appears, select the needed connection profile from the dropdown list that opens if you click in the respective field. In our case - Salesforce CP. Add some title for your sync flow, and description if needed.

❗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


3. You also need to tell Shelf how to run content synchronization: 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 18. Configuring the scheduled run of Salesforce sync flow


4. Finally, you can optionally add filters to apply to the content syncing from Salesforce into Shelf KMS. To do so, click Apply Filter and then select the filter type, criterion, and value. Read more about filters in Table 3 of the Sync Flows chapter in the Shelf Content Integration Layer Feature User Guide document.

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.

  1. Open the newly created Salesforce 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 19. Manually running content syncing from Salesforce into Shelf


3. In the popup window that appears, confirm the sync start by clicking the Sync button.

Figure 20. Confirming the sync start


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

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.


5. While the job is running, you can stop it by accessing its More Actions menu and selecting the Stop option in the dropdown list as shown below.

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