Skip to content

DendriticShadow/connect-contactflow-generator

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
frontend
frontend
 
 
README.md
README.md
 
 

Repository files navigation

Amazon Connect Resource Automation Web Application

Project Overview

This web application automates the creation of Amazon Connect resources through a simple, user-friendly interface. Users authenticate via AWS Cognito, fill out a form, and trigger the automated creation of hours of operation, queues, contact flows, and phone number assignment - all with a single click.

Goals

Primary Objective: Eliminate manual, repetitive tasks in Amazon Connect by providing a self-service portal for creating standardized contact center resources.

Specific Goals:

  1. Reduce time to provision new contact flows from hours to minutes
  2. Ensure consistency across all created resources using templates
  3. Minimize human error in resource configuration
  4. Enable non-technical users to provision Connect resources safely
  5. Provide audit trail of all automated resource creation

How It Works

User Workflow

  1. Login: User authenticates via AWS Cognito
  2. Select Instance: Choose the Amazon Connect instance from a dropdown menu
  3. Configure Hours of Operation:
    • Enter a name for the hours of operation
    • Select timezone
    • Use visual time picker to set operating hours
  4. Configure Queue:
    • Enter queue name
    • Automatically links to the hours of operation created above
  5. Configure Contact Flow:
    • Enter contact flow name
    • Provide S3 URI to the contact flow template (JSON file)
    • System automatically updates the "Set Working Queue" block with the new queue
  6. Phone Number (Optional):
    • System attempts to claim a toll-free number
    • Associates it with the newly created contact flow
    • If claiming fails, resources are still created successfully
  7. Submit: Click submit and watch the progress

Backend Workflow

User Submits Form
       ↓
API Gateway (Cognito Authorizer validates JWT)
       ↓
Step Functions State Machine Starts
       ↓
   ┌───────────────────────────────────┐
   │  Step 1: Validate Input           │
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 2: Create Hours of Operation│ → Returns HoO ID & ARN
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 3: Create Queue             │ → Uses HoO ID, Returns Queue ARN
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 4: Copy Contact Flow        │
   │  - Download template from S3      │
   │  - Update Queue ARN in JSON       │
   │  - Create in Connect              │ → Returns Contact Flow ID & ARN
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 5: Claim Phone Number       │ → Returns Phone Number (Optional)
   │  (Failure here doesn't rollback)  │
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 6: Associate Phone to Flow  │
   └───────────┬───────────────────────┘
               ↓
   ┌───────────────────────────────────┐
   │  Step 7: Notify User of Success   │
   └───────────────────────────────────┘

Rollback Logic:

  • If Hours of Operation fails → No rollback needed (first step)
  • If Queue fails → Delete Hours of Operation
  • If Contact Flow fails → Delete Queue → Delete Hours of Operation
  • If Phone Claiming fails → NO ROLLBACK (resources remain, phone can be assigned manually later)

Architecture

Frontend

  • Technology: React 18 with Vite
  • Hosting: Amazon S3 (static site) + CloudFront (CDN)
  • Authentication: AWS Amplify UI + Cognito User Pools
  • Styling: CSS Modules (or Tailwind CSS - TBD)
  • State Management: React Context API

Backend

  • API Layer: Amazon API Gateway (REST API)
  • Orchestration: AWS Step Functions (Standard Workflows)
  • Compute: AWS Lambda (Python 3.12 with boto3)
  • Storage: Amazon S3 (for contact flow templates)
  • State Tracking: Amazon DynamoDB (optional, for execution history)

AWS Services Required

Service Purpose Configuration
Cognito User Pool User authentication Email/password, MFA optional
S3 Bucket (Templates) Store contact flow JSON templates Versioning enabled, private
S3 Bucket (Frontend) Host React application Public read, static website hosting
CloudFront CDN for frontend Origin: S3 frontend bucket
API Gateway REST API endpoints Cognito authorizer, CORS enabled
Step Functions Workflow orchestration Standard workflow, 7 Lambda integrations
Lambda Functions Business logic (7 functions total) Python 3.12, 512MB RAM, 30s timeout
IAM Roles Permissions Lambda execution role, Step Functions role
DynamoDB (optional) Execution history tracking On-demand billing

Region

  • Fixed Region: us-east-1

Infrastructure Components

1. Cognito User Pool

  • Purpose: Authentication and authorization
  • Users: Manual creation or self-registration
  • Attributes: Email (required), name
  • MFA: Optional (can be enabled later)

2. S3 Buckets

Template Bucket

Bucket Name: connect-automation-templates-{account-id}
├── templates/
│   ├── customer-service-flow.json
│   ├── sales-flow.json
│   └── support-flow.json
└── README.md

Frontend Bucket

Bucket Name: connect-automation-frontend-{account-id}
├── index.html
├── assets/
│   ├── index-{hash}.js
│   └── index-{hash}.css
└── favicon.ico

3. Lambda Functions

Function Name Purpose Timeout
ListConnectInstances Populate instance dropdown 10s
CreateHoursOfOperation Create HoO in Connect 30s
CreateQueue Create queue with HoO reference 30s
CopyUpdateContactFlow Download template, update queue, create flow 60s
ClaimPhoneNumber Search and claim toll-free number 30s
AssociatePhoneToFlow Link phone to contact flow 30s
NotifyUser Send success/failure notification 10s

Rollback Functions:

  • RollbackHoursOfOperation
  • RollbackQueue
  • RollbackContactFlow
  • RollbackPhoneNumber (only disassociates, doesn't release)

4. API Gateway Endpoints

POST /automation/start
  - Trigger: User submits form
  - Auth: Cognito authorizer (requires valid JWT)
  - Request Body: { instanceId, hoursConfig, queueConfig, flowConfig, templateS3Uri }
  - Response: { executionArn, message }

GET /automation/status/{executionId}
  - Trigger: Frontend polls for status
  - Auth: Cognito authorizer
  - Response: { status, currentStep, result }

GET /instances
  - Trigger: Page load (populate dropdown)
  - Auth: Cognito authorizer
  - Response: { instances: [{id, name, alias}] }

5. Step Functions State Machine

State Machine Name: ConnectResourceAutomation

States:

  1. ValidateInput (Lambda)
  2. CreateHoursOfOperation (Lambda)
  3. CreateQueue (Lambda)
  4. CopyAndUpdateContactFlow (Lambda)
  5. ClaimPhoneNumber (Lambda - optional)
  6. AssociatePhoneToFlow (Lambda - optional)
  7. NotifySuccess (Pass state)
  8. RollbackQueue (Lambda - on error)
  9. RollbackHoursOfOperation (Lambda - on error)
  10. NotifyFailure (Pass state)

Execution Input Example:

{
  "instanceId": "connect-instance-id-here",
  "hoursOfOperation": {
    "name": "Business Hours - Sales",
    "description": "Mon-Fri 9am-5pm EST",
    "timeZone": "America/New_York",
    "config": [
      { "Day": "MONDAY", "StartTime": {"Hours": 9, "Minutes": 0}, "EndTime": {"Hours": 17, "Minutes": 0} },
      { "Day": "TUESDAY", "StartTime": {"Hours": 9, "Minutes": 0}, "EndTime": {"Hours": 17, "Minutes": 0} },
      { "Day": "WEDNESDAY", "StartTime": {"Hours": 9, "Minutes": 0}, "EndTime": {"Hours": 17, "Minutes": 0} },
      { "Day": "THURSDAY", "StartTime": {"Hours": 9, "Minutes": 0}, "EndTime": {"Hours": 17, "Minutes": 0} },
      { "Day": "FRIDAY", "StartTime": {"Hours": 9, "Minutes": 0}, "EndTime": {"Hours": 17, "Minutes": 0} }
    ]
  },
  "queueConfig": {
    "name": "Sales Queue - East",
    "description": "Sales team queue for East region",
    "maxContacts": 10
  },
  "flowConfig": {
    "name": "Sales IVR - East",
    "description": "Customer-facing sales IVR",
    "templateS3Uri": "s3://connect-automation-templates-123456789012/templates/sales-flow.json"
  },
  "claimPhoneNumber": true,
  "phoneNumberDescription": "Sales line - East"
}

IAM Permissions Required

Lambda Execution Role

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "connect:ListInstances",
        "connect:CreateHoursOfOperation",
        "connect:CreateQueue",
        "connect:CreateContactFlow",
        "connect:SearchAvailablePhoneNumbers",
        "connect:ClaimPhoneNumber",
        "connect:AssociatePhoneNumberContactFlow",
        "connect:DeleteHoursOfOperation",
        "connect:DeleteQueue",
        "connect:DeleteContactFlow"
      ],
      "Resource": [
        "arn:aws:connect:us-east-1:*:instance/*",
        "arn:aws:connect:us-east-1:*:instance/*/queue/*",
        "arn:aws:connect:us-east-1:*:instance/*/hours-of-operation/*",
        "arn:aws:connect:us-east-1:*:instance/*/contact-flow/*",
        "arn:aws:connect:us-east-1:*:phone-number/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::bucketnamehere-*/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:us-east-1:*:*"
    }
  ]
}

Project Directory Structure

connect-automation-webapp/
├── PROJECT-README.md                 # This file
├── frontend/                         # React application
│   ├── src/
│   │   ├── components/
│   │   │   ├── Login.jsx            # Cognito login
│   │   │   ├── InstanceSelector.jsx # Connect instance dropdown
│   │   │   ├── HoursOfOperationForm.jsx # HoO configuration
│   │   │   ├── QueueForm.jsx        # Queue configuration
│   │   │   ├── ContactFlowForm.jsx  # Flow configuration
│   │   │   ├── TimePicker.jsx       # Visual time picker
│   │   │   └── ProgressTracker.jsx  # Step Functions progress
│   │   ├── services/
│   │   │   ├── api.js               # API Gateway calls
│   │   │   └── auth.js              # Cognito auth helpers
│   │   ├── App.jsx                  # Main app component
│   │   └── main.jsx                 # Entry point
│   ├── package.json
│   ├── vite.config.js
│   └── index.html
├── infrastructure/                   # AWS infrastructure code
│   ├── cloudformation/
│   │   ├── 01-cognito.yaml          # User pool
│   │   ├── 02-s3-buckets.yaml       # Template & frontend buckets
│   │   ├── 03-lambda-functions.yaml # All Lambda functions
│   │   ├── 04-step-functions.yaml   # State machine
│   │   ├── 05-api-gateway.yaml      # REST API
│   │   ├── 06-cloudfront.yaml       # CDN
│   │   └── main-stack.yaml          # Master stack (nested)
│   ├── lambda/                      # Lambda function code
│   │   ├── list_instances/
│   │   │   └── index.py
│   │   ├── create_hours_of_operation/
│   │   │   └── index.py
│   │   ├── create_queue/
│   │   │   └── index.py
│   │   ├── copy_update_contact_flow/
│   │   │   └── index.py
│   │   ├── claim_phone_number/
│   │   │   └── index.py
│   │   ├── associate_phone_to_flow/
│   │   │   └── index.py
│   │   └── rollback/
│   │       ├── rollback_hoo.py
│   │       ├── rollback_queue.py
│   │       └── rollback_flow.py
│   └── scripts/
│       ├── deploy.sh                # Deployment script
│       └── package-lambdas.sh       # ZIP Lambda functions
└── templates/                       # Sample contact flow templates
    ├── sample-customer-service-flow.json
    └── README.md

Getting Started

Prerequisites

  • AWS Account with Amazon Connect instance created
  • AWS CLI configured with appropriate credentials
  • Node.js 18+ and npm
  • Python 3.12+ (for Lambda functions)

Local Development (Frontend Only)

  1. Navigate to frontend directory:

    cd /connect-contactflow-generator/frontend

  2. Install dependencies:

    npm install

  3. Configure environment variables: Create .env.local file:

    VITE_AWS_REGION=us-east-1
VITE_COGNITO_USER_POOL_ID=your-user-pool-id
VITE_COGNITO_CLIENT_ID=your-client-id
VITE_API_GATEWAY_URL=your-api-url

  4. Start development server:

    npm run dev

  5. Access locally: Open browser to http://localhost:5173

Deployment

Step 1: Deploy Infrastructure

cd infrastructure
./scripts/deploy.sh

This will:

  • Create all CloudFormation stacks
  • Package and upload Lambda functions
  • Deploy API Gateway
  • Create Cognito User Pool
  • Set up S3 buckets
  • Configure CloudFront distribution

Step 2: Upload Contact Flow Templates

aws s3 cp templates/sample-customer-service-flow.json \
  s3://connect-automation-templates-{account-id}/templates/

Step 3: Build and Deploy Frontend

cd frontend
npm run build
aws s3 sync dist/ s3://connect-automation-frontend-{account-id}/
aws cloudfront create-invalidation --distribution-id {dist-id} --paths "/*"

Step 4: Create Cognito Users

aws cognito-idp admin-create-user \
  --user-pool-id {pool-id} \
  --username admin@example.com \
  --user-attributes Name=email,Value=admin@example.com \
  --temporary-password TempPass123!

Testing

Frontend Testing (Local)

cd frontend
npm run dev
  • Test UI components visually
  • Verify form validation
  • Test time picker functionality

Integration Testing (Post-Deployment)

  1. Login with test Cognito user
  2. Fill out form with test data
  3. Monitor Step Functions execution in AWS Console
  4. Verify resources created in Amazon Connect console
  5. Test phone number claiming (if applicable)

Rollback Testing

  1. Modify Lambda to intentionally fail at specific step
  2. Submit form
  3. Verify rollback deletes resources in correct order
  4. Check CloudWatch Logs for error messages

Monitoring & Troubleshooting

CloudWatch Dashboards

Create dashboard to monitor:

  • Step Functions execution success rate
  • Lambda function errors
  • API Gateway 4xx/5xx errors
  • Average execution time

Logs

  • Step Functions: View execution history in console
  • Lambda: CloudWatch Logs group per function
  • API Gateway: Access logs (if enabled)

About

Automated solution for creating contact flows in amazon connect

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages