Tags:
Categories:

Aura configuration updater

Aura configuration updater is a set of operations to modify channel information in aura-configuration-api and locale files with the changes indicated

Introduction

Aura configuration updater allows making changes in certain aura-bot configuration directly in Aura environments in an easier way.

This tool allows changes in:

  • channel configuration (aura-configuration_api server):
    • contextFilters of the intents of the dialogs.
    • aura-bot libraries and dialogs authorization fields: scopes and purposes.
    • Channels scopes and purposes to be requested when generating a Kernel access_token.
  • POEditor resources, to include new ones or update those already existing.

Aura configuration updater can work in two modes:

  • Included during the local-deploy procedure: all configuration changes defined will be applied after the aura-bot make-up job before rebooting the instances.

  • Local dry-run: where the script generates the files according to the changes requested in legacy format, so they can be reviewed before uploading them to the Azure Storage and being applied to aura-bot.

Development

Aura configuration updater configuration

AURA_VERSION: Mandatory. `String`. Aura version.
AURA_AUTHORIZATION_HEADER: Optional. `String`. Mandatory only if _aura-configuration-api_ is used.
AURA_MAKEUP_FILES_ORIGIN: Mandatory. `String` Default 'blob'. Possible values: ['config-server', 'blob']. Source from where the channel information will be obtained.
AURA_MAKEUP_FILES_DESTINATION: Mandatory. `String` Default 'blob'. Possible values: ['config-server', 'blob', 'all']. Destination where modifications to channel information will be saved.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY. Mandatory. `String`. Storage access key.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT. Mandatory. `String`. Storage account name.
AURA_LOGGING_LEVEL. Optional. `String` Default 'DEBUG'. Loggin level.
AURA_LOGGING_FORMAT. Optional. `String` Default 'DEV'. Loggin format.
CONFIG_FILE. Optional. `String`, File with environment variables
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT. Optional. `String`. _aura-configuration-api_ url.
AURA_CHANNELS_CONFIGURATION_BLOB. Optional. `String` Default 'bot-response.json'. Name of blob of to configuration.
AURA_UPDATE_CONF_CHANNELS_CONFIGURATION_CHANGES_BLOB. Optional. `String` Default 'changes-bot-response.json'. Name of blob with changes to apply in bot configuration file.
AURA_UPDATE_CONF_CHANNELS_CONFIGURATION_CHANGES_PATH. Optional. `String` Default 'changes'. Path for file with changes to apply in bot configuration file.
AURA_CONFIGURATION_CONTAINER. Optional. `String` Default 'aura-configuration'. Name of configuration container.
AURA_UPDATE_CONF_LOCALE_CHANGES_PREFIX. Optional. `String` Default 'changes-locale-'. Prefix of files with changes to apply in locale files.
AURA_UPDATE_CONF_LOCALE_CHANGES_PATH. Optional. `String` Default 'changes'. Path for files wiht changes to apply in locale files.
AURA_UPDATE_CONF_LOCALE_PATH. Optional. `String` Default 'locale'. Path of locale files.
AURA_UPDATE_CONF_MODE_DRY_RUN. Optional. `boolean` Default 'false'. Flag to indicate whether or not updater is executed in dry-run mode.
AURA_UPDATE_CONF_MODE_DRY_RUN_PATH. Optional. `String` Default 'dry-run'. Output path for dry-run mode.
AURA_STATIC_CONTAINER. Optional. `String` Default 'static-resources'. Name of static container, container with locale files.

Prepare your CONFIG_FILE

  • Example to read and write using aura-configuration-api:
AURA_AUTHORIZATION_HEADER=${AUTHORIZATION_HEADER}
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT=${CONFIGURATION_API_ENDPOINT}
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY=${STORAGE_ACCESS_KEY=}
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT=${STORAGE_ACCOUNT}
AURA_MAKEUP_FILES_ORIGIN='config-server'
AURA_MAKEUP_FILES_DESTINATION='config-server'
AURA_VERSION='7.2.0'

The AURA_CHANNELS_CONFIGURATION_API_ENDPOINT variable is needed to make changes in aura-configuration-api server.

Running on dry-run mode

To execute on dry_run mode, it is necessary to set the AURA_UPDATE_CONF_MODE_DRY_RUN variable to true.

By default, the files generated during the process will be saved on the dry-run folder. It is possible to change this location using the AURA_UPDATE_CONF_MODE_DRY_RUN_PATH variable.

The aura-configuration-updater script already allows you to run in dry-run mode:

npm run aura-configuration-updater

The result will be available in the dry-run folder (or the one defined in the AURA_UPDATE_CONF_MODE_DRY_RUN_PATH variable) in blob container.

Execution example

  • Add a file in aura-configuration/7.4.0/changes/changes-bot-response.json:
{
    "version": "1.0",
    "channels": [
        {
            "channelId": "45494a5b-835a-4fff-a813-b3d2be529dbe",
            "fpaAuthPurposes": {
                "add": "my-purpose"
            }
        }
    ]
}
  • Run in dry-run mode:
npm run aura-configuration-updater

# Output:
# INFO  Saving changes in: 7.4.0/dry-run/bot-response-2022-09-19T10:24:21.129Z.json {
#        module: 'aura-update-bot-response',
#        corr: 'd693e0a2-1382-45d5-a774-3380479f04db',
#        host: 'zbook'
#      }
  • Validate generated file in the aura-configuration/7.4.0/dry-run folder:
[
    {
        ...
        "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "nlp": {
        "enabled": true,
            "enabled": true
        }
        },
        "requestOptions": {
        "requestOptionsVersion": {
            "1": {
            "channel": "directline"
            }
        }
        },
        "name": "novum-mytelco",
        "fpa_auth_purposes": "customer-self-service identify-customer aura-technical-problems-purpose my-purpose",
        "fpa_auth_scopes": "",
        "prefix": "nov",
        ...
    }
]

Running as docker container

Pull image from repository

For this step, previous login is required.

docker login -u <username> -p <password> auraregistry.azurecr.io

docker pull auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

An example is shown below:

docker pull auraregistry.azurecr.io/aura/aura-configuration-updater:7.2.0-devironmaiden.71

Run docker container

In order to run the docker container, two procedures are available:

With .env file

Change $VERSION accordingly, exporting it or changing the string in the commands.

docker run -e CONFIG_FILE=/opt/aura-configuration-updater/.env \
     -v $(pwd)/.env:/opt/aura-configuration-updater/.env  \
    auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

With .env variables in command

docker run 
     -e AURA_AUTHORIZATION_HEADER = \
     -e AURA_CHANNELS_CONFIGURATION_API_ENDPOINT = \
     -e AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY=  \
     -e AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT=  \
     -e AURA_VERSION= \
     auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

File changes formats

File changes bot configuration format (changes-bot-response.json)

It will be a JSON file with a version and an array of ‘channels’. Each element of this array is specified with the following properties:

  • Properties marked in bold are mandatory.

  • Properties marked in italics are optional.

  • channelId: Aura channel to which the changes apply.

  • fpaAuthPurposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:

    • add: space-separated text string for Kernel purposes that needs to be added to this channel.
    • delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.

  • fpaAuthScopes: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:

    • add: space-separated text string with the Kernel scopes that need to be added to this channel.
    • delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.

  • dialogLibraries: array with the changes on the dialog libraries (or plugins). ONLY the contextFilters that apply to each dialog on each channel are allowed to be modified. The format of each object in this array will be:

    • name: name of the library that has the dialog on which you want to apply the change.
    • authorization: object with the modifications in the Kernel purposes and scopes to perform for this library:
      • purposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:
        • add: space-separated text string for Kernel purposes that needs to be added to this channel.
        • delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.
      • scope: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:
        • add: space-separated text string with the Kernel scopes that need to be added to this channel.
        • delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.
    • dialogs: array of dialogs whose configuration is going to change within the library. Each object in this array will contain:
      • id: identifier of the dialog whose configuration you want to modify.
      • authorization: object with the modifications in the Kernel purposes and scopes to perform for this library:
        • purposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:
          • add: space-separated text string for Kernel purposes that needs to be added to this channel.
          • delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.
        • scope: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:
          • add: space-separated text string with the Kernel scopes that need to be added to this channel.
          • delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.
      • triggerConditions: array of dialog start conditions. Each object in this array will contain:
        • intent: intent that will launch the dialog.
        • settings: object with the dialog settings.
        • contextFilters: array with the user context validation and channel to launch the use case. This array will carry the FULL LIST of contextFilters from the dialog for the channel. The contextFilters array of each dialog will be populated with the information that comes in this file.
      • suggestions: boolean that determines if the main dialog will execute the suggestions dialog.

Running the Aura configuration updater script multiple times with the same changes-bot-response.json file will not cause data to be duplicated. The information in dialogLibraries field will be overridden and the list of purposes and scopes will be unique (no duplication).

Example of changes-bot-response.json file

{
    "version": "1.0",
    "channels": [
        {
            "channelId": "45494a5b-835a-4fff-a813-b3d2be529dbe",
            "fpaAuthPurposes": {
                "add": "mi-purpose",
                "delete": "aura-technical-problems-purpose"
            },
            "fpaAuthScopes":  {
                "add": "mi-scope"
            },
            "dialogLibraries": [
                {
                    "name": "bill",
                    "authorization": {
                        "scopes": {
                            "add": "mi-lib-scope"
                        }
                    },
                    "dialogs": [
                        {
                            "id": "balance-check",
                            "authorization": {
                                "purposes": {
                                    "add": "aura-technical-problems-purpose",
                                    "delete": "customer-self-service"
                                },
                                "scopes": {
                                    "delete": "mobile-balance-read"
                                }
                            },
                            "triggerConditions": [
                                {
                                    "intent": "intent.balance.check",
                                    "contextFilters": [
                                        {
                                            "name": "Anonymous redirect to linking",
                                            "type": "type",
                                            "conditions": "/type eq 'anonymous'",
                                            "true": {
                                                "name": "Anonymous redirect to linking",
                                                "breakDialogExecution": true,
                                                "breakFilterEval": true,
                                                "redirectToIntent": "intent.account.linking"
                                            }
                                        }
                                    ]
                                }
                            ],
                            "suggestions": false
                        }
                    ]
                }
            ]
        }
    ]
}

File changes locale format (changes-locale-es-es.json)

It is a JSON object with a version and the text resources that you want to change with the same format as the aura-bot, as it is obtained from PoEditor with aura-locale-importer.

  • If a text resource (common:common.error.main) already existed, it will be replaced by the one in the changelog.
  • If a text resource (my:mi.es-es.locale.uno) does not exist, it will be added to the locales file.

Example of changes-locale-es-es.json

{
    "version": "1.0",
    "common:common.error.main": [
        "Ein unerwarteter Fehler ist aufgetreten. Bitte versuche es erneut"
    ],
    "common:common.goodbyes.main": [
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen.",
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen.",
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen."
    ],
    "mi:mi.es-es.locale.uno": [
        "Mi locale uno",
        "Mi locale 1",
        "Mi locale primero"
    ]
}
Last modified May 18, 2026: Remove KGB (52b04d91)