Managing user hierarchy with a new API in Amazon Connect

Customers have had to create and maintain their agent hierarchy structure manually in Amazon Connect and keep it in sync with their internal systems of record. Every time an agent was added or removed or changed the department or location they worked at, their hierarchy settings needed to be manually changed in Connect. This was time consuming and error prone for contact centers with thousands of agents.

Amazon Connect now provides an API to programmatically create and manage user hierarchies. With APIs, customers can decrease the time it takes to onboard new agents and make configuration changes, increasing their pace of innovation now that they can manage hundreds / thousands of agents and their hierarchies through APIs. User hierarchies are a way for you to organize users into groups such as what location they work in or which department they are a part of. With new API, you can now programmatically mirror your organization’s hierarchy in Amazon Connect as changes are made in your internal systems of record, such as HR systems. Additionally, you can extract all hierarchy and agent data as a point-in-time snapshot and copy it into a different instance.

In this blog you will examine Amazon Connect’s full set of capabilities to create, read (describe), update, and delete agent hierarchies via API. You can use these APIs within your existing solutions, or explore them through an Art of the Possible User Interface (UI) by following the steps detailed here.

Services used

• Amazon Connect
• AWS CloudFormation
• Amazon CloudFront
• AWS IAM
• Amazon S3

Overview of solution

This solution uses an AWS CloudFormation template, which creates a S3 bucket and loads all the assets into CloudFront for this solution. As a user, you use the CloudFront URL to view the website to test different scenarios, including changing the user hierarchy configuration or creating a new user hierarchy.

Prerequisites

For this walkthrough, you should have the following prerequisites:

• An AWS account
• An existing Amazon Connect instance
• Access to AWS services
  • AWS IAM with access to create policies and roles
  • Amazon CloudFront with access to create a distribution
  • Amazon S3 with access to create buckets
  • AWS CloudFormation to run the stack
• AWS IAM access key and secret access key credentials to access your instance user hierarchy using the API’s

Deploy the solution

Note: The CloudFormation template will deploy resources in the US West (Oregon) Region.

To deploy in other regions, download the solution from this GitHub repository: https://github.com/aws-samples/ac-userhierarchyapi

Overview of the steps

• Create the CloudFormation stack
• Access the CloudFront web UI to access the portal
• Configure the AWS credentials to manage the user hierarchies of an Amazon Connect instance
• Get all the user hierarchies in an instance
• Test and validate the solution by performing actions on user hierarchies of an Amazon Connect instance

CloudFormation deployment:

1. 1. Sign in to the AWS Management Console in the US West (Oregon) region.
   2. Launch the CloudFormation template here:
   3. Enter the stack name (e.g. userhierarchyapi-blog). The stack name must be unique.
   4. Enter a globally unique name for a new S3 bucket. The template creates and stores all the assets that are required for the website you access through the Amazon CloudFront URL.

1. Check the box for “I acknowledge that AWS CloudFormation might create IAM resources.”
2. Choose Create Stack.
3. The AWS CloudFormation template may take 15-30 minutes to create all the resources. Once done, it will show the status as “CREATE_COMPLETE”. It may take another 15-20 min for Amazon CloudFront to complete its deployment of the website assets after the status changes to “CREATE_COMPLETE”.

Launch the Amazon Connect User Hierarchy APIs user interface website

1. 1. Open the AWS CloudFormation service in the AWS Management Console and choose the stack that you just created.
   2. Go to the Outputs section of the newly created stack, and copy the CloudFrontEndpoint URL from the Value column

1. 1. Open the URL in a new browser tab or window to navigate to the Amazon Connect User Hierarchy website. You will see the options to list all existing user hierarchies, create a new user hierarchy, modify an existing hierarchy, or describe a hierarchy in JSON format.
   2. Enter the AWS IAM Access Key and Secret Key for your user.
   3. Enter the Region and Instance ID of your Amazon Connect instance.
   4. Choose Save Configurations.

1. 1. Refresh the page by selecting the refresh button in the browser.
   2. When the page loads, observe all of the user hierarchy structures that are configured in your Amazon Connect instance.

Management of user hierarchy structure

User hierarchy structure provides the skeleton of the way the hierarchies are organized. To define the hierarchy structure:

1. 1. Select Manage user hierarchy structure to load the existing hierarchy structure that you have defined in your instance. This operation uses the DescribeUserHierarchyStructure API.
   2. Enter up to 5 levels of hierarchy structure.
   3. Choose Save user hierarchy structure. This saves the structure details of your hierarchy using the UpdateUserHierarchyStructure API.

Create user hierarchy groups

1. 1. Choose All user hierarchy groups to retrieve all the user hierarchy groups defined in your instance using the ListUserHierarchyGroups and DescribeUserHierarchyGroup APIs.

1. 1. Choose Add {hierarchy structure in different levels} (in the example above, it appears as Add Planet). This brings up a pop up to enter the new hierarchy group name.

1. Choose Add hierarchy. This will add a new hierarchy group under the current hierarchy structure that you are navigating using the CreateUserHierarchyGroup API.

Rename a hierarchy group

1. Choose Rename next to the desired hierarchy group name.
2. Enter the new name.
3. Choose Rename hierarchy button, that will rename the hierarchy group by using the UpdateUserHierarchyGroupName API.

Delete a hierarchy group

1. 1. Choose Delete next to the desired hierarchy group name.
   2. Choose Yes to confirm deletion. The hierarchy group is deleted using the DeleteUserHierarchyGroup API.

Cleaning up

To avoid incurring future charges, remove all created resources by deleting the AWS CloudFormation stack.

Conclusion

This post demonstrated how to use Amazon Connect’s new user hierarchy APIs to manage user hierarchies in an Amazon Connect instance, using the new APIs you can now programmatically assign your agents to the right hierarchy depending on the location or other changing conditions. You learned how to perform the following functions programmatically through the web UI:

• List all user hierarchy structures and groups in an Amazon Connect instance
• Create and modify a user hierarchy, including adding, deleting, and modifying hierarchy structure
• Create and modify a user hierarchy, including adding, deleting, and modifying user hierarchies

To learn more about how this solution was built and see how the APIs were executed, refer to the GitHub repo.

Related links

To learn more about the technologies or features used to create this solution, see the following:

• Amazon Connect
• Amazon CloudFormation
• Amazon S3
• Amazon CloudFront
• AWS-SDK