Example of invoking a custom process in BMC Helix Chatbot

As an application business analyst or an administrator, you can configure BMC Helix Chatbot to invoke custom processes created in BMC Helix Innovation Studio. These processes are invoked from the IBM Watson Assistant service.

You can invoke the custom processes in the following ways: 

• By using process output variables in IBM Watson Assistant.

• By connecting to the REST API in a codeless way. 

Example of invoking a custom process by using process output variables in IBM Watson Assistant

Example of invoking a custom process by using a process output variable workflow

This example describes the end-to-end tasks to be performed in BMC Helix Innovation Studio and IBM Watson Assistant service.

Tasks in BMC Helix Innovation Studio and IBM Watson Assistant service:

The following image gives an overview of the tasks in BMC Helix Innovation Studioand their results:

After completing the tasks in BMC Helix Innovation Studio, the following image gives an overview of the tasks to be performed in IBM Watson Assistant service and their results:

To create a sample custom process and invoke it in the chatbot, perform the following tasks:

Task 1: To create a record definition 

1. Log in to BMC Helix Innovation Studio and open the PTO application.

2. On the Records tab, click New and create a Record definition with the following fields:

   Field	Description
   Name of the record definition	PTO
   username	User name of the employee
   Full name	Full name of the employee
   Available days	Number of available PTOs
   Days taken	Number of consumed PTOs

3. Save the record definition. 

Task 2: To create sample data for a user

1. On the Records tab, select the PTO record definition.
2. Select Edit Data > New. 

3. Fill out the fields with the following values. 
   These values are used in the example further. 

   Field	Value
   username	Allen
   Full name	Allen Albrook
   Available days	5
   Days taken	10
   Description	PTO for Allen Albrook

4. Click Save. 

The following image shows the record instance with sample data for a user:

Task 3: To create the custom process

1. On the Processes tab, click New. 
2. Select General  and in the Name field, enter Get PTO Status. 

3. In the VARIABLES section, create the following input and output variables:

   Variable (Input/ Output)	Name	Type
   Input	Input username	Text
   Output	output available days	Text
   Output	output taken days	Text
   Output	output full name	Text

4. Save the process. 
5. Open the process and open the variables. 

6. Note the variable ID of each input and output variable that you created earlier. 

   Variable IDs are generated by the system. You require the variable IDs for further configuration in IBM Watson Assistant.

   
   

7. From the PALETTE, drag the Get Record by Query activity to the canvas. 
8. On the Settings  tab, in the INPUT MAP section, in Record Definition Name, select PTO. 
9. In Query Expression, click Edit and specify the following query: 
   username = Input username
   This query looks for the first matching record instance where the PTO field username matches the value of the Process Input variable Input username.
10. In the OUTPUT MAP section, in Name, select output available days. 
11. In Source, click Edit and specify the following query in the expression: 
    Available days
    The number of available days that we get from the Source are stored in the output available days variable.

12. Similarly, create output maps for the output taken days and output full name variables as shown in the following image: 

     View the output maps

    

13. Click Save. 
    
    

The following image shows the input variable with the variable ID:

After creating all the variables, you should see the list as shown in the following image: 

The following image shows the query expression for the INPUT MAP:

Task 4: To test the custom process

1. On the Processes tab, select the Get PTO Status process and click Manage Processes. 
2. Click Run. 
3. On Run Get PTO Status page, in Input username, enter Allen. 
   Allen is the sample data we created earlier. 
4. Open the entry that appeared and verify that the process output values are correct.

The following image shows the process outputs that should appear: 

You have now completed the tasks in BMC Helix Innovation Studio.  

Task 5: To create intents

An employee requests the chatbot for PTOs. To make sure that the chatbot understands this query, create an intent in IBM Watson Assistant service. 

1. Log in to IBM Watson Assistant service and navigate to the Skills in which you want to invoke the custom process. 
2. Create an intent FetchPTOCounterForSpecificUser. 
   You create the intent to make sure that the chatbot understands when the user asks a query about PTOs.
3. Add several examples to match this intent. 
   
   

The following image shows the intent and examples:

After creating intents, you specify the chatbot dialog flow by creating the dialog nodes as shown in the following image:

Task 6: To create a dialog to ask the username and the first child dialog node to store the username 

After the chatbot understands the intent, it asks the employee for the username. This is the first dialog. After getting the username, IBM Watson Assistant service must store the username in a variable. This information is then used to call the custom process. 

1. Log in to IBM Watson Assistant service and navigate to the Skills in which you want to invoke the custom process. 
2. In Dialog, click Add node and specify the name Get My PTOs. 
3. In the If assistant recognizes section, select FetchPTOCounterForSpecificUser.
   This is the intent you created earlier. 
4. In the Assistant responds section, select Text.
5. Click the menu icon and select Open context editor as shown in the following image: 
   
   
6. In the Then set context section, specify the following variable and value: 
   • Variable— varUsername. 
   • Value—"<? context.remove('varUsername') ?>"
     This variable and value ensures that any existing value in this variable is removed. 
7. In the Assistant responds section, select Text and type I can help you with that! What is your username?
8. In Then assistant should section, select Wait for reply. 
   You have created the first dialog to ask the employee for the user name. 
9. To create the second dialog node, go to the Get My PTOs dialog you created earlier and click Add child node. 
10. In the Assistant responds section, select true. 
    Because we do not need any condition in this dialog node, we set the value to true. 
11. In the Assistant responds section, select Text > Open context editor. 
12. In the Then set context section, specify the following variable and value: 
    • Variable— varUsername. 
    • Value—"<?input.text?>"
      This variable and value ensures that the value entered by the end user is stored. 
    It is not necessary to set anything in the Assistant responds section because this will be handled in the next task.

The following image shows the dialog to ask the username: 

The following image shows the first child dialog node to save the username in a variable:

Task 7: To create the second child dialog node to invoke the custom process

Create this dialog node to invoke the custom process when the value in the varUsername variable is not null. 

1. In IBM Watson AssistantSkills, navigate to the child dialog node you created in the earlier task.
2. Click Add child node. 
3. In the If assistant recognizes section, type $varUsername!=null. 

4. In the Assistant responds section, to invoke the custom process, select Open JSON editor as shown in the following image: 
   

    Sample of original JSON structure

   {
  "output": {
    "text": {
      "values": [
        ""
      ],
      "selection_policy": "sequential"
    },
    "action": {
      "inputMap": {
        "<ProcessInputVariableId>": "$<WatsonVariableName>",
        "<ProcessInputVariableId>": "$<WatsonVariableName>",
        "<ProcessInputVariableId>": "$<WatsonVariableName>"
      },
      "outputMap": {
        "<WatsonVariableName>": "${actionResult.<ProcessOutputVariableId>}",
        "<WatsonVariableName>": "${actionResult.<ProcessOutputVariableId>}",
        "<WatsonVariableName>": "${actionResult.<ProcessOutputVariableId>}"
      },
      "processDefinitionName": "<ProcessFullyQualifiedName>",
      "waitForActionExecution": true
    }
  },
  "context": {}
}

5. In the original JSON structure, replace the following variable values: 

   Best practice

   We recommend to prepare the JSON in a text editor such a Notepad ++ and paste it in the dialog instead of editing the values directly in the dialog.

   JSON keyword	Source product	IBM Watson variable name or process variable ID
   Input map
   ProcessInputVariableId	BMC Helix Innovation Studio	Process Input Variable ID: 536870914 This ID is taken from the following screen when creating the custom process:
   WatsonVariableName	IBM Watson	"536870914": "$varUsername"
   Output map (Information passed from the custom process to IBM Watson Assistant)
   ProcessInputVariableId	BMC Helix Innovation Studio	Process Output Variable ID: 536870912 This ID is taken from the following screen when creating the custom process:
   WatsonVariableName	IBM Watson	"varAvailableDays": "${actionResult.536870912}"
   ProcessInputVariableId	BMC Helix Innovation Studio	Process Output Variable ID: 536870913 This ID is taken from the following screen when creating the custom process:
   WatsonVariableName	IBM Watson	"varTakenDays": "${actionResult.536870913}"
   ProcessInputVariableId	BMC Helix Innovation Studio	Process Output Variable ID: 536870915 This ID is taken from the following screen when creating the custom process:
   WatsonVariableName	IBM Watson	"varFullName": "${actionResult.536870915}"
   processDefinitionName	BMC Helix Innovation Studio	Fully qualified name of the custom process definition: "com.example.lunchbot:Get PTO Status"

   After replacing the variable values, the JSON payload for this example is as follows: 

   {
     "output": {
       "text": {
         "values": [
           ""
         ],
         "selection_policy": "sequential"
       },
       "action": {
         "inputMap": {
           "536870914": "$varUsername"
         },
         "outputMap": {
           "varFullName": "${actionResult.536870915}",
           "varTakenDays": "${actionResult.536870913}",
           "varAvailableDays": "${actionResult.536870912}"
         },
         "processDefinitionName": "com.example.lunchbot:Get PTO Status",
         "waitForActionExecution": true
       }
     },
     "context": {}
   }

6. In the Then assistant should section, select Wait for reply. 
   
   

    View the image that shows the dialog node that invokes the custom process

   
   

Task 8: To create the third child dialog node to display the values returned by the custom process

Create this dialog node to display the total available PTOs, total taken PTOs, and full name.

1. In IBM Watson Assistant Skill, navigate to the child dialog node you created to invoke the custom process. 
2. Click Add child node. 
3. In the If assistant recognizes section, type true. 
4. In the Assistant responds section, select Text and type Hi $varFullName! You currently have $varAvailableDays PTO available, and for your information you already took $varTakenDays days.
   This message uses the values returned by the custom process and displays the values in a meaningful way to the end users. 

The following image shows the third child dialog node to display the values returned by the custom process: 

Task 9: To modify the parent dialog node

Specify how to call this dialog node in the parent dialog node that you created earlier. 

1. In IBM Watson AssistantSkills, navigate to the parent dialog node. 
2. In the Then assistant should section, select Skip user input. 
   The default value Wait for reply implies that the Skills should wait till the end user types a message. However, we already have the username and the Skills should skip the user input. 
   The text and evaluate child nodes is populated automatically. 

The following image shows the modified parent dialog node: 

You have now completed all the tasks in IBM Watson Assistant service.

Result

After completing the configuration tasks in BMC Helix Innovation Studio and IBM Watson Assistant, you can log in to BMC Helix Innovation Studio and launch the chatbot. Provide the username and then request the chatbot to show the available PTOs.

You should see the following chatbot conversation:

Example of invoking a custom process by connecting to the REST API in a codeless way

The following video (8:43) shows how you can integrate with JIRA REST API service to extend BMC Helix Chatbot:

  https://youtu.be/n2X0YUTJ_68

To learn more about connecting to REST API in a codeless way, see Integrating with REST services in a codeless way .