{"id":15524346,"url":"https://github.com/codeforequity-at/botium-connector-watson","last_synced_at":"2025-04-23T07:31:30.265Z","repository":{"id":44486354,"uuid":"152717561","full_name":"codeforequity-at/botium-connector-watson","owner":"codeforequity-at","description":"Botium Connector for IBM Watson Assistant https://www.botium.at","archived":false,"fork":false,"pushed_at":"2022-12-12T13:25:37.000Z","size":391,"stargazers_count":7,"open_issues_count":1,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-09T23:38:12.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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}},"created_at":"2018-10-12T08:20:16.000Z","updated_at":"2022-11-03T23:14:28.000Z","dependencies_parsed_at":"2023-01-27T20:01:33.999Z","dependency_job_id":null,"html_url":"https://github.com/codeforequity-at/botium-connector-watson","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-watson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-watson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-watson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeforequity-at%2Fbotium-connector-watson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeforequity-at","download_url":"https://codeload.github.com/codeforequity-at/botium-connector-watson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249947526,"owners_count":21349819,"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":[],"created_at":"2024-10-02T10:51:02.906Z","updated_at":"2025-04-23T07:31:30.237Z","avatar_url":"https://github.com/codeforequity-at.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Botium Connector for IBM Watson Assistant\n\n[![NPM](https://nodei.co/npm/botium-connector-watson.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/botium-connector-watson/)\n\n[ ![Codeship Status for codeforequity-at/botium-connector-watson](https://app.codeship.com/projects/6075bd10-b02e-0136-4bcc-2eae8ef75d66/status?branch=master)](https://app.codeship.com/projects/310383)\n[![npm version](https://badge.fury.io/js/botium-connector-watson.svg)](https://badge.fury.io/js/botium-connector-watson)\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 IBM Watson Assistant chatbots.\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 uses the IBM Watson Assistant API to run conversations.\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.ai)\n\nThis connector processes info about NLP. So Intent/Entity asserters can be used.\n\n## Requirements\n\n* __Node.js and NPM__\n* a __IBM Watson Assistant__ chatbot, 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 Watson Connector\n\nWhen using __Botium CLI__:\n\n```\n\u003e npm install -g botium-cli\n\u003e npm install -g botium-connector-watson\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-watson\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 IBM Watson Assistant to Botium\nYou need IBM Cloud credentials (Username/Password or API Key) - see [IBM Docs](https://cloud.ibm.com/apidocs/assistant/assistant-v2?code=node#authentication) on how to get it.\n\nOpen the file _botium.json_ in your working directory and add the secret:\n\n```\n{\n  \"botium\": {\n    \"Capabilities\": {\n      \"PROJECTNAME\": \"\u003cwhatever\u003e\",\n      \"CONTAINERMODE\": \"watson\",\n      \"WATSON_WORKSPACE_ID\": \"\u003cwatson workspace id\u003e\",\n      \"WATSON_APIKEY\": \"\u003cibm cloud api key\u003e\"\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## Using the botium-connector-watson-cli\n\nThis connector provides a CLI interface for importing convos and utterances from your Watson workspace and convert it to BotiumScript.\n\n* Intents and user examples are converted to BotiumScript utterances and convo files (using the _import_ command and the _--buildconvos_ or _--buildentities_ option)\n* Entities and synonyms are converted to BotiumScript utterances and convo files (using the _import_ command and the _--buildentities_ option)\n* User Conversations are downloaded and converted to BotiumScript convos or just a plain list for analytics (using the _importlogs_ command)\n\nYou can either run the CLI with botium-cli (it is integrated there), or directly from this connector (see samples/convoV1/package.json for some examples):\n\n    \u003e botium-connector-watson-cli import\n    \u003e botium-connector-watson-cli importlogs --watsonformat convo\n    \u003e botium-connector-watson-cli importlogs --watsonformat intent\n\n_Please note that a botium-core installation is required_\n\nFor getting help on the available CLI options and switches, run:\n\n    \u003e botium-connector-watson-cli import --help\n    \u003e botium-connector-watson-cli importlogs --help\n\n## Watson Assistant Context Handling\n\nWhen using BotiumScript, you can do assertions on and manipulation of the Watson Assistant context variables.\n\n### Asserting context variables\n\nFor asserting context variables, you can use the [JSON_PATH asserter](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#jsonpath-asserter):\n\n    #bot\n    JSON_PATH $.context.skills['main skill'].user_defined.lightonoff|off\n\n_Depending on your Watson Assistant skill structure, this may different - but by default, this should work_\n\n### Initializing context variables\n\nYou can use the _WATSON\\_INITIAL\\_CONTEXT_ capability to initialize the context in your botium.json:\n\n    \"WATSON_INITIAL_CONTEXT\"{\n      \"initcontext1\": \"initcontext1value\",\n      \"initcontext2\": \"initcontext2value\"\n    }\n\n### Adding context variables\n\nFor adding a context variable within a test case, you have to use the [UPDATE_CUSTOM logic hook](https://botium-docs.readthedocs.io/en/latest/05_botiumscript/index.html#update-custom). This example will set two context variables (when using V2 API), one to a plain string, the other one to a JSON object:\n\n    #me\n    play some jazz music\n    UPDATE_CUSTOM SET_WATSON_CONTEXT|skills['main skill'].user_defined.mycontext1|botium\n    UPDATE_CUSTOM SET_WATSON_CONTEXT|skills['main skill'].user_defined.mycontext2|{\"nested\": \"botium\"}\n\nThe parameters are:\n1. SET_WATSON_CONTEXT\n2. The path to the context variable\n3. The value of the context variable\n\n### Removing context variables\n\nFor removing a context variable, the same logic hook is used (when using V2 API):\n\n    #me\n    play some jazz music\n    UPDATE_CUSTOM UNSET_WATSON_CONTEXT|skills['main skill'].user_defined.mycontext1\n    UPDATE_CUSTOM UNSET_WATSON_CONTEXT|skills['main skill'].user_defined.mycontext2\n\nThe parameters are:\n1. UNSET_WATSON_CONTEXT\n2. The path to the context variable\n\n## Usage behind a corporate proxy\n\nIn case you have an HTTPS proxy, set the _HTTPS_PROXY_ environment variable\n\n    \u003e HTTPS_PROXY=my-proxy-address:port npm test\n\nIf you have an HTTP proxy, Botium has to tunnel the HTTPS traffic to Watson Assistant services over HTTP. Set the _WATSON_HTTP_PROXY_HOST_ and _WATSON_HTTP_PROXY_PORT_ capabilities in botium.json (see below).\n\n## Supported Capabilities\n\nSet the capability __CONTAINERMODE__ to __watson__ to activate this connector.\n\n### WATSON_ASSISTANT_VERSION\n_Default: V1_\n\nWatson supports two Assistant SDK versions, V1 and V2.\n* With **V1**, Botium accesses a workspace (or _Skill_) directly\n* With **V2**, Botium accesses an assistant wrapping a versioned skill\n\n### WATSON_URL\n_Default: \"https://api.us-south.assistant.watson.cloud.ibm.com\"_\n\nHas to be set to the URL shown in the Skill API details page (e.g. https://api.us-east.assistant.watson.cloud.ibm.com) - for a list of valid IBM Cloud URLs see [IBM Docs](https://cloud.ibm.com/apidocs/assistant/assistant-v2?code=node#service-endpoint).\n\n### WATSON_HTTP_PROXY_HOST / WATSON_HTTP_PROXY_PORT\nHostname/IP Address and port of your HTTP proxy\n\n**This is only required if you have a HTTP proxy only. For HTTPS proxies, you can use the HTTPS_PROXY environment variable**\n\n### WATSON_VERSION\n_Default: \"2018-09-20\"_\n\n### WATSON_APIKEY *\nIAM API Key for IBM Watson - see [IBM Docs](https://cloud.ibm.com/apidocs/assistant/assistant-v2?code=node#authentication) how to create it for your IBM Watson account. Either the IAM API Key or the Service credentials (see below) are required.\n\n### WATSON_BEARER *\n\nIBM Watson instances using the [Cloud Pak For Data Platform](https://cloud.ibm.com/apidocs/cloud-pak-data#getauthorizationtoken) do not have IAM API Keys, but can instead be authenticated using the bearer token found within the service instance details.\n\n### WATSON_USER * and WATSON_PASSWORD *\nService credentials for your IBM Watson instance - see [here](https://console.bluemix.net/docs/services/watson/getting-started-credentials.html#service-credentials-for-watson-services) how to create them for your IBM Watson account.\n\n### WATSON_WORKSPACE_ID *\nThe Skill ID to use (Workspace ID). You can find it in the IBM Watson Assistant Dashboard when clicking on \"View API Details\" in the popup menu of a skill in the Skills overview list.\n\n_This is only supported for Assistant SDK V1_\n\n### WATSON_ASSISTANT_ID *\nThe Assistant ID to use. You can find it in the IBM Watson Assistant Dashboard when clicking on \"Settings\" in the popup menu of an assistant in the Assistants overview list.\n\n_This is only supported for Assistant SDK V2_\n\n### WATSON_FORCE_INTENT_RESOLUTION\n_Default: false_\nIf this capability is disabled, then a response will be dropped if the connector does not recognizes any component like text or button in it. But the dropped message has NLP recognition info like intent and entities, which could be checked.\n\n### WATSON_COPY_WORKSPACE\n_Default: false_\n\nThis capability will copy the Watson workspace and run the Botium script on the new workspace (and delete it afterwards). Typically, when running a large amount of tests on production conversation service, the Watson workspace should not get \"polluted\" with test data - enabling this capability will prevent that. \n\n_This is only supported for Assistant SDK V1_\n\n_Attention: as the copied workspace will run through Watson training session, it could take some time until the copied workspace is available. Botium will only continue after training is complete_\n\n### WATSON_WELCOME_MESSAGE\n_default: empty_\n\nTrigger a welcome message from IBM Watson by sending some input upfront (for example \"WELCOME\")\n\n### WATSON_ASSISTANT_USER_ID\nFor user-based Watson Assistant plans, it is possible to set the user-id\n\n### WATSON_INITIAL_CONTEXT\n_default: empty_\n\nInitial context variables (as JSON struct)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-watson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-watson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeforequity-at%2Fbotium-connector-watson/lists"}