Shelf App for Salesforce: Installation and Configuration Guide 

Installation and configuration 

Add the package 

Figure 1. Browsing the Installation screen

1. Indicate users for which you want to install the Shelf App by selecting the respective installation options, for example - Install for All Users. 
2. Select the I acknowledge… checkbox to confirm that you are aware that the Shelf App is not placed on Salesforce AppExchange and is distributed on an as is basis. 
3. Click the Installbutton.
   

   Figure 2. Initiating the installation

4. Since the app is using third-party services, you need to approve the access by clicking the Continuebutton:
   

   Figure 3. Enabling third-party services in version 1.x and 2.x packages 

   

   Figure 3a. Enabling third-party services in version 3.x package
5. Once the installation is underway, you will see a progress bar displayed. Once the installation is finished, the Installation Complete! the message is displayed. You will also receive a corresponding email message titled “Package Shelf Install Successful”. Once the respective messages are received, click the Donebutton to close the installation window.
   

   Figure 4. Finishing the installation process

Configure the package 

Configuring version 1.x and version 2.x packages

Content Library Configurator in 1.x and 2.x package versions uses Custom Metadata to save configuration and you have to give the right for the App to create it. For this purpose, go to the Setup page, search for Apex Settings in the search box, and then select the respective checkbox in the window that appears. Once done, confirm your selection by clicking the Save button.

Figure 5. Enabling metadata deployment from non-certified package versions via Apex

Configuration procedure for version 1.x package

1. Once the initial installation is successfully completed, you are able to see the Shelf App on the list of installed packages. To get to this list, follow the path: Setup (Home) > Installed Packages.
   

   Figure 6. Viewing installed packages

2. Near the installed Shelf App, click the Configurelink button to get to the configuration options for the Shelf App. 
   

   Figure 7. Viewing configuration options for Shelf App

Table 1. Details of Shelf App’s configuration options

Configuration procedure for version 2.x package

1. Once the initial installation is successfully completed, you need to open the Shelf configuration menu. To do so, go to your Salesforce instance’s Application menu and search for the Shelf Configurationapplication there. 
   

   Figure 8. Finding the Shelf Configuration application in the Salesforce Application menu
2. Once you have found the Shelf Configuration application, open it and complete the configuration options as needed. Refer to Table 1 above for details on the configuration options.
   

   Figure 9. Completing the configuration options for Shelf App 

Configuring version 3.x package

Figure 10. Accessing Shelf Datadog Configurator app

Figure 11. Viewing and copying the Datadog public API key

• message (error or warning message), 
• Salesforce environment-related information, like hostname, Org name, User ID, environment type, etc
• Shelf environment-related information, like server region, account id

• AgentAssist Utilitybar menu click
• The duplicated Utilitybar component is loaded
• AgentAssist failed initialization
• AgentAssist config fetching
• AgentAssist loading duration
• Fetching suggestions for Salesforce Record
• Fetching suggestions for the Chat
• Error message for failed component loading

Configure access 

1. Go to Setup (Home) > Permissions Sets > Shelf Assist Access.
   

   Figure 12. Accessing permission sets 

2. In the Permission Sets window that appears, click the Manage Assignmentsbutton.
   

   Figure 13. Starting permission set assignment

3. In the window that opens, click the Add Assignment button. Then, in the window that appears next, select the checkbox(es) next to the needed user(s) and click the Next button.
   
   

   Figure 14. Assigning a user

4. In the next window, select a suitable expiration option for the user you are assigning, by selecting the appropriate checkbox. Once done, click the Assign button to complete the assignment procedure.
   

   Figure 15. Setting the expiration date for the assigned user 

Configure Shelf components 

Figure 16. Accessing Lightning App Builder

1. To start editing, click the Edit link button near the needed Lightning Page.
   

   Figure 17. Starting the Lightning record page editing

2. In the next window that appears, you can simply drag and drop a needed Shelf component or components from the left-side Components panel’s block titled Custom - Managed.
   

   Figure 18. Placing Shelf Assist component on the page (package 1.x and 2.x versions)

   

   Figure 18a. Placing Answer Assist component on the page (package 3.x version)

Table 2. Shelf components and their details

Figure 19. Page activation prompt

4. Once in the Activation: [Page Name] window, if you have no other record pages, you can set your new page as the default one, set its form factor, and confirm your settings.

Figure 20. Setting the page as default

Figure 21. Selecting the page form factor

Figure 22. Reviewing and saving the page

Figure 23. Viewing your Account Record page with the added Shelf Component

Configure Shelf Assist 

Configuring Answer Assist on Shelf

1. Log in to Shelf under your Admin credentials and navigate to the Admin Panel. Then select the Answer Assist Configurator submenu in the Admin Paneltree menu.
   

   Figure 24. Accessing Answer Assist Configurator on Shelf

2. Select a configuration to open its settings. 
   

   Figure 25. Accessing Answer Assist configuration

   
   

3. Go to the Advancedtab and add the desired configuration for Shelf Assist. For each object in Salesforce to which you intend to add Shelf Assist, define the fields that Shelf should interpret in order to render context-aware suggestions. 
   

   Figure 26. Accessing and configuring Advanced settings of Answer Assist

   See an example configuration below that configures Shelf’s Answer Assist for Cases in Salesforce ServiceCloud and for Opportunities in Salesforce SalesCloud. {
       "salesforce": {
           "suggestionAttributes": {
               "Case": {
                   "fields": [
   "Description", 
   "Subject", 
   “amazonconnect__AC_Contact_Id__c”]
               },
               "Opportunity": {
                   "fields": ["Name"]
               }
           }
       }
   }
   Note:
   As seen from the code snippet above, the Amazon Connect Contact Id field support has been added for the Salesforce Case object. The respective API name is amazonconnect__AC_Contact_Id__c.   This support allows using Connect ID as Conversation ID (Interaction ID) and replacing Case Record ID. 
4. Save the configuration by clicking the SAVE button.
   
   Note:The Assist Advanced Configuration is not limited to Salesforce and may contain other settings as well. 
   
   Note:
   Make sure to add the following lines to JSON code in the Advanced tab: 
   },
     "assist": {
       "enabled": true
   These lines are responsible for enabling the context-mapped suggestions in Shelf’s Answer Assist.
   
   

   Figure 27. Viewing the context suggestions enabling lines

5. Once the configuration is saved, go to the General tab and copy the Configuration ID.
   

   Figure 28. Copying Answer Assist Configuration ID

   Once done, save the copied Answer Assist Configuration ID to a file for further use.

Configuring dynamic context-mapped suggestions

1. Setup the content mapping in the Content Mapping submenu in the Shelf Admin Panel.
   
   

   Figure 29. Starting the Content Mapping

   1. Initiate the search with a filter you want to map an external Salesforce field to. In this exemplary case, we use Unit__c Salesforce field as the tag filter on Shelf to narrow down the suggestions.
      
      

      Figure 30. Running tag-filtered search and viewing search results

   2. Copy the search result URL in the browser search bar. 
   3. Go to https://{your_subdomain}.shelf.io/admin-panel/content-mappings/ 
   4. Click the ADD MAPPING button. Then, In the mappingValue field,  paste the copied search result URL, but replace the selected tag (pizza, in our case) with a dynamic variable, which in this exemplary case is {{tag}} .
      

      

      Figure 31. Setting the mappingValue

   5. Once done, click the OK button of the mappingValue field and then SAVE. Now, your Content Mapping configuration is saved.
2. Now, you need to configure the Answer Assist context suggestions. Go to the Answer Assist Configurator in your Admin Panel, navigate to the Advanced tab, and make the respective changes to the JSON, paying attention to the following details:
   id - the unique value among different contextTypes 
   type - “text” 
   accessor - the JSON path to an external Salesforce context value.
   

   

   Figure 32. JSON code in Answer Assist Configurator’s Advanced tab

intent - the intent of content mapping

Figure 33. Intent value in the Content Mapping Configuration

intentGroupId - (optional) the intentGroupId of content mapping (defaultIntentGroupId will be used if not provided)

Figure 34. IntentGroupId value in the Content Mapping Configuration

templateVariableName - the name of dynamic value in content mapping into which external context will be applied 

Figure 35. mappingValue in the Content Mapping Configuration

Make sure to set proper values in the JSON code. Our exemplary case’s JSON is expected to be as follows:

{   "salesforce": {     "suggestionAttributes": {       "Chat": {         "fields": [           "Message"         ]       },       "Case": {         "ai": {           "fields": [             "Description"           ]         },         "context": {           "fields": [             "Subject"           ]         },         "fields": [           "Description",           "Subject",           "Status",           "Type",           "Reason",           "Priority"         ]       },       "Opportunity": {         "fields": [           "Name",           "Description",           "Subject"         ]       }     }   },   "contextSuggestions": {     "contextTypes": [       {         "options": [           {             "intent": "pizza",             "intentGroupId": "food",             "value": "food",             "displayName": "food"           }         ],         "id": "herbalife",         "color": "#067A46",         "type": "list",         "displayName": "Herbalife"       },       {         "accessor": "Case.Status",         "id": "Status",         "color": "#ffb75d",         "type": "text",         "displayName": "Case Status"       },       {         "accessor": "Case.Priority",         "id": "Priority",         "color": "blue",         "type": "text",         "displayName": "Case Priority"       },       {         "accessor": "Case.Subject",         "id": "Subject",         "color": "green",         "type": "text",         "displayName": "Case Subject"       },       {         "accessor": "Case.Description",         "id": "Description",         "color": "purple",         "type": "text",         "displayName": "Case Description"       },       {         "accessor": "Chat.Message",         "id": "ChatMessage",         "color": "purple",         "type": "text",         "displayName": "Chat Message"       },       {         "accessor": "Opportunity.Description",         "id": "OppDescription",         "color": "purple",         "type": "text",         "displayName": "Opportunity Description"       }     ],     "visibility": "menu",     "displayContextValue": true,     "enabled": true,     "defaultIntentGroupId": "food"   },   "contentLinking":      "enabled": true   },   "assist": {     "enabled": true   },   "tabs": {     "defaultOpenedTab": "suggestions"   } }

Figure 36. Viewing content suggestions in the Shelf Assist component on Salesforce

Configuring Shelf Assist on your Salesforce instance

1. Navigate to the page where you want to add the Shelf Answer Assist component and open the Setup menu.
   
   

   Figure 37. Accessing the page setup

2. Select the Edit Page option from the menu.
   
   

   Figure 38. Starting the page editing

3. Select the respective Answer Assist component (Shelf Assist 1.0, Shelf Assist 2.0 or Answer Assist (for version 3.x packages) from the respective block in the Components panel, and drag and drop in any needed place of the page you want it to be displayed.
   
   

   Figure 39. Placing Shelf Answer Assist on Salesforce page

4. Copy the Configuration ID you have previously copied on the Shelf side and paste it into the respective field of the Shelf Assist properties.
   
   

   Figure 40. Adding the Shelf’s Answer Assist Configuration ID on Salesforce

   Note:Note that now you don’t need to fill in the Shelf URL field as the URL address is automatically fetched from the Shelf App’s general settings, in particular - from the Metadata Configuration window. The Shelf URL field though not subject to manual population is retained in the Answer Assist Configuration window due to the Salesforce regulations.
5. Save changes by clicking the Save button. Once done, go back to the page and check if everything works as expected. 
   
   

   Figure 41. Viewing Salesforce page with the Shelf Assist component 

 

Adding custom label for Shelf Answer Assist

While in the Answer Assist Properties panel, you can also edit the text used as a title for your Answer Assist component on the Salesforce pages. To do so, find the Shelf Component Label for Page Template field and enter there the desired text. For example, instead of the label “Answer Assist”, we want to see “My Beautiful Answer Assist”.

Figure 42. Editing the Answer Assist label 

Once done, click Save and go back to the needed page to check. The label text should change.

Figure 43. Viewing the edited text for the Answer Assist label

Enable and configure the Utility Bar component (for version 3.x packages only)

Enabling Utility Bar

• Answer Assist must be enabled for your Shelf account
• Shelf App version 3.0 must be installed and configured on your Salesforce instance

1. Go to the Setup page.
2. Find and expand the Apps section in the left sidebar panel.
3. Select the App Manager option in the Apps menu. 
4. In the Lightning Experience App Manager window that appears, find the Sales app with Lightning type (or any app according to your business requirements).
5. Click the More Actions button to open the app’s context menu.
6. Select the Edit option in the menu.
   
   

   Figure 44. Accessing the Sales app in Salesforce

7. In the App Settings window that appears, find and select the Utility Items (Desktop Only) option in the left sidebar panel. 
8. Following that click the Add Utility Item button.
   

   

   Figure 45. Adding a new Utility Item in Sales App

9. In the dropdown menu that appears on the screen, find and select the Answer Assist option.
   

   

   Figure 46. Adding Answer Assist to Utility Bar

Configuring Utility Bar with Shelf Assist

After selecting Answer Assist—and, respectively, pre-adding it to Utility Bar—you need to perform its configuration. The figure below shows what configuration items are available and how you can complete them.

Figure 47. Configuring Answer Assist as a Utility Bar item

1. Label: In this field you can identify how your Answer Assist needs to be named in Utility Bar. You can leave it default—Answer Assist—or enter any desired name. Note that this field is mandatory and cannot be left blank.
2. Icon: This is responsible for the icon assigned to Answer Assist as a Utility Bar item. You can leave it default or delete the default one and select any suitable one.
3. Width: This setting is responsible for the width of the popup window in which Answer Assist is to open from Utility Bar. Note that the maximum width cannot exceed 720 px.
4. Height: This setting is responsible for the height of the popup window in which Answer Assist is to open from Utility Bar.
5. Start automatically: If you select this checkbox during the configuration, your Answer Assist as a Utility Bar item will start automatically once you log into your Salesforce. If not, you need to launch it manually by clicking the Utility bar App button.
6. Shelf Component Label for Page Template: This attribute allows you to adjust the text of the Answer Assist component’s label as displayed on your Salesforce pages. Details can be found in the respective subsection.
7. AA Configuration ID: This is where you need to enter some specific Configuration ID for your Answer Assist in Shelf. If you leave it blank, the first default configuration in the list of Answer Assist configurations is used.
8. Shelf URL: This is the address line for your Shelf instance domain that can be different based on your geography or market.

Figure 48. Viewing Utility Bar and Answer Assist widget added to it

Using Answer Assist as a Utility Bar item

1. Once you open the Answer Assist widget from Utility Bar, it remains open when you navigate across your Salesforce pages. However, if you navigate to any of your Opportunity or Case pages, the widget is automatically reloaded. It occurs to fetch suggestions from Shelf.
   
   

   Figure 49. Navigating in Salesforce with Answer Assist opened from Utility Bar
2. If you have opened the Answer Assist widget from Utility Bar and need to clear the display for better visibility of some Salesforce page elements, you can minimize the widget back to Utility Bar by clicking the Minimize button on the widget. When minimized to Utility Bar, the Answer Assist widget remains active and all the requests and suggestions are sent and received as usual.
   
   

   Figure 50. Minimizing Answer Assist back to Utility Bar

3. If you have minimized Answer Assist to Utility Bar and the new suggestion(s) is/are triggered, the respective notification arrives at the widget in Utility Bar. 
   
   

   Figure 51. Viewing notification on Answer Assist widget in Utility Bar

   You can make this notification disappear by re-opening the widget from Utility Bar or by opening the Case or Opportunity page with the added Answer Assist component where the suggestion(s) has/have been triggered.
   
   

   Figure 52 Removing the notification by reopening Answer Assist from Utility Bar

   

   Figure 53. Removing the notification by opening the Opportunity page with the added Answer Assist component

4. If you have the Answer Assist component added to any of your Case or Opportunity pages and attempt to open the Answer Assist widget from Utility Bar, you will see a warning message about the already running component in the widget.
   
   

   Figure 54. Opening Answer Assist from Utility Bar with the Answer Assist component working 

   In order to remove it, you need to reopen the Salesforce page you are on without the Answer Assist component and refresh it

      

Using Answer Assist from Utility Bar as a popup browser window 

Another scenario of using the Answer Assist widget added to Utility Bar is using it as a popup browser window. Shelf has implemented this capability to let you enjoy the improved user experience. In particular, using the widget in such a manner allows you to locate it anywhere on the screen so that it doesn’t prevent you from working with your Salesforce resources. 

To switch the widget to the popup browser window mode, open it from Utility Bar and click the Pop-out button.

Figure 55. Opening the Answer Assist widget as a popup browser window 

The widget becomes open in a separate popup window which you can resize by dragging its borders or relocate on the screen to a better position.

Figure 56. Opening, resizing, and repositioning the widget as a popup window 

The operation of the widget opened as a popup window is the same as described in the Using Answer Assist as a Utility Bar item section above. The only difference is that you can close the popup window of the widget in which case the window closes and the Utility Bar widget opens automatically.

        

First login 

When opening your Salesforce page with the Shelf Assist component installed for the first time, you will see the standard Shelf Login window (or the SSO Login window, depending upon your Shelf setup). 

Figure 57. Shelf Login window on Salesforce

After successful authentication you should expect getting content and suggestions from Shelf. 

Figure 58. Shelf Answer Assist showing suggestions

Shelf App tips

Deleting comments in Gems (ver 1.x and 2.x)

• You are logged in to your account in Shelf App on Salesforce
• You have a Gem in one of your libraries in Shelf KMS that has some comments.

Figure 59. Viewing Shelf on Salesforce

1. Find the needed Gem in Shelf App on Salesforce.
2. Open the Gem by hovering over it and selecting the Open option from its context menu.
   
   

   Figure 60. Opening a Gem in Shelf on Salesforce

3. Scroll down to the bottom of the Gem and find the Comments tab there. It is opened by default, so when you reach the bottom of the Gem, you can expect to see comments.
   
   

   Figure 61. Deleting a comment in Gem

4. Find the comment you want to delete and open its context menu. Select the Remove Comment option in the dropdown list as shown in the figure above.
5. In the popup window that appears, confirm your choice by clicking OK.
   

   

   Figure 62. Confirming the comment removal

6. The Gem page is automatically updated and the notification message is displayed telling that the comment has been successfully removed from the Gem. It means that the subject comment has been deleted and is no longer displayed in the Comments section of the Gem.

Highlighting search results (ver 2.x)

Searching data in Gems in Shelf App for Salesforce used to have some drawbacks - when you looked for something using keywords or keyphrases, you then needed to read the entire Gem offered in the search results to figure out whether it contains the relevant data. Now, with the new capability - highlighting keywords and keyphrases in the search results - you can easily and clearly see that you have found exactly what you have been looking for,

Let’s see how this capability works in real-life scenarios.

Prerequisites:

• You are logged in to your account in Shelf App on Salesforce
• You have Gems in your libraries on Shelf.

Figure 63 Viewing the Shelf App page on Salesforce

To check how Shelf App on Salesforce highlights keywords you look for, perform the following steps:

1. On the homepage of the Shelf App on Salesforce, conduct a search by entering some keyword(s) in the Search field as shown in the figure below.
   
   

   Figure 64. Performing search in Shelf App on Salesforce

2. Once the search is done, you will see search results, where the keyword you used is already highlighted. But that is not what we expect to see. To get to the needed destination, click the More Results button next to the Gem of your interest.
   
   

   Figure 65. Accessing the detailed search results for the selected Gem

3. Further, once you see the list of occurrences of the keyword you have been looking for, click on the highlighted keyword in the occurrence that matches your search.
   

   Figure 66. Viewing more results for a selected Gem

   
   

4. Once you have done it, the Gem will open in a new popup window where the keyword you have used in the search is highlighted in text. 
   

   Figure 67. Viewing the found Gem with highlighted search keywords

   
   

Keyphrases consisting of two or more words are supported by this capability.

Figure 68. Viewing the found Gem with highlighted search keyphrase

Note: 

If the keyword you look for is in singular, the highlighted results will show both singular and plural words. However, it applies to those words where the plural is formed in a simple manner - by adding “-s“ to the singular form of the keyword. If the plural is formed in a complex manner, that is by adding “-ies” or by using a special plural form, such plural keywords will not be highlighted. 

Viewing Gems in the Full Screen mode (ver 2.x)

For better user experience while using the Shelf App on Salesforce, we have made it possible to view Gems in the full-screen mode. You do not need to enable it additionally or otherwise use your efforts. The only thing you need to do is to click the Expand button in the Gem popup window.

The scenario is as follows:

1. Once you are in your Shelf App on Salesforce, logged in under your valid credentials, you can find and open any needed Gem. The Gem opens in a new popup window in the center of the screen.
   
   

   Figure 69. Viewing the Gem in the popup window

2. You can open the Gem in the full-screen mode by clicking the Expand button as shown in the figure above.

Figure 70. Viewing the Gem in the full-screen mode

To go back to the popup window, click the Expand button again.

         

Collapsing and expanding Shelf Answer Assist widget (ver 2.x)

One more great improvement has been introduced to the Shelf Answer Assist widget configured as a component for your Cases, Opportunities or other pages. Now, you can collapse and expand its view for better visual appeal of your respective pages. 

Note that by default Shelf Answer Assist widget is expanded. We would also like to mention that Figure 71 and Figure 72 below depict Shelf Assist 2.0 collapsing and expanding, but Answer Assist (for ver 3.x packages) works in the same manner.

To collapse the Shelf Answer Assist widget view, simply click the Collapse button as shown in the figure below.

Figure 71. Collapsing the Shelf Answer Assist 2.0 widget

As a result, the widget becomes collapsed and does not clutter your page up.

Figure 72. Viewing the Shelf Answer Assist 2.0 widget collapsed

For expanding the widget back, just click the Expand button in the upper right corner of the collapsed Answer Assist widget. The widget becomes expanded and you can see all tabs and data in it.

---

            

Upgrade 

Once you receive the URL for the new version of the package, you can initiate the installation process by opening the URL in your browser, entering username and password for the Salesforce organization in which the package should be installed, and clicking the Login button.

After the successful logon, you should expect to see the screen with the available update installation options. 

Figure 73. Viewing the update installation window

Select the appropriate Shelf Upgrade option and select the I acknowledge… checkbox to enable the Upgrade button. Click it to start the package upgrade process, and wait for a successful completion notification. Once it is displayed, the Shelf package has been successfully updated. 

If you update your Salesforce Shelf package to Shelf Assist 2.0, make sure, after the updating process is successfully completed, to go to the Shelf Configuration utility and refresh the environment. See Figure 8 and Figure 9 above. 

Note that updating to Shelf Assist 3.0 (Answer Assist widget) does not require it as no Shelf Configuration utility is available for this version.

If you update your Salesforce Shelf package between Major releases, from a 1.x version to the 2.x version or to the 3.x version, you need to do the following:

• remove all the installed Shelf Salesforce components of the 1.x version from your pages
• remove the assigned users from the configured permission set
• uninstall Shelf Salesforce package of the 1.x version
• install Shelf Salesforce package of the 2.x version/3.x version
• follow all the needed configuration steps.

             

Uninstalling Shelf App package

As a Salesforce administrator, you can remove the Shelf package, including all its components and all the data in the package. Also, any custom fields, links, or anything else that has been added to the Shelf app after installation, will be removed. 

Note that the content itself remains on your Shelf instance and is not deleted when the Shelf App is removed from Salesforce. However, any associations of the Shelf content with Salesforce are removed. 

Navigate to the Setup page and enter Installed Packages in the Quick Find box. In the Installed Packages window that appears, locate the Shelf App package you want to delete and click the Uninstall link button next to it.

Figure 74. Uninstalling Shelf App on Salesforce

In the next window, scroll down to its bottom, select the Yes, I want to uninstall checkbox and click the Uninstall button.

Figure 75. Confirming the Shelf App uninstall  

Once the Shelf App is uninstalled, Salesforce automatically creates an export file containing the package data, associated notes, and any attachments. When the uninstall is complete, Salesforce sends you an email with the link to the export file. The export file and the related notes and attachments are laid down below the list of installed packages. We recommend storing the file elsewhere because it’s available for only two days (48 hours) after you have uninstalled Shelf App. After this period expires, the file is deleted from the Salesforce server and you cannot be able to recover it.