Customer Integration Guide - Amazon Connect

Introduction

This page helps customers integrating Amazon Connect ACD with CXone WFM using the Engagement Hub. It provides implementation guidance for inbound voice and chat channel integrations, targeting IT administrators, system integrators, and WFM planners.

Scope

This guide:

  • Covers historical, real-time, and intraday data exchange.

  • Applicable to inbound voice channel integrations.

  • Supports only 1 Service Level Agreement per queue (Only one field needs to be configured for Contacts answered in X seconds, Contacts abandoned in X seconds while scheduling the reports on Amazon connect. here X is the service level)

  • Queue configuration handles contacts for one media channel (voice or chat) and in one direction (inbound). Skill as a queue is supported.

    Example: voice-inbound, chat-inbound.

Not in Scope

  • Agent activity report.

  • Outbound and digital channel events.

  • Inbound and outbound in the same queue.

  • Abandon Service Level.

  • Queue configuration to handle contacts of multiple media channels (voice, chat, email, tasks) of both direction (inbound and outbound) is not supported (Skill as an attribute is not supported). For example, voice-inbound-outbound, voice-chat-inbound.

Customer responsibilities

  • The customer is responsible for downloading and installing the connector, with guidance from the implementation team.

    You must be logged into the CXone WFM application to access the Downloads page. If not logged in, no files will be available for download.

  • Ensure network connectivity from the customer’s AWS environment to the NiCE AWS environment.

  • Configure Amazon Connect channels and routing as required.

  • An active subscription to Amazon connect is required, along with the appropriate licenses for:

    • Channels

    • CXone WFM

  • Provide S3 bucket and Kinesis stream connection details during connector installation.

  • Assign a technical point-of-contact to coordinate with the implementation team.

Integration Overview

Prerequisites

Ensure the following configurations and access are in place before implementation:

  • Read access to the S3 bucket for reading the historical reports.

  • Read access to the Amazon Kinesis stream for real-time data.

  • Agent IDs and Skill IDs must be mapped in CXone WFM according to customer-specific requirements.

  • Access to a testing environment for validation and configuration.(if applicable)

CloudFormation stack parameters required from the customer

parameter

type

description

default value
VpcId AWS::EC2::VPC::Id Existing VPC ID None
SubnetId1 AWS::EC2::Subnet::Id Subnet ID in first availability zone with egress (NAT Gateway) access for ECS deployment None
SubnetId2 AWS::EC2::Subnet::Id Subnet ID in second availability zone with egress (NAT Gateway) access for ECS deployment None
AvailabilityZone1 AWS::EC2::AvailabilityZone::Name First availability zone for ECS deployment None
AvailabilityZone2 AWS::EC2::AvailabilityZone::Name Second availability zone for ECS deployment None
InstanceType String EC2 instance type for ECS cluster t3.small
AmazonConnectS3BucketName String S3 bucket Name for this specific Amazon Connect instance's historical reports None
AmazonConnectS3FolderPrefix String Folder prefix for this Amazon Connect instance's uploads None
AmazonConnectKinesisStreamArn String Kinesis Stream ARN for Amazon Connect instance's real-time data None
AmazonConnectKinesisStreamName String Amazon Connect Kinesis Stream Name None
EnableCloudWatchAlarms String Should enable CloudWatch alarms for monitoring (YES/NO) Yes, No
AlarmNotificationEmail1 String Email to send subscription for alarm notifications (Manadtory if EnableCloudWatchAlarms is set to "YES" otherwise can be kept empty) None
AlarmNotificationEmail2 String Email to send subscription for alarm notifications None
AlarmNotificationEmail3 String Email to send subscription for alarm notifications None
AlarmNotificationEmail4 String Email to send subscription for alarm notifications None
AlarmNotificationEmail5 String Email to send subscription for alarm notifications None

High-Level Architecture

Architecture

  • Connector → ACD Hub → CXone Mpower WFM.

  • The NiCE developed connector provides Historic and RTA functionality for Engagement Hub integration.

  • The Engagement Hub setup is hosted on the NiCE-owned AWS account.

  • The connector setup is hosted on the customer's AWS account.

  • The connector is designed to read report data only from Amazon Kinesis streams and S3 buckets. It sends this data to the ACD Hub service for processing. It does not create, update, or modify any existing data within the tenant.

  • The customer must prefix report file names in the S3 bucket as follows, with a 15-minute interval between files:

    • QR – Queue Report

    • AQR – Agent Queue Report

    • ASPR – Agent System Performance Report

Key Components

S3 Bucket

  • Stores historical reports.

  • A one-time Lambda function is created to set up a trigger that activates whenever a new file is added to the bucket.

Kinesis Stream

  • Processes records from Amazon Connect real-time agent data.

  • Requires appropriate permissions for data access and processing.

Historical SQS queue: is created to track historical reports uploaded to the S3 bucket.

Dead Letter Queue (DLQ): captures and stores unprocessed file data for later analysis.

Unified Connector: hosts and runs the Amazon Connect Connector service.

Roles and Permissions

IAM roles required to run the connector

The connector automatically creates the following IAM roles when the setup script is executed.

ECS Task Execution Role

Name: acdhub-amazon-connector-task-execution-role

  • Purpose: Allows ECS to manage the container life cycle (examples pulling images, sending logs).

  • Trusted Entity: ecs-tasks.amazonaws.com

  • Managed Policies: AmazonECSTaskExecutionRolePolicy

ECS Instance Role

Name: acdhub-amazon-connector-instance-role

  • Purpose: Allows EC2 instances to join the ECS cluster

  • Trusted Entity: ec2.amazonaws.com

  • Managed Policies: AmazonEC2ContainerServiceforEC2Role

ECS Task Role

Name: acdhub-amazon-connector-task-role

  • Purpose: Provides application-level permissions for the connector service.

  • Trusted Entity: ecs-tasks.amazonaws.com

  • Custom Inline Policies:

Lambda execution role

Name: Role849a3c81

  • Purpose:

    • Supports S3 bucket notification management (used by a custom CloudFormation resource).

  • Trusted Entity: lambda.amazonaws.com

  • Managed Policies: AWSLambdaBasicExecutionRole

  • Custom Inline Policy: DefaultPolicye3c7c10e

    Actions

    • s3:GetBucketNotification

    • s3:PutBucketNotification

      Resources

      • ["*"]

    For SQS Notification

    • sqs:GetQueueAttributes

    • sqs:GetQueueUrl

    • sqs:SendMessage

    Principal

    Condition

    • ArnLike: "aws:SourceArn":

      "arn:aws:s3:::{amazon_connect_s3_bucket.bucket_name}"

    External dependencies

    • Amazon Connect Instance: Requires access credentials and configuration.

    • Existing VPC: Must provide VPC ID and subnet IDs.

    • ECR Repository: Must exist with the connector container image.

Configurations

Tenant Configuration

  1. Open Tenant Manager and navigate to:

    Tenants > Applications and Features > WFM > Edit WFM Application Configuration > Configure Settings

  2. In select features, choose WFM Advanced.

  3. Select via WFM Engagement Hub option from the dropdown ACD Integration and click Finish.

    • Name: ACD name without spaces

    • Version: Example 17.0.0 and above.

Data Mapping

Default agent states

NAME

EVENT ID

EVENT REASON

ACTIVITY CODE

STATE
Break Break   Break Closed
Available Available   Open Open
Login LOGIN   Open Open
Logout LOGOUT   Logoff Closed
Offline Offline   Logoff Closed
VOICE-INBOUND-CONNECTING VOICE-INBOUND-CONNECTING   Open Open
VOICE-INBOUND-CONNECTED VOICE-INBOUND-CONNECTED   Open Open
VOICE-INBOUND-CONNECTED_ONHOLD VOICE-INBOUND-CONNECTED_ONHOLD   Open Open
VOICE-INBOUND-ENDED VOICE-INBOUND-ENDED   Open Open
VOICE-INBOUND-MISSED VOICE-INBOUND-MISSED   Open Open
VOICE-INBOUND-ERROR VOICE-INBOUND-ERROR   Open Open
VOICE-INBOUND-ONHOLD VOICE-INBOUND-ONHOLD   Open Open
VOICE-TRANSFER-CONNECTING VOICE-TRANSFER-CONNECTING   Open Open
VOICE-TRANSFER-CONNECTED VOICE-TRANSFER-CONNECTED   Open Open
VOICE-TRANSFER-CONNECTED_ONHOLD VOICE-TRANSFER-CONNECTED_ONHOLD   Open Open
VOICE-TRANSFER-ENDED VOICE-TRANSFER-ENDED   Open Open
CHAT-API-CONNECTING CHAT-API-CONNECTING   Open Open
CHAT-API-CONNECTED CHAT-API-CONNECTED   Open Open
CHAT-API-ENDED CHAT-API-ENDED   Open Open
CHAT-API-MISSED CHAT-API-MISSED   Open Open
CHAT-API-ERROR CHAT-API-ERROR   Open Open
CHAT-API-ONHOLD CHAT-API-ONHOLD   Open Open
CHAT-QUEUE_TRANSFER-CONNECTING CHAT-QUEUE_TRANSFER-CONNECTING   Open Open
CHAT-QUEUE_TRANSFER-CONNECTED CHAT-QUEUE_TRANSFER-CONNECTED   Open Open
CHAT-QUEUE_TRANSFER-ENDED CHAT-QUEUE_TRANSFER-ENDED   Open Open

Historical Metrics

Queue report

  • Contacts Received

  • Abandoned Short

  • Abandoned Long

  • Handled Short

  • Handled Long

  • Handled Time

  • Hold Time

  • Work (ACW) Time

  • Queue Delay Time

  • Service Level Percent

  • Backlog

  • Backlog Expired

  • Backlog Not Expired

  • Right Party Contacts

  • Right Party Talk Time / Handle Time

  • Wrong Party Contacts

  • Wrong Party Talk Time / Handle Time

  • Active

Agent queue report

  • AgentValue

  • Agent Id

  • Handled Time

  • Hold Time

  • Work (ACW) Time

  • Right Party Contacts

  • Right Party Talk Time / Handle Time

  • Wrong Party Contacts

  • Wrong Party Contacts

  • Active

Agent System Performance Report

  • AgentValue

  • Agent Id

  • ReadyTime

  • NotReadyTime

  • LoginTime

Supported Media Types

    • Inbound voice

    • Chat

Media Channel Classifications

  • Immediate response (via inbound voice)

  • Deferrable response (via chat)

Protocols

  • For real-time, customer must configure S3 bucket in the customer AWS account.

  • For historical reports, the connector establishes connection with Amazon Kinesis stream.

Data Types Supported

  • Historical Data (15 min)

    • Forecast data

    • Intraday

  • Real-Time Adherence (Agent State Transitions)

Data Retrieval Specifics

The connector supports these data retrieval mechanisms:

  • Real Time: Connector listens to the Amazon Connect Kinesis stream for agent state events.

  • Historical: Connector periodically fetches historical data from the S3 bucket.

  • Manual Reload/Repost: Available when a support representative uploads the required historical data file to the S3 bucket. Reloaded data is consumed by WFM after approximately 3 hours.

  • Intraday Manager: Supports data reload for the last 24 hours.

  • When the ACD or the connector is down then the agent's state is shown as the last state in the CXOne WFM RTA screen.

  • For midnight/holiday intervals (where no data is generated by the ACD), no data is displayed on the Intraday screen of CXOne WFM.

Deployment Models

Amazon Connect ACD integrated with the NiCE-developed connector and CXone WFM.

  • The connector runs exclusively on ECS tasks on EC2 instances.

  • Multi-AZ ECS setup ensures resilience. Tasks consume Kinesis streams and SQS queues per tenant.

  • Check pointing and polling intervals are configurable.

Contact Data Pegging

Contact Time Values are pegged to the interval when the contact completes.

All the values for Engagement Hub integration contacts are pegged at the end in the interval when the contact completes.

Example:

If a contact starts in the 12:00–12:15 interval and completes in the 12:15–12:30 interval, it is pegged to 12:15–12:30.

Known Limitations

  • Historical Adherence report is not available.

  • A queue can support only one media type and one direction (e.g., voice-inbound or chat-inbound).

  • There is a 6–16 minute delay after the end of each interval before Amazon Connect ACD sends historical data to the NiCE connector.

    As a result, Intraday data may appear in the CXone WFM UI approximately 25 minutes after the interval ends.

  • Only one Service Level Agreement per queue is supported.

  • If the customer is already integrated with the IEX product, a separate S3 bucket must be created for CXone WFM Engagement Hub consumption.

  • Manual reload of historical data is supported for up to 30 days prior.

  • RTA data export is not available for Amazon connect ACD.

  • When the ACD or the connector is down then there is no change in the agent state on the RTA screen in CXOne WFM, it continues to show the last updated state.

FAQs

Query: Can multiple Amazon Connect ACD instances be integrated into a single NiCE WFM environment?

Ans: Currently, only 1 ACD mapping is been supported.

Query: What happens if the integration fails or data is delayed?

Ans: Reach out to the support team.

Query: Is any downtime required during setup?

Ans: For new customer, downtime follows the standard CXone WFM setup process.

Query: What should I do if the default agent state changes?

Ans: Contact the Implementation team to update the ACD data mapping in the CXone WFM Tenant Manager.

Query: What should I do if queue name is changed?

Ans: Contact the Implementation team to update the queue name mapping in the CXone WFM Tenant Manager.

Query: What should I do if new Agent is added?

Ans: Contact the Implementation team to update the agent name in the CXone WFM Employees section.

Query: What should I do when ACD name is changed?

Ans: Manually import the historical data on the CXOne WFM application.

Query: What should I do when WEM skill name is changed?

Ans: Manually import the historical data on the CXOne WFM application.

Query: What if agent IDs change?

Ans: Ensure consistent ID mapping to avoid RTA mismatches.

Query: What if the CloudFormation stack parameters change?

Ans: Contact the Implementation team to update the parameters.

Query: What should I do if we want to add more media channels?

Ans: Contact the product team to discuss supported options.

Support and Resources

  • NICE Professional Services Contact.

  • CXone WFM Help Center.