Overview

Document Purpose: This document outlines the infrastructure and configuration requirements for deploying the CSI (Genesys Cloud Data Adapter) platform in a customer-hosted environment. The platform synchronises Genesys Cloud operational and historical data into PostgreSQL, MSSQL, or Snowflake databases for analytics and reporting.

Architecture Overview

The CSI platform consists of two primary components:

┌─────────────────────┐         ┌──────────────────────┐
│  Application Server │────────▶│  Database Server     │
│  (Docker Container) │         │  PostgreSQL/MSSQL/   │
│                     │         │  Snowflake           │
└─────────────────────┘         └──────────────────────┘
         │
         │ HTTPS
         ▼
┌─────────────────────┐
│   Genesys Cloud     │
│   API Endpoints     │
└─────────────────────┘

Key Components:

• Application Server: Runs the Genesys Adapter as a Docker container
• Database Server: Stores synchronised data (PostgreSQL, MSSQL, or Snowflake)
• Genesys Cloud: Source system providing operational data via REST APIs

Application Server Requirements

Minimum Specifications (REQUIRED)

Recommended Operating Systems

Linux (Preferred):

• Ubuntu 22.04 LTS
• Amazon Linux 2023
• Red Hat Enterprise Linux 8+
• Debian 11+

Windows (Supported):

• Windows Server 2019/2022 with Docker Desktop

Note: Linux is strongly preferred for simplified deployment, better performance, and ongoing support.

Software Prerequisites

• Docker Engine 20.10 or higher
• Docker Compose 2.0 or higher
• SSH server (for remote access and deployment)
• Git (optional, for version control)
• curl or wget (for connectivity testing)

Database Server Requirements

Supported Database Types

The adapter supports three database platforms:

1. PostgreSQL (Most Common)
2. Microsoft SQL Server (MSSQL)
3. Snowflake (Cloud Data Warehouse)

PostgreSQL Server Specifications

MSSQL Server Specifications

Snowflake Specifications

Database Configuration

Required Database Settings (PostgreSQL):

• Database name: contactcentredb (or customer-preferred name)
• Character encoding: UTF8
• Collation: en_US.UTF-8 (or appropriate locale)
• Timezone: UTC (recommended for consistency)

Connection Settings (PostgreSQL):

• max_connections: 100 or higher
• shared_buffers: 25% of available RAM
• effective_cache_size: 50-75% of available RAM
• work_mem: 16-64 MB (adjust based on concurrent queries)
• maintenance_work_mem: 256 MB - 1 GB

Database User Permissions

PostgreSQL:

-- Create database and user
CREATE DATABASE contactcentredb WITH ENCODING 'UTF8';
CREATE USER genesys_adapter WITH PASSWORD 'secure_password';

-- Grant required permissions
GRANT CREATE, CONNECT ON DATABASE contactcentredb TO genesys_adapter;
GRANT CREATE ON SCHEMA public TO genesys_adapter;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO genesys_adapter;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO genesys_adapter;
GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO genesys_adapter;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO genesys_adapter;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO genesys_adapter;

Minimum Required Privileges:

• CREATE - For creating tables, indexes, and functions
• ALTER - For modifying table structures
• INSERT, UPDATE, DELETE, SELECT - For data operations
• TRUNCATE - For data cleanup operations
• EXECUTE - For stored procedures and functions

Storage Sizing Guidelines

Estimate database storage requirements based on your call center metrics:

Important: Storage requirements increase significantly with: - Longer retention periods (5-7 years is common for regulatory compliance) - Additional data types (voice analytics, real-time data, recordings metadata, quality evaluations) - Voice transcripts and sentiment analysis data - Plan for 20-30% annual growth in storage requirements

Storage Calculation Basis:

• Base interaction data: ~1-2 KB per interaction (conversation summary, participants)
• Detailed segments: ~2-3 KB per interaction (detailed interaction data, attributes)
• Voice analytics: +20-30 KB per voice interaction (transcripts, sentiment, topics)
• Real-time data: Minimal incremental (aggregated hourly/daily)
• Quality evaluations: ~3-5 KB per evaluated interaction
• Workforce management: ~5-10% overhead for schedules and adherence

Network Requirements

Firewall Rules

Outbound (from Application Server):

Inbound (to Application Server):

• SSH (port 22) - For deployment and administration
• Optional: Monitoring endpoints (Prometheus, health checks)

Inbound (to Database Server):

• Port 5432 (PostgreSQL) or 1433 (MSSQL) from Application Server IP - Database connections
• Optional: Port 5432/1433 from BI/reporting tools for direct database access

Network Connectivity Testing

Before deployment, verify connectivity:

# Test Genesys Cloud API access
curl -I https://api.mypurecloud.com.au

# Test PostgreSQL connectivity
psql -h <database-host> -U <database-user> -d contactcentredb -c "SELECT version();"

# Test MSSQL connectivity (using sqlcmd)
sqlcmd -S <database-host> -U <database-user> -P <password> -Q "SELECT @@VERSION"

# Test NTP synchronisation
ntpdate -q pool.ntp.org

# Test DNS resolution
nslookup api.mypurecloud.com.au

SSL/TLS Requirements

• All connections to Genesys Cloud APIs use HTTPS (TLS 1.2+)
• Database connections should use SSL/TLS encryption:
• PostgreSQL: SSL Mode=Require in connection string
• MSSQL: Encrypt=True in connection string
• Snowflake: HTTPS by default
• Docker registry connections use HTTPS

AWS Self-Hosting Reference

The preceding sections describe the platform's generic compute, database, and network requirements. This section maps those requirements to a concrete deployment on Amazon Web Services for customers self-hosting the platform in their own AWS account.

The subsections below mirror the same order as the requirements above — Application Server on AWS, Database on AWS, Network on AWS — and add AWS-specific operational concerns (IAM, secrets, monitoring, and backup). All resources should be provisioned in a single AWS region matched to the Genesys Cloud region.

Region Selection

Choose the AWS region closest to the corresponding Genesys Cloud region to minimise API latency and cross-region data egress. Every other resource described in this section should be provisioned in this same region.

Reference Architecture

The diagram below summarises the recommended layout. The components shown are described in the subsections that follow.

Architecture diagram — see PNG export embedded in the article.

Application Server on AWS

This subsection translates the Application Server Requirements into specific AWS compute resources. Use the workload tier matching your daily interaction volume to select an instance type, EBS configuration, and AMI.

EC2 Instance Sizing

Recommended EC2 instance types for the Genesys Adapter, sized by daily interaction volume:

Notes on instance choice: - Architecture: x86_64 (AMD64) is required. ARM64 / Graviton (t4g, m7g) instances are not supported by the current container image. - Burstable (t3/t3a): Acceptable for small workloads or non-production. Enable Unlimited mode so CPU credits do not throttle scheduled jobs. Avoid for real-time WebSocket workloads. - AMD vs Intel (m5a/m6a vs m5/m6i): AMD variants offer comparable performance and are an acceptable substitute. - Compute-optimised (c6i): Preferred when running heavy voice analytics / transcript processing. - Use the latest generation available in your region (e.g., m7i over m6i where supported) for better price/performance.

EBS Storage

EBS recommendations: - Use gp3 rather than gp2 for better baseline performance and configurable IOPS/throughput. - Enable EBS encryption at rest using AWS-managed (aws/ebs) or customer-managed KMS keys. - Enable EBS snapshots via AWS Backup or Data Lifecycle Manager (daily, 7–30 day retention). - For high-volume environments processing voice transcripts, mount a separate data volume to isolate Docker storage from the OS.

Amazon Machine Image (AMI)

Always use the latest patched AMI from AWS Marketplace or the official publisher. Enable EC2 Image Builder or rebuild on a regular cadence to pick up security patches.

Database on AWS

This subsection translates the Database Server Requirements into AWS-managed database options. Amazon RDS is recommended for PostgreSQL and SQL Server workloads; Snowflake remains the option when the target is a cloud data warehouse.

Amazon RDS (PostgreSQL or SQL Server)

When using Amazon RDS instead of a self-managed database server, size the instance class to the same workload tier used for the application server:

Configuration recommendations:

RDS vs. self-managed on EC2: RDS is strongly recommended over running PostgreSQL/MSSQL on EC2 — it provides automated backups, Multi-AZ failover, patching, and monitoring out of the box. Use self-managed only when specific extensions or configurations are not supported by RDS.

Snowflake on AWS

When using Snowflake as the target data warehouse:

• Region matching: Provision the Snowflake account in the same AWS region as the EC2 instance (e.g., AWS_AP_SOUTHEAST_2 for Sydney).
• PrivateLink (recommended for production): Use AWS PrivateLink for Snowflake to keep traffic off the public internet. Requires Snowflake Business Critical edition or higher.
• Warehouse sizing: Start with X-SMALL for ingestion; scale to SMALL/MEDIUM if Snowflake-side query concurrency increases.
• Authentication: Use key pair authentication (RSA 2048+) — store the private key in AWS Secrets Manager, not on the EC2 filesystem.
• Network policy: Restrict Snowflake account access to the EC2 instance's NAT Gateway Elastic IP (or VPC endpoint when using PrivateLink).

Network on AWS

This subsection translates the Network Requirements into a concrete AWS VPC layout, security groups, and supporting endpoints.

VPC and Subnets

Supporting components:

• Internet Gateway (IGW) — attached to the VPC for public subnet egress.
• NAT Gateway — in a public subnet, allowing the private EC2 instance to reach Genesys Cloud APIs. Allocate an Elastic IP so Genesys Cloud / Snowflake IP allowlists remain stable.
• Route tables — private subnets route 0.0.0.0/0 via the NAT Gateway; data subnets have no internet route.
• VPC Endpoints (recommended) — to reduce NAT Gateway egress traffic and improve security:
• com.amazonaws.<region>.s3 (Gateway endpoint) — for backups and AWS CLI usage
• com.amazonaws.<region>.secretsmanager (Interface endpoint) — for credential retrieval
• com.amazonaws.<region>.logs (Interface endpoint) — for CloudWatch Logs
• com.amazonaws.<region>.ssm / ssmmessages / ec2messages — for Systems Manager Session Manager (replaces SSH bastion)

Security Groups

Prefer AWS Systems Manager Session Manager over SSH bastion hosts — eliminates the need for inbound port 22 and SSH key management entirely.

Security and Operations on AWS

These AWS-managed services support the secure operation of the platform. Together they cover identity (IAM), credential storage (Secrets Manager), observability (CloudWatch), and resilience (AWS Backup).

IAM Role for the EC2 Instance

Attach an EC2 instance profile with an IAM role granting only the permissions the adapter actually needs. Do not embed AWS credentials inside the container or appsettings.json.

Minimum policy statements:

Follow the principle of least privilege — never attach AdministratorAccess or wildcard resource ARNs.

Secrets Management

Store all sensitive configuration in AWS Secrets Manager (preferred) or AWS Systems Manager Parameter Store (SecureString):

Inject secrets into the container at startup using the EC2 IAM role and a small entrypoint wrapper, or via environment variable references. Never bake secrets into Docker images.

Logging and Monitoring (CloudWatch)

Backup and Disaster Recovery

For multi-region DR, replicate RDS snapshots and EBS snapshots to a secondary AWS region using AWS Backup cross-region copy.

Genesys Cloud Requirements

OAuth Client Credentials

The adapter authenticates to Genesys Cloud using an OAuth Client Credentials grant assigned to a dedicated role. The recommended setup is to import the supplied permission policy file into a new role rather than ticking permissions individually — the policy set spans ~80 entities across analytics, routing, wfm, quality, recording, speechAndTextAnalytics, knowledge, outbound, architect, audits, directory, groups, learning, coaching, conversation, externalContacts, billing, oauth, and authorisation domains.

Step-by-step walkthrough: Genesys Cloud OAuth for Genesys Adapter — follow this knowledge base article for the authoritative procedure (screenshots and current UI paths).

Setup overview:

1. Create a role in Genesys Cloud (Admin → People & Permissions → Roles / Permissions → Add Role), name it e.g. Genesys Adapter Integration.
2. Import the permission policy file schema/GCPermissions.json into the role using the Import option on the role's Permissions tab. This applies the complete permission set required by every adapter job in a single action.
3. Create the OAuth client (Admin → Integrations → OAuth → Add Client): - Grant Type: Client Credentials - Authorised Roles: select the role created in step 1 - Token Duration: leave at default (86400s)
4. Assign the role to a Division that includes every queue, user, and conversation the adapter must read (typically the Home division for full-tenant access).
5. Capture the Client ID and Client Secret — store both in a secrets manager (e.g., AWS Secrets Manager, Azure Key Vault). The secret is shown once at creation.

Permission policy file:

The canonical permission set lives at schema/GCPermissions.json in this repository and is the same file referenced by the knowledge base article. Re-import this file whenever the adapter is upgraded so newly required permissions are picked up automatically.

Credential Format:

• Client ID — GUID format (e.g., 12345678-1234-1234-1234-123456789abc)
• Client Secret — opaque string (treat as a password; never commit to source control)
• Region identifier — one of mypurecloud.com, mypurecloud.ie, mypurecloud.de, mypurecloud.com.au, mypurecloud.jp, aps1.pure.cloud, usw2.pure.cloud, cac1.pure.cloud — must match the Genesys Cloud organisation's region.

API Rate Limits

The application respects Genesys Cloud API rate limits: - Default: 300 requests per minute per OAuth client - Concurrent requests: Limited to 10 simultaneous requests - Token refresh: Automatic every 275 requests (300 limit with buffer) - Retry logic: Exponential backoff (2-30 seconds) for rate limit errors

For high-volume environments (50k+ daily interactions), consider: - Requesting increased rate limits from Genesys Cloud support - Using multiple OAuth clients for different job categories - Scheduling jobs to avoid peak API usage times

Pre-Deployment Checklist

Use this checklist to ensure readiness before deployment:

Infrastructure

• [ ] EC2 instance (or equivalent VM) provisioned with minimum specifications
• [ ] Operating system installed and updated (Ubuntu 22.04 LTS recommended)
• [ ] Docker Engine and Docker Compose installed and tested
• [ ] Dedicated service account created with Docker permissions
• [ ] SSH access configured and tested
• [ ] Disk space verified (80+ GB available)
• [ ] Time synchronisation (NTP) configured and verified

Database

• [ ] Database server installed and running (PostgreSQL/MSSQL/Snowflake)
• [ ] Database contactcentredb created (or customer-preferred name)
• [ ] Database user created with required permissions (see SQL scripts above)
• [ ] Network connectivity tested from application server to database
• [ ] SSL/TLS encryption enabled for database connections
• [ ] Backup strategy configured and tested (daily backups minimum)
• [ ] Firewall rules configured for database port (5432/1433)
• [ ] Storage capacity verified based on sizing guidelines
• [ ] Database performance tuning applied (shared_buffers, work_mem, etc.)

Network

• [ ] Outbound HTTPS access to Genesys Cloud API verified (curl test)
• [ ] Outbound access to database server verified (psql/sqlcmd test)
• [ ] Inbound SSH access configured and tested
• [ ] DNS resolution tested for all required endpoints
• [ ] NTP synchronisation verified (ntpdate -q pool.ntp.org)
• [ ] Firewall rules documented and applied
• [ ] Proxy configuration documented (if applicable)
• [ ] VPN requirements documented (if applicable)

Genesys Cloud

• [ ] Genesys Cloud region identified (e.g., mypurecloud.com.au)
• [ ] Integration role created and schema/GCPermissions.json imported into the role
• [ ] Role assigned to a Division covering all in-scope queues, users, and conversations
• [ ] OAuth client created with Client Credentials grant and the integration role attached
• [ ] Client ID and Client Secret captured and stored in the chosen secrets manager
• [ ] API access tested with credentials (curl with bearer token)
• [ ] Test API calls successful (users, queues, conversations)
• [ ] Rate limit requirements assessed (standard or increased limits)

Access & Credentials

• [ ] Remote access credentials provided to deployment team (SSH keys)
• [ ] Database connection string documented and tested
• [ ] Genesys Cloud OAuth credentials documented (Client ID/Secret)
• [ ] Environment variable template prepared (see configuration section)
• [ ] Any proxy or VPN requirements documented
• [ ] Secure credential storage method confirmed (e.g., Azure Key Vault)

Documentation

• [ ] Customer-specific configuration documented
• [ ] Job schedule requirements documented
• [ ] Data retention policies documented
• [ ] Backup and recovery procedures documented
• [ ] Escalation contacts documented
• [ ] Monitoring and alerting requirements documented

AWS-Specific (if self-hosting on AWS)

Complete these items in addition to the sections above.

• [ ] AWS region selected to match the Genesys Cloud region
• [ ] VPC with public + private app + private data subnets across two AZs, route tables, IGW and NAT Gateway provisioned
• [ ] Security groups (sg-adapter-ec2, sg-rds, optional sg-bastion) created with least-privilege rules
• [ ] EC2 instance launched with the recommended type, IMDSv2 enforced, and EBS encryption enabled
• [ ] EC2 IAM instance profile attached with scoped permissions (Secrets Manager, KMS, CloudWatch Logs, SSM)
• [ ] RDS instance provisioned with Multi-AZ, encryption at rest, automated backups, and deletion protection
• [ ] Secrets stored in AWS Secrets Manager (DB password, Genesys client secret, Snowflake key)
• [ ] CloudWatch Log Group created and Docker awslogs driver configured
• [ ] CloudWatch alarms configured (EC2 CPU, RDS storage, RDS CPU, status checks)
• [ ] AWS Backup plan covering EBS volumes (RDS snapshots are managed natively)
• [ ] Session Manager access verified (no inbound SSH from the public internet)
• [ ] VPC endpoints created for S3, Secrets Manager, CloudWatch Logs, and SSM (recommended)

Getting Help

Support Channels:

• Technical Support: Contact your Customer Science representative
• Support Line: +61 2 8214 6695
• Support Email: support@customerscience.com.au
• Documentation Portal: https://support2.customerscience.com.au/portal/en/kb

Information to Provide When Requesting Support:

1. Application logs (last 1000 lines): docker logs --tail 1000 genesys-adapter
2. Job configuration (environment variables, sanitised)
3. Database type and version
4. Error messages and stack traces
5. Job name and execution time
6. Recent changes to configuration or infrastructure

Document Owner: Customer Science Product Team Last Updated: May 2026 Version: 2.4