This documentation supports the 21.3 version of BMC Helix Virtual Agent, which is available only to BMC Helix customers (SaaS).To view an earlier version, select the version from the Product version menu.

Customizing the chatbot actions

BMC Helix Virtual Agent provides support by interacting with users through natural language, understanding the conversation context, and performing tasks on behalf of the user. As an application business analyst or an administrator, you can configure BMC Helix Virtual Agent to invoke custom actions that are performed by the chatbot on behalf of the user. These actions are invoked from the IBM Watson Assistant service. 

To use custom processes and actions in BMC Helix Virtual Agent

You can use custom processes and actions in BMC Helix Virtual Agent. The custom processes are created in the Process designer of BMC Helix Innovation Studio. For more information about creating custom processes, see Defining the application business logic through processes in the BMC Helix Innovation Suite online documentation.

After creating the processes and actions, you can invoke the custom processes and actions from a dialog in IBM Watson Assistant Skill. To view examples of the JSON code of dialog response with chat actions, see Example JSON of BMC Chatbot dialog responses.

Example JSON of BMC Helix Virtual Agent dialog responses

To enable BMC Helix Virtual Agent to interact with your users, you must build a dialog in the IBM Watson Assistant Skill. Based on the conversation, IBM Watson Assistant sends an action to your application that needs to be performed on the behalf of the user. In the Skills dialog, you can define these actions to call the processes or actions that you have created.

See the following JSON code samples:

Sample: Creating a service request

After an employee provides all the details to create a service request, for example, a time-off-request, BMC Helix Virtual Agent uses these details to create a service request. The following JSON illustrates the dialog response that contains a chat action to create a service request:

Sample JSON: Creating a service request
Sample JSON: Creating a service request
{
"output": {
"text": {
"values": [
""
],
"selection_policy": "sequential"
},
"action": {
"inputMap": {
"536870920": "trigger",
"536870921": "sb_apply_pto",
"536870922": "$loginName",
"536870923": {
"6491c1f4-5dc7-0887-b8b2-6b11284a49fd": "$startDate",
"ab9a845c-0e69-2929-8a25-66a5a319a539": "$vacationType",
"ef1145f2-2730-d43b-706e-d25b812ef041": "$endDate",
"f4036404-f6cb-9173-6bb1-007296a27463": "$userQuestion"
}
},
"outputMap": {
"status": "${actionResult.536870910}",
"requestId": "${actionResult.536870911}"
“description”: “${actionResult.<description field id>}”
},
"processDefinitionName": "com.bmc.dsm.chatbot:Create Service Request",
"waitForActionExecution": true
}
}
}


The following table explains the inputs provided in the action block for creating a service request:

Field ID

Input text

Description

536870920

trigger

Defines the action status.


536870921

sb_apply_pto

Specifies the name of the action.

Ensure that the name matches to the Service Request Name specified in the BMC Helix Business Workflows Catalog.

536870922

$loginName

Specifies the login name of the user.

536870923

"6491c1f4-5dc7-0887-b8b2-6b11284a49fd": "$startDate"

"ab9a845c-0e69-2929-8a25-66a5a319a539": "$vacationType"

"ef1145f2-2730-d43b-706e-d25b812ef041": "$endDate"

"f4036404-f6cb-9173-6bb1-007296a27463": "$userQuestion"

Specifies the vacation start date.

Specifies the vacation type. For example, paid vacation.

Specifies the vacation end date.


Output map

The following table explains the outputs provided:

Field ID

Output

Description

536870910

Status

Specifies the status of the service request.

536870911

Request Id

Specifies the ID of the service request.

<Description field ID>

Description

Specifies the description of the service request. Ensure that the Field Id exists and the content in the field ID placeholder is not blank.

In a service request, when the process in the output action map is executed, the process result is embedded in the user message and sent to the user. If you want to return a process result to Watson for validation or conditional child dialog execution, you must use "waitForActionExecution": true in the output action map.

Sample: Searching for a knowledge article

If there are any knowledge articles related to a request from a user, you can enable BMC Helix Virtual Agent to return a list of related knowledge articles. The following JSON illustrates the dialog response that contains a chat action to search for knowledge articles:

Sample JSON: Searching for a knowledge article
Sample JSON: Searching for a knowledge article
{
"output": {
 "text": {
  "values": [
  "I found the following knowledge articles relating to your issue.${actionResult.536870911} Is this helpful?"
      ]
    },
"action": {
"inputMap": {
 "536870920": "<?input.text?>”,     
  "536870921": "0”,                 
 "536870922": “3”                 
      },
"outputMap": {
 "status": "${actionResult.536870910}”,         
  "results": "${actionResult.536870911}”    
      },
    
"processDefinitionName": "com.bmc.dsm.chatbot:Search Knowledge"
    },
"result": "${actionResult.536870911}",
"status": "${actionResult.536870910}"
  }
}

The following table explains the inputs provided in the action block for retrieving the knowledge articles:

Field

Input text

Description

536870920

<?input.text?>

Specifies the text that has to be searched.

536870921

0

Specifies the beginning of the search index.

536870922

3

Specifies the maximum number of knowledge articles that should be returned.

results

${actionResult.536870911}

Returns a JSON string with the related knowledge article details.

Sample: Getting the status of the service request

After creating a service request based on the details provided by the user, BMC Helix Virtual Agent returns the status of the service request.

For example, for time-off request, BMC Helix Virtual Agent creates a new service request and returns the service request ID to the user.

The following JSON illustrates the dialog response that contains a chat action to get the status of your request:

Sample JSON: Getting the status of the service request
Sample JSON: Getting the status of the service request
{
"output": {
"text": {     
"values": [
 "Your requests ${actionResult.536870911}"
      ]
    },
"action": {
"inputMap": {
 "536870920": "trigger",
 "536870922": “$loginName",
  "536870923": "4”,        
 "536870924": [
    “@entities.values”       
  ]
 },    
"outputMap": {
 "status": "${actionResult.536870910}",     
 "seachResult": "${actionResult.536870911}"
      },     
"processDefinitionName": "com.bmc.dsm.chatbot:Get Request Status"
    }
  }
}

The following table explains the inputs provided in the action block for receiving the status of the service request:

Field

Input text

Description

536870920

trigger

Defines the action status.

536870922

$loginName

Specifies the login name of the user.

536870923

4

Specifies the maximum number of service requests to show for the user.

 Sample: Publishing an event in a chat dialog

If you are tracking an event to derive the chatbot usage metrics, you must publish the event details in the dialog in the IBM Watson Assistant Skill. The following JSON illustrates the dialog that contains the publish event action:

Sample JSON: Publishing an event in a chat dialog
Sample JSON: Publishing an event in a chat dialog
{  
  "output":{  
     "text":{  
        "values":[  
           "event created"
         ],
        "selection_policy":"sequential"
     },
     "action":{  
        "inputMap":{  
           "values":{  
              "BotId":"BotId",
              "BotName":"Admin",
              "Channel":"SMS",
              "UserName":"Hannah",
              "ServiceName":"Knowledge"
           },
           "eventDefinitionName":"com.bmc.dsm.chatbot:ServiceRequest"
        },
        "actionTypeName":"publishEvent",
        "waitForActionExecution":true
     }
  }
}

The input variables in the JSON change for each event. The following variables are available from chatbot:

Variable name

Description

chatbot_channel

To set the channel

chatbot_id

To set the chatbot id

chatbot_name

To set the chatbot name

Sample: Checking entitlements and questions with default answers

The chatbot checks whether an end user is entitled for a service. The chatbot also checks whether a service question has default answers by using the Entitlement Check and Fill Default Questions action.

The following JSON illustrates the dialog that contains the Entitlement Check and Fill Default Questions action:

Sample JSON: Checking entitlements and questions with default answers
Sample JSON: Checking entitlements and questions with default answers
{ "output": { "text": { "values": [], "selection_policy": "sequential" }, "action": { "inputMap": { "service Id": "ABBCD1EFP0GHIJK7L0MNO9PQRE3S4" }, "outputMap": { "status": "${actionResult.output.status}", "message": "${actionResult.output.message}" }, "actionTypeName": "com.bmc.dsm.chatbot:checkEntitlementAndFillDefaultValues", "waitForActionExecution": true } }, "context": { } }

The following table describes the parameters in the JSON:

Parameter

Description

service Id

ID of the service created in BMC Helix Digital Workplace Catalog

Status

  • Success
  • Error
  • Not Found

Message

  • If the status is Success, the message includes the entire object.
  • If the status is Error, the error message string is displayed.
  • If the status is Not Found, a message stating that the user does not have access to the service is displayed.


Sample Output map of Entitlement Check and Fill Default Questions

If the action is successful, it returns the following output map:

Sample output map for Entitlement Check and Fill Default Questions
Sample output map for Entitlement Check and Fill Default Questions
{
   "bmc_answerByQuestionId": {
       "CountryNameID1": "United States",
       "DevicesOwnedID2": [
           "Laptop",
           "Mobile"
        ]
   },
   "bmc_lookup_mappings": {
       "CountryNameID1": [
           {
               "label": "United States",
               "value": "1"
           },
           {
               "label": "India",
               "value": "2"
           }
        ]
   },
   "bmc_visibilityByQuestionId": {
       "CountyNameID4": true,
       "StateNameID5": false
   },
   "bmc_requestId": "requestId",
   "bmc_questionnaireId": "questionnairedId"
}

The following table describes the output map:

Parameter

Description

CountryNameID1


ID of the question

United States

Default answer of the CountryNameID1 question.

Sample: Populating default answers to service request questions

If a service has dependent questions or has a default answer to a question, the answers populated in the output map of the Entitlement Check and Fill Default Questions action are used as input for the submitAnswer action.

The following JSON illustrates the dialog that contains the submitAnswer action:

Sample JSON: Populating default answers to service request questions
Sample JSON: Populating default answers to service request questions
{
  "output": {
    "action": {
      "inputMap": {
        "answer": "$country",
        "requestId": "$bmc_requestId",
        "serviceId": "ABBCDE1FGH0IJKLM7N0OPH9QRST3U4",
        "questionId": "6ab57c6-53de-fghi-9jk9-351l8m771n1o",
        "questionnaireId": "$bmc_questionnaireId"
      },
      "outputMap": {
        "status": "${actionResult.output.status}",
        "message": "${actionResult.output.message}"
      },
      "actionTypeName": "com.bmc.dsm.chatbot:submitAnswer",
      "waitForActionExecution": true
    },
    "generic": [
      {
        "values": [],
        "response_type": "text",
        "selection_policy": "sequential"
      }
    ]
  }
}

The following table describes the parameters in the JSON:

Parameter

Description

Status

  • Success
  • Error

Message

  • If the status is Success, the message includes the entire object.
  • If the status is Error, the error message string is displayed.

Sample output map of the SubmitAnswer action

If the action is successful, it returns the following output map:

Sample output map for Submit Answer
Sample output map for Submit Answer
{
    "bmc_answerByQuestionId": {
       "CountryNameID1": "United States",
       "DevicesOwnedID2": [
           "Laptop",
           "Mobile"
        ]
   },
   "bmc_lookup_mappings": {
       "CountryNameID1": [
           {
               "label": "United States",
               "value": "1"
           },
           {
               "label": "India",
               "value": "2"
           }
        ]
   },
   "bmc_visibilityByQuestionId": {
       "CountyNameID4": true,
       "StateNameID5": false
   }
}

Related topics

Importing-chat-enabled-services-from-BMC-Helix-Digital-Workplace-Advanced

Integrating


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*