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

For proper operation of your Zendesk connector and successful synchronization of your content from the Zendesk platform into Shelf KMS, the following preconditions must be met:

• Admin Panel must be accessible on your Shelf KMS account
• Zendesk account must be created and configured
• Content items (articles, documents, etc.) must be available in your Zendesk storage.

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 Zendesk.
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 Zendesk connector to sync your content from Zendesk into Shelf KMS, you need to do certain actions both in Zendesk and in Shelf. Read the chapters below to learn what exactly you need to do.

Once you have logged in to your Zendesk account in your web browser, navigate to the address bar and copy the URL address which is your Zendesk instance URL.

Copy it and save locally for further use during the configurations on the Shelf side.

To get the Zendesk API token needed for the proper integration of your Zendesk instance with Shelf KMS, perform the following steps.

Your new Zendesk API token is now created and saved. It is visible on the list of active API tokens. Moreover, you have copied it to the clipboard and can save it locally for further use.

Once done, all the configurations on the Zendesk side are completed. You now have all the parameters - Zendesk login email address, Zendesk instance URL, and Zendesk API token - needed to set up your Shelf KMS for syncing content from your Zendesk storage. You can now proceed to the configurations on the Shelf side as described in the sections below.

From the standard workflow described above you see that to start configuring and using your Zendesk 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.

In fact, no configurations are needed for your Zendesk 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.

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 Zendesk storage.

The Zendesk connection profile is a feature that uses the prebuilt Zendesk connector and allows Shelf KMS to access, authenticate on Zendesk, 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 Zendesk, so you need to create a new connection profile. Click the Create Connection Profile button to start.

In the Runtime Settings section, you need to enter the Zendesk instance URL value you have copied from the address bar once in your Zendesk account. In the Credentials section, in the Email field you need to enter the email address you use to log in to your Zendesk account. In the API Token field, you need to respectively enter the Zendesk API token you have previously created and copied.

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

Now that you have configured the Zendesk connector and connection profile, you need to create and configure the Zendesk 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 - Zendesk.

To create and configure the Zendesk 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.

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

Once you have created the Zendesk 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 Zendesk into Shelf, follow the below steps.

1. Open the newly created Zendesk 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.

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

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 Zendesk 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 Zendesk into Shelf.

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

Even when you successfully configured the Zendesk connector, connection profile, sync flow, run the sync job and pulled the content from your Zendesk repository, you need to add Zendesk 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.

In the selected user group window that opens, go and select the Collection Permissions tab. Once it opens, click the Add Collection button.

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

Figure 24. Selecting Zendesk collections

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

Figure 25. Viewing the added Zendesk collections

Once done, you are finished with all the configurations needed to sync content from Zendesk into Shelf KMS using the Zendesk connector.