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

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

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.

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

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

Figure 11. Accessing CIL modules in Admin Panel

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.

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 

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

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

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

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

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

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.

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.