Botium Connector for Bot Framework Direct Line 3 API
This is a Botium connector for testing your Microsoft Bot Framework chatbots.
Did you read the Botium in a Nutshell articles ? Be warned, without prior knowledge of Botium you won't be able to properly use this library!
How it works?
The Direct Line API 3.0, part of the Microsoft Bot Framework, enables Botium to talk to a chatbot deployed and running with the Microsoft Bot Framework.
The Direct Line version number does not correspond to the Microsoft Bot Framework version number. So this connector actually supports Microsoft Bot Framework v3 as well as v4.
It can be used as any other Botium connector with all Botium Stack components:
Features
- Button, Media, Card, Form extraction.
- Adaptive Card support.
Requirements
- Node.js and NPM
- a Microsoft Bot Framework chatbot, and user account with administrative rights
- a project directory on your workstation to hold test cases and Botium configuration
Install Botium and Directline3 Connector
When using Botium CLI:
> npm install -g botium-cli
> npm install -g botium-connector-directline3
> botium-cli init
> botium-cli run
When using Botium Bindings:
> npm install -g botium-bindings
> npm install -g botium-connector-directline3
> botium-bindings init mocha
> npm install && npm run mocha
When using Botium Box:
Already integrated into Botium Box, no setup required
Connecting Microsoft Bot Framework to Botium
You have to connect the Direct Line channel (with version 3.0) in Azure Portal and obtain the secret - see here for instructions.
Open the file botium.json in your working directory and add the secret:
{
"botium": {
"Capabilities": {
"PROJECTNAME": "<whatever>",
"CONTAINERMODE": "directline3",
"DIRECTLINE3_SECRET": "<directline secret>"
}
}
}
To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:
> botium-cli emulator
Botium setup is ready, you can begin to write your BotiumScript files.
Finetuning Directline3 Activity
For finetuning the Activity object sent to your bot, you can use the UPDATE_CUSTOM logic hook. This example will add some custom values to the channelData:
#me
do some channel specific thingy ...
UPDATE_CUSTOM SET_ACTIVITY_VALUE|channelData|{"channelData1": "botium", "channelData2": "something else"}
The parameters are:
- SET_ACTIVITY_VALUE
- The path to the activity field
- The value of the activity field
Another option for having full control over the activity is to use the DIRECTLINE3_ACTIVITY_TEMPLATE capability. It is a JSON structure used as a template when sending an activity to the bot.
...
"DIRECTLINE3_ACTIVITY_TEMPLATE": {
"channelData": {
"my-special-channel-data": "..."
}
}
...
Supported Capabilities
Set the capability CONTAINERMODE to directline3 to activate this connector.
DIRECTLINE3_SECRET *
The secret for accessing your chatbot from the Azure Portal.
Note: it is advised to not add this secret to a configuration file but hand it over by environment variable BOTIUM_DIRECTLINE3_SECRET
DIRECTLINE3_DOMAIN
If not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here
DIRECTLINE3_WEBSOCKET
true or false Wether to use Websocket connection or HTTP polling. Usually, using Websockets is prefered, but sometimes this is not possible (maybe with blocking proxies).
DIRECTLINE3_POLLINGINTERVAL
in milliseconds HTTP Polling interval
DIRECTLINE3_BUTTON_TYPE and DIRECTLINE3_BUTTON_VALUE_FIELD
Default type: event
Default field: name
Activity fields to use for simulating button clicks by the user. Depending on your implementation, you maybe have to change the activity type or the field to use - see here for some ideas.
Usually, the activity type is event, and the button value is submitted in the name field, but using those capabilities you can adapt it to your implementation.
Note: if you want to disable this, then set DIRECTLINE3_BUTTON_TYPE to "message" and DIRECTLINE3_BUTTON_VALUE_FIELD to "text", to make the button clicks appear as normal user text input
DIRECTLINE3_GENERATE_USERNAME
Default: false
Botium simulates conversations with username me. Depending on your implementation, running multiple conversations with the same username could make them fail (for example, session handling).
Setting this capability to true will generate a new username (uuid) for each conversation.
DIRECTLINE3_HANDLE_ACTIVITY_TYPES
Default: "message"
Activity types to handle (either JSON array or comma separated list). All other activity types will be ignored.
Example: set to "message,event" (or [ "message", "event" ]) to also handle Bot Framework event activities with Botium
DIRECTLINE3_ACTIVITY_VALUE_MAP
default: { 'event': 'name' }
When using activity types other than message, this capability maps the activity type to the activity attribute to use as message text for Botium.
By default, for event activities the name attribute is used as message text, for other activity types the activity type itself.
DIRECTLINE3_ACTIVITY_TEMPLATE
default: {}
JSON object holding the activity template used for sending activities to the bot. Can be used to hold for example channelData:
...
"DIRECTLINE3_ACTIVITY_TEMPLATE": {
"channelData": {
"kb": "demo"
}
},
...
DIRECTLINE3_ACTIVITY_VALIDATION
default: 'error'
Set to 'warning' if you want to suppress activity validation errors.
DIRECTLINE3_WELCOME_ACTIVITY
default: empty
Send some activity upfront to start a session. Can be used to simulate the webchat/join event.
...
"DIRECTLINE3_WELCOME_ACTIVITY": {
"type": "event",
"name": "webchat/join",
"value": {
"language": "de-DE"
},
"channelData": {
"kb": "demo"
}
},
...