• What is the Shelf Content Integration Layer?
• What purposes does this feature serve?
• How is it enabled?
• How is it configured?
• How is it used in practice?

In order to create a custom connector, follow the below procedure:

1. On the Connectors page, click the CREATE CONNECTOR button as shown in Figure 3 above.
2. On the Create Connector page that appears, fill in the fields as described below.

Figure 4. Creating a custom connector

Table 1. The Create Connector Page Elements and Their Details

❗Note: 

Fields and other elements marked with an asterisk are mandatory and cannot be left blank.

Figure 5. Viewing the newly created custom connector

If you are able to see your newly created custom connector - in our case, it is Zendesk_Shelf - in the list, it means that you have successfully created the custom connector. You can differentiate prebuilt connectors as they have Shelf in the Created by column.

Any custom connector can be edited if needed. For this purpose, perform the following steps:

1. Go to the More Actions menu by clicking the More Actions (...) button (1) and select the Open option (2).

Figure 6. Accessing and using the More Actions menu

Figure 7. Editing the custom connector

Once the needed changes are made to the custom connector, click the SAVE button to confirm them and update the connector. Otherwise, click the CANCEL button to cancel the connector editing and close the Update Connector page.

❗Note: 

When you edit a connector and change its name, API URL, or API Key, the respective changes are made to connection profiles and sync flows that use the edited connector. For instance, when you change the connector name, it is changed in all connection profiles using this connector. When you change the API URL or API Key for the connector, this change applies to all sync flows that use a connector profile, which, in its turn, uses the edited connector. The changes made in this case come into force at the next run of the respective sync flow.

Any custom connector can also be deleted if no longer needed. In particular, when there are no connection profiles that use such a connector. It can be done in two ways as described below.

1. Go to the needed connector’s More Actions menu by clicking the More Actions (...) button (1) and select the Delete option (3). In the popup window that appears, confirm that you still want to delete the connector by clicking the DELETE button. Otherwise, click the NO, CANCEL button to cancel the deletion and retain the connector.

Figure 8. Confirming or canceling the connector deletion

Once you have clicked the DELETE button, the Update Connector page closes, the connector becomes deleted and removed from the list of available connectors on the Connectors page.

Once you have performed the actions described in either of the above two methods and no error messages have been displayed, it means that you have successfully deleted the custom connector and removed it from the list of available connectors on the Connectors page.

❗Note: 

Remember that deleting a connector is irreversible, that is you are not able to restore it later. However, you cannot delete a connector if there is a sync flow using this connector via some connection profile. In such a case, you first need to delete that sync flow, then delete that connection profile, and only after that delete the needed connector.

Now that you have learned how to create, edit, and delete custom connectors and successfully created your own custom connector, you can proceed to the next stage of the Content Integration Layer configuration, which is creating and configuring a Connection Profile.

Creating a new connection profile is needed, for example, when the existing connection profile’s API token expires. In such a case, you need first to create a new API token via your content storage or management system’s capabilities, and then to create a new connection profile with this new API token.

Same approach applies in case of a change in user email address or password - you need to create a new API token first, because it contains user credentials inside it. Once the new relevant API token is available, you can create a new connection profile for a new user email address and with this new API token. Attempting to use expired user credentials or API token results in the display of the respective error message.

You can also create multiple connection profiles for your connector. It may be needed when you need to provide different user roles different levels of access to your or third-party platform’s content. In such a case, these different user roles will have different credentials, which you need to use when creating the relevant connection profiles for these user roles.

Sometimes, different user roles may have access to different instances of your or third-party content storage or management system. In such a case, to enable these roles to access content on the respective system instance, you need to create new connection profiles with the relevant instance URLs.

In order to create a connection profile and associate any prebuilt or custom connector with it, follow the below procedure.

1. On the Connection Profiles page, find and click the CREATE CONNECTION PROFILE button.
2. On the Create Connection Profile page that opens, fill in the necessary fields as shown in the figure below.

Figure 10. Creating a connection profile

Table 2. The Create Connection Profile Page Elements and Their Details

❗Note: 

Fields and other elements marked with an asterisk are mandatory and cannot be left blank.

Once you have clicked the CREATE button and no error messages have been displayed, it means that you have successfully created your custom connection profile. You can verify it by checking the table grid on the Connection Profiles page: if you can see the connection profile you have created in the list, it means it has been successfully created and saved.

Figure 11. Checking the connection profile availability

Note that you cannot edit connection profiles, no matter whether they are prebuilt by Shelf or manually created by you. You can open them only to view their data as shown below. In case you need to modify a custom connection profile, you need to create a new one and enter the new, correct data.

Figure 12. Viewing the connection profile details and properties

Using the Content Integration Layer feature of Shelf, you are able to delete any connection profile excluding those prebuilt by Shelf.

To delete a connection profile, follow the below steps.

1. When on the Connection Profiles page, click the More Actions menu (...) button next to the needed custom connection profile and in the dropdown menu select the Delete option.

Figure 13. Deleting the connection profile

Figure 14. Confirming/canceling the connection profile deletion

You can also use an alternative method to delete the connection profile.

For this purpose, when on the Connection Profiles page, click the More Actions menu (...) button next to the needed custom connection profile and in the dropdown menu select the Open option. On the View Connection Profile page that appears, locate and click the DELETE button at the bottom of the page. Then, confirm your intention to delete the selected connection profile by clicking the DELETE button in the popup window that appears, as shown in Figure 14 above.

Regardless of the method you have selected to delete the connection profile, once you have confirmed your desire to delete the connection profile and if no error messages have been displayed after clicking the DELETE button in the popup window, the selected connection profile is deleted and removed from the list of available connection profiles in the table grid on the Connection Profiles page.

It should be also noted that deletion of connection profiles cannot be undone and they are deleted with no possibility of restoring.

Now that you have learned what connection profiles are, how you can view, create, or delete them, you can proceed to the next stage of the Content Integration Layer configuration - creating and configuring Sync Flows.

In order to create a new custom sync flow, once on the Sync Flows page, perform the following procedure.

1. Click the CREATE SYNC FLOW button.
2. On the Create Sync Flow page that opens, fill in the fields as shown in the figure below and detailed in Items 1-5 of Table 3 above.

Figure 22. Creating a custom sync flow

At this step, you need to select one of available connection profiles, give name to your new sync flow, optionally provide some description to this sync flow, and also select how it is expected to be executed: on demand or according to some schedule. See more about the run type options in Items 4-7 of Table 3 above.

Figure 23. Adding filters to streamline your content synchronization

❗Note: 

It needs to be mentioned that there are some restrictions regarding the filters. In particular, it relates to the Updated At and Created At filters. These filters will not work on their own as standalone filters. It means that they need to be used in combination with any other filter, for example with Label Names, Text, or Section. However, the Updated At filter can be used as a standalone filter if you choose the greater than value in the Criteria field. 

See more details about filters in Items 10-11 of Table 3 above. 

You can also remove any unneeded filter as well. For this purpose, click the trash bin icon that pops up when you hover over the needed filter.

Figure 24. Deleting a filter

Once the CREATE button is clicked, wait for the display of a message about the successful creation of the sync flow. Once such a message is shown, your sync flow has been created, and you can check it in the table grid on the Sync Flows page.

Figure 25. Verifying the sync flow availability

Note that creating a sync flow does not mean that it starts immediately after the creation. If you create an on-demand sync flow, it will run only after you start the sync job manually as described in the Starting and Stopping the Synchronization Job section below. In case you create a scheduled sync flow, its execution is expected to start in [N] hours or days (depending on which option - Hours or Days you have selected in the Period field during the sync flow creation) after its creation.

It may occur that at some point you would need to make changes to the sync flow: to change how it needs to be executed, enter or remove its name or description, add or remove filter(s), or even switch to another connection profile. All the mentioned actions are enabled for custom sync flows only, and you cannot edit any prebuilt sync flow, if any.

Follow the below steps to make necessary changes to your custom sync flow.

1. Once on the Sync Flows page, find the needed sync flow in the table grid or using the search feature.
2. Once the needed sync flow to be edited has been found, click the More Action (...) menu icon next to it.
3. In the dropdown list menu that appears, select the Open option.

Figure 26. Opening the sync flow for editing

If you decide to save the changes, then confirm it in the popup window that opens after you click the SAVE button on the Edit Sync Flow page.

Figure 27. Confirming the change saving

Once the above steps have been completed without any error messages, it means that you have successfully edited the needed sync flow.

In case you no longer need some certain sync flow, you can always delete it. Note that you cannot delete prebuilt sync flows. Only custom sync flows, that is those sync flows that have been created by you, can be deleted.

It needs to be mentioned that you cannot also delete a sync flow if there is a sync job running under it. In case you attempt to delete such a sync flow, the respective error message is displayed from which you can navigate to the Jobs tab where you can cancel the necessary running sync job.

To delete a sync flow, follow the below steps.

1. Once on the Sync Flows page, find the needed sync flow in the table grid or using the search feature.
2. Once the needed sync flow to be edited has been found, click the More Action (...) menu icon next to it.
3. In the dropdown list menu that appears, select the Open option.
4. On the Edit Sync Flow page that opens, navigate to its bottom, find and click the DELETE button.

Figure 28. Deleting a sync flow in CIL

Figure 29. Confirming the sync flow deletion

Once the above steps have been completed, the selected sync flow has been deleted and removed from the table grid on the Sync Flows page.

However, there is an alternative and more simple way to delete sync flows. To walk this path, once on the Sync Flows page, find the needed sync flow in the table grid or using the search feature. Once the needed sync flow to be edited has been found, click the More Action (...) menu icon next to it. In the dropdown list menu that appears, select the Delete option. Finally, confirm your choice by clicking the DELETE button in the popup window that appears.

Once any of the two abovementioned procedures has been completed, the needed sync flow becomes deleted.

Once you have created or updated a 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 the synchronization of your content, follow the below steps.

1. Once on the Sync Flows page, find the needed sync flow in the table grid or using the search feature.
2. Once the needed sync flow for which you want to start the synchronization has been found, click the More Action (...) menu icon next to it and, In the dropdown list menu that appears, select the Open option. Or you can open the sync flow simply by clicking on it in the table grid.
3. On the Edit Sync Flow page that opens, navigate and select the Jobs tab.

Figure 30. Starting the synchronization job in CIL

Figure 31. Triggering the synchronization job

Once the above steps have been completed, the job becomes 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 is no other sync jobs running in this sync flow, the Jobs tab window refreshes, and a new job appears in the table grid. The status of this new job is IN PROGRESS, meaning that the job is not yet finished.

Figure 32. Viewing the triggered job

At this very stage, you can stop the synchronization job by accessing the More Actions menu for this job by clicking the respective More Actions (...) menu icon next to it, and selecting the Stop option in the dropdown list as shown below.

Figure 33. Stopping the synchronization job

Then, in the popup window that appears, select the STOP button to confirm that you want to stop the running job.

Figure 34. Confirming the job stopping

The job becomes stopped and changes its status in the respective column of the table grid in the Jobs tab window.

If you decide not to stop the job, refresh the page when the job status is IN PROGRESS. The status will change to SUCCESS, meaning that the job has been successfully executed. The table grid columns provide you with the details about the job result. See more about it in Table 4 above.

Once the respective job has been successfully executed, you can go and check whether any content has been synced as a result of this job.

For this purpose, once on the Edit Sync Flow page, find and select the Recent Sync tab to open it.

In the Recent Sync tab window that appears, you can see which content items have been synced during the performed job. Note that only the last 50 sync items of the content are shown in the table grid in the Recent Sync tab window.

Figure 35. Viewing the synchronization job results

In our case, we used the filter - Text - in order to sync only the matching content. The filtering criteria was that the content needs to contain the word “dog”. The content item we see in the table grid must have some text that contains this word.

In order to verify that the synced content item contains this word, you can access this item directly from CIL. For this purpose, hover the pointer over the content item name and then click the link icon appearing next to that name.

Figure 36. Following the content item link to the external resource

If everything is configured properly, you will access the needed content item on the external portal where it is stored.

Figure 36. Viewing the synced content item on the external resource

If you need more details about the Recent Sync tab, its table grid, and other elements, see Table 5 above.

The CIL Collection Permissions functionality is only operational when there is at least one connector, one connection profile, one sync flow created and at least one external collection with some content synced to Shelf.

One user group can have access to not more than 100 collections. If the number of collections exceeds 100, the ability to provide access for the user group to one more collection is disabled and the ADD COLLECTIONS button becomes inactive.

To enable the CIL Collection Permissions, follow the below steps after logging in to your Shelf account under the Admin role and go to the Admin Panel.

1. In the Admin Panel, find and select the User Groups submenu in the left sidebar panel.

Figure 37. Accessing the User Groups feature in the Shelf Admin Panel

Figure 38. Viewing the collection permissions for the selected user group

Figure 39. Adding collections for the needed user group

Once the needed collections have been added, they become available for CIL users and can be used as content sources for the CIL purposes.

In case if some user group no longer needs to have access to some collection(s) via CIL, this access can be removed using the Collection Permissions feature.

To do so, once in the Collection Permissions tab window for the needed user group, find the collection you want to disallow for this user group and click the trash bin icon next to it.

Figure 40. Removing the collection permissions for the needed user group

Confirm that you want to delete the collection by clicking the REMOVE button in the popup window that appears.

Figure 41. Confirming the collection access revoking

Once done, the popup window closes and the collection access to which has been removed for the subject user group becomes unavailable in the list of collections. Moreover, users within this user group lose access to any content kept in the respective collection, both on the end of the Shelf Answer Automation products (Answer Assist etc.) and in the Content Integration Layer interface (the Sync Flows module > the Recent Sync tab).