Watson Assistant syntax validation for Voice Gateway and SOE integration

Photo by Franck V. on Unsplash

Watson Assistant supports building many kinds of automated assistants from including those with “just” dialog, those that integrate with backend systems, and those that use voice channels. Common patterns include using a Service Orchestration Engine (SOE) for managing external API calls or IBM Voice Gateway for voice bots.

Watson Assistant is easily extended for those use cases with its existing dialog response and context objects which are configurable with JSON. Watson Assistant natively validates that legal JSON is used in this configuration but you should also validate the contents within these fields against established patterns. That is where this post comes into play.

Attached is a syntax validator for Watson Assistant workspaces (skills) integrate with a Service Orchestration Engine (SOE) or a Voice Gateway. SOEs and Voice Gateway have syntax constructs that are not natively validated by Watson Assistant. This tool examines a Watson Assistant workspace and prints error and warning conditions based on common patterns and best practices. The tool includes command line options to customize the conditions that are validated. The tool is available at https://github.com/cognitive-catalyst/WA-Testing-Tool/tree/master/validate_workspace.

Common syntax patterns

For example, a chatbot with voice integration and an SOE layer will use the action section to specify a route. Routes will indicate what should happen next, perhaps a Text to Speech playback or an API call that needs to be made. One important validation is to make sure each route specified is a legal route.

"context": {
    "action": {
        "info": null,
        "route": "TTS",
        "method": "",
        "parameters": null
    }
}

IBM Voice Gateway uses action sequences to dictate a series of commands. A common pattern is to use a common action sequence on all dialog nodes that play text to a user — that sequence being a Speech To Text configuration (used to understand the user’s vocalization) and a play text command (used to play text to the user). One important validation is to detect dialog nodes that do not include a minimal set of commands.

"vgwActionSequence": [
 {
  "command": "vgwActSetSTTConfig",
  "parameters": {
   "config": {
    "customization_id": "Your model id here"
   }
  }
 },
 {
  "command": "vgwActPlayText",
  "parameters": {
   "text": [
    "Your text here"
   ]
  }
 }
]

Preparing to run the tool

1. Gather the information needed to connect to your workspace. You can run the tool against a local copy of the workspace or can use the remote copy. Perform one of the following sub-steps.

a. Export the Watson Assistant workspace you wish to validate to a file: https://developer.ibm.com/tutorials/learn-how-to-export-import-a-watson-assistant-workspace/

b. Gather the username/password, URL, and workspace ID to connect directly to Watson Assistant.

2. Decide whether you are validating against an SOE contract, an IBM Voice Gateway contract, or both.

3. Determine the configurations (legal routes, expected Voice Gateway command sequences, etc)

Running the tool

You are required to provide:

1. Arguments to find your workspace (either -f or -o set)

A local file is referenced with -f your_filename_here.

An online connection to the workspace is referenced with -o --username your_username_here --password your_password_here --url your_url_here --workspace_id your_workspace_id_here.

2. At least one validation group (either -sor -g)

You can optionally specify the legal “route” values with --soe_route.

You can optionally specify the expected voice gateway commands that should be present on any playback nodes with --voice_gateway_commands.

You may specify both validation groups in the same command

Example syntax:

python validateWS.py -f your_workspace_file.json -s — soe_route “TTS,OPT_OUT,UI,SOE,API,None”

Or

python validateWS.py -f your_workspace_file.json -g — voice_gateway_commands “vgwActSetSTTConfig,vgwActPlayText”

Example output:

Input workspace is called "example_workspace" and contains 208 dialog nodes
WARN: node_2_1536155880612 Does not contain command 'vgwActSetSTTConfig'
WARN: node_3_1536157780613 Does not contain command 'vgwActPlayText'
WARN: node_4_1536157980614 Has invalid route 'TSS'

The syntax validator is open source. Feel free to customize to suit your own needs! Thanks to Leo Mazzoli for reviewing early versions of the tool.

Download the tool at https://github.com/cognitive-catalyst/WA-Testing-Tool/tree/master/validate_workspace.