> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot the AWS integration

> Diagnose and fix missing Contact Trace Records, CloudFormation failures, KMS errors, and stale Operata secrets in the Cloud Collector integration.

The Cloud Collector on Amazon Connect fails in four common ways: CTR delivery gaps, CloudFormation failures, integration monitoring gaps, and stale Operata secrets. Start at the section that matches your symptom.

## Before you start

* Admin access to the AWS account hosting the [Cloud Collector](/docs/concepts-cloud-collector).
* The Operata Group ID for the integration.
* AWS CLI configured with permissions for CloudWatch, Secrets Manager, and Amazon EventBridge.

## Contact Trace Records are not appearing in Operata

### Wait at least five minutes

Contact Trace Records (CTRs) only emit when the contact is fully closed. Allow up to five minutes between the contact ending and the record appearing in Operata.

Check the basics:

* The [Agent Experience Collector](/docs/collector-overview) is installed in the agent's browser.
* The CCP URL matches the Amazon Connect instance the stack was deployed against.
* The agent closed the contact (set status to `After Contact Work →
  Available` or similar).

### Check the source Kinesis stream for KMS encryption

If the Kinesis CTR stream uses a customer-managed AWS Key Management Service (KMS) key, the Amazon EventBridge Pipe execution role needs decrypt permission. Follow [Grant KMS access to the EventBridge Pipe](/docs/kms-encryption).

### Check the EventBridge Pipe status

In the AWS console, open **EventBridge → Pipes** and find `operataEventsPipe-{instance}-amazonConnect`. The status should be `RUNNING`. Click into the pipe and check **Monitoring** for delivery failures. The most common failures are KMS access denied (see above), Lambda timeouts (raise the Lambda's memory or VPC routing), and API destination 4xx responses (regenerate the Operata API token).

### Check the redactor Lambda logs

In the AWS console, open **CloudWatch → Log groups** and find `/aws/lambda/CloudCollectorV3Stack-cloudcollectorv3redactor-…`. Look for `ERROR` or `Task timed out`. Forward the relevant log lines to [Operata Support](mailto:support@operata.com).

## CloudFormation deployment fails

### Verify the deploying principal's IAM permissions

The stack creates IAM roles, Secrets Manager secrets, Amazon EventBridge resources, and a Lambda. Confirm the deploying principal has the [administrator deployment policy](/docs/iam-policies#administrator-deployment-policy) attached, or equivalent permissions.

### Check for leftover resources from a prior install

If CloudFormation reports `ResourceAlreadyExists` on Secrets Manager or the EventBridge connection, an earlier install left state behind. Follow [Rotate or delete Operata secrets](#rotate-or-delete-operata-secrets) below, then re-run the stack.

### Send the failure to Operata Support

If the deploy still fails, take a screenshot of the **Events** tab of the failed CloudFormation stack and send it to [Operata Support](mailto:support@operata.com).

## Monitor the integration

The Amazon EventBridge Pipe and the redactor Lambda emit CloudTrail events and CloudWatch metrics. Operata recommends:

* **CloudWatch alarm on `Invocations` failing** for the redactor Lambda (above zero over five minutes).
* **CloudWatch alarm on EventBridge Pipe delivery failures** (above zero over five minutes).
* **CloudTrail trail** for all `events`, `pipes`, and `lambda` API calls in the integration region.

For details on Pipe-specific monitoring, see [Monitoring EventBridge Pipes](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-monitoring.html) in the AWS documentation.

## Rotate or delete Operata secrets

The Cloud Collector stores credentials in two places:

1. **`cloud-collector-v3/ctr/{Operata Group ID}/apiToken`** in Secrets Manager — the Operata API token the Lambda uses to authenticate.
2. **`events!connection/operataAPIgroup-{Operata Group ID}/…`** in Secrets Manager — created by EventBridge when the API destination was registered. Holds the API destination connection credentials.

Rotate or delete them when you rotate the Operata API token, decommission the integration, or hit a `ResourceAlreadyExists` error on redeploy.

<Warning>
  **Deleting the API token secret immediately stops CTR delivery.**

  The Lambda can't authenticate with Operata while the secret is gone. No CTRs reach the Operata API until you create a new secret with a valid token.
</Warning>

### Delete the Secrets Manager API token

```bash theme={null}
# List Operata secrets in this region
aws secretsmanager list-secrets \
  --filters Key=name,Values=cloud-collector-v3

# Delete with the default seven-day recovery window
aws secretsmanager delete-secret \
  --secret-id "cloud-collector-v3/ctr/$OPERATA_GROUP_ID/apiToken"

# Or delete immediately (no recovery window — use with care)
aws secretsmanager delete-secret \
  --secret-id "cloud-collector-v3/ctr/$OPERATA_GROUP_ID/apiToken" \
  --force-delete-without-recovery
```

### Delete the EventBridge connection secret

Deleting the EventBridge connection deletes the associated secret.

```bash theme={null}
aws events list-connections

aws events delete-connection \
  --name "operataAPIgroup-$OPERATA_GROUP_ID"
```

### Console alternative

In the AWS console, open **Secrets Manager**, filter on `cloud-collector-v3`, select the secret, and choose **Actions → Delete**. To delete the EventBridge connection, open **EventBridge → API destinations → Connections** and delete `operataAPIgroup-{Group ID}`.

### Restore the integration after deletion

1. If you used the default recovery window, wait it out, or restore the secret in the console.
2. Update the CloudFormation stack — re-running it with a valid API token recreates both secrets.
3. Verify the pipe status returns to `RUNNING` and CTRs flow again under [Contact Trace Records are not appearing in Operata](#contact-trace-records-are-not-appearing-in-operata).

## Verify

Place a test contact through Amazon Connect. Within five minutes of contact end, the contact appears in **Get the Details** in the [Operata console](https://app.operata.io). If it doesn't, the [EventBridge Pipe monitoring panel](https://console.aws.amazon.com/events/home#/pipes) shows the failure reason.

## What next

* [Install CTR collection](/docs/ctr-installation) — re-run if you deleted the stack.
* [IAM policies reference](/docs/iam-policies) — the roles the stack creates and what each one is for.
* [Grant KMS access to the EventBridge Pipe](/docs/kms-encryption) — for CMK-encrypted streams.
* [Concept: Cloud Collector](/docs/concepts-cloud-collector) — the data path you're troubleshooting.