Pesquise programaticamente usuários usando uma API no Amazon Connect

En este blog, lo guiaremos a través de diferentes escenarios y casos de uso que se pueden utilizar para buscar usuarios en Amazon Connect a través de una API. Puede utilizar estos ejemplos como una extensión de sus soluciones existentes o modificarlos en función de sus necesidades específicas. En este post, en el «arte de lo posible», se utiliza un ejemplo de interfaz de usuario web (UI) para activar funciones y diferentes resultados de búsqueda. En su caso, esta interfaz de usuario web se puede reemplazar fácilmente por una aplicación interna o utilidades de interfaz que necesiten invocar una API.

Visión general de la solución

Esta solución se implementará mediante una plantilla (template) de AWS CloudFormation. La plantilla crea un bucket de Amazon S3 y carga todos los activos en Amazon CloudFront. Como usuario, utiliza la URL de Amazon CloudFront para ver la interfaz de usuario web mencionada anteriormente. En función de los filtros que aplique, esta interfaz de usuario web activará una API de búsqueda en Amazon Connect para proporcionar los resultados adecuados.

Este post abordará las siguientes categorías de búsqueda en detalle:

1. Nombre, apellido, nombre de usuario (user-name)
2. Perfiles de enrutamiento, perfiles de seguridad, jerarquía de agentes de usuarios
3. Tags atribuidas a los usuarios
4. Condiciones AND/OR entre las categorías
5. Política del AWS Identity and Access Management (IAM) para restringir la salida del perfil del usuario (Resumen vs Completo)

Nota:

Este es un proyecto de muestra diseñado para que se pueda implementar fácilmente para la experimentación. Los permisos de la política de IAM utilizan el menor número de privilegios; sin embargo, los recursos de Amazon CloudFront y Amazon API Gateway implementados serán de acceso público. Tome las medidas adecuadas para proteger su distribución de Cloudfront y API Gateway siguiendo las instrucciones necesarias.

Prerrequisitos

Para este tutorial, se asume que usted comprende y dispone de los siguientes recursos:

1. Una cuenta de AWS
2. Una instancia existente de Amazon Connect
3. AWS IAM con acceso para criar políticas y roles
4. Amazon CloudFront con acceso para crear una distribución
5. Amazon S3 con acceso para crear buckets
6. AWS CloudFormation para ejecutar el stack
7. Amazon Cognito para crear usuarios para acceder a las funciones de la API de búsqueda de Amazon Connect y ejecutarlas

Implemente la solución

Nota: La plantilla de CloudFormation implementará los recursos en la región oeste de EE. UU. (US West – Oregón). Para implementar en otras regiones, descarga la solución desde este repositorio de GitHub.

Visión general de la etapas:

1. Implementar un stack de CloudFormation
2. Crear usuarios dentro da instancia de Amazon Connect para pruebas
3. Adicionar usuarios en Amazon y ejecutar la interface de usuario web del CloudFront
4. Probar la solución y busca los usuarios con base a los diferentes escenarios

Implantação do CloudFormation

1. Inicie la sesión en la Consola de Administración de AWS en la región US West (Oregon).
2. Haga click en el botón Launch Stack para criar un stack
3. Introduzca un nombre único para el stack (por ejemplo: search-user-api).
4. En la configuración de Amazon S3 (por ejemplo: search-user-api-blog-XXX), introduzca un nombre único a nivel mundial para el nuevo bucket de S3 que se creará. Este depósito almacenará todos los activos necesarios para la interfaz de usuario web a la que accede a través de la URL de Amazon CloudFront.

5. Marque la opción “Reconozco que AWS CloudFormation podría crear recursos de IAM.“ (“I acknowledge that AWS CloudFormation might create IAM resources.”)

6. Seleccione Create Stack.

7. La plantilla de AWS CloudFormation puede levar de 15 a 30 minutos para crear todos los recursos. Una vez hecho, el mostrará el estado como “CREATE_COMPLETE”.

8. Puede tardar otros 15 a 20 minutos para que Amazon CloudFront complete su despliegue de los activos del sitio web, una vez que el estado cambie a “CREATE_COMPLETE”.

B. Crear usuarios en tu instancia de Amazon Connect

1. Cree una jerarquía de agentes con cinco niveles diferentes, como Earth/North America/USA/California, o puede utilizar un ejemplo de su elección.

2. Cree dos perfiles de enrutamiento en Amazon Connect de su elección. Puede utilizar el “Perfil de enrutamiento básico” (“Basic routing profile”) existente y crear otro de su elección, como el “Soporte técnico” (“Technical Support”).

3. Cree cuatro usuarios de su elección y asigne a cada uno de ellos un perfil de enrutamiento diferente de los dos creados anteriormente y también una jerarquía de agentes diferente.

4. Asegúrese de que cada usuario también tenga un perfil de seguridad diferente, como administrador, agente, etc. A continuación, se muestra una instantánea de una configuración de ejemplo:

C. Inicie la interfaz de usuario web de CloudFront y añada usuarios a Amazon Cognito

1. Inicie la sesión login en Amazon Cognito y haga clic en el “grupo de usuários”(“user pool”) que comienza por {cloudformation-stack-name}-blog-user-pool

2. Seleccione Crear usuario en la parte inferior derecha.

3. Seleccione Enviar una invitación por e-mail o Enviar una invitación por SMS o Enviar invitación por e-mail y SMS, según tu elección. En nuestro post, seleccionaremos Enviar una invitación por e-mail.

4. Introduzca el nombre de usuario y una dirección de e-mail válido en la que recibirá un e-mail.

5. Seleccione Definir una contraseña em Contraseña temporal e introduzca 8 caracteres o dígitos o una combinación de ambos.

6. Seleccione Criar usuario en la parte inferior izquierda.

7. Recibirás un correo electrónico con el nombre de usuario y la contraseña temporal que has introducido con el asunto “Tu contraseña temporal”. Si no lo ves en tu bandeja de entrada, comprueba la carpeta de correo no deseado.

8. Inicie sesión en la Consola de Administración de AWS y navegue hasta AWS CloudFormation digitando el nombre del servicio en la barra de búsqueda.

9. Seleccione el stack que acabas de crear.

10. Ve a la sección Outputs do stack recién creado. Copia la URL del CloudFrontEndpoint de la columna value. 

11. Pega la URL en una nueva pestaña/ventana del navegador web para a la interfaz de usuario web de CloudFront.

12. Deberá introducir el nombre de usuario y la contraseña que recibió en el correo electrónico y hacer clic en el botón Login.

13. Se le pedirá que cambie la contraseña, ya que es el primer intento de inicio de sesión. Introduzca la nueva contraseña de su elección y haga clic en el botón Change Password (Cambiar contraseña)

14. Se cambiará su contraseña y se le pedirá que introduzca su nombre de usuario y contraseña.

Introduzca los detalles y haga clic en el botón Login.

15. Tras iniciar sesión correctamente, verá todos los usuarios configurados en su instancia de Amazon Connect en la interfaz de usuario web, en Selected user details.

D. Probar la solución y buscar usuarios en función de los diferentes escenarios

Ahora probemos la solución en función de diferentes escenarios. En el lado izquierdo de la interfaz de usuario web, verás opciones como la búsqueda de perfil (Profile search) y la búsqueda de etiquetas (Tag Search).

i.Buscando usuarios por nombre, apellido y user-name (nombre de usuario)

1. Seleccione Profile search. Tienes la opción de buscar escribiendo: –

• • Primer nombre (el tipo de comparación se basará en el valor EXACT que introduzca).
  • Apellido (el tipo de comparación se basará en el valor STARTS_WITH que introduzca).
  • User-name (el tipo de comparación se basará en el valor CONTAINS que introduzca).

2. Escriba los nombres según la elección y la configuración y haga clic en Search User.

3. Proporcionará la lista de usuarios en función de las coincidencias en una salida JSON. En nuestro ejemplo, produce 3 usuarios en los resultados.

ii. Búsqueda de perfiles de enrutamiento de Amazon Connect entre usuarios

1. Seleccione Profile search y elija el perfil de enrutamiento que desee en la lista desplegable.
2. En nuestro ejemplo, elegimos “Perfil de enrutamiento básico” (“Basic routing profile”) en el cuadro de lista de Routing Profiles (Perfiles de enrutamiento).
3. Haga clic en Search user (Buscar usuario) y obtendrá los resultados pertinentes (con la condición: routingProfileID = ‘routing-profile-id-or-arn’).
4. En nuestro ejemplo, proporciona dos resultados en formato JSON.

iii. Búsqueda de usuarios por perfiles de seguridad de Amazon Connect

1. Elija Profile search (Búsqueda de perfiles) y seleccione el perfil de seguridad de su elección en el cuadro de lista de Security Profiles (perfiles de seguridad).
2. Haga clic en Search user (Buscar usuario) y obtendrá los resultados pertinentes (utilizando condition:securityProfileId= «security-profile-id-or-arn»).
3. En nuestro ejemplo, obtenemos 1 usuario en la salida JSON que coincide con la condición seleccionada: “Basic routing profile” (Perfil de enrutamiento básico).

iv. Búsqueda de usuarios de Amazon Connect por jerarquía de agentes

1. Seleccione Profile Search (Búsqueda de perfiles) y elija la jerarquía de agentes que desee en el cuadro de lista de User Hierarchy (jerarquías de usuarios).
2. Haga clic en Search User (Buscar usuario) y obtendrá los resultados pertinentes (con la condición: securityProfileID = «security-profile-id-or-arn»).
3. En nuestro ejemplo, obtenemos 1 usuario en la salida JSON que corresponde a la condición seleccionada: San Jose

v. Búsqueda de usuarios por perfil de enrutamiento de Amazon Connect, jerarquía de agentes y perfil de seguridad

1. Elija Profile Search (Búsqueda de perfil) y seleccione el perfil de enrutamiento de su elección en el cuadro de lista de Routing Profile (perfiles de enrutamiento). (Por ejemplo: perfil de enrutamiento básico – Basic Routing Profile).
2. Elija el perfil de seguridad de su elección en el cuadro de lista de Security Profiles (perfiles de seguridad). (Por ejemplo: agente).
3. Elija la jerarquía de usuarios que prefiera en el cuadro de lista User Hierarchy (Jerarquía de usuarios). (Por ejemplo: San José).
4. Haga clic en Search User (Buscar usuario) y obtendrá los resultados pertinentes (condition : (routingProfileId = “routing-profile-id-or-arn” AND securityProfileId = “security-profile-id-or-arn” AND agentGroup = “agent-group-id-or-arn”).
5. En nuestro ejemplo, obtenemos 1 usuario en la salida JSON.

vi. Búsqueda de usuarios por nombre OR nombre de usuario AND jerarquía de agentes AND perfil de seguridad AND perfil de enrutamiento

1. Elija Profile Search (Busqueda de Perfil) e introduzca el fisrt name (nombre, por ejemplo: Mike) y el username (nombre de usuario, por ejemplo, wbuff) de su elección en los campos respectivos.
2. Elija el perfil de enrutamiento de su elección (por ejemplo: soporte técnico) en el cuadro de lista de Routing Profile (Perfil de enrutamiento).
3. Elija el perfil de seguridad de su elección (por ejemplo: agente) en el cuadro de lista de Security Profile (perfiles de seguridad).
4. Elija la jerarquía de agentes que prefiera (por ejemplo: Pleasanton) en el cuadro de lista de User Hierarchy (jerarquías de usuarios).
5. Haz clic en Search User (Buscar usuario). La API de búsqueda generará una consulta con la siguiente condición: (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. En nuestro ejemplo, obtenemos dos usuarios en la salida JSON.

vii. Asignar tags a los usuarios

Amazon Connect le permite etiquetar a los usuarios para que sea más fácil organizarlos, identificarlos y buscarlos. En esta sección, asignaremos etiquetas a nuestros usuarios mediante la API TagResource.

1. Elija uno de sus usuarios en el panel de detalles del usuario seleccionado de la interfaz de usuario web. En nuestro caso será: ‘admin’. Haga clic en el botón Tag User (Etiquetar usuario).
2. Del mismo modo, elige otro usuario (en nuestro caso ‘jcollins’) y pulsa el botón Tag User (Etiquetar usuario).
3. Ahora elige los usuarios de forma individual y verás que se asigna al usuario «Location» con «USA» y «Sensitive» con «True» en la salida JSON.

viii. Búsqueda de usuarios en función de tags

1. A la izquierda de la interfaz de usuario web, selecciona Tag Search (Búsqueda de etiquetas).
2. Elija OrConditions en el cuadro de lista Condition Type (tipos de condiciones).
3. Elija HAVE, Location y USA en la segunda fila.
4. Elija HAVE, Sensitive y True en la tercera fila.
5. Elija SUMMARY en el cuadro Profile Details (Detalles del Perfil).
6. Haga clic en Search User (Buscar usuario) y verá 2 usuarios (con información de perfil limitada) listados en la salida JSON.

7. Del mismo modo, repitamos los mismos pasos para una condición NOT_HAVE.

8. Elija Tag Search (Búsqueda de etiquetas) y elija AndConditions en el cuadro de lista de Condition Type (tipos de condiciones).

9. Elija NOT_HAVE, Location e USA en la segunda fila.

10. Elija NOT_HAVE, Sensitive e True en la tercera fila.

11. Seleccione SUMMARY en el cuadro de lista de detalles del perfil.

12. Haga clic en el botón Search User (Buscar usuario) y verá 2 usuarios que no tienen «Location» y «Sensitive» en la salida.

ix. Defina funciones de IAM para restringir el acceso de los usuarios en función de los tags

También puede crear roles de IAM y restringir el acceso a la búsqueda en función de tags. A continuación, se muestra un ejemplo de política de la API SearchUser para proporcionar resultados a los usuarios que tienen etiquetas «Ubicación» con el valor «USA» y «Sensitive» con el valor «true».

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

Limpiando el ambiente

Para evitar incurrir en cargos futuros, elimine todos los recursos creados eliminando el stack del AWS CloudFormation.

Conclusão

Esta publicación mostró ejemplos de cómo se puede utilizar la nueva API de búsqueda de usuarios de Amazon Connect en diferentes casos de uso y escenarios.

Para obtener más información sobre cómo se creó esta solución y ver cómo se ejecutaron las API, consulta el repositorio de GitHub.