Tags:
Categories:

Install full Aura Bot

Guidelines for the installation and configuration of full Aura Bot

Introduction to full Aura Bot

This document details the steps to locally deploy a fully functional working aura-bot instance. By fully functional working instance, we mean a bot interacting with the Aura Cognitive services as well as with the Kernel APIs deployed as part of the desired environment the local aura-bot instance should interact with. 

Install Aura Bot

ℹ️ This is a general process suitable for every developer and environment.

The general process for the installation of an aura-bot instance is explained below.

  1. Access to the main aura-bot repository:
    https://github.com/Telefonica/aura-bot-platform

  2. Clone the repository for the intended release branch, i.e., for Killers release:
    git clone https://github.com/Telefonica/aura-bot-platform.git --branch release/killers

  3. Get into the local repository root directory:
    $ cd aura-bot-platform

  4. Log in NPM to be able to download the private NPM package dependencies (request the token from the Aura Platform Team (APE) to properly log in). You can login with user/password or using the token:

  • User/password -> npm login
  • Token -> Add the token to the environment variables on your machine. Follow the guidelines for mac/linux.

  1. Now configure your bot as explained in the section configure Aura Bot.

  2. If required, install the existing local use cases (packaged as .tgz files)
    There are two options:

  • a. Add the library .tgz file to the file plugin-config.json (placed in the aura-bot-platform Github repository).
    Note that manual addition of libraries to plugin-config.json file requires manual installation too:
    npm install <library>

  • b. Use the automatic script:
    npm run import-libraries
    This process will install any .tgz in aura-bot-platform/local_modules folder.
    The previous command will add the library in package.json and plugin-config.json files and will install them into the project.
    If a further configuration of the library is required (for example, disabling some dialogs), this must be done manually by editing plugin-config.json available at the root of the aura-bot-platform folder.

Practical example for working with full Aura Bot

The current section includes a practical example of the process for a specific environment (for example, applied to MacOS, Visual Studio, access to the kubernetes cluster, etc.). Therefore, the steps explained below may slightly differ from the general guidelines, but provide a useful practical approach for developers.

Dependencies

The following tools and artifacts are needed:

  1. NodeJS version 14 You can download it here and install it via package manager.

  2. ngrok
    The executable binary can be downloaded for several systems in ngrok. Alternatively, ngrok can be installed via the NPM package, once NodeJS is installed, with the following command:

        npm install -g ngrok

  3. Personal Kubernetes configuration file
    Your local DevOps or Development Team will provide you with it. In this case, this file looks like this (the certificate and key data have been modified for security reasons):

    apiVersion: v1

    clusters:

        cluster:

            certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV5RENDQXJDZ0F3S

            server: https://aura-auradev-1-14-6.westeurope.cloudapp.azure.com

            name: aura-auradev-1-14-6

    contexts:

        context:

            cluster: aura-auradev-1-14-6

            user: german.torodelvalle-1573743046

            name: aura-auradev-1-14-6

        current-context: aura-auradev-1-14-6

            kind: Config

            preferences: {}

    users:

        name: user-1573743046

        user:

            client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVHRENDQWdDZ0F3SUJB

            client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdTR4

  1. A bot service deployed in the Microsoft Azure portal (https://portal.azure.com) enabling the Direct Line channel to be able to interact with the bot from any client using Direct Line.

  2. Visual Studio Code (https://code.visualstudio.com) to be able to debug the running instance of the Aura Bot locally.

Procedure for working with full Aura Bot

To install a working fully operational local instance of aura-bot, follow the steps below:

  1. Local deployment of the aura-bot instance for your Aura Platform release. Check the example below for Jimi Hendrix release (each line corresponds to a command to be executed):

        git clone https://github.com/Telefonica/aura-bot-platform.git --branch release/jimihendrix

    cd aura-bot-platform

    npm install

  2. Kubernetes configuration: Consider including the next environment variable export in your local terminal starting up configuration file to avoid running the following command each time. Obviously, a correct path to the personal Kubernetes configuration file mentioned as a dependency in the previous dependencies section should be used in the following command.

        export KUBECONFIG=~/kubernetes-config.yaml

  3. Get the list of available Kubernetes namespaces:

        kubectl get ns

  4. Get the configuration for the Kubernetes namespace of interest (contact your local DevOps team to figure it out). In our case, since we are deploying a local release of the aura-bot instance, the aura-ap-next should be used as the namespace (the configuration will be stored in a file named aura-bot.ap-next.env):

        (kubectl -n aura-ap-next get cm aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring)\")|.[]" ; kubectl -n aura-ap-next get secret aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring|@base64d)\")|.[]" ) > aura-bot.ap-next.env

  5. Work with Visual Studio Code:

    • Open the previous aura-bot-platform directory (see step 1) in Visual Studio Code.

    • Open the internal Visual Studio Code terminal (CONTROL + ` in Windows).

    • Place the aura-bot.ap-next.env file (see step 4) in the .vscode/.env/ subfolder inside the aura-bot folder. Create the needed directories if not already created.

    • Include the following launch configuration in the .vscode/launch.json file inside the aura-bot-platform repository (create the needed directories if not already created) to be able to start the aura-bot instance from inside Visual Studio Code. Please, set the AURA_MICROSOFT_APP_ID as well as the AURA_MICROSOFT_APP_PASSWORD configuration variables to the appropriate values obtained when creating the bot service in the Microsoft Azure portal (see the dependency number 4 included in the previous dependencies section):

      {

    // Use IntelliSense to learn about possible attributes.

    // Hover to view descriptions of existing attributes.

    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387

    "version": "0.2.0",

    "configurations": [

        {

            "type": "node",

            "request": "launch",

            "name": "aura-bot.ap-next.env",

            "program": "${workspaceFolder}/lib/index.js",

            "console": "integratedTerminal",

            "outFiles": [

                "${workspaceFolder}/lib/**/*.js"

            ],

            "env": {

                "CONFIG_FILE": ".vscode/.env/aura-bot.ap-next.env",

                "AURA_MICROSOFT_APP_ID": "8d72c407-XXXX-4b50-a076-76XXXX5437e4",

                "AURA_MICROSOFT_APP_PASSWORD": "password",

                "AURA_LOGGING_FORMAT": "dev",

                "AURA_LOGGING_LEVEL": "DEBUG"

            }

        }

    ]

}

  6. In the aura-bot.ap-next.env file: Set the values of the configuration variables named AURA_DEFAULT_LOCALE and AURA_DEFAULT_TIME_ZONE to the desired values according to the appropriate language and time zone. For example, for Spain these values are:

    AURA_DEFAULT_LOCALE=es-es

AURA_DEFAULT_TIME_ZONE=Europe/Madrid

  7. Provide access to the Aura Mongo databases:

    • Substitute the Mongo connection URI configuration variable (named AURA_MONGODB_URI) located in the .vscode/.env/aura-bot.ap-next.env configuration file to the next value: 
          AURA_MONGODB_URI=mongodb://localhost:27017
    • Port forwards the local URI to the real one running the following command in an internal Visual Studio Code terminal using the following command: 
          kubectl port-forward mongodb-0 -n aura-system 27017:27017

    This makes your bot use the Mongo database in your development environment, if you are not using Atlas.

  8. Provide access to the Aura Cognitive Services:

    • Substitute the Aura Cognitive URI configuration variable (named AURA_COGNITIVE_ENDPOINT) located in the .vscode/.env/aura-bot.ap-next.env configuration file to the next value: 
          AURA_COGNITIVE_ENDPOINT=http://localhost:7000/auracognitive/v3
    • Port forwards the local URI to the real one running the following command in an internal Visual Studio Code terminal using the following command: 
          kubectl -n aura-ap-next port-forward deployment/api-gw 7000:80

  9. Provide external access to the locally deployed release of the aura-bot instance:

    • Start ngrok in an internal Visual Studio Code terminal using the following command:

          ngrok http 8080

    • Set the new HTTPS URL provided by ngrok in the configuration of the bot service available in the Microsoft Azure portal (see the dependency number 4 included in the dependencies section). The messaging connection endpoint should have a value similar to: https://55a1d84f.ngrok.io/api/messages

  10. The locally deployed release of the aura-bot instance is ready to be started. Click on the “Play” icon in Visual Studio Code to run the launch configuration named aura-bot.ap-next.env.

  11. Interact with the locally deployed Aura release of the aura-bot instance:

    • 11.1. Get a DirectLine token running the following command (instead of the included one, use the secret for the Direct Line channel of the bot service available in the Microsoft Azure portal (see the dependency number 4 included in the dependencies section):

      curl --location --request POST 'https://directline.botframework.com/v3/directline/tokens/generate' \

--header 'Authorization: Bearer 55FhfjL8soI.bm-NhUy68mwCfPar4zIjTYHGd5cEGmKWt5zXqmA9rxI' \

-d ''

      A response such as the following one is received:

          {

    "conversationId": "AUR2oOohW9Z64MtvuQyoFO-a",

    "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg",

    "expires_in": 3600

    }

    • 11.2. Start the conversation using the token obtained in the previous step (11.1).

      curl --location --request POST 'https://directline.botframework.com/v3/directline/conversations' \

--header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg' \

--data-raw ''

      A response such as the following one is received:

      {

  "conversationId": "AUR2oOohW9Z64MtvuQyoFO-a",

  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd0b3JvZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJu1234OiAxNTg4NzYyMjY5LA0KICAiZXhwIjogMTU4ODc2NTg2OSwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.Ft_r71JQ-Qq39nXqzO2u3SEHYMjGY8vMb4_OJL89Uw9NXXXXcvYmM62iu6YG8DcFCy2PFj2hmOev35f06zNXsgbHAthPxTPTIboPO8DyXYFQe8yYbhBKXBt2AIoI4SOO16e_OKaEETh-R2sXe6rfSp3PTgKddzFyLkXCl77e2Tz3TI7Zwe-NIyfmXKhJwd-XzTl7lxJAunSDSDS1i2rwzz8yAjBwJl5wFFhGXnOxPph1bHi_Ag-gU-XIMk_vhTTMLvkCORhBGWZJCNSGXxs5XBUYOZf2oZJA_UWtHqNolNO3K5mF6-cHg188YbAax78-gq0lB2XQCKCamZTmD9TRCg",

  "expires_in": 3600,

  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/stream?watermark=-&t=ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI61234T08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd0b3JvZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjY5LA0KICAiZXhwIjogMTU4ODc2MjMyOSwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.igWA6xJmWwYoTeOV_A5cY_1_spptYgG2xqhJFGBc6PR0l62W-XXXXohqwZqfs7-z-VfyRrWKmD6x2xCw17DRGua6P7qE5Sk9XeV5DcD4XE_f80jGsr86CxFxL_F23iAYWOnpRtYNXJ3yCn69GXHBHvp0sAefLno7JqaoeHZlstyEm72o1v_WqFVd1RHW9zzbbEzQrIhmixUoQbEacuIIMAc6Wtesi3bb8iPOVtFIN_nEovceIieeQggMn0YesYDjiQ600zUX6p4FnU8MPtWpwV6XCSspC3iTuuUSjnpMMbekXYqJHItdgPTE4dPFkqQI_mhPEU0Ravn4vWNQLMd0rg",

  "referenceGrammarId": "95090c7e-6475-5a58-ba7a-35e45f903d38"

}

    • 11.3. Send a message to the bot using the conversation obtained in the previous step and any of the tokens obtained in step 11.1 or 11.2 (you should use a valid user Aura id set in the from.id property, request it from your local QA or DevOps team):

          curl --location --request POST 'https://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/activities' \

    --header 'Content-Type: application/json' \--header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg
    ' \

    --data-raw ' {

        "type": "message",

        "from": {

            "id": "d1626d20-4e16-46ac-ba3c-c140fa3742a1"

        },

        "text": "Hola"

    }'

      A response such as the following one is received:

              {
            "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000001"
        }

    • To get the message sent by the aura-bot instance, run the following command to get the activities sent in the conversation (use the same conversation started in step 11.2 and any of the tokens obtained in step 11.1.

          curl --location --request GET 'https://directline.botframework.com/v3/directline/conversations/AUR2oOohW9Z64MtvuQyoFO-a/activities' \

    --header 'Authorization: Bearer ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJBT08tZXhGd2puR3lDTEJhOTgwVkxOME1tUTgiLA0KICAieDV0IjogIkFPTy1leEZ3am5HeUNMQmE5ODBWTE4wTW1ROCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogImF1cmEtYm90LWd01234ZGVsdmFsbGUiLA0KICAic2l0ZSI6ICI1NUZ1dmdMOHNvSSIsDQogICJjb252IjogIkFVUjJvT29oVzlaNjRNdHZ1UXlvRk8tYSIsDQogICJuYmYiOiAxNTg4NzYyMjQwLA0KICAiZXhwIjogMTU4ODc2NTg0MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3XXXXLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.pps98q5aYO2T4S7XwdIBudCzZB1T31HlwJ51tbEMcGGJrcHRI-hXnZskjHlcXIzBJiABeYiZSncqyWsNRWSmoVQ3iIYTrBiJM6y1EYn2qDJO4JYjZI5IZeFnp3GieB3eMP-HsW1DixK2p_C2DwxZy5pDc3nveclejI7SeUpl6m4frzNDPfqv7UoEW6aMthnT64JWhzncfF3y3_X-6J5v5RhTPW0OJEXpEuZ94AkhwHLfjLKzyewMwk0NzyAwmnCSZ0p6XyJjx9lA1FByHMRP0OLwcrfE8l_N_eXwUZuSY10gqRl5Tmm-D9p869mooA_0DuJYZUhgH_0D_4yg8PFjtg
    '

      A response such as the following one is received:

      {

  "activities": [

    {

      "type": "message",

      "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000000",

      "timestamp": "2020-05-06T11:14:43.8618783Z",

      "serviceUrl": "https://directline.botframework.com/",

      "channelId": "directline",

      "from": {

        "id": "d1626d20-4e16-46ac-ba3c-c140fa3742a1"

      },

      "conversation": {

        "id": "DvpneVrCrDG9DVIL7pQr5N-a"

      },

      "text": "Hola"

    },

    {

      "type": "message",

      "id": "AUR2oOohW9Z64MtvuQyoFO-a|0000001",

      "timestamp": "2020-05-06T11:14:49.2303326Z",

      "localTimestamp": "2020-05-06T11:14:45.764+00:00",

      "channelId": "directline",

      "from": {

        "id": "aura-bot-gtorodelvalle",

        "name": "aura-bot-gtorodelvalle"

      },

      "conversation": {

        "id": "AUR2oOohW9Z64MtvuQyoFO-a"

      },

      "text": "Hola, buenas",

      "inputHint": "acceptingInput",

      "channelData": {

        "correlator": "6a3ccc2a-c80e-441f-83ff-945691fd3407"

      },

      "replyToId": "DvpneVrCrDG9DVIL7pQr5N-a|0000000"

    }

  ],

  "watermark": "1"

}

ℹ️ Instead of using HTTP requests, another possibility is to use the Web Sockets URL obtained in step 11.2 (see the streamUrl property obtained in the response) using a Web Sockets client such as the Smart Web Sockets extension for Google Chrome.

Notice the Aura Cognitive services recognized the “Hola” text message sent to the bot as a greeting and it responded with a greeting message (“Hola, buenas”).

You could set a breakpoint in any part of the code (for example, in the greetings dialog) to debug it.

Last modified January 15, 2025: feat: Documentation Assistant and ATRIA for Linkin Park release #AURA-26619 [RTM] (409958c0)