Installation Prerequisites¶

Amazon Connect API Access¶

The connector retrieves data using Amazon Connect API. All requests are made using Amazon Connect authentication. To make requests, the instance id, access key, secret access key, and region are needed.

Amazon Kinesis Stream¶

Additional data can be retrieved using Amazon Kinesis Stream. Instructions for enabling data streaming can be found in the Amazon Documentation. The 2Ring DW Amazon Connect connector relies on Contact Events, Contact Records and Agent Events; no other data should be sent to the Kinesis Stream. To read the stream data, the same parameters used for the Amazon Connect API are required, along with the stream name and account ID.

Set up and usage of Amazon Kinesis Stream may incur additional charges by Amazon. For more information, see the Amazon Kinesis Data Streams pricing.

Contact Events¶

Amazon Connect Contact Events are required to be sent into the Amazon Kinesis Stream for the Current Contacts grid functions to be able to display currently ongoing contacts. This can be done using Amazon EventBridge.

If there is a need to display attributes of a contact, the events have be enriched first before being sent into the Amazon Kinesis Stream.

Amazon EventBridge¶

To create a rule for the Amazon Connect Contact Events to be sent into the Amazon Kinesis Stream, follow the steps bellow:

Open IAM Management Console
Navigate to Amazon EventBridge
Navigate to Buses => Rules
Click the Create Rule button
Define the rule detail
- Fill out the Name field
- Select the appropriate Event bus
- Enable the rule
- Set the Rule type as Rule with an event pattern
Click the Next button
Build event pattern
- Select AWS events or EventBridge partner events as the Event source
- Select Use pattern form as the Creation method
- Select AWS services as the Event source
- Select Amazon Connect as the AWS service
- Select Amazon Connect Contact Event as the Event type
Click the Next button
Select target
- Select AWS service as the target type
- Select Kinesis stream as the target
- Select the Amazon Kinesis Stream used by the 2Ring DW Amazon Connect connector
- Select the appropriate Execution role Note: If using an existing role, make sure the role has permissions on the Amazon Kinesis Stream for the following actions: kinesis:PutRecord, kinesis:PutRecords
Click the Next button
Configure tags if need be
Click the Next button
Review the configuration is correct
Click the Create rule button

Enriching¶

Enriching the Amazon Connect Contact Event with contact attributes can be done by using a Lambda function which will be the target of the Amazon EventBridge rule instead of the Amazon Kinesis Stream. The rest of the Amazon EventBridge setup should be the same. Note: The Lambda code provided below should serve as a starting point and should be adjusted as required. The only requirement is for the contact attributes to be present in a field called attributes on the detail object of the event.

To create a Lambda function for the Amazon Connect Contact Events to be enriched and then sent to the Amazon Kinesis Stream, follow the steps below:

Open IAM Management Console
Navigate to Lambda
Navigate to Functions
Click the Create function button
Create function
- Select Author from scratch
- Fill out the Function name field
- Select Python 3.13 as the Runtime
- Select x86_64 as the Architecture
- Select the appropriate Execution role
Click the Create function button
Navigate to Code

Paste in the following

import os
import json
import logging
from botocore.exceptions import ClientError
import boto3

connect_client = boto3.client('connect')
kinesis_client = boto3.client('kinesis')

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# Read stream name from environment variables
STREAM_NAME = os.environ['TWORING_KINESIS_STREAM']

def lambda_handler(event, context):
    """Enrich Connect event with attributes and send to Kinesis."""
    try:
        detail = event.get('detail', {})
        contact_id = detail['contactId']

        # Extract Instance ID
        instance_arn = event['resources'][0]
        instance_id = instance_arn.split('/')[-1]

        # Fetch contact attributes
        resp = connect_client.get_contact_attributes(
            InstanceId=instance_id,
            InitialContactId=contact_id
        )
        attributes = resp.get('Attributes', {})
        detail['attributes'] = attributes

        # Publish enriched event
        kinesis_client.put_record(
            StreamName=STREAM_NAME,
            Data=json.dumps(event),
            PartitionKey=contact_id
        )

        logger.info("Enriched event for contact %s sent to Kinesis.", contact_id)
        return {'statusCode': 200, 'body': 'Success'}

    except ClientError as e:
        logger.error("AWS API error: %s", e, exc_info=True)
        raise
    except KeyError as e:
        logger.error("Missing key in event payload: %s", e, exc_info=True)
        raise
    except Exception as e:
        logger.error("Unexpected error: %s", e, exc_info=True)
        raise

Click the Deploy button
Navigate to Configuration => Environment variables
Click the Edit button
Click the Add environment variable button
Enter TWORING_KINESIS_STREAM as the Key and the name of the Amazon Kinesis Stream used by the 2Ring DW Amazon Connect connector as the Value
Click the Save button
Navigate to Configuration => Permissions
Verify the Execution role has the following permissions:
- Amazon CloudWatch Logs
  - arn:aws:logs:<region>:<account-id>:*
    - Allow: logs:CreateLogGroup
  - arn:aws:logs:<region>:<account-id>:log-group:/aws/lambda/<lambda-name>:*
    - Allow: logs:CreateLogStream
    - Allow: logs:PutLogEvents
- Amazon Connect
  - All resources
    - Allow: connect:GetContactAttributes
- Amazon Kinesis Data Streams
  - arn:aws:kinesis:<region>:<account-id>:stream/<stream-name>
    - Allow: kinesis:PutRecord Amazon CloudWatch Logs permissions are only needed if the Lambda function code is using logging like in the provided code.

API Permissions¶

The 2Ring DW AmazonConnect Connector requires the following actions to be allowed for the user associated with the Access Key ID:

Connect
- DescribeUser
- GetCurrentMetricData
- GetMetricData
- GetMetricDataV2
- ListAgentStatuses
- ListQueues
- ListRoutingProfiles
- ListRoutingProfileQueues
- ListUserHierarchyGroups
- ListUsers
Kinesis
- GetRecords
- GetShardIterator
- ListShards
- ListStreamConsumers
- RegisterStreamConsumer
- DeregisterStreamConsumer
- SubscribeToShard

Below is described how to setup a managed identity-based policy and attach it to an existing user, however, this is but one way of allowing the needed actions. Based on your organization’s policies, the implementation might differ.

Creating a minimum permission policy¶

To create a minimum permission policy, follow the steps below:

Open IAM Management Console
Navigate to Access Management
Navigate to Policies
Click the Create policy button
Switch to the JSON tab

Paste in the following JSON:

{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Sid": "ConnectPermissions",
             "Effect": "Allow",
             "Action": [
                 "connect:DescribeUser",
                 "connect:GetCurrentMetricData",
                 "connect:GetMetricData",
                 "connect:GetMetricDataV2",
                 "connect:ListAgentStatuses",
                 "connect:ListQueues",
                 "connect:ListRoutingProfiles",
                 "connect:ListRoutingProfileQueues",
                 "connect:ListUserHierarchyGroups",
                 "connect:ListUsers"
             ],
             "Resource": [
                 "<ARN CONNECT INSTANCE>",
                 "<ARN CONNECT INSTANCE>/agent/*",
                 "<ARN CONNECT INSTANCE>/queue/*",
                 "<ARN CONNECT INSTANCE>/routing-profile/*",
                 "<ARN CONNECT INSTANCE>/agent-state/*"
             ]
         },
         {
             "Sid": "KinesisPermissions",
             "Effect": "Allow",
             "Action": [
                 "kinesis:GetRecords",
                 "kinesis:GetShardIterator",
                 "kinesis:ListShards",
                 "kinesis:ListStreamConsumers",
                 "kinesis:RegisterStreamConsumer",
                 "kinesis:DeregisterStreamConsumer",
                 "kinesis:SubscribeToShard"
             ],
             "Resource": [
                 "<ARN KINESIS DATA STREAM>/<STREAM NAME>",
                 "<ARN KINESIS DATA STREAM>/<STREAM NAME>/consumer/*"
             ]
         }
     ]
 }

Replace <ARN CONNECT INSTANCE> with the full ARN of your Amazon Connect instance
Replace <ARN KINESIS DATA STREAM> with the full ARN of the Kinesis Data Stream used by the connector
Replace <STREAM NAME> with the name of stream, that you entered in Kinesis Stream section in the settings of the connector.
Click the Next: Tags button
Add tags (if needed)
Click the Next: Review button
Fill out the Name field
Fill out the Description field
Click the Create policy button

Example JSON policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ConnectPermissions",
            "Effect": "Allow",
            "Action": [
                "connect:DescribeUser",
                "connect:GetCurrentMetricData",
                "connect:GetMetricData",
                "connect:GetMetricDataV2",
                "connect:ListAgentStatuses",
                "connect:ListQueues",
                "connect:ListRoutingProfiles",
                "connect:ListRoutingProfileQueues",
                "connect:ListUserHierarchyGroups",
                "connect:ListUsers"
            ],
            "Resource": [
                "arn:aws:connect:us-east-1:000000000000:instance/00000000-0000-0000-0000-000000000000",
                "arn:aws:connect:us-east-1:000000000000:instance/00000000-0000-0000-0000-000000000000/agent/*",
                "arn:aws:connect:us-east-1:000000000000:instance/00000000-0000-0000-0000-000000000000/queue/*",
                "arn:aws:connect:us-east-1:000000000000:instance/00000000-0000-0000-0000-000000000000/routing-profile/*",
                "arn:aws:connect:us-east-1:000000000000:instance/00000000-0000-0000-0000-000000000000/agent-state/*"
            ]
        },
        {
            "Sid": "KinesisPermissions",
            "Effect": "Allow",
            "Action": [
                "kinesis:GetRecords",
                "kinesis:GetShardIterator",
                "kinesis:ListShards",
                "kinesis:ListStreamConsumers",
                "kinesis:RegisterStreamConsumer",
                "kinesis:DeregisterStreamConsumer",
                "kinesis:SubscribeToShard"
            ],
            "Resource": [
                "arn:aws:kinesis:us-east-1:000000000000:stream/AwesomeStreamName",
                "arn:aws:kinesis:us-east-1:000000000000:stream/AwesomeStreamName/consumer/*"
            ]
        }
    ]
}

Attaching a policy to an existing user¶

To attach a policy to an existing user, follow the steps below:

Open IAM Management Console
Navigate to Access Management
Navigate to Users
Click the user associated with the Access Key ID used by the connector
Click the Add permissions button
Select Attach existing policies directly
Select the policy you have just created
Click the Next: Review button
Click the Add permissions button