Shelf Federated Search End-to-End Guide


Document Version History

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

27 October  2022

Expired

1.1

Shelf

Changes and fixes introduced to the document to update it.

27 April 2023

Active






















Document Purpose

This document provides an understanding of what the Shelf Federated Search feature is, how it is configured, and how it can be used. The guide’s target audience is Admins and Content Managers of the organizations subscribed to the Shelf Answer Assist product. This particular version of the document is developed for Ring.

If you require further assistance, please do not hesitate to contact us at support@shelf.io, via the live chat on the Shelf website or from the in-app chat support within the Shelf platform.





Federated Search Definition and Purpose

The Shelf platform supports advanced search capabilities to enable our clients to easily and efficiently look for and find the needed content. However, it is only efficient if the search is performed across the content stored in the Shelf Knowledge Management System. 

Knowing that multiple clients are subscribed to Answer Assist, a Shelf Answer Automation product, store their content externally, and willing to help them improve their experience of using Answer Assist while enabling them to easily find content they store outside the Shelf platform, Shelf has implemented the Federated Search feature.

What Federated Search does is that it helps Content Admins, Content Managers, and Agents search for the needed content simultaneously across Shelf and across their own or third-party content storage platform from within Answer Assist.

Operation of Federated Search is implemented via Shelf’s proprietary Content Integration Layer feature and also requires the properly configured Answer Assist. 

Detailed information on the Content Integration Layer and Answer Assist products can be found in the respective Content Integration Layer Feature Guide and Answer Assist End-to-End Guide.


Prerequisites

In order to start using the Shelf Federated Search, the following conditions must be met:
  • Content Integration Layer feature must be enabled on the Shelf side
  • Zendesk Connector option must be enabled on the Shelf side
  • Your user role in Shelf must allow for accessing the Admin Panel in Shelf and managing various settings there

Once all the prerequisites are met, you can proceed with the initial configurations needed to start using Federated Search. 




Configuring the Content Integration Layer Settings

Content Integration Layer, or CIL, is a feature that allows for connecting the Shelf Answer Automation products with various knowledge and content management systems, not only Shelf KMS. 
The feature serves as a director and a mediator between the Shelf Answer Automation products and the customers’ or third-party CMS, with no need to implement any other integrations. 
CIL fetches the content from CMSs to the Shelf Answer Assist and lets users enjoy fast and efficient Answer Automation capabilities.

The Shelf Content Integration Layer consists of the following modules:
  • Connectors Module
  • Connection Profiles Module
  • Sync Flows Module

All these modules are accessible from the Shelf Admin Panel and have their own block of the menu. 

Figure 1. Content Integration Layer in the Shelf Admin Panel


        

Configuring the Connector 

In the Shelf terminology, a connector is an entity that defines which external Content Management System Shelf is to connect to through Content Integration Layer (e.g. the Zendesk connector is a set of API parameters to define how to connect Shelf to Zendesk).

In fact, Shelf has prebuilt and preconfigured the connector needed for Content Integration Layer to work with Zendesk. You can find it in the Connectors menu of the Content Integration Layer block in the Shelf Admin Panel.

Figure 2. Viewing the Zendesk Connector prebuilt by Shelf

It means that it is not necessary for you to create the Zendesk Connector from scratch. However, if you want to create a new connector, please refer to the respective section of the Content Integration Layer Feature Guide where the new connector creation procedure is described in detail.


          

Configuring the Connection Profile 

The next step of the preparation needed before you can start using the Federated Search feature in Answer Assist is to create and configure the Connection Profile.

According to the Shelf’s terminology, a connection profile is a specific instance of your connector with the user's credentials that make it possible to connect to it. In other words, a connection profile can be used to provide segregated access to content for a specific unit or department or person within an organization via the relevant connector. 

As in case with the connectors, connection profiles are stored and created in the Connection Profiles section of the Content Integration Layer block in the Shelf Admin Panel.

Figure 3. Viewing the Connection Profiles in the Shelf Admin Panel

Once you have opened the Connection Profiles menu, you need to create the connection profile. For the purpose of this guide, the relevant Zendesk_CP Connection Profile has been already prebuilt by Shelf. This connection profile uses the Zendesk Connector also prebuilt by Shelf. 
However, if you need to have your own connection profile, please refer to the respective section of the Content Integration Layer Feature Guide where the new connection profile creation procedure is described in detail.

Note: 
If you create the connection profile from scratch, it is important to note that you need to have valid credentials - email address used to log into your account and API token -  for your account on Zendesk.
You also need to make sure that you entered the right URL address of your Zendesk instance. For the purpose of this guide, the Instance URL is support.ring.com hosted on Zendesk.

Figure 4. Viewing the Connection Profile creation form


Configuring the Sync Flow

The next step is to create and configure the sync flow for the previously created and configured connector and connection profile. 



Creating the Sync Flow

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

  1. On the Create Sync Flow page that opens, fill in the fields shown in the figure below. 
    At this step, you need to select the previously created and configured connection profile - in our case it is Zendesk_CP, 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. 
    Figure 5. Creating a new sync flow

  2. Once you have selected the connection profile, named your new sync flow, entered or not entered any description for it, and selected how it needs to be run, the Content Filtering block becomes available, where you can add some filters - not more than 100 filters per one sync flow - in order to sync only that content which matches the filtering criteria. 

    Figure 6. Adding filters to streamline your content synchronization

  3. Once you have filled in all the needed fields and added, or not added, some filters for the content to be synced, click the CREATE button as shown in Figure 6 above, in order to finish the sync flow creation procedure.
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 7. 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 of the Content Integration Layer Feature Guide. 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.


Starting the Sync Job

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.
    Figure 8. Accessing the Edit Sync Flow page
  3. On the Edit Sync Flow page that opens, navigate and select the Jobs tab. 

    Figure 9. Starting the synchronization job in CIL

  4. In the Jobs tab window that appears, find and click the TRIGGER NOW button to launch the synchronization job for the selected sync flow. In the popup window that opens, confirm your desire to start the content synchronization by clicking the SYNC button. 
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. 

If there are 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 10. Viewing the triggered job

Note: 
The started synced job is not refreshing automatically when it is performed. You need to manually refresh the page to see whether the content is being synced.

Once the sync job has been completed and no errors have occurred, its status will change to SUCCESS. Now you can open the Recent Sync tab to see the content synced by this job.

Figure 11. Viewing the content synced by the triggered sync job

Now, when you have completed the configuration of your connector and connection profile and successfully run the sync job and synced some needed content, it is time to configure permissions needed to view/search the external content via Answer Assist. 


Configuring the Permissions for External Content

In order to configure the permissions needed for you to search and view content, which is stored externally, in the Shelf Answer Assist, you need to perform the following procedure.

  1. In the Shelf Admin Panel, find and select the User Groups menu in the sidebar panel.

    Figure 12.  Accessing the User Groups functionality in Shelf

  2. In the User Groups page that opens, find and select the needed user group from the list of available ones, by clicking on it. 
  3. In the page that appears, find and open the Collection Permissions tab. Next, click the ADD COLLECTIONS button since the user group has no permissions to view and access external collections yet.

    Figure 13. Adding permissions for the user group to work with external collection(s)

  4. In the new popup window, find and select the needed collection by selecting the respective checkbox and then click the ADD button.

    Figure 14. Adding the needed collection

  5. Once done, make sure the needed collection and the connector are displayed in the table grid of the Collection Permissions tab.

    Figure 15. Verifying that the external collection has been added for the user group 

Once the collection has been added for the needed user group, you can now proceed to the next step which is enabling the Federated Search feature for your Answer Assist configuration.



Enabling Federated Search for the Answer Assist Configuration

To enable the Federated Search feature for your Answer Assist configuration, perform the following steps.

  1. In the Shelf Admin Panel, find and select the Answer Assist Configurator option in the sidebar panel.

    Figure 16. Accessing Answer Assist Configurator in Shelf

  2. In the Answer Assist Configurator window that opens, find and select your Answer Assist configuration by clicking on it.

    Figure 17. Selecting the Answer Assist configuration

  3. In the window that opens, find and select the Advanced tab. This is the place where you configure advanced settings for your Answer Assist integration configuration. All the configurations here are implemented by means of JSON parameters and values entered in the Code Editor field. 
  4. In the Code Editor field, add the following string to your JSON code: “isCILSearchEnabled”: true. Following that, click the SAVE button.
    Figure 18. Adding the Federated Search support for your Answer Assist integration
If no errors have been returned it means that you have successfully enabled Federated Search for your Answer Assist integration and now can test how it works.


Verifying and Using the Federated Search Feature in Answer Assist

Verifying the Federated Search Feature Operation

In order to verify that the Federated Search feature is operational, go to the Preview tab in your Answer Assist Configuration window.
 

Figure 19. Accessing the Preview tab for your Answer Assist Configuration

In this tab, you can test the operation of your Answer Assist integration on the fly, immediately after making changes to its settings either general or advanced. 
The tab hosts the fully functional Answer Assist widget where you can test all of its features and capabilities, such as suggestions, announcements, and, most importantly, search.

To verify that the Federated Search feature is now fully operational, perform the following steps.
  1. Select the Search tab in the Answer Assist widget by clicking the magnifying glass icon.

    Figure 20. Accessing the Search tab and Advanced Search feature  in Answer Assist

  2. In the Search field, click the menu icon to access the advanced search options.
  3. In the popup window that appears, find and click the Source field. 

    Figure 21. Checking the external content source integration

If the dropdown field that opens contains the external content source you have integrated and configured during the previous procedures, it means that you have successfully enabled and configured the Federated Search feature for your Answer Assist integration and now can start using it.



Using the Federated Search Feature in Answer Assist

Federated Search helps you to search for the needed content without thinking where it is stored - in Shelf or in your external system, i.e. Zendesk. 

All its capabilities are implemented in the advanced search options accessible by clicking the menu icon in the search field of the Search tab.

Figure 22. Advanced search capabilities with the Federated Search feature enabled for Answer Assist
(1) Collection: You can filter your search by the needed collection(s) only. Both Shelf KMS libraries and external libraries can be selected for search results filtering.

Figure 23. Filtering the search by collection(s)

(2) Language: You can filter your search by the language of content. 

Figure 24. Filtering the search results by the content language


(3) Source: You can filter your search by the source - Shelf KMS or external storage or both

Figure 25. Filtering the search by source

(4) Tag: Finally, you can filter your search results by tags assigned to your content - Gems or Articles. Multiple choice and search by keyword are supported.

Figure 27. Filtering the search results by the assigned tags


                           

Difference in the Content Appearance and Display 

The important peculiarity of the Shelf Federated Search is that you can immediately tell where the content you have found is stored - in Shelf or in your external content storage. It is possible thanks to labels displayed near each of the found content items. 


Figure 28. Viewing the content from different sources in one place

In case the content is fetched from your external storage, the label near all such content items will be the same and will display only such external storage loge. At the same time, content items that are stored in Shelf KMS will bear individual labels, depending on the type of the Gem. 

Figure 29. Viewing the different Gem types
Another important consideration is that the content stored in Shelf KMS and the content stored in your external system are viewed in a different way: 
  • Content stored in Shelf is opened in the Gem tab of your Answer Assist widget

    Figure 30. Viewing the Shelf content in Answer Assist

  • Content stored in your external storage system opens in your external system in a new tab or window of your browser. 

    Figure 31. Viewing the external content in the external storage system, Zendesk



Conclusion 

Now, when you have read and walked through this guide, you are able to properly configure the Shelf environment necessary for the Federated Search feature operation and the Federated Search feature itself.
 
In case you have any questions in relation to Federated Search, Content Integration Layer, or Answer Assist, feel free to contact us at support@shelf.io or from the in-app chat support within the Shelf platform.