contact-flow-parser for Amazon Connect

Managing Amazon Connect contact flows across multiple environments requires some planning. In this post, I'd like to share a utility script that can help streamlining this process by automatically parameterizing the AWS Resource Numbers (ARNs) in your contact flows.

The challenge

A contact flow can be exported both via the Amazon Connect admin interface and via the Amazon Connect API. However, your contact flow will most of the times, if not always, have references to ARNs of some other resources, like queues, prompts, Amazon Lex bots and many more. When you import the contact flow into the destination instance, you will need to replace the ARNs to the corresponding ones that are accessible from there.

In case you are looking to set up a proper CI/CD pipeline, there is a great workshop that can be used to get some inspiration. However, some times you just need to quickly export a contact flow, import it somewhere else, and get done with it. When done manually, the process can be tedious and error prone.

Introducing contact-flow-parser

The contact-flow-parser tool addresses this problem by:

Parsing Amazon Connect contact flow JSON files
Automatically identifying all ARN references
Converting them into parameters
Generating a parametrized output in one of the following formats
1. A parametrized JSON file, where all ARNs are replaced by placeholder, in mustache format, so that they can easily remapped via search and replace
2. A Cloud Formation template (either a full template or a Cloud Formation resource that you can add to an existing template), where all ARNs are passed as parameters

Key benefits

Time savings: What used to take minutes now can happen in a few seconds. When the activity is repeated multiple times, this can lead to consistent time saving.
Error prevention: Eliminates the risk of missing or incorrect ARN updates
Infrastructure as Code: Seamlessly integrate contact flows into your CloudFormation stacks
Version control friendly: Better diff comparisons when ARNs are parameterized

How to deploy contact-flow-parser

The following will guide you through how to deploy contact-flow-parser

Prerequisites

Contact flow parser is written in Python, and make use of these packages, which you will need to install, using your package manager of choice:

chevron is used to map to and from the mustache format
ruamel.yaml is used to generate properly formatted CloudFormation templates

Installing contact-flow-parser

Create all the following files in the same directory

main.py

arn-map.json

cloudformation-resource.yaml.mustache

cloudformation-template.yaml.mustache

How to use it

Invoke the script with -h option to get help on the supported syntax

Usage examples

Let’s assume that you create a contact flow that simply routes incoming contacts to BasicQueue call and that you have exported the contact flow from the Amazon Connect administrator interface and saved it into the input_flow.json file.

You can invoke contact-flow-parser as follow to generate an output-flow.yaml file containing a full CloudFrormation template.

output-flow.yaml will look as follows. The actual contact flow content is omitted here for sake of brevity, and replaced with LONG CONTACT FLOW JSON WILL BE HERE.

When deploying this CloudFormation template, you will need to provide three paremeters. The first two will always be present, for any input contact flow. The remaining parameter(s) are based on the actual content of the contact flow:

InstanceArn: ARN of the Amazon Connect instance where you want to deploy this contact flow
ContactFlowName: the name you want to use for the contact flow
BasicQueue: the ARN of the queue to use in the destination instance

Alternatively, you can use the following syntax to only generate a single CloudFormation resource. You can then copy this resource into an existing CloudFormation template.

output-flow.yaml will look as follows. The parameters are now included between double curly brackets. You will need to replace these with actual values, or the name of CloudFormation parameters or resources.

How does it work

contact-flow-parser parses the contact flow JSON and looks for any ARN reference in the flow actions. Once an ARN is found, it needs to find a name for the parameter it is going to generate. In order to find the name, it looks into the contact flow metadata section. meta

The arn-map.json file contains mapping between:

a regular expression to match the ARN,
the corresponding resource type
the path in the contact flow metadata where the name of the resource will be found
optionally, a regular expression to apply to the name found at the metadata path

At the moment, arn-map.json contains mapping for queues, prompts and Lex bots, but can easily be expanded as needed.

If contact-flow-parser founds an ARN for which it knows no mapping, an error is thrown. An additional error is thrown if the mapping is found, but not item is found at the metadata path identified by the map.

Once contact-flow-parser has found a parameter name for all the ARNs included in the contact flow JSON, it generates an output depending on the format requested.

Conclusions and what’s next

contact-flow-parser can significantly simplify the management of Amazon Connect contact flows across environments. Over the coming months, I am looking to expand the supported mapping, and work on a reference architecture to automatically run the script whenever a contact flow is saved (or published), and export the parametrized version. If you find this useful and would like to see more resource types supported, or if you have any other suggestion for improvement, please reach out to gvegetti@amazon.it.

Remember to follow AWS best practices for parameter management and always test the parameterized flows in a non-production environment before running it in production.

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Site Terms, Privacy, and more.