Phased rollout This version is currently available to SaaS customers only. It will be available to on-premises customers soon.

Example of invoking a custom process in BMC Helix Virtual Agent

As an application business analyst or an administrator, you can configure BMC Helix Virtual Agent 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: 

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


Scenario

A company has implemented chatbot with its PTO management application. As an application business analyst, you want to create and invoke a custom process in the chatbot so that when an employee requests for a PTO, the chatbot can respond with the available and consumed PTOs of that employee.   


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.

Important

This process is specific to this example and might differ depending on your scenario and environment.

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:

Custom_process_Workflow for IS.png

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:

custom_process_workflow_Watson.png

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:

custom_process_sample_data.png


Task 3: To create the custom process

  1. On the Processes tab, click New. 
  2. Select General General properties icon.JPG 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 Settings icon.PNG 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

    custom_process_output_map.png

  13. Click Save. 

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

custom_process_variables.png

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

custom_process_variables_list.png

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

custom_process_input_map.png


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: 

custom_process_outputs.png

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 Skill 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. 

Important

IBM Watson Assistant might take a few minutes to retrain the Skill after creating the new intent.

The following image shows the intent and examples:

custom_process_intents.png



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

custom_process_dialog tree.png


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 Skill 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: 
    Watson_open context editor.png
  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: 

custom_process_dialog1.png

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

custom_process_child dialog1.png


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 AssistantSkill, 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: 
    Watson_open JSON editor.png

    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:

    custom_process_variable ID.png

    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:

    custom_process_output_avdays.png

    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:

    custom_process_output_tkdays.png

    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:

    custom_process_output_fullname.png

    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

    custom_process_invoke_dialog.png


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: 

custom_process_display_values.png


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 AssistantSkill, 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 Skill should wait till the end user types a message. However, we already have the username and the Skill should skip the user input. 
    The text and evaluate child nodes is populated automatically. 

The following image shows the modified parent dialog node: 

custom_process_modify_parent.png

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:

custom_process_result.png


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:

icon_play.png  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.