Pipelines

Appearance

Introduction ​

This repository contains a tool for migrating resources from one Amazon Connect instance to another. Amazon Connect does not provide an out-of-the-box solution for migrating resources between instances, so this tool aims to fill that gap.

WARNING

This tool does not support the migration of Phone Numbers and Outbound Caller IDs in Queues. These resources need to be manually configured in the target Amazon Connect instance.

Please see the Supported Resources section for more.

Pre-requisites ​

Before using this tool, ensure that you have the following:

  • Node.js (version 20.11.1 or higher)
  • npm (Node Package Manager)
  • AWS account with appropriate permissions to access the source and target Connect instances

Configuration ​

using .env ​

Before running the migration tool, you need to set up the following environment variables on your local:

  • SOURCE_AWS_ACCESS_KEY_ID: Access key ID for the source AWS account.
  • SOURCE_AWS_SECRET_ACCESS_KEY: Secret access key for the source AWS account.
  • SOURCE_AWS_SESSION_TOKEN: Session token for the source AWS account (optional).
  • SOURCE_AWS_REGION: AWS region of the source Connect instance.
  • SOURCE_INSTANCE_ARN: Instance ID of the source Connect instance.
  • DEST_AWS_ACCESS_KEY_ID: Access key ID for the target AWS account.
  • DEST_AWS_SECRET_ACCESS_KEY: Secret access key for the target AWS account.
  • DEST_AWS_SESSION_TOKEN: Session token for the target AWS account (optional).
  • DEST_AWS_REGION: AWS region of the target Connect instance.
  • DEST_INSTANCE_ARN: Instance ID of the target Connect instance (optional).
  • CUSTOMER_IDENTIFIER: Customer Identifier to enable the tool validation (optional).

If DEST_INSTANCE_ARN is not provided, the tool will create a new instance in the target AWS account.

using env.json ​

We can also use a env.json file to store multiple envs; its format is. Here the VT_DEMO_TO_PROD is the profile name and this can be invoked using the below command as well

bash
node vcx.mjs generate --profile=VT_DEMO_TO_PROD
node vcx.mjs migrate --profile=VT_DEMO_TO_PROD
json
{
  "VT_DEMO_TO_PROD": {
    "source": {
      "AWS_ACCESS_KEY_ID": "",
      "AWS_SECRET_ACCESS_KEY": "",
      "AWS_SESSION_TOKEN": "",
      "INSTANCE_ARN": "",
      "AWS_REGION": "us-east-1"
    },
    "target": {
      "AWS_ACCESS_KEY_ID": "",
      "AWS_SECRET_ACCESS_KEY": "",
      "AWS_SESSION_TOKEN": "",
      "AWS_REGION": "",
      "INSTANCE_ARN": ""
    },
    "CUSTOMER_IDENTIFIER": "xxxxxxxxxxxxxx" // Optional
  }
}

Customer Identifier Validation ​

Before running the migration tool, you can set the CUSTOMER_IDENTIFIER environment variable if you want to use this validation. This identifier will be used to validate permissions for the migration.

Setting Up the Environment Variable ​

Add the following line to your .env.json file or set it in your environment .env:

bash
CUSTOMER_IDENTIFIER="xxxxxxxxxxxxxx"

The tool will error out during both the Generate and Migrate steps if the validation fails. Ensure that the CUSTOMER_IDENTIFIER is set correctly and that the account permissions are valid before proceeding with the migration.

Usage ​

  1. Fetch the data for all AWS Connect resources from the source instance:
bash
node vcx.mjs generate

This command will retrieve the data for all supported resources from the source Connect instance and save it to a output/${profileName || default}.json file.

  1. Migrate the resources to the target instance:
bash
node vcx.mjs migrate

This command will create or update the resources in the target Connect instance based on the data fetched from the source instance.

config.json ​

The config.json file is used to control the migration process. It is located in the root of the project and is named config.json.

Also you can pass --config flag to specify the path to the config.json file if you want to use a custom config.json file.

bash
node vcx.mjs migrate --config=./path/to/config.json

example of config.json file:

json
{
  "lambda": false,
  "lex": false,
  "queues": true,
  "routing_profiles": true,
  "security_profiles": true,
  "source_flows_to_skip": ["flowArn1", "flowArn2"],
}

Selective Migration ​

You can control which resources to migrate by specifying them in the config.json when running the migrate command:

bash
node vcx.mjs migrate --profile VT_DEMO_TO_PROD

Supported Resources ​

The following resources can be specified:

  • resources - Resources to migrate (Object)
    • lambda - Lambda Functions (Boolean)
    • lex - Lex Bots (Boolean)
    • queues - Queues (Boolean)
    • routing_profiles - Routing Profiles (Boolean)
    • security_profiles - Security Profiles (Boolean)
    • hours_of_operation - Hours of Operation (Boolean)
    • user_hierarchies - User Hierarchies (Boolean)
    • users - Users (Boolean)
    • contact_flows - Contact Flows (Boolean)
    • quick_connects - Quick Connects (Boolean)
    • views - Views (Boolean)
    • flow_modules - Contact Flow Modules (Boolean)
    • prompts - Prompts (Boolean)
    • agent_statuses - Agent Statuses (Boolean)
    • quick_responses - Quick Responses (Boolean)
    • evaluation_forms - Evaluation Forms (Boolean)
    • rules - Rules (Boolean)
    • cases - Connect Cases (Boolean)
  • force_update_modified_hoos - Force Update Modified Hours of Operation (Boolean)
  • force_update_modified_prompts - Force Update Modified Prompts (Boolean)
  • force_update_modified_queues - Force Update Modified Queues (Boolean)
  • force_update_modified_quick_connects - Force Update Modified Quick Connects (Boolean)
  • force_update_modified_routing_profiles - Force Update Modified Routing Profiles (Boolean)
  • force_update_modified_security_profiles - Force Update Modified Security Profiles (Boolean)
  • force_update_modified_users - Force Update Modified Users (Boolean)
  • force_update_modified_user_hierarchies - Force Update Modified User Hierarchies (Boolean)
  • force_update_modified_flows - Force Update Modified Contact Flows (Boolean)
  • force_update_modified_agent_statuses - Force Update Modified Agent Statuses (Boolean)
  • force_update_modified_flow_modules - Force Update Modified Contact Flow Modules (Boolean)
  • force_update_modified_quick_responses - Force Update Modified Quick Responses (Boolean)
  • force_update_modified_views - Force Update Modified Views (Boolean)
  • force_update_modified_case_fields - Force Update Modified Connect Case Fields (Boolean)
  • force_update_modified_case_layouts - Force Update Modified Connect Case Layouts (Boolean)
  • force_update_modified_case_templates - Force Update Modified Connect Case Templates (Boolean)
  • force_update_modified_case_rules - Force Update Modified Connect Case Rules/Field Conditions (Boolean)
  • skip_flow_modules_diff_check - Skip the diff check for Contact Flow Modules (Boolean)
  • assets_storage_bucket_name - Name of the S3 bucket to store assets (String)
  • assets_storage_bucket_prefix - Prefix for the S3 bucket to store assets (String)
  • force_add_override_tags - Force add the override tags (Boolean)
  • tags_override - Override tags (Object)
  • ignored_resources - Ignore resources (Object) check the ignored_resources section for more information.
  • export_lex_bots_concurrency - No of lex bots to export in parallel
  • use_assets_storage_bucket_for_lex_bots - Use the asset bucket for storage if true, Else create one for lex bots.

Note: If a resource is not specified in the config.json file, it will be skipped.

Note: If the assets_storage_bucket_name and assets_storage_bucket_prefix are not provided, the tool will not migrate assets. For more information on how to setup the assets_storage_bucket_name and assets_storage_bucket_prefix, please refer to the Assets Storage Bucket section.

Additional Migration Options ​

  • --exclude-disabled-resources: Exclude disabled resources from migration
  • -p, --profile: Specify the profile to use (If not provided, it will use the CLI mode)
  • --export-csv: Export a CSV report of the migration

Additional Generate Options ​

  • -p, --profile: Specify the profile to use (If not provided, it will use the CLI mode)
  • --export-lex-bots: Export Lex bots (Boolean)
  • --export-target-resources: Export target resources (Boolean)

Example with multiple options:

bash
node vcx.mjs generate \
  --profile VT_DEMO_TO_PROD \
  --export-lex-bots true \
  --export-target-resources true \

Resource Modification Tracking ​

The tool tracks modifications to resources using the vcxUpdatedAt tag. This prevents overwriting resources that have been modified in the target environment after the last deployment.

For each supported resource, you can configure:

  • Whether to skip the resource
  • Whether to force update modified resources

Supported Resources and Configuration ​

The following resources can be configured to support the Modification Tracking feature:

  • Hours of Operation
  • Prompts
  • Queues
  • Quick Connects
  • Routing Profiles
  • Security Profiles
  • Users
  • User Hierarchies
  • Contact Flows
  • Agent Statuses
  • Flow Modules
  • Quick Responses
  • Views
  • Connect Case Fields
  • Connect Case Layouts
  • Connect Case Templates
  • Connect Case Field Conditions/Rules

For more information on how to force update these resources, please refer to the Selective Migration Documentation.

VCX Diff ​

VCX Diff is a built-in tool that helps you compare Amazon Connect resources between instances. Currently, it supports the comparison of Contact Flows and Flow Modules only.

Usage ​

bash
node vcx.mjs diff --profile=VT_DEMO_TO_PROD --export-diff true/false --view-diff true/false

The diff command will:

  1. Fetch resources from both source and destination instances
  2. Normalize the content for comparison
  3. Generate a detailed diff report highlighting changes
  4. Display missing or additional resources in either environment
  5. Export the diff report to a CSV file if the --export-csv flag is set to true
  6. Display the diff report in the console if the --view-diff flag is set to true

Diff additional options in config.json ​

  • include_disabled_resources: Include the disabled resources in the selective config. This would be used if you want to capture the diff for all supported resources (Boolean)
  • ignore_destination_only_resources: Ignore destination only resources (Boolean). This will ignore the resources that exist in the destination but not in the source.
json
{
  "diff": {
    "include_disabled_resources": true/false,
    "ignore_destination_only_resources": true/false,
  }
}

Resource Validation ​

Contact Flow and Module Validation ​

The tool automatically validates all referenced resources within Contact Flows and Contact Flow Modules to ensure they exist in the source instance. This includes:

  • Queues
  • Prompts
  • Hours of Operation
  • Contact Flows
  • Contact Flow Modules
  • Lex Bots and Aliases
  • Views

The validation checks:

  • Resource existence in source instance
  • Account ID matches
  • Instance ID matches

If any validation fails, detailed error messages are provided indicating:

  • Error type
  • Resource type
  • Resource ARN
  • Flow/Module ID and name
  • Specific error message

Resource Map ​

The Resource Map is a built-in tool that helps you map custom resources between instances. Which does not exits in source but exists in destination only. You need to use config.json to specify the Resource Map.

Supported Resources ​

  • Lex
    • If you specify the Lex Resource Map, the tool will use it to map the Lex aliases between instances. And it will skip the Lex validation.
  • Phone Numbers
  • Lambda
  • Qin Connect

Example Resource Map ​

json
{
  "resource_map": {
    "lex": {
      "arn:aws:lex:us-east-1:123456789012:bot-alias/bot_id/MyBotAlias": "arn:aws:lex:us-east-2:123456789012:bot-alias/bot_id/MyBotAlias"
    },
    "phone_numbers": {
      "SOURCE_ARN": "TARGET_ARN"
    },
    "lambda": {
      "SOURCE_ARN": "TARGET_ARN"
    },
    "q_connect": {
      "SOURCE_ARN": "TARGET_ARN"
    }
  }
}

Tags Override ​

Tags override can be used to override the tags of the resources. There are two ways to use tags override:

  1. Using the tags_override field in the config.json file.
  • In this case the tool will check for the tags in the source resource and if it finds any it will add the of override that tag to the target resource.
  1. Using the force_add_override_tags field in the config.json file.
  • In this case the tool will always add the override tags to the target resource.

The tool supports tags override for the following resources:

  • Queues
  • Routing Profiles
  • Security Profiles
  • Hours of Operation
  • User Hierarchies
  • Users
  • Contact Flows
  • Contact Flow Modules
  • Prompts
  • Quick Connects
  • Views
  • Flow Modules
  • Quick Responses
  • Agent Statuses
  • Cases

Assets Storage Bucket ​

The tool supports the migration of prompts and any other assets which requires a S3 bucket. You need to provide the assets_storage_bucket_name and assets_storage_bucket_prefix in the config.json file.

Important Requirements ​

  1. Region Compatibility: The S3 bucket must be in the same AWS region as the destination Amazon Connect instance.

  2. Bucket Policy: You need to configure the appropriate permissions on your S3 bucket to allow the migration tool to access it. Below is a sample bucket policy:

json
{
    "Version": "2012-10-17",
    "Id": "ConnectMigrationBucketPolicy",
    "Statement": [
        {
            "Sid": "AllowConnectAccess",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::target-account-id:root"
            },
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/your-prefix/*"
            ]
        }
    ]
}

Replace target-account-id with your destination AWS account ID, your-bucket-name with your S3 assets bucket name, and your-prefix with the prefix you specified in the configuration.

Configuration Example ​

In your config.json file:

json
{
  "assets_storage_bucket_name": "your-connect-migration-bucket",
  "assets_storage_bucket_prefix": "vcx"
}

This configuration will store and retrieve prompt files or any other assets from the specified S3 bucket path during migration.

Ignored Resources ​

The tool supports the ability to ignore resources during the migration process. This is useful when you want to skip certain resources that are not needed to be migrated.

Note: The ignored resources configuration is also respected in the VCX Diff.

Supported Resources ​

  • Queues
  • Quick Connect
  • Contact Flows
  • Flow Modules
  • Hours of operations

Example Configuration ​

json
{
   "ignored_resources":{
    "source":{
      "flows": ["ID"],
      "flow_modules": ["ID"],
      "queues": ["ID"],
      "quick_connects": ["ID"],
      "hoops": ["ID"]

    },
    "target":{
      "flows": ["ID"],
      "flow_modules": ["ID"],
      "queues": ["ID"],
      "quick_connects": ["ID"],
      "hoops": ["ID"]

    }
  }
}