LexV2 Workers

Type: NLP Worker

A LexV2 worker takes user input and sends it to a LexV2 bot for natural language processing. A LexV2 worker can be created through the CLI or through the Add Resource button on a bot’s detail page within portal.

Secrets

An AWS cross-account role is required in order to access LexV2, and the cross account role must contain the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "<CROSS_ACCOUNT_ROLE_ARN>",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": [
                        "lexv2.amazonaws.com",
                        "lex.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Action": [
                "lex:CreateCustomVocabulary",
                "lex:UpdateCustomVocabulary",
                "lex:DeleteCustomVocabulary",
                "lex:DescribeCustomVocabulary",
                "lex:DescribeCustomVocabularyMetadata",
                "lex:StartImport",
                "lex:DescribeImport",
                "lex:CreateBot",
                "lex:UpdateBot",
                "lex:DeleteBot",
                "lex:DescribeBot",
                "lex:DeleteBotChannel",
                "lex:CreateBotLocale",
                "lex:UpdateBotLocale",
                "lex:DescribeBotLocale",
                "lex:DeleteBotLocale",
                "lex:BuildBotLocale",
                "lex:CreateBotAlias",
                "lex:UpdateBotAlias",
                "lex:DeleteBotAlias",
                "lex:DescribeBotAlias",
                "lex:DeleteBotVersion",
                "lex:CreateBotVersion",
                "lex:DescribeBotVersion",
                "lex:ListBotVersions",
                "lex:CreateIntent",
                "lex:UpdateIntent",
                "lex:DeleteIntent",
                "lex:CreateSlotType",
                "lex:UpdateSlotType",
                "lex:DeleteSlotType",
                "lex:CreateSlot",
                "lex:UpdateSlot",
                "lex:DeleteSlot",
                "lex:StartConversation",
                "lex:RecognizeText",
                "lex:RecognizeUtterance",
                "lex:GetSession",
                "lex:PutSession",
                "lex:DeleteSession"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot/*",
                "arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot-alias/*"
            ]
        },
        {
            "Action": [
                "lex:CreateUploadUrl"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:*"
            ]
        }
    ]
} 

In the above please note that following placeholders should be substituted before creating the policy:

  • <CROSS_ACCOUNT_ROLE_ARN> - This refers to the cross account role ARN which the policy is being attached to.
  • <AWS_ACCOUNT_NUMBER> - This refers to your AWS account number.

The above policy will allow ServisBOT to manage LexV2 bots within your AWS account, if you are bringing an existing bot to be managed by ServisBOT you may narrow down the permissions to a specific resource by changing the following resources:

  • “arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot/*"
  • “arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot-alias/*"

to:

  • “arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot/<BOT_ID>"
  • “arn:aws:lex:eu-west-1:<AWS_ACCOUNT_NUMBER>:bot-alias/<BOT_ALIAS_ID>"

where <BOT_ID> is the id of your LexV2 bot and BOT_ALIAS_ID is the bot alias id of your LexV2 Bot.

Please see cross-account roles for more information on how to create a cross account role secret within ServisBOT.

Creating LexV2 Worker Through the CLI

When creating a LexV2 worker you have two options, you can choose to bring your existing LexV2 bot or allow ServisBOT to create and update a new LexV2 bot for you.

The attributes that make up a LexV2 worker configuration are as follows:

  • BotId - (Optional) The Bot Id of the LexV2 Bot. If this is not provided then ServisBOT will create a new LexV2 Bot on your behalf named after the ServisBOT bot name.
  • BotAliasId - (Optional) The Bot Alias Id of the LexV2 Bot. If this is not provided then ServisBOT will create a new LexV2 Alias associated with the newly created bot named after the ServisBOT bot name.
  • Secret - (Required) The ServisBOT Secret SRN which references the LexV2 cross-account role secret.
  • Locale - (Required) The locale to use when creating, updating and communicating with a lex V2 Bot, e.g “en_US”, for a full list of supported Lex V2 locales see here.
  • Region - (Required) The AWS Region where the LexV2 Bot will be used.
  • NluConfidenceThresholdOverride - (Optional) You can use this as an override of the returned detected intent confidence. If this value is higher than that returned from the nlu provider it will change the response to be a fallback, this value defaults to 0.

If you want to bring an existing LexV2 Bot and use it within ServisBOT you must provide the BotId & BotAliasId of the LexV2 Bot you wish to use.

If you want ServisBOT to create and update a LexV2 Bot on your behalf you can omit the BotId & BotAliasId from the worker configuration.

ServisBOT Managed

ServisBOT can create and update LexV2 bots on your behalf to allow for a quicker and simpler setup when integrating with LexV2.

To create a LexV2 Worker which is managed by ServisBOT put the following json into a file called worker.json:

{
  "Data": {
    "NluConfiguration": {
      "Locale": "en_US",
      "Region": "eu-west-1",
      "Secret": "srn:vault::acme:aws-cross-account-role:lexcrossaccount"
    },
    "NluType": "LexV2"
  },
  "Organization": "acme",
  "Config": {
    "Avatar": "default-bot"
  },
  "Enabled": true,
  "Description": "A LexV2 Worker",
  "Type": "nlp-worker",
  "Name": "LexV2Worker",
  "Status": "published"
}

Remote Managed (Bring Your Own Bot)

If you want to integrate an existing LexV2 bot into ServisBOT you can must provide the BotId & BotAliasId of the LexV2 bot you wish to use.

To create a LexV2 Worker which uses an existing LexV2 bot put the following json into a file called worker.json:

{
  "Data": {
    "NluConfiguration": {
      "BotId": "a-lex-v2-bot-id",
      "BotAliasId": "a-lex-v2-bot-alias-id",
      "Locale": "en_US",
      "Region": "eu-west-1",
      "Secret": "srn:vault::acme:aws-cross-account-role:lexcrossaccount"
    },
    "NluType": "LexV2"
  },
  "Organization": "acme",
  "Config": {
    "Avatar": "default-bot"
  },
  "Enabled": true,
  "Description": "A LexV2 Worker",
  "Type": "nlp-worker",
  "Name": "LexV2Worker",
  "Status": "published"
}

You can then run the following cli command to create the worker:

sb-cli worker create worker.json

Once you have created the worker using the CLI, it will return an id for you. You can then create or update a bot to reference the newly created worker using the worker id. To reference the worker in your bot you must place it in the Workers array in your bot configuration with a type of nlp-worker. Below is a sample configuration of a bot which shows you where to place the id of your newly created LexV2 worker.

{
  "Workers": [
    {
      "Type": "nlp-worker",
      "Id": "<your-worker-id-goes-here>"
    }
  ],
  "State": "RUNNING",
  "SecureSession": false,
  "QuietTimeEnabled": false,
  "NluManagementMode": "ServisBOT",
  "Persona": "default-bot",
  "Organization": "acme",
  "Description": "Default Description for a bot",
  "Tags": [
    "Getting Started"
  ],
  "Name": "LexV2",
  "Srn": "srn:botnet:eu-private-3:acme:bot:LexV2"
}