Skip to main content
This workflow guides you through creating an integration with an external system and testing its connection. Related: Source: Feature Inventory, Source: Feature Inventory

​
Goal

Create a new integration with an external system, configure its connection parameters, and verify it’s working correctly.

​
Preconditions

  • Access to a Veratrace instance
  • Valid AWS Cognito authentication
  • Appropriate permissions to create and manage integrations (Administrator or Editor role)
  • Credentials for the external system you want to integrate
  • Backend API running at http://localhost:8080 (development)
Source: Source: Feature Inventory

​
Permissions

Required roles: Administrator or Editor (inferred from mock roles)
Source: Source: Feature Inventory

​
UI Steps

Screenshot: Integrations Create Page (TODO)

​
Step 1: Navigate to Create Page

  1. Click Integrations in the navigation sidebar
  2. Click Create Integration button or navigate directly to /integrations/create
UI Route: /integrations/create Component: CreateIntegrationPage (wraps AddEditIntegrationPage) Source: /Users/vincentgraham/clearline-ui/src/app/routes/routerConfig.jsx (line 126-127)

​
Step 2: Select Integration Type

  1. Choose integration type from the list (40+ types available)
  2. Integration types include:
    • Contact Center/CX: AMAZON_CONNECT, GENESYS_CLOUD, ZENDESK, etc.
    • CRM/Sales: SALESFORCE, HUBSPOT, MICROSOFT_DYNAMICS, etc.
    • AI Agents: INTERCOM_FIN, MICROSOFT_COPILOT, etc.
    • Data/Documents: AWS_S3, SNOWFLAKE, etc.
    • And more…
UI Route: /integrations/create Component: AddEditIntegrationPage Source: /Users/vincentgraham/clearline-ui/src/features/integrations/types/integration.js (line 6-84)

​
Step 3: Configure Integration

  1. Enter Name - Integration name (required)
  2. Fill in integration-specific configuration fields
Example for Amazon Connect:
  • Instance ID
  • Access Key ID
  • Secret Access Key
  • AWS Region
Example for Salesforce:
  • Instance URL
  • Consumer Key
  • Consumer Secret
  • Username
  • Password + Security Token
UI Route: /integrations/create Component: AddEditIntegrationPage Source: /Users/vincentgraham/clearline-ui/src/features/integrations/types/integration.js (line 111-150, 178-225)

​
Step 4: Save Integration

  1. Click Save or Create button
  2. Integration is created with status “connecting”
UI Route: /integrations/create Component: AddEditIntegrationPage Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js

​
Step 5: Test Connection

  1. Navigate to /integrations/:integrationId/edit
  2. Click Test Connection button
  3. Wait for test results
UI Route: /integrations/:integrationId/edit Component: AddEditIntegrationPage Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 346-386)

​
Step 6: Verify Status

  1. Check integration status:
    • active - Integration is operational
    • inactive - Integration is disabled
    • connecting - Integration is being set up
    • error - Integration has encountered an error
  2. Check health information:
    • isHealthy - Whether integration is currently healthy
    • lastHealthCheck - When last health check was performed
UI Route: /integrations or /integrations/:integrationId/edit Component: IntegrationsLandingPage or AddEditIntegrationPage Source: /Users/vincentgraham/clearline-ui/src/features/integrations/types/integration.js (line 100-106)

​
Backend API Calls

​
Create Integration

Endpoint: POST /instances/:instanceId/integrations Called when: User clicks “Save” or “Create” button Request: 
{
  "name": "Amazon Connect Integration",
  "type": "AMAZON_CONNECT",
  "metadata": {
    "instanceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}
Response: Created integration object Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 191-243)

​
Test Connection

Endpoint: POST /instances/:instanceId/integrations/:integrationId/test Called when: User clicks “Test Connection” button Request: No body (uses integrationId from URL) Response: 
{
  "success": true,
  "message": "Connection successful",
  "timestamp": "2024-12-26T..."
}
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 346-386)

​
Update Integration

Endpoint: PUT /instances/:instanceId/integrations/:integrationId Called when: User clicks “Save” in edit mode Request: Same as Create Integration Response: Updated integration object Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 252-296)

​
Get Integration

Endpoint: GET /instances/:instanceId/integrations/:integrationId Called when: Loading integration for editing Response: Integration object Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 142-183)

​
List Integrations

Endpoint: GET /instances/:instanceId/integrations Called when: Loading integrations list page Query Parameters:
  • type - Filter by integration type
  • status - Filter by status
  • search - Search by name/description
  • page, size, sort - Pagination and sorting
Response: Paginated response with integration list Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 21-134)

​
Audit/Evidence Implications

Source: Source: Feature Inventory Source: Source: Feature Inventory

​
Troubleshooting

​
Error: “Instance configuration not available”

Cause: Instance config not loaded or invalid Solution:
  • Verify authentication is complete
  • Check instance ID is valid
  • Refresh page and retry
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 24-26)

​
Error: “Failed to create integration”

Cause: Invalid integration data or backend error Solution:
  • Verify all required fields are filled
  • Check integration type-specific requirements
  • Verify credentials are correct
  • Review backend logs for details
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 211-213)

​
Connection Test Fails

Cause: Invalid credentials, network issues, or external system unavailable Solution:
  • Verify credentials are correct
  • Check network connectivity
  • Verify external system is accessible
  • Review connection test response message
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/api/integrations.js (line 365-367)

​
Integration Status: “error”

Cause: Integration encountered an error during operation Solution:
  • Check integration health information
  • Review last health check timestamp
  • Test connection again
  • Verify external system is operational
  • Check integration logs
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/types/integration.js (line 100-106)

​
Integration Status: “connecting”

Cause: Integration is still being set up Solution:
  • Wait for setup to complete
  • Check integration health periodically
  • Test connection to verify setup completed
Source: /Users/vincentgraham/clearline-ui/src/features/integrations/types/integration.js (line 100-106)