Botium Connector for Bot Framework Direct Line 3 API


![license]()

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:
* Botium CLI
* Botium Bindings
* Botium Box

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": "",
"CONTAINERMODE": "directline3",
"DIRECTLINE3_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:
1. SET_ACTIVITY_VALUE
2. The path to the activity field
3. 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.

$3

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_

$3

If not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here

$3

_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).

$3

_in milliseconds_
HTTP Polling interval

$3

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

$3

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

$3

_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

$3

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

$3

_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"
}
},
...

$3

_default: 'error'_

Set to 'warning' if you want to suppress activity validation errors.

$3

_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"
}
},
...