Phased rollout

 

This version of the software is currently available only to early adopter SaaS customers as the first step in our phased rollout. Click here to view an earlier version.

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:

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:

    FieldDescription
    Name of the record definitionPTO
    usernameUser name of the employee
    Full nameFull name of the employee
    Available daysNumber of available PTOs
    Days takenNumber 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. 

    FieldValue
    usernameAllen
    Full nameAllen Albrook
    Available days5
    Days taken10
    DescriptionPTO 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)NameType
    InputInput usernameText
    Outputoutput available daysText
    Outputoutput taken daysText
    Outputoutput full nameText
  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 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:



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 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: 

  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 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: 

     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 keywordSource 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 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: 

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 .

Was this page helpful? Yes No Submitting... Thank you

Comments