Create and update agents in bulk with Amazon Connect

Contact center managers must often add and remove agents quickly, or manage agents as a group. The ability to do so efficiently and in bulk is essential to the timely management of contact center agents. Amazon Connect currently offers methods to perform bulk user (agent) creation and bulk user updates within the User Management functions of the Amazon Connect console. Utilizing the tools described here, contact center managers will now be able to manage currently supported agent settings in bulk, as well as those previously not able to be changed in bulk. The intent of the user creation and update tools described in this blog is to provide an efficient way to perform these bulk operations using a spreadsheet and the Amazon Connect API. This adds the ability to set user hierarchy at agent creation time, and later manage user hierarchy and soft or desk phone settings.

The creation and update tools shown here work independently of each other. It is not required to use the creation tool before using the update tool. These tools are set up as AWS Lambda functions via an AWS CloudFormation template.

Prerequisites

The solution presented in this blog has the following prerequisites:

• An AWS account
• Basic knowledge of AWS, Amazon S3, Amazon Connect, and AWS Lambda
• An Amazon Connect instance

Solution overview

This solution is a simple utility to enable creation or update of users in Amazon Connect using API operations. CSV (Excel) files containing data (one row per agent) are uploaded to an Amazon S3 bucket. Upon upload of a CSV file, the associated AWS Lambda functions are triggered to process the file. API calls are throttled to run every 600 ms to avoid hitting the API throttling limit for Amazon Connect (currently two requests per second). If any operations fail, they are retried multiple times and then written out to a failure file in the same S3 bucket for future review. The number of times to retry is specified as a parameter when setting up the CloudFormation stack.

All resources are created using a CloudFormation stack. The Lambda functions are written in Python, compatible with Python 3.8.

Setting up the Solution

In an effort to create a repeatable and automated deployment process, the solution is deployed using an AWS CloudFormation template. The following steps detail how to launch the stack within an AWS account.

1. Log in to your AWS Management Console.
2. Confirm that the AWS Region selected has the Amazon Connect service available.
3. Click the following Launch Stack and begin the CloudFormation stack creation process. Note, this stack uses a template and source code bucket in us-west-2. For other Regions, download code and launch the CloudFormation stack manually.  
4. On the AWS CloudFormation page, modify the stack name if desired. Keep the other options as default. Note that if you do change the stack name, the text in this document referencing createUpdateStack will be inaccurate.
5. On the same page, provide the requested parameters necessary for the deployment. Specify the AmazonConnectARN of the instance you want to use for the creation and update operations. The ARN is found in the AWS Management Console page for the Amazon Connect instance (not the Amazon Connect console itself). See the Amazon Connect Admin Guide for more information on how to locate the ARN.
6. Specify UserManagementS3BucketName for the S3 bucket to be created by the AWS CloudFormation template for use by the tool.
7. Specify NumberOfRetries for the number of times a record will be retried before it is written to the failure file.
8. Read, review, and check the Capabilities and Transforms acknowledgments.
   
9. Choose Create stack to begin the stack creation operation.

Using the tools

To utilize the creation or update tools, follow the instructions for Creation and Update, respectively.

Creation tool

1. Download the example template. Template is the same for both non-SSO and SSO Amazon Connect instances.
   
2. Fill in the data for each agent to be created, with one agent per row. For multiple security profiles, use the syntax Profile1|Profile2 (such as Agent|CallCenterManager). For nested user hierarchies, use the format Level1/Level2/Level3 (such as technical support/US/Eastern).
   

   NOTE: Security profiles, routing profile names, and agent hierarchy names must match those already created within the Amazon Connect instance. Desk phone numbers must be valid and in E.164 format. For instances using single sign-on, keep the column headers for email address and password but do not populate those fields for SSO users.

3. After the .csv data is filled out, upload the file to the create folder of the S3 bucket created via the CloudFormation stack creation in the previous steps.
4. Uploading the file triggers the Creation Tool Lambda function to read the file and update the users. When complete, the file is renamed with the date, time, and .bak added to the file name.
5. Once the triggered AWS Lambda function is complete, the users from the uploaded .csv file are visible in the Amazon Connect User Management interface.
   
6. If any user creations fail, they are written to a file in the failed folder of the same S3 bucket called failedActions-<dateTime>.csv.bak.

Update tool

The Update process is essentially the same as the Creation process previously discussed. To update existing users, utilize the same CSV template and input the data to be updated in the respective columns. Users do not have to be created using the Creation tool to be updated via the Update tool – any existing Amazon Connect user will work.

1. Download the example template. Template is the same for both non-SSO and SSO Amazon Connect instances.
   
2. Fill in the data for each agent to be updated, with one agent per row. User login must remain unique and is the key by which the tool matches existing users. For multiple security profiles, use the syntax Profile1|Profile2 (such as Agent|CallCenterManager). For nested user hierarchies, use the format Level1/Level2/Level3 (such as technical support/US/Eastern). Although keeping the password column in the template keeps the template consistent, the API does not allow update of passwords or user names via the API.
   

   NOTE: User login, security profiles, routing profile names, and agent hierarchy names must match those already created within the Amazon Connect instance. Desk phone numbers must be valid. For instances using single sign-on, keep the column headers for email address and password but do not populate those fields for SSO users.

   NOTE: There is a known issue when removing user hierarchies from a user via the Python SDK (which is used in this blog). After this issue is resolved, this tool will allow removal of user hierarchies. Modification of user hierarchies is not affected and will still work via this tool.

3. After the .csv data is updated, upload the file to the update folder of the S3 bucket created with the CloudFormation stack creation in the previous steps.
4. Uploading the file triggers the Update Tool Lambda function to read the file and update the users. When complete, the file is renamed with the date, time, and .bak added to the file name.
5. After the triggered AWS Lambda function is complete, the updates to the users from the uploaded .csv file are visible in the Amazon Connect User Management interface.
6. If any user updates fail, they are written to a file in the failed folder of the same S3 bucket called failedActions-<dateTime>.csv.bak.

Reporting and recovering from failures

To ensure that any failures are captured and reported, the tool deposits a .csv.bak file in the failed folder of the same working S3 bucket. To review any failures, the file can be read and cross-referenced with Amazon CloudWatch to view detailed errors from the Lambda error logs. This file is formatted in such a way that after any issues are corrected, it can be dropped back into the create or update folder immediately to re-process those records.

1. To review the reason for the failures found in the failed actions file, navigate to Amazon CloudWatch via the AWS Management Console.
2. Select Log Groups
3. Select the associated Lambda function created during the CloudFormation stack process earlier in this blog.
   

   NOTE: The Lambda function names are prefixed with the name of the CloudFormation stack.

4. Select the desired log group and find the entries corresponding to the time the operation was run. Each failure, including failures from retry attempts, is visible in the log entries.
   

Cleaning up

To avoid incurring future charges, empty the S3 bucket created as part of this solution. Then, remove all created resources by deleting the CloudFormation stack.

Conclusion

In order for a contact center to remain nimble and agile in its user management, quick adjustments to users are essential. This blog has detailed two new tools to aid contact center managers in their day to day task of creating and updating users in Amazon Connect in bulk. With these tools, settings like user hierarchy or soft and desk phone settings become easily managed and maintained right alongside all other agent settings using a spreadsheet and the Amazon Connect API.