Programmatically search for users using an API in Amazon Connect

User management is a critical component of a contact center. Typical use cases include creating and updating user profiles. However, another significant use case is searching for and reporting on these users based on unique characteristics such as their profiles or tags.

Amazon Connect now provides an API using which customers can search for contact center users based on their first name, last name, user name, routing profiles, security profiles, user hierarchy and tags.

In this blog post, we will walk you through different scenarios and use cases that can be leveraged to search users in Amazon Connect via an API. You can use these examples as an extension in your existing solutions or modify them based on your specific needs. In this post, an ‘art of the possible’, sample web user interface (UI) is used to trigger the functions and different search results. In your scenario, this web UI can easily be replaced with the in-house application or front-end utilities that need to invoke the API.

Overview of solution

This solution will be deployed using an AWS CloudFormation template. It creates an Amazon S3 bucket and loads all the assets into Amazon CloudFront. As a user, you use the Amazon CloudFront URL to view the web interface UI mentioned earlier. Based on the filters you apply; this UI will trigger the search API in Amazon Connect to deliver appropriate results.

This post will cover the following search categories in detail:

• First name, last name, user name of the users
• Routing profiles, security profiles, agent hierarchy of the users
• Tags assigned to the users
• AND/OR conditions across categories
• AWS Identity and Access Management (IAM) policy to restrict the user profile output (Summary vs Full)

Note:

This is a sample project designed to be easily deployable for experimentation. The IAM policy permissions use least privilege, however the Amazon CloudFront and Amazon API Gateway resources deployed will be publicly accessible. Please take the appropriate measures to secure your Cloudfront distribution and API Gateway following as required.

Prerequisites

For this walkthrough, it is assumed that you understand and have the following resources:

• An AWS account
• An existing Amazon Connect instance
• 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
• Amazon Cognito to create users in order to access and execute the Amazon Connect search API functions

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.

Overview of the steps:

1. Deploy the CloudFormation stack
2. Create users within the Amazon Connect instance to test with
3. Add users in Amazon  and launch the CloudFront web UI
4. Test the solution and search for users based on the different scenarios

A. CloudFormation deployment

1. Log in to the AWS Management Console in the US West (Oregon) region.
2. Click on the Launch Stack button below to create a stack
3. Enter a unique Stack name (e.g. search-user-api).
4. Under Amazon S3 configuration (e.g. search-user-api-blog-XXX), enter a globally unique name for a new S3 bucket that will be created. This bucket will store all the assets that are required for the web UI you access through the Amazon CloudFront URL.
5.  Check the box for “I acknowledge that AWS CloudFormation might create IAM resources.”
6. Choose Create Stack.
7. The AWS CloudFormation template may take 15-30 minutes to create all the resources. Once done, it will show the status as “CREATE_COMPLETE”.
8. It may take another 15-20 minutes for Amazon CloudFront to complete its deployment of the website assets after the status changes to “CREATE_COMPLETE”.

B. Create users in your Amazon Connect instance

1. Create agent hierarchy with five different levels such as Earth/North America/USA/California or you could use an example of your choice.
2. Create two Amazon Connect routing profiles of choice. You can use the existing ‘Basic routing profile’ and create another one of choice such as ‘Technical Support’
3. Create four users of your choice assigning each of them a different routing profile amongst the two created earlier and a different agent hierarchy as well.
4. Ensure that each user has a different security profile too such as admin, agent etc. A snapshot of a sample configuration is as below:

C. Launch the CloudFront web UI and Add users to Amazon Cognito

1. Log into Amazon Cognito and click the ‘user pool’ that starts with the {cloudformation-stack-name}-blog-user-pool
2. Choose Create user on the bottom right.
3. Choose Send an email invitation or Send an SMS invitation or Send both email and SMS invitation depending on your choice. In our post, we will choose Send an email invitation.
4. Enter User name and valid Email address on which you shall receive an email.
5. Choose Set a password under Temporary password and enter 8 character(s) or digit(s) or combination of both.
6. Choose Create user on the bottom left.
7. You will receive an email with username and temporary password that you entered with subject “Your temporary password”. If you don’t see in your inbox, check in your junk folder.
8. Log in to you AWS Management Console and navigate to AWS CloudFormation by typing the service name in the search bar.
9. Select the stack you just created.
10. Go to the Outputs section of the newly created stack. Copy the CloudFrontEndpoint url from the Value column.
11. Paste the URL in a new web browser tab /window to navigate to the CloudFront web UI.
12. You will need to enter the username and password that you received in the email and click on the Login button.
13. You will be prompted to change the password, as this is the first  login attempt. Enter the new password of choice and click on the Change password button

15. Your password will be changed and you will  be prompted to enter your username and password.

Enter the details and click on the Login button.

16. After a successful login, you will observe all the users that are configured in your Amazon Connect

instance in the web UI under Selected user details

D. Test the solution and search users based on different scenarios

Let us now test the solution based on different scenarios. On the left side of the web UI you will see options such as Profile Search and Tag Search.

i. Searching users by first name, last name and user name

1. Choose Profile Search. You have the option to search by entering: –
   • first name (comparison type will be based on EXACT value that you enter).
   • last name (comparison type will be based on STARTS_WITH value that you enter).
   • user name (comparison type will be based on CONTAINS value that you enter).
2. Enter the names based on choice and configuration and Click on Search User.
3. It will provide users based on matches in a JSON output. In our example, it produces 3 users in results.

ii. Searching users by Amazon Connect routing profiles

1. Choose Profile Search and select the routing profile of choice from the drop down.
2. In our example we have chosen ‘Basic Routing Profile’ in the Routing Profiles list box.
3. Click on Search User and you will get relevant results (using condition: routingProfileId = ‘routing-profile-id-or-arn’)
4. In our example, it provides two results in JSON format.

iii. Searching users by Amazon Connect security profiles

1. Choose Profile Search and select a security profile of choice from the Security Profiles list box.
2. Click on Search User and you will get relevant results (using condition :securityProfileId= “security-profile-id-or-arn”)
3. In our example, we get 1 user in the JSON output that matches the condition selected –‘Basic routing profile’

iv. Searching users by Amazon Connect agent hierarchy

1. Choose Profile Search and select an agent hierarchy of choice from the User Hierarchy list box.
2. Click on Search User and you will get relevant results (using condition:1.       :securityProfileId = “security-profile-id-or-arn”)
3. In our example, we get 1 user in the JSON output that matches the condition selected- San Jose

v. Searching users by Amazon Connect routing profile AND agent hierarchy AND security profile

1. Choose Profile Search and select routing profile of your choice from the Routing Profile list box. (E.g. Basic routing profile)
2. Choose security profile of choice in the Security Profile list box. (E.g. agent).
3. Choose agent hierarchy of choice in the User Hierarchy list box. (E.g. San Jose)
4. Click on Search User and you will get relevant results (condition :
   (routingProfileId = “routing-profile-id-or-arn” AND securityProfileId = “security-profile-id-or-arn” AND agentGroup = “agent-group-id-or-arn”)
5. In our example we get 1 user in the JSON output.

vi. Searching users by first name OR username AND agent hierarchy AND security profile AND routing profile

1. Choose Profile Search and enter first name (E.g. Mike) and username (E.g. wbuff ) of your choice in the respective fields.
2. Choose routing profile of choice (E.g. Technical Support) in the Routing Profile list box.
3. Choose security profile of choice (E.g. agent) in the Security Profile list box.
4. Choose agent hierarchy of choice (E.g. Pleasanton) in the User Heirarchy list box.
5. Click on Search User. Search api will produce a query with the following condition :
   (firstname = “Mike” OR username CONTAIN “wbuff) AND (securityProfileId = “security-profile-id-or-arn” AND agentGroup = “agent-group-id-or-arn” AND routingProfileId = “routing-profile-id-or-arn”)
6. In our example we get two users in the JSON output.

vii. Assign tags to users

Amazon Connect allows you to tag users to make it easier to organize, identify and search for them. In this section, we will assign tags to our users using the TagResource API.

1. Choose on of your users in the Selected user details pane of the web UI. In our case it will be- ‘admin’. Click on the Tag User button.
2. Similarly, choose another user (in our case ‘jcollins’) and click on the Tag User button.
3. Now choose the users individually and you will see “Location” with “USA” and “Sensitive” with “True” is assigned to the user in the JSON output.

viii. Search for users based on tags

1. On the left of the web UI, Choose Tag Search.
2. Choose Or Conditions in the Condition Type list box.
3. Choose HAVE, Location and USA in the 2nd row.
4. Choose HAVE, Sensitive and True in the 3rd row.
5. Choose SUMMARY in the Profile Details list box.
6. Click on the Search User and you will see 2 users (with limited profile information) listed in the JSON Output.
   
7. Similarly, let’s repeat the same steps for a NOT_HAVE condition.
8. Choose Tag Search and choose And Conditions in the Condition Type list box.
9. Choose NOT_HAVE, Location and USA in the 2nd row.
10. Choose NOT_HAVE, Sensitive and True in the 3rd row.
11. Choose SUMMARY in the Profile Details list box.
12. Click on the Search User and you will see 2 users who do not have ‘Location and ‘Sensitive’ in the output.

ix. Define IAM roles to restrict user access based on tags

You can create IAM Roles and restrict the search access based on tags as well. Below is the sample policy for the SearchUser API to provide results for users who have tags ‘Location’ with value ‘USA’ and ‘Sensitive” with value ‘True’.

		{
		  "Version": "2012-10-17",
		  "Statement": [
			{
			  "Effect": "Allow",
			  "Action": [
				"connect:SearchUser"
			  ],
			  "Resource": "*",
			  "Condition": {
				"StringEquals": {
				  "connect:SearchTag/Location": "USA",
				  "connect:SearchTag/Sensitive": "True"
				}
			  }
			}
		  ]
		}
	

Cleaning up

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

Conclusion

This post demonstrated examples of how one can use Amazon Connect’s new search user API using different use cases and scenarios.

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