Amazon Connect Integration - Cloudformation

Owned by Patrick Hernandez
Last updated: Aug 03, 2023 by Ram Rocabo

This is a guide for integrating your Amazon Connect Instance with eMite.

This involves the deployment of several additional components on your AWS Cloud, such as Kinesis streams and elasticsearch.

For easier deployment of these components - we can make use of a CloudFormation template to create a CloudFormation stack.

This guide assumes all components will be deployed in the same region as the Amazon Connect instance, and also all under the same AWS Account.

Overview of Stack Components

  • EmiteDomain
    • AWS Elasticsearch Domain that will store data used by eMite such as the Contact Trace Records (CTRs) and Metrics and Observations
  • EmiteAgentEvents
    • AWS Kinesis Stream that gets Agent Events data from Amazon Connect
  • EmiteCTR
    • AWS Kinesis Stream that gets CTR data from Amazon Connect
  • EmiteRole
    • IAM Role that eMite will use to get data from Kinesis Streams and Amazon Connect
  • EmiteKinesisPolicy
    • IAM Policy to allow read access to Kinesis Streams (Agent Events and CTR)
  • EmiteAmazonConnectPolicy
    • IAM Policy to allow read access to AmazonConnect instance

Deploying the Stack

Load the eMite CloudFormation template on the console

  • On the eMite Onboarding page, under Step 1, click the CloudFormation URL Link
  • This will take you to your CloudFormation console on the same region as your Amazon connect instance.
    • This also automatically loads the eMite CloudFormation template, as well as load some default parameters.

Define Stack Parameters

  • Stack Name
    • Input your preferred stack name
    • E.g. emite-amazonconnect-stack
  • Parameters
    • AgentEventsStreamName
      • Name of the Agent Events Kinesis stream. You can leave this as default
      • Default: connect-agentevents
    • AmazonConnectInstanceARN
      • Open a new console window and go to Amazon Connect > select your Amazon Connect instance
      • On the overview tab, copy the Instance ARN
    • CTRStreamName
      • Name of the Agent Events Kinesis stream. You can leave this as default
      • Default: connect-ctr
    • ContactLensARN
      • ARN of the S3 Bucket which contains Contact Lens data. Leave it as default if you do not have Contact Lens data.
      • Default: none
    • ContactLensKMSARN
      • ARN of the KMS key that is used to encrypt the S3 Bucket which contains Contact Lens data. Leave it as default if you do not have Contact Lens data.
      • Default: none
    • ConnnectReportsBucketArn
      • ARN of Amazon Connect Reports S3 Bucket. Leave it as default if you do not have Connect Reports Data.
      • Default: none
    • ConnectReportsLocation
      • Location of Reports in S3 (excluding bucket name in path). Leave it as default if you do not have Connect Reports Data.
      • Default: none
    • CustomerID
      • Autogenerated Unique Customer ID provided by eMite
      • Please don't change this value
    • ESDomainName
      • Name of the elasticsearch domain. You can leave this as default
      • Default: emite-connect
    • EmiteAccountID
      • eMite AWS Account ID
      • Please don't change this value
    • ExistingVPC
      • Yes, If you want to deploy the OpenSearch service in an existing VPC. 
        • If yes, need to modify OSVPCID and Private Subnet ID
      • No, New VPC will be created for OpenSearch.
    • OSVPCID
      • Modify if you are going to deploy the Opensearch in an existing VPC, Input the VPC ID that where you want to deploy the opensearch cluster.
      • Default: none
    • PrivateSubnetID
      • Modify if you are going to deploy the Opensearch in an existing VPC, Input the PrivateSubnet ID that where you want to deploy the opensearch cluster
      • Default: none
    • KinesisAgentEventCheck
      • Yes, If you have an existing AgentsEventStream you can modify the "AgentEventStreamName" parameter to input your existing AgentsEvent name.
        • If you will use an existing AgentEventStream please increase the retention period of the stream to 60 days
      • No, Agents Event kinesis stream will be created name will depend on AgentEventsStreamName.
    • KinesisCtrStreamCheck
      • Yes, If you have an existing CTRStream you can modify the "CTRStreamName" parameter to input your existing CTRStream name
        • If you will use an existing CTRStream please increase the retention period of the stream to 60 days
      • No, CTRStream kinesis stream will be created name will depend on CTRStreamName.
    • OpenSearchKMSKey
      • ID of KMS key that you use to encrypt the OpenSearch.
      • Default: none
    • OpenSearchNumberOfAZ
      • Number of AZ and Data Nodes, openSearch Service allocates the nodes and replica index shards that belong to a cluster across.
        • If selected 2 or 3, servers will be deployed in multi-az setup.
        • If selected 2 or 3, and ExistingVPC is Yes, you will need to provide 2 or 3 subnets to accommodate the multi-az setup.
      • Default: 1
    • OpenSearchVersion:
      • This is the default version of the Opensearch required for the eMite.
      • Default: Elasticsearch7_9
    • OpenSearchInstanceType:
      • This is the standard Open search instance type, can be modified depending on the number of data.
      • Default: m6g.large.search
    • StreamKMSKey
      • ARN of KMS key that you use to encrypt the kinesis streams.
      • Default: None, if you did not encrypt your kinesis streams.
  • Click Next

Configure Stack Options

  • You can skip the other options here, and click Next

Review

  • Tick this box under Capabilities - since the CloudFormation stack will be creating IAM roles/policies
  • Click Create Stack

Check Status of Stack Creation

On the CloudFormation Console > Stacks, click the stack you created

You should see the the current status on Stack Info tab, and more details under the Event tab

Wait for Status to change to CREATE_COMPLETE before proceeding to the next step below

Enable Amazon Connect Data Streaming

Now that the Kinesis Stream and Firehose have been setup, we can now enable data streaming from Amazon Connect.

  • Go to Amazon Connnect > select your Amazon Connect instance
  • Go to Data Streaming
    • Tick Enable data streaming
    • Contact Trace Records
      • Select Kinesis Stream
      • Select connect-ctr
    • Agent Events
      • Select Kinesis Stream
      • Select connect-agentevents

Authorize Emite AWS Account to Use OpenSearch VPC Endpoint

Now that the Kinesis Stream and Firehose have been set up, we can now enable data streaming from Amazon Connect.

  • Go to the OpenSearch Console > Select the "emite-kinesis-connect"
  • Go to VPC Endpoints tab > Select Authorize Principal
    • Input the AWS Account ID referring to EmiteAccountID parameter.

Complete Registration / Send data to eMite team

Data to be sent to eMite team can be found on the Outputs Tab of the created stack:

  • Amazon Connect Instance ARN
    • Copy the Value for AmazonConnectInstanceARN
  • Elasticsearch Domain Endpoint ARN:
    • Copy the Value for ESDomainEndpointURL
  • eMite Role ARN
    • Copy the ARN returned for EmiteRoleARN
  • AgentEvents Kinesis Stream ARN
    • Copy the Value returned for AgentEventsKinesisARN
  • CTR Kinesis Stream ARN
    • Copy the Value returned for CTRKinesisARN
  • Contact Lens Bucket ARN (if using Contact Lens integration)
    • Copy the Value returned for ContactLensBucket

Additional steps if using Customer-Managed Keys (CMK) for encryption 

If you're using CMK's for encrypting Amazon Connect / Kinesis streams, you'll need to update the Key Policy of the CMK to allow the eMite IAM Role permission to use kms:decypt action

  • Go to KMS > select the Customer Managed Key you're using to encrypt Amazon Connect / Kinesis Streams 
  • Edit the policy and add this section:

{
"Sid": "Allow use of the key to decrypt",
"Effect": "Allow",
"Principal": {
"AWS": "<EmiteRoleARN>"
},
"Action": "kms:Decrypt",
"Resource": "*"
}

  • This will allow the eMite IAM Role to decrypt using the CMK

If you're using Permissions Boundaries on your account, you'll also need to add permission to allow KMS actions on the policy.