botium-connector-lex

v0.1.6

Published

3 months ago

Botium Connector for Amazon Lex

Downloads

0High
0Medium
0Low

ftreml

Botium Connector for Amazon Lex

This is a Botium connector for testing your Amazon Lex chatbot.

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

Botium connects to the Amazon Lex API.

It can be used as any other Botium connector with all Botium Stack components:

This connector processes info about NLP. So Intent/Entity asserters can be used. (Does not returns confidences, and alternative intents)

Requirements

Node.js and NPM
a published Lex bot, and user account with administrative rights
a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Amazon Lex Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-lex
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-lex
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Amazon Lex to Botium

There are two possibilities to connect to Amazon Lex:

Connect with Amazon Access Keys

You have to create an IAM user to enable Botium to access the Amazon Lex API.

Create an IAM user (see here for help)
- Important: choose Programmatic access as access type
- Note access key and secret, you need it later
Choose Attach existing policies to user directly to give permissions AmazonLexFullAccess
- Feel free to use finer grained policies if you know what you are doing, or read Authentication and Access Control for Amazon Lex

Connect with Assuming Amazon IAM Role

Create an IAM Role (see here)
- Choose Attach existing policies to user directly to give permissions AmazonLexFullAccess
  - Feel free to use finer grained policies if you know what you are doing, or read Authentication and Access Control for Amazon Lex
- Add a trust policy (see here)
  - The external Id has to to be provided as Capability
- The Role ARN has to to be provided as Capability

Create a botium.json with

Amazon region where you have created your bot. See Amazon Lex Console
access key and secret of IAM user,
name of the bot
alias of the bot (see publishing)

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "lex",
      "LEX_REGION": "xxx",
      "LEX_AUTH_MODE": "xxx",
      "LEX_ROLE_ARN": "xxx",
      "LEX_ROLE_EXTERNAL_ID": "xxx",
      "LEX_ACCESS_KEY_ID": "xxx",
      "LEX_SECRET_ACCESS_KEY": "xxx",
      "LEX_PROJECT_NAME": "xxx",
      "LEX_PROJECT_ALIAS": "xxx"
    }
  }
}

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.

How to start sample

There is a small demo in samples/BookTrip dir with Botium Bindings. This tests the BookTrip template of Amazon Lex. To start it you have to :

Create and publish a bot from the template
- Go to console
- Choose region (top right) and note it, you need it later
- Click Create
- Choose BookTrip
- Choose a name and note it, you need it later
- Accept COPPA
- Click Create to create the Lex project
- Now click Publish and select an alias
Adapt botium.json in the sample directory
Run the sample

> cd ./samples/BookTrip
> npm install && npm test

Setting Session and Request Attributes

Session attributes can be initialized with the LEX_SESSION_ATTRIBUTES-capability (see below). They will be updated on each Lex response.

They can be updated within a conversation as well:

#me
I would like to order some flowers
UPDATE_CUSTOM SET_LEX_SESSION_ATTRIBUTE|attr1|attr1-value

Request attributes to be used on each request can be set with the LEX_REQUEST_ATTRIBUTES-capability (see below)

They can be given within a conversation as well:

#me
I would like to order some flowers
UPDATE_CUSTOM SET_LEX_REQUEST_ATTRIBUTE|attr2|attr2-value

Using the botium-connector-lex-cli

This connector provides a CLI interface for importing convos and utterances from your Amazon Lex bot and convert it to BotiumScript.

Bot intents and user examples are mapped to utterances in BotiumScript
Slots in user examples are either filled with enumeration values (for enumeration slot types) or with samples values from the official documentation
Convos are using the utterances as input and attach an INTENT asserter
If using the --buildentities switch, the utterances are separated by slot names and an additional ENTITIES asserter is attached

You can either run the CLI with botium-cli (recommended - it is integrated there), or directly from this connector (see samples/BookTrip directory for some examples):

> npx botium-connector-lex-cli import --buildconvos --buildentities --output spec/convo

Please note that you will have to install the npm package botium-core manually before using this CLI

For getting help on the available CLI options and switches, run:

> npx botium-connector-lex-cli import --help

Supported Capabilities

Set the capability CONTAINERMODE to lex to activate this connector.