---
title: "Update Platform Status"
description: "The \"IntegrationPlatformTestPage -> UpdateStatus\" flow describes the process initiated when a user attempts to test an existing integration connection from the Integration Platform Test Page. This ..."
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/update-platform-status"
---

<details>
<summary>Relevant source files</summary>

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)
- [apps/api/src/integration-platform/repositories/connection.repository.ts](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/repositories/connection.repository.ts)
</details>

The "IntegrationPlatformTestPage -> UpdateStatus" flow describes the process initiated when a user attempts to test an existing integration connection from the Integration Platform Test Page. This flow validates the connection's credentials (e.g., AWS IAM role and Security Hub status) and subsequently updates the connection's status in the database to either `active` (if successful) or `error` (if validation fails), along with a descriptive error message.

This process is crucial for ensuring the health and validity of integrated services, providing immediate feedback to users about their connection's operational status. It helps identify misconfigurations or permission issues proactively, preventing downstream failures in data synchronization or automated checks.

Sources: [apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:1-550](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx#L1-L550), [apps/api/src/integration-platform/controllers/connections.controller.ts:1-748](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L1-L748)

<Steps>
<Step>
### User Initiates Connection Test
The process begins on the `IntegrationPlatformTestPage` (`apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx`), a client-side React component. This page displays a list of integration connections. When a user clicks the "Test" button associated with a specific connection, it triggers the `handleTestConnection` function. This function captures the `connectionId` and `providerSlug` for the connection to be tested.
</Step>
<Step>
### Client-Side Test Request
The `handleTestConnection` function (`apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx`) sets a loading state and logs the action to the UI. It then calls the `testConnection` mutation (provided by `useIntegrationMutations`), which internally makes an API call to the backend. This call is typically a `POST` request to `/v1/integrations/connections/:id/test`, sending the `connectionId` to the API.
</Step>
<Step>
### Backend Receives Test Request
The `testConnection` method in `ConnectionsController` (`apps/api/src/integration-platform/controllers/connections.controller.ts`) receives the API request. It first retrieves the `IntegrationConnection` object from the database using the provided `connectionId`. It then fetches the decrypted credentials associated with this connection from the `credentialVaultService`.

<Callout variant="info" title="Provider-Specific Logic">
The controller checks the `providerSlug` of the connection. For specific providers like AWS, it delegates to a specialized testing method (`testAwsConnection`). For other providers, it attempts to use a `testConnection` handler defined within the provider's manifest, if available. If no specific handler exists, it defaults to activating the connection.
</Callout>
</Step>
<Step>
### AWS Connection Validation
For AWS connections, the `testAwsConnection` method (`apps/api/src/integration-platform/controllers/connections.controller.ts`) is invoked. This method performs a comprehensive validation:
1.  **Credential Parsing**: Extracts `roleArn`, `externalId`, and `regions` from the connection's credentials.
2.  **IAM Role Assumption**: Attempts to assume an internal "role assumer" role, and then uses those temporary credentials to assume the customer's provided IAM role (`roleArn`) with the `externalId`. This verifies the IAM role's validity and permissions.
3.  **Security Hub Check**: If role assumption is successful, it then attempts to describe Security Hub in each specified AWS region using the assumed customer credentials. This confirms that Security Hub is enabled and accessible.

The result of this validation (success or failure) is returned, along with a detailed message.
</Step>
<Step>
### Setting Connection Error Status
If the validation in `testAwsConnection` (or any other provider's test handler) fails, the `setConnectionError` method in `ConnectionService` (`apps/api/src/integration-platform/services/connection.service.ts`) is called. This method is a convenience wrapper that prepares the connection for an error state. It takes the `connectionId` and an `errorMessage` as input.
</Step>
<Step>
### Updating Connection Status in Service Layer
The `setConnectionError` method (or `activateConnection` in case of success) internally calls `updateConnectionStatus` in `ConnectionService` (`apps/api/src/integration-platform/services/connection.service.ts`). This method is responsible for orchestrating the status update. It first performs a check to ensure the connection exists by calling `getConnection(connectionId)`. If the connection is found, it proceeds to call the repository layer to persist the status change.
</Step>
<Step>
### Persisting Status Update to Database
Finally, the `updateStatus` method in `ConnectionRepository` (`apps/api/src/integration-platform/repositories/connection.repository.ts`) is invoked. This method directly interacts with the database. It updates the `status` field of the `IntegrationConnection` record corresponding to the `connectionId` to either `active` or `error`, and also stores the `errorMessage` if provided. This completes the backend process, and the updated status is then reflected in the frontend after the `refreshConnections` call.
</Step>
</Steps>

Sources: [apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:392-400](https://github.com/blade47/comp/blob/main/apps/app/src/app/(app)/%5BorgId%5D/integrations/platform-test/page.tsx#L392-L400), [apps/api/src/integration-platform/controllers/connections.controller.ts:499-668](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L499-L668), [apps/api/src/integration-platform/services/connection.service.ts:104-110](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L104-L110), [apps/api/src/integration-platform/services/connection.service.ts:112-117](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L112-L117), [apps/api/src/integration-platform/repositories/connection.repository.ts:121-131](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/repositories/connection.repository.ts#L121-L131)

```mermaid
sequenceDiagram
    participant UI as IntegrationPlatformTestPage
    participant Client as Client-side Logic
    participant Controller as ConnectionsController
    participant Service as ConnectionService
    participant Repository as ConnectionRepository
    participant AWS as AWS Services (STS, SecurityHub)
    participant CredVault as CredentialVaultService

    UI->>Client: User clicks "Test Connection"
    Client->>Client: handleTestConnection(connectionId, providerSlug)
    Client->>Controller: POST /v1/integrations/connections/:id/test
    activate Controller
    Controller->>Service: getConnection(connectionId)
    activate Service
    Service->>Repository: findById(connectionId)
    activate Repository
    Repository-->>Service: Connection
    deactivate Repository
    Service-->>Controller: Connection
    deactivate Service
    Controller->>CredVault: getDecryptedCredentials(connectionId)
    activate CredVault
    CredVault-->>Controller: Credentials
    deactivate CredVault

    alt Provider is AWS
        Controller->>Controller: testAwsConnection(connectionId, credentials)
        activate Controller
        Controller->>AWS: validateAwsCredentials(credentials)
        activate AWS
        AWS-->>Controller: ValidationResult (success/failure)
        deactivate AWS
        alt Validation successful
            Controller->>Service: activateConnection(connectionId)
            activate Service
            Service->>Service: updateConnectionStatus(connectionId, 'active')
            Service->>Repository: updateStatus(connectionId, 'active', null)
            activate Repository
            Repository-->>Service: UpdatedConnection
            deactivate Repository
            Service-->>Controller: UpdatedConnection
            deactivate Service
        else Validation failed
            Controller->>Service: setConnectionError(connectionId, errorMessage)
            activate Service
            Service->>Service: updateConnectionStatus(connectionId, 'error', errorMessage)
            Service->>Repository: updateStatus(connectionId, 'error', errorMessage)
            activate Repository
            Repository-->>Service: UpdatedConnection
            deactivate Repository
            Service-->>Controller: UpdatedConnection
            deactivate Service
        end
        Controller-->>Client: { success, message, details }
        deactivate Controller
    else Other Provider with manifest handler
        Controller->>Controller: manifest.handler.testConnection(credentials)
        activate Controller
        alt Test successful
            Controller->>Service: activateConnection(connectionId)
            activate Service
            Service->>Service: updateConnectionStatus(connectionId, 'active')
            Service->>Repository: updateStatus(connectionId, 'active', null)
            activate Repository
            Repository-->>Service: UpdatedConnection
            deactivate Repository
            Service-->>Controller: UpdatedConnection
            deactivate Service
        else Test failed
            Controller->>Service: setConnectionError(connectionId, errorMessage)
            activate Service
            Service->>Service: updateConnectionStatus(connectionId, 'error', errorMessage)
            Service->>Repository: updateStatus(connectionId, 'error', errorMessage)
            activate Repository
            Repository-->>Service: UpdatedConnection
            deactivate Repository
            Service-->>Controller: UpdatedConnection
            deactivate Service
        end
        Controller-->>Client: { success, message }
        deactivate Controller
    end

    Client->>Client: log(message)
    Client->>Client: refreshConnections()
    Client-->>UI: Display updated status
```



### Key Observations

This flow demonstrates a robust mechanism for validating and updating integration connection statuses, spanning multiple architectural layers.

*   **Cross-Module Boundaries**: The execution crosses significant boundaries:
    *   **Client-side (Next.js App) to Server-side (NestJS API)**: The initial user interaction on the `IntegrationPlatformTestPage` triggers an API call to the `ConnectionsController`.
    *   **Controller to Service Layer**: The `ConnectionsController` delegates business logic to the `ConnectionService` and `CredentialVaultService`.
    *   **Service to Repository Layer**: The `ConnectionService` interacts with the `ConnectionRepository` for database operations.
    *   **API to External Services**: For AWS connections, the `ConnectionsController` directly interacts with external AWS SDKs (STS, SecurityHub) to perform real-time credential validation. This is a critical external dependency.

*   **Potential Failure Points and Handling**:
    *   **Network Issues**: The API call from client to server can fail due to network problems. The client-side `handleTestConnection` function includes `try-catch` blocks to log errors.
    *   **Invalid Connection ID/Credentials**: The `ConnectionsController` and `ConnectionService` validate the existence of the connection and its credentials. Missing credentials or an invalid connection ID will result in `NotFoundException` or `BadRequestException`.
    *   **AWS Credential Validation Failures**: This is a major potential failure point. `validateAwsCredentials` handles various AWS-specific errors:
        *   **Invalid IAM Role ARN/External ID**: Caught during `sts:AssumeRole`.
        *   **Insufficient Permissions**: If the assumed role lacks necessary permissions (e.g., for Security Hub), `AccessDenied` errors will occur.
        *   **Security Hub Not Enabled**: If Security Hub is not active in the specified regions, a specific error is returned.
        *   These failures lead to the connection status being set to `error` with a user-friendly message.
    *   **Generic Provider Test Failures**: If a manifest's `testConnection` handler throws an error or returns `false`, the connection status is set to `error`.
    *   **Database Errors**: Failures during `updateStatus` in the `ConnectionRepository` could occur, though typically handled by the ORM/database layer.
    *   **Error Propagation**: Errors are caught at various levels (AWS SDK calls, service calls) and propagated back up the stack, eventually resulting in an API response indicating success or failure, which is then logged on the client.

<Callout variant="warning" title="Critical External Dependency">
The AWS credential validation (`validateAwsCredentials`) is a critical external dependency. Any issues with AWS services, network connectivity to AWS, or misconfigurations of the internal `SECURITY_HUB_ROLE_ASSUMER_ARN` environment variable could lead to validation failures, even if the customer's credentials are correct.
</Callout>

*   **Performance Considerations**:
    *   **Real-time External Calls**: The AWS credential validation involves multiple external API calls to AWS (STS AssumeRole twice, then Security Hub DescribeHub for each region). This can introduce latency, making the `testConnection` operation potentially slow.
    *   **Database Lookups**: Multiple database lookups (`findById`, `findBySlug`) occur. These are generally fast but contribute to the overall latency.
    *   **Client-side Refresh**: After the test, `refreshConnections()` is called on the client, which refetches all connections. This ensures the UI is up-to-date but adds another round trip.
    *   The current implementation seems to prioritize correctness and thorough validation over raw speed for this specific "test connection" operation, which is typically an infrequent user action.

Sources: [apps/api/src/integration-platform/controllers/connections.controller.ts:499-668](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/controllers/connections.controller.ts#L499-L668), [apps/api/src/integration-platform/services/connection.service.ts:104-117](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/services/connection.service.ts#L104-L117), [apps/api/src/integration-platform/repositories/connection.repository.ts:121-131](https://github.com/blade47/comp/blob/main/apps/api/src/integration-platform/repositories/connection.repository.ts#L121-L131)

## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.