At the end of July, Amazon introduced the User Management API to Amazon Connect. The User API opens the door for customers and partners to start scripting user setup and maintenance actions, create custom user management applications and modify user data from Lambda functions. For this post, I took a few hours to code up a simple web application that shows a list of users and details for each user. It isn’t too pretty and doesn’t do a whole lot, but if it gives you a sense of what’s possible and how easy is it use to the API, I’ll feel satisfied.
Let’s start with the end product. This app has two screens, a list of Connect users and a Connect user detail view. Every Connect user in the list is clickable and takes you to the details page.
These screens are shown below.
Nothing too fancy, right? However, if you wanted to make the user details editable or add a button to create a new user, the structure is there for you.
Let’s get into the fun part, some code!
Some Code…
I used the Express web app framework with Node. I kept all the code in one file, the index.js and used the Pug templating language to render each of the views. To make the code more readable, I used async methods along with the await keyword. This avoids massively indented callback chains and makes the logic easier to follow by just scanning down the file. More details on the tech stack are in the Helpful Resources section at the end of this post.
I’ve included the code of the two views for reference, but the important part of this post is to look at the User API code, which is in the index.js.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| const express = require("express"); | |
| const app = express(); | |
| const AWS = require("aws-sdk"); | |
| require("express-async-errors"); | |
| const connectInstanceId = "7f03…"; | |
| var connectClient = new AWS.Connect({ | |
| apiVersion: "2017-08-08", | |
| region: "us-east-1" | |
| }); | |
| // serve static content from public directory | |
| app.use(express.static("public")); | |
| // configuration for pug views | |
| app.set("views", "./views"); | |
| app.set("view engine", "pug"); | |
| // index – list of users | |
| app.get("/", async (req, res) => { | |
| var listUsersParams = { | |
| InstanceId: connectInstanceId | |
| }; | |
| var listUsersPromise = connectClient.listUsers(listUsersParams).promise(); | |
| var listUsersResponse = await listUsersPromise; | |
| res.render("index", { | |
| title: "Connect Users", | |
| dataList: listUsersResponse.UserSummaryList | |
| }); | |
| }); | |
| // user detail by user id | |
| app.get("/user/:userId", async (req, res) => { | |
| var userId = req.params.userId; | |
| var describeUserParams = { | |
| InstanceId: connectInstanceId, | |
| UserId: userId | |
| }; | |
| var describeUserPromise = connectClient | |
| .describeUser(describeUserParams) | |
| .promise(); | |
| var describeUserResult = await describeUserPromise; | |
| res.render("user", { | |
| title: describeUserResult.User.Username, | |
| user: describeUserResult.User | |
| }); | |
| }); | |
| app.listen(3000, () => console.log("App listening on port 3000!")); |
The first step in using the Connect User API is to load the AWS SDK and create a Connect client object, as shown in lines 8-11. We tell the client object which version of the Connect API to use and what region your Connect instance is in.
From there, we can call individual API methods in the routing methods. For the index view method app.get(“/”)… we call the listUsers method which takes in your Connect instance id and returns a list of user basic info objects. We pass the objects to the view to render and away we go.
For the detail view method app.get(“/user/:userId”)… we call the describeUser method which takes that Connect instance id again, along with the user id of the user you want details on. That method returns a detailed user object. Again, we pass that object to the view to render.
In case you were wondering, because I don’t specify an alternative, this Node app will simply use the default profile credentials from the Amazon Command Line Interface tool installed on the machine. See the Helpful Resources section for a link with details on how to specify alternative credentials.
And that’s really it. No particular secret incantations needed here. Amazon has done a nice job in providing an easy to use, thoroughly documented API. I’d love to see more added to the API, for example to pull out the Queues associated with a Routing Profile, but this is a solid base to start off with. Again, the view code is reproduced below for your curiosity.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| html | |
| head | |
| title= title | |
| link(rel="stylesheet" href="css/base.css") | |
| body | |
| h2= "Users in my Connect Instance (" + dataList.length + ")" | |
| ul | |
| each val in dataList | |
| li | |
| a(href="user/" + val.Id) #{val.Username} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| html | |
| head | |
| title= title | |
| link(rel="stylesheet" href="../css/base.css") | |
| body | |
| h2= "Details for " + user.Username | |
| ul | |
| li= "ARN: " + user.Arn | |
| li= "First Name: " + user.IdentityInfo.FirstName | |
| li= "Last Name: " + user.IdentityInfo.LastName | |
| li= "Routing Profile Id: " + user.RoutingProfileId | |
| br | |
| a(href="../") #{"Back"} |
Helpful Resources
- Credit for the ul and li styles goes to Design Shack
- I used David Banham’s express-async-error package so that any exceptions from the async methods would bubble up to the default Express error handler
- For programming in Express, the official Express documentation is quite good to get you started. I used the guide pages on error handling to better understand why I needed the express-async-errors package, and the pages on template engines and serving static files to get the basic set up
- The official Pug documentation was also good, for example on understanding how to set attributes on tags
- The Amazon Connect API is documented in several different places, the best resource for using it from JavaScript is in the AWS JavaScript SDK guide under Connect. For a reference that shows the HTTP requests and responses, see the Amazon Connect Service API reference
- For more information on credentials and where the Amazon Connect API looks to figure out what identity and access privileges to use, see the Setting Credentials section of the API reference.
Thanks for reading. Any questions, comments or corrections are greatly appreciated. Stay tuned next week for another post on the Connect API.
To learn more about what we can do with Amazon Connect, check out Helping You Get the Most Out of Amazon Connect
