{"id":15524360,"url":"https://github.com/codeforequity-at/botium-connector-lex","last_synced_at":"2025-04-19T13:49:43.617Z","repository":{"id":56415246,"uuid":"169565765","full_name":"codeforequity-at/botium-connector-lex","owner":"codeforequity-at","description":"Botium Connector for Amazon Lex","archived":false,"fork":false,"pushed_at":"2024-10-04T08:46:28.000Z","size":204,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-11T06:17:32.389Z","etag":null,"topics":["alexa","amazon","automation-test","botium","chatbot","lex","test"],"latest_commit_sha":null,"homepage":"https://www.botium.ai","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeforequity-at.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-07T12:07:19.000Z","updated_at":"2024-10-04T08:46:11.000Z","dependencies_parsed_at":"2024-06-21T14:24:04.170Z","dependency_job_id":"bccbe3e0-4b08-45b3-b592-59d3a7311d19","html_url":"https://github.com/codeforequity-at/botium-connector-lex","commit_stats":{"total_commits":69,"total_committers":7,"mean_commits":9.857142857142858,"dds":"0.42028985507246375","last_synced_commit":"4f10231c4b53c24922fac7c004781133b6503efb"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-lex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-lex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-lex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-lex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-lex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249707365,"owners_count":21313826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","amazon","automation-test","botium","chatbot","lex","test"],"created_at":"2024-10-02T10:51:04.041Z","updated_at":"2025-04-19T13:49:43.583Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for Amazon Lex\n\n[![NPM](https://nodei.co/npm/botium-connector-lex.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-lex/)\n\n[![Codeship Status for codeforequity-at/botium-connector-lex](https://app.codeship.com/projects/c947b780-0daa-0137-4acf-3a9e8715cbf8/status?branch=master)](https://app.codeship.com/projects/326745)\n[![npm version](https://badge.fury.io/js/botium-connector-lex.svg)](https://badge.fury.io/js/botium-connector-lex)\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)]()\n\nThis is a [Botium](https://github.com/codeforequity-at/botium-core) connector for testing your Amazon Lex chatbot.\n\n__Did you read the [Botium in a Nutshell](https://medium.com/@floriantreml/botium-in-a-nutshell-part-1-overview-f8d0ceaf8fb4) articles? Be warned, without prior knowledge of Botium you won't be able to properly use this library!__\n\n## How it works\nBotium connects to the [Amazon Lex API](https://docs.aws.amazon.com/de_de/lex/latest/dg/API_Reference.html).\n\nIt can be used as any other Botium connector with all Botium Stack components:\n* [Botium CLI](https://github.com/codeforequity-at/botium-cli/)\n* [Botium Bindings](https://github.com/codeforequity-at/botium-bindings/)\n* [Botium Box](https://www.botium.at)\n\nThis connector processes info about NLP. So Intent/Entity asserters can be used. (Does not returns confidences, and alternative intents)\n\n## Requirements\n* **Node.js and NPM**\n* a **published Lex bot**, and user account with administrative rights\n* a **project directory** on your workstation to hold test cases and Botium configuration\n\n## Install Botium and Amazon Lex Connector\n\nWhen using __Botium CLI__:\n\n```\n\u003e npm install -g botium-cli\n\u003e npm install -g botium-connector-lex\n\u003e botium-cli init\n\u003e botium-cli run\n```\n\nWhen using __Botium Bindings__:\n\n```\n\u003e npm install -g botium-bindings\n\u003e npm install -g botium-connector-lex\n\u003e botium-bindings init mocha\n\u003e npm install \u0026\u0026 npm run mocha\n```\n\nWhen using __Botium Box__:\n\n_Already integrated into Botium Box, no setup required_\n\n## Connecting Amazon Lex to Botium\n\nThere are two possibilities to connect to Amazon Lex:\n\n### Connect with Amazon Access Keys\nYou have to create an **IAM user** to enable Botium to access the Amazon Lex API.\n\n* [Create an IAM user](https://console.aws.amazon.com/iam/) (see [here](https://docs.aws.amazon.com/de_de/IAM/latest/UserGuide/id_users_create.html) for help)\n  * Important: choose _Programmatic access_ as access type\n  * Note access key and secret, you need it later\n* Choose _Attach existing policies to user directly_ to give permissions _AmazonLexFullAccess_\n  * Feel free to use finer grained policies if you know what you are doing, \n  or read [Authentication and Access Control for Amazon Lex](https://docs.aws.amazon.com/lex/latest/dg/auth-and-access-control.html)\n\n### Connect with Assuming Amazon IAM Role\n\n* [Create an IAM Role](https://console.aws.amazon.com/iam/) (see [here](https://docs.aws.amazon.com/de_de/IAM/latest/UserGuide/id_roles_create_for-service.html))\n  * Choose _Attach existing policies to user directly_ to give permissions _AmazonLexFullAccess_\n    * Feel free to use finer grained policies if you know what you are doing, \n    or read [Authentication and Access Control for Amazon Lex](https://docs.aws.amazon.com/lex/latest/dg/auth-and-access-control.html)\n  * Add a trust policy (see [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html))\n    * The external Id has to to be provided as Capability\n  * The Role ARN has to to be provided as Capability\n\nCreate a botium.json with \n* Amazon region where you have created your bot. See [Amazon Lex Console](https://console.aws.amazon.com/lex)\n* access key and secret of IAM user,\n* name of the bot\n* alias of the bot (see publishing)\n\n```\n{\n  \"botium\": {\n    \"Capabilities\": {\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\n      \"CONTAINERMODE\": \"lex\",\n      \"LEX_REGION\": \"xxx\",\n      \"LEX_AUTH_MODE\": \"xxx\",\n      \"LEX_ROLE_ARN\": \"xxx\",\n      \"LEX_ROLE_EXTERNAL_ID\": \"xxx\",\n      \"LEX_ACCESS_KEY_ID\": \"xxx\",\n      \"LEX_SECRET_ACCESS_KEY\": \"xxx\",\n      \"LEX_PROJECT_NAME\": \"xxx\",\n      \"LEX_PROJECT_ALIAS\": \"xxx\"\n    }\n  }\n}\n```\n\nTo check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:\n\n```\n\u003e botium-cli emulator\n```\n\nBotium setup is ready, you can begin to write your [BotiumScript](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html) files.\n\n## How to start sample\n\nThere is a small demo in [samples/BookTrip dir](./samples/BookTrip) with Botium Bindings. This tests the BookTrip template of Amazon Lex. To start it you have to :\n\n* Create and publish a bot from the template\n  * Go to [console](https://console.aws.amazon.com/lex/home)\n  * Choose **region** (top right) and note it, you need it later\n  * Click _Create_\n  * Choose _BookTrip_\n  * Choose a **name** and note it, you need it later\n  * Accept COPPA\n  * Click _Create_ to create the Lex project\n  * Now click _Publish_ and select an **alias**\n* Adapt botium.json in the sample directory\n* Run the sample\n\n```\n\u003e cd ./samples/BookTrip\n\u003e npm install \u0026\u0026 npm test\n```\n\n## Setting Session and Request Attributes\n\n**Session attributes** can be initialized with the _LEX_SESSION_ATTRIBUTES_-capability (see below). They will be updated on each Lex response.\n\nThey can be updated within a conversation as well:\n\n    #me\n    I would like to order some flowers\n    UPDATE_CUSTOM SET_LEX_SESSION_ATTRIBUTE|attr1|attr1-value\n\n**Request attributes** to be used on each request can be set with the _LEX_REQUEST_ATTRIBUTES_-capability (see below)\n\nThey can be given within a conversation as well:\n\n    #me\n    I would like to order some flowers\n    UPDATE_CUSTOM SET_LEX_REQUEST_ATTRIBUTE|attr2|attr2-value\n\n## Using the botium-connector-lex-cli\n\nThis connector provides a CLI interface for importing convos and utterances from your Amazon Lex bot and convert it to BotiumScript.\n\n* Bot intents and user examples are mapped to utterances in BotiumScript\n* Slots in user examples are either filled with enumeration values (for enumeration slot types) or with samples values from the [official documentation](https://developer.amazon.com/de/docs/custom-skills/slot-type-reference.html)\n* Convos are using the utterances as input and attach an INTENT asserter\n* If using the _--buildentities_ switch, the utterances are separated by slot names and an additional ENTITIES asserter is attached\n\nYou can either run the CLI with *[botium-cli](https://github.com/codeforequity-at/botium-cli) (recommended - it is integrated there)*, or directly from this connector (see samples/BookTrip directory for some examples):\n\n    \u003e npx botium-connector-lex-cli import --buildconvos --buildentities --output spec/convo\n\n_Please note that you will have to install the npm package botium-core manually before using this CLI_\n\nFor getting help on the available CLI options and switches, run:\n\n    \u003e npx botium-connector-lex-cli import --help\n\n## Supported Capabilities\n\nSet the capability __CONTAINERMODE__ to __lex__ to activate this connector.\n\n### LEX_VERSION\n_Default: V1_\n\nV1 or V2\n\n### LEX_AUTH_MODE\nSee Connecting Amazon Lex to Botium\n\n### LEX_ROLE_ARN\nSee Connecting Amazon Lex to Botium\n\n### LEX_ROLE_EXTERNAL_ID\nSee Connecting Amazon Lex to Botium\n\n### LEX_ACCESS_KEY_ID\nSee Connecting Amazon Lex to Botium\n\n### LEX_SECRET_ACCESS_KEY\nSee Connecting Amazon Lex to Botium\n\n### LEX_REGION\nAmazon region code where you have created your bot. [Amazon Lex V1 Console](https://console.aws.amazon.com/lex)/[Amazon Lex V2 Console](https://console.aws.amazon.com/lexv2).\n\n_Hint: a list of region codes is available [here](https://docs.aws.amazon.com/de_de/general/latest/gr/rande.html)_\n\n### LEX_PROJECT_NAME\nThe name (V1) or ID (V2) of the bot. See [Amazon Lex V1 Console](https://console.aws.amazon.com/lex)/[Amazon Lex V2 Console](https://console.aws.amazon.com/lexv2).\n\n_For Lex V2, use the Project **ID** instead of the name_\n\n### LEX_PROJECT_ALIAS\nThe alias name (V1) or ID (V2) of the bot. (see Publishing section in the Amazon Lex Console)\n\n_For Lex V2, use the alias **ID** instead of the name_\n\n### LEX_LOCALE (V2 only)\n_Default: en\\_US_\n\nPublishing alias locale. (see Publishing section in the Amazon Lex Console)\n\n### LEX_SESSION_ATTRIBUTES\n_Optional_.\n\nInitial session attributes. It must be object, or object as string. Lex supports just string attributes. \n(otherwise retrurns error like \"error sending to bot Error: Lex answered with error { InvalidParameterType: Expected params.sessionAttributes['somenumber'] to be a string\")\n\n### LEX_REQUEST_ATTRIBUTES\n_Optional_.\n\nRequest attributes.\n\n### LEX_ACCEPT\n_Default: text/plain; charset=utf-8_\n\nThe response content type. If you prefer to receive audio set it to one of the supported audio formats (see [Lex docs](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/LexRuntime.html#postContent-property))\n\n### LEX_CONTENTTYPE_TEXT\n_Default: text/plain; charset=utf-8_\n\nContent type used when sending text.\n\n### LEX_CONTENTTYPE_AUDIO\n_Default: audio/l16; rate=16000; channels=1_\n\nContent type used when sending audio. Has to match your audio data format.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-lex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-lex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-lex/lists"}