Skip to main content
doc0blade47/compdocumentation home
Sign in

Update Platform Status

Last updated Oct 11, 2026
Relevant source files

The following files were used as context for generating this wiki page:

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, apps/api/src/integration-platform/controllers/connections.controller.ts:1-748

  1. 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.

  2. 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.

  3. 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.

    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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:392-400, apps/api/src/integration-platform/controllers/connections.controller.ts:499-668, apps/api/src/integration-platform/services/connection.service.ts:104-110, apps/api/src/integration-platform/services/connection.service.ts:112-117, apps/api/src/integration-platform/repositories/connection.repository.ts:121-131

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.
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.

  • 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, apps/api/src/integration-platform/services/connection.service.ts:104-117, apps/api/src/integration-platform/repositories/connection.repository.ts:121-131

Was this page helpful?