Configuring display templates for cognitive search output

As an administrator or application business analyst, you can configure the out-of-the-box display templates to define the layout and specific fields that you want to display when a document is selected from the search results and viewed. You can use the out-of-the-box templates as is, or customize them to suit your needs. You must apply the display templates for each data set you configure for cognitive search. 

The cognitive search configuration can include external and internal data sets. A data set contains collections of knowledge articles, such as a How-To collection, Problem-Solution collection, and so on. BMC Helix Chatbot provides templates for displaying the knowledge articles on the following chatbot channels:

• Web channel: This channel includes the regular BMC Helix Chatbot UI.
• Non-web channel: This channel includes the other chatbot channels, such as Slack, Skype for Business on-premises, and Twilio (SMS).

The difference between web and non-web channel templates is that the web channel template does not contain full HTML tags as it displays an article inside the same chatbot search window while the non-web channel template uses full-fledged HTML tags, which displays an article in a new browser window. 

When an end user enters a search term in a BMC Helix Chatbot channel, the chatbot displays snippets of knowledge articles relevant to the search terms. When the end user clicks a snippet, the chatbot displays the knowledge article in a specific format. To configure the display of an article, BMC Helix Chatbot provides out-of-the-box templates in the HTML format.

Out-of-the-box templates

The out-of-the-box templates are available as a downloadable .zip file attached to this page and not in the BMC Helix Chatbot UI. 

By default, BMC Helix Platform provides the following templates:

Before you begin

• Download the out-of-the-box templates and extract the file. Note the download location because later when you configure cognitive search, you will upload the templates from the same location.

To configure display templates for cognitive search output

The following steps explain, as a sample, how to configure the out-of-the-box template file internal_web.html. You must apply this template to display knowledge articles of an internal data set on the web channel.

1. Log in to BMC Helix Innovation Studio.
2. On the Workspace tab, select the application for which you want to configure the display templates.
3. On the Records tab, click the record definition for which you want to apply the web channel template.
   The record definition of the internal data set is displayed.
   The following image shows an example of the Test Sample Articles record:
   
   The Field Name column contains fields for a knowledge article, such as Description, Article Number, and so on. Each Field Name has a corresponding, unique Field ID; for example, Description has a Field ID value of 8.
4. From the location where you downloaded the out-of-the-box templates, open the internal_web.html file in an editor such as Notepad++, as shown in the following image:
   
   
   As a sample, only one code snippet for the Description field of the knowledge article is highlighted in red and explained in the following table. Similarly, you can configure the code for the other fields and delete the code for fields that you do not want to display in the article. 

5. Edit the parameters as shown in the following table:

   Code parameter	Action
   <#if metadata_Field ID??>	Set the Field ID component to the Field ID of the record definition field that you want to display. Example: To display the Description of an article, set the Field ID component to 8: <#if metadata_8??>
   <h6 class="mb-0">Field Name</h6>	Set the Field Name to the actual text that you want to display as the heading of a section. Example: To display a section heading as Description, set the code to: <h6 class="mb-0">Description</h6>
   <div class="mt-4">${metadata_Field ID}</div>	Set the Field ID component to the Field ID of the record definition field whose actual contents you want to display under the heading. Example: To display the actual contents of the Description field, set the Field ID component to 8: <div class="mt-4">${metadata_8}</div>

6. If a knowledge article contains attachments that you want to display as downloadable links, do the following:
   • For a web channel, the template displays a knowledge article's attachments by default. You do not need to insert code in the template to enable the display of attachments. 

   • For a non-web channel, insert the following code in the template to enable the display and download of a knowledge article's attachments:

     <#if sys_attachments??>
     <div class="mt-4">
        <div class="font-weight-bold">Attachments</div>
        <p class="mt-4 cb-article-topic-content">${sys_attachments}</p>
     </div>
     </#if>

     Ideally, place this code snippet as the last entry in the template so that the links to download the attachments are displayed at the bottom of an article.

7. Select File > Save, and close the HTML file.

The edited HTML file is ready to be uploaded as the display template for the web channel of the internal data set.

Where to go from here

 Configuring cognitive insights for BMC Helix Chatbot