--- title: "Get Platform Connection" description: "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 pro..." last_updated: "2026-05-06T07:30:58.159818+00:00" canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/how-it-works/get-platform-connection" ---
Relevant source files The following files were used as context for generating this wiki page: - [apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx) - [apps/api/src/integration-platform/controllers/connections.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts) - [apps/api/src/integration-platform/services/connection.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts)
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. ### 1. IntegrationPlatformTestPage 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](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx#L427-L690) ### 2. handleTestConnection 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](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx#L498-L508) ### 3. testConnection 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: * **If the `providerSlug` is 'aws'**: The request is delegated to the `testAwsConnection` private method for AWS-specific validation. * **For other providers**: It checks if the provider's manifest defines a `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](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L707-L748) ### 4. testAwsConnection 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: 1. Validating the format of the IAM Role ARN, External ID, and regions. 2. Assuming an internal "role assumer" role. 3. Using the assumed role to then assume the customer's provided IAM role with the External ID. 4. Checking if AWS Security Hub is enabled in all specified regions using the customer's assumed role. Based on the `validateAwsCredentials` result: * If validation is `success: true`, `activateConnection` is called on the `connectionService`. * If validation is `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](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L751-L772) ### 5. setConnectionError 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](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L150-L153) ### 6. updateConnectionStatus 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](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L139-L147) ### 7. getConnection 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](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L25-L31) ### Sequence Diagram ```mermaid sequenceDiagram participant UI as IntegrationPlatformTestPage participant Frontend as handleTestConnection participant API_Controller as ConnectionsController participant Connection_Service as ConnectionService participant Credential_Vault as CredentialVaultService participant AWS_SDK as AWS SDK (STS, SecurityHub) participant DB as ConnectionRepository UI->>Frontend: User clicks "Test Connection" Frontend->>API_Controller: POST /integrations/connections/:id/test (testConnection) API_Controller->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Find connection by ID DB-->>Connection_Service: Connection record Connection_Service-->>API_Controller: Connection record API_Controller->>Credential_Vault: getDecryptedCredentials(connectionId) Credential_Vault-->>API_Controller: Decrypted credentials alt Provider is AWS API_Controller->>API_Controller: testAwsConnection(connectionId, credentials) API_Controller->>AWS_SDK: validateAwsCredentials(credentials) AWS_SDK-->>API_Controller: Validation Result (success/failure) alt AWS Validation Success API_Controller->>Connection_Service: activateConnection(connectionId) Connection_Service->>Connection_Service: updateConnectionStatus(connectionId, 'active') Connection_Service->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Update connection status to 'active' DB-->>Connection_Service: Updated connection Connection_Service-->>API_Controller: Updated connection API_Controller-->>Frontend: { success: true, message: "Validated!" } else AWS Validation Failure API_Controller->>Connection_Service: setConnectionError(connectionId, errorMessage) Connection_Service->>Connection_Service: updateConnectionStatus(connectionId, 'error', errorMessage) Connection_Service->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Update connection status to 'error' DB-->>Connection_Service: Updated connection Connection_Service-->>API_Controller: Updated connection API_Controller-->>Frontend: { success: false, message: "Validation failed" } end else Provider has custom test handler API_Controller->>API_Controller: manifest.handler.testConnection(credentials) alt Custom Test Success API_Controller->>Connection_Service: activateConnection(connectionId) Connection_Service->>Connection_Service: updateConnectionStatus(connectionId, 'active') Connection_Service->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Update connection status to 'active' DB-->>Connection_Service: Updated connection Connection_Service-->>API_Controller: Updated connection API_Controller-->>Frontend: { success: true, message: "Connection test successful" } else Custom Test Failure API_Controller->>Connection_Service: setConnectionError(connectionId, errorMessage) Connection_Service->>Connection_Service: updateConnectionStatus(connectionId, 'error', errorMessage) Connection_Service->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Update connection status to 'error' DB-->>Connection_Service: Updated connection Connection_Service-->>API_Controller: Updated connection API_Controller-->>Frontend: { success: false, message: "Connection test failed" } end else No custom test handler API_Controller->>Connection_Service: activateConnection(connectionId) Connection_Service->>Connection_Service: updateConnectionStatus(connectionId, 'active') Connection_Service->>Connection_Service: getConnection(connectionId) Connection_Service->>DB: Update connection status to 'active' DB-->>Connection_Service: Updated connection Connection_Service-->>API_Controller: Updated connection API_Controller-->>Frontend: { success: true, message: "Connection activated" } end Frontend->>UI: Display result and refresh connections ``` ### Flowchart ### Key Observations * **Cross-Module Boundaries**: This flow extensively crosses module boundaries, starting from the React frontend (`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. * **Potential Failure Points**: * **Network Issues**: API calls between frontend and backend, or backend and AWS, can fail due to network problems. * **Invalid Credentials**: Incorrect or expired credentials (e.g., AWS IAM Role ARN, External ID, API keys, OAuth tokens) are a common failure point. The system explicitly handles this by calling `setConnectionError`. * **Missing Permissions**: For AWS, the assumed IAM role might lack necessary permissions (e.g., `sts:AssumeRole`, `securityhub:DescribeHub`), leading to validation failures. * **External Service Unavailability**: The AWS Security Hub service itself might be unavailable or not enabled in a region, causing the test to fail. * **Database Errors**: Issues with retrieving or updating connection records in the database. * **Manifest Handler Errors**: Custom `testConnection` handlers defined in integration manifests can throw unhandled exceptions. * **Error Handling**: The flow demonstrates robust error handling. On the backend, `testConnection` and `testAwsConnection` catch exceptions and explicitly call `setConnectionError` to update the connection's status in the database, providing a clear indication of failure. The frontend `handleTestConnection` also logs both success and failure messages to the UI. * **Performance Considerations**: * The AWS validation step (`testAwsConnection`) 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. * Database lookups (`getConnection`, `updateConnectionStatus`) are generally fast but could become a bottleneck under very high load if not properly indexed. * Decryption of credentials from the vault adds a small overhead but is necessary for security. Sources: [apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:498-508](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx#L498-L508) [apps/api/src/integration-platform/controllers/connections.controller.ts:707-748](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L707-L748) [apps/api/src/integration-platform/controllers/connections.controller.ts:751-772](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L751-L772) [apps/api/src/integration-platform/services/connection.service.ts:150-153](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L150-L153) [apps/api/src/integration-platform/services/connection.service.ts:139-147](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L139-L147) [apps/api/src/integration-platform/services/connection.service.ts:25-31](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L25-L31) ## Sitemap See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.