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
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 thehandleTestConnectionfunction. This function captures theconnectionIdandproviderSlugfor the connection to be tested.Client-Side Test Request
The
handleTestConnectionfunction (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 thetestConnectionmutation (provided byuseIntegrationMutations), which internally makes an API call to the backend. This call is typically aPOSTrequest to/v1/integrations/connections/:id/test, sending theconnectionIdto the API.Backend Receives Test Request
The
testConnectionmethod inConnectionsController(apps/api/src/integration-platform/controllers/connections.controller.ts) receives the API request. It first retrieves theIntegrationConnectionobject from the database using the providedconnectionId. It then fetches the decrypted credentials associated with this connection from thecredentialVaultService.Provider-Specific LogicThe controller checks the
providerSlugof the connection. For specific providers like AWS, it delegates to a specialized testing method (testAwsConnection). For other providers, it attempts to use atestConnectionhandler defined within the provider's manifest, if available. If no specific handler exists, it defaults to activating the connection.AWS Connection Validation
For AWS connections, the
testAwsConnectionmethod (apps/api/src/integration-platform/controllers/connections.controller.ts) is invoked. This method performs a comprehensive validation:- Credential Parsing: Extracts
roleArn,externalId, andregionsfrom the connection's credentials. - 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 theexternalId. This verifies the IAM role's validity and permissions. - 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.
- Credential Parsing: Extracts
Setting Connection Error Status
If the validation in
testAwsConnection(or any other provider's test handler) fails, thesetConnectionErrormethod inConnectionService(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 theconnectionIdand anerrorMessageas input.Updating Connection Status in Service Layer
The
setConnectionErrormethod (oractivateConnectionin case of success) internally callsupdateConnectionStatusinConnectionService(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 callinggetConnection(connectionId). If the connection is found, it proceeds to call the repository layer to persist the status change.Persisting Status Update to Database
Finally, the
updateStatusmethod inConnectionRepository(apps/api/src/integration-platform/repositories/connection.repository.ts) is invoked. This method directly interacts with the database. It updates thestatusfield of theIntegrationConnectionrecord corresponding to theconnectionIdto eitheractiveorerror, and also stores theerrorMessageif provided. This completes the backend process, and the updated status is then reflected in the frontend after therefreshConnectionscall.
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
IntegrationPlatformTestPagetriggers an API call to theConnectionsController. - Controller to Service Layer: The
ConnectionsControllerdelegates business logic to theConnectionServiceandCredentialVaultService. - Service to Repository Layer: The
ConnectionServiceinteracts with theConnectionRepositoryfor database operations. - API to External Services: For AWS connections, the
ConnectionsControllerdirectly interacts with external AWS SDKs (STS, SecurityHub) to perform real-time credential validation. This is a critical external dependency.
- Client-side (Next.js App) to Server-side (NestJS API): The initial user interaction on the
-
Potential Failure Points and Handling:
- Network Issues: The API call from client to server can fail due to network problems. The client-side
handleTestConnectionfunction includestry-catchblocks to log errors. - Invalid Connection ID/Credentials: The
ConnectionsControllerandConnectionServicevalidate the existence of the connection and its credentials. Missing credentials or an invalid connection ID will result inNotFoundExceptionorBadRequestException. - AWS Credential Validation Failures: This is a major potential failure point.
validateAwsCredentialshandles 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),
AccessDeniederrors 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
errorwith a user-friendly message.
- Invalid IAM Role ARN/External ID: Caught during
- Generic Provider Test Failures: If a manifest's
testConnectionhandler throws an error or returnsfalse, the connection status is set toerror. - Database Errors: Failures during
updateStatusin theConnectionRepositorycould 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.
- Network Issues: The API call from client to server can fail due to network problems. The client-side
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
testConnectionoperation 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.
- 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
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