README.md

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:

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

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.

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