System Architecture
Core Features
Data Management
Frontend Components
Extensibility
The following files were used as context for generating this wiki page:
This document outlines the execution flow for testing an integration connection, specifically focusing on how the IntegrationPlatformTestPage initiates a connection test and how the backend API processes this request, including updating the connection's status in case of an error. This flow is crucial for users to verify their integration configurations and for the system to maintain accurate connection health.
The process begins when a user interacts with the IntegrationPlatformTestPage in the frontend application. This action triggers an API call to the backend, which then retrieves the connection details and its associated credentials. For AWS connections, a specialized validation routine is executed. If any part of the connection test fails, the system updates the connection's status to 'error' in the database, providing immediate feedback to the user and marking the connection as unhealthy.
The IntegrationPlatformTestPage is a React component that serves as a debug and testing interface for the integration platform. It displays a list of available integration providers and existing connections, allowing users to perform various actions like connecting, pausing, resuming, and testing connections. This page is the user-facing entry point for initiating a connection test.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:427-690
When a user clicks the "Test" button next to a connection on the IntegrationPlatformTestPage, the handleTestConnection asynchronous function is invoked. This function is responsible for orchestrating the client-side logic for testing a connection. It logs the action to the UI's action log, sets a loading state, and then makes an API call to the backend to initiate the actual connection test.
The function takes connectionId and providerSlug as arguments. It uses the testConnection mutation from useIntegrationMutations (which internally uses api.post to call the backend endpoint) and then logs the result (success or failure message) back to the UI. Finally, it refreshes the list of connections to reflect any status changes.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:498-508
Upon receiving the API request from the frontend (via api.post('/v1/integrations/connections/:id/test')), the ConnectionsController's testConnection method is executed. This method is the backend entry point for validating an integration connection.
It first retrieves the connection details using the provided connectionId. It then fetches the decrypted credentials associated with this connection from the credentialVaultService. If no credentials are found, it throws an error.
A critical branching point occurs here:
providerSlug is 'aws': The request is delegated to the testAwsConnection private method for AWS-specific validation.testConnection handler. If a handler exists, it's invoked with the decrypted credentials. If no handler is defined, the connection is simply activated, assuming it's a basic connection that doesn't require complex testing.In case of a successful test, the connection is activated. If the test fails (either by the handler returning false or throwing an error), setConnectionError is called to update the connection status to 'error' along with a descriptive message.
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:707-748
This private method within ConnectionsController is specifically designed to validate AWS integration credentials. It is called by testConnection when the providerSlug is 'aws'.
It reuses the validateAwsCredentials method to perform a comprehensive check, which involves:
Based on the validateAwsCredentials result:
success: true, activateConnection is called on the connectionService.success: false, setConnectionError is called on the connectionService with the validation error message.This method returns the validation result, which includes a success flag, a message, and optional details about region-specific checks.
Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:751-772
The setConnectionError method in ConnectionService is called when a connection test (or any other operation) fails and the connection needs to be marked as unhealthy. Its primary responsibility is to update the connection's status to 'error' and store the specific errorMessage provided.
It delegates the actual database update to updateConnectionStatus, passing 'error' as the new status and the received error message.
Sources: apps/api/src/integration-platform/services/connection.service.ts:150-153
This method in ConnectionService is a core utility for changing the operational state of an IntegrationConnection. It is called by setConnectionError (and activateConnection, pauseConnection) to perform the actual persistence of the status change.
Before updating, it first calls getConnection to ensure the connection with the given connectionId exists. This prevents attempting to update a non-existent record. After verification, it calls the connectionRepository.updateStatus method to persist the new status and error message (if any) to the database.
Sources: apps/api/src/integration-platform/services/connection.service.ts:139-147
The getConnection method in ConnectionService is a fundamental data access operation. It is called by updateConnectionStatus (and other service methods) to retrieve a specific IntegrationConnection record from the database using its connectionId.
If a connection with the given ID is not found, it throws a NotFoundException, ensuring that subsequent operations don't proceed with invalid data. This acts as a crucial validation step before any modifications are attempted.
Sources: apps/api/src/integration-platform/services/connection.service.ts:25-31
apps/app) to the NestJS backend (apps/api). Within the backend, it traverses from the ConnectionsController to the ConnectionService and CredentialVaultService, and potentially interacts with external AWS SDKs. This layered architecture promotes separation of concerns but requires careful coordination of data flow and error handling.setConnectionError.sts:AssumeRole, securityhub:DescribeHub), leading to validation failures.testConnection handlers defined in integration manifests can throw unhandled exceptions.Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:498-508 apps/api/src/integration-platform/controllers/connections.controller.ts:707-748 apps/api/src/integration-platform/controllers/connections.controller.ts:751-772 apps/api/src/integration-platform/services/connection.service.ts:150-153 apps/api/src/integration-platform/services/connection.service.ts:139-147 apps/api/src/integration-platform/services/connection.service.ts:25-31
testConnectiontestAwsConnectionsetConnectionErrorhandleTestConnectiontestAwsConnection) involves multiple AWS SDK calls (STS AssumeRole, SecurityHub DescribeHub across multiple regions), which can introduce latency. This is an inherent cost of validating external cloud resources.getConnection, updateConnectionStatus) are generally fast but could become a bottleneck under very high load if not properly indexed.