--- id: WF-PFM-INT-002 title: 'Adopt, suspend, resume and uninstall an integration' trigger: The initiating integration administrator starts this flow. product_area: platform module: integrations revision: 1 status: draft design_intent: confirmed implementation_evidence: observed origin: 'docs/milestones/INTG-M1-find-install-connect.md#Decisions D7, D11 (INTG-M1 Product Accepted)' inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-PFM-INT-003 - CAP-PFM-INT-014 moves: - STATE-PFM-INT-002 - STATE-PFM-INT-003 - STATE-PFM-INT-006 - STATE-PFM-INT-011 crosses: [] idempotency: >- Reinstallation restores the retained record; repeat installation of an existing adoption is refused. Edits require a matching read version. concurrency: Requests lock the installation and changed account rows; binding reassessment shares their transaction. hops: - 'n': 1 actor_or_service: Integration administrator action: 'Submit installation settings and accepted access, or send an edit with the version already read.' anchor: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:installIntegration seam: sync on_failure: Show the service’s validation or refusal details. left_inconsistent: Rejected input changes no installation record. observer: The administrator provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:installIntegration - 'n': 2 actor_or_service: Integrations service action: >- Validate availability, settings and access against the current declaration; an edit clears affected notices and pauses subscriptions whose acceptance was withdrawn. anchor: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:changeInstallation seam: sync on_failure: Reject invalid input or an out-of-date version. left_inconsistent: 'The existing settings, access and subscription states remain.' observer: The administrator provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:changeInstallation - 'n': 3 actor_or_service: Integrations service action: >- Suspend the installation with a reason, pausing active and degraded accounts and invalidating their bindings in the same transaction. anchor: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:suspendInstallation seam: sync on_failure: Any cascade error aborts suspension. left_inconsistent: The installation and its dependants retain their prior state. observer: The administrator and the integration trail provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:suspendInstallation - 'n': 4 actor_or_service: Integrations service action: >- Resume only accounts attributed to this installation’s suspension and restore bindings that qualify again. anchor: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:resumeInstallation seam: sync on_failure: Abort the resumption if its cascade fails. left_inconsistent: No partial account restoration commits. observer: The administrator provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:resumeInstallation - 'n': 5 actor_or_service: Integrations service action: >- Uninstall after every account link is disconnected, removing the installation’s subscriptions atomically. anchor: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:uninstallInstallation seam: sync on_failure: Return the remaining account links when the guard fails. left_inconsistent: The installation stays installed and subscriptions remain. observer: The administrator provenance: observed source: >- services-platform:modules/integrations/services/installations/installation-lifecycle.ts:uninstallInstallation - 'n': 6 actor_or_service: Integrations service action: >- Commit both audit entries with the change, then request administrator notices for newly invalid bindings. anchor: 'services-platform:modules/integrations/services/bindings/binding-notices.ts' seam: sync on_failure: Log mail failures after commit. left_inconsistent: The audited change remains even if administrators receive no message. observer: Mail logs provenance: observed source: 'services-platform:modules/integrations/services/bindings/binding-notices.ts' evidence: - >- services-platform at ad3f6a65: modules/integrations/services/installations/installation-lifecycle.ts; services/bindings/invalidation.ts, binding-notices.ts; services/persistence/integration-subscriptions.ts; docs/milestones/INTG-M1-find-install-connect.md (D4, D7, D11) - >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses settings the manifest’s schema refuses, and writes nothing - >- services-platform:modules/integrations/tests/integration/services/subscriptions/subscription-consent.integration.spec.js#pauses the active subscription of the type left out - >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#suspends the active and degraded connections of the installation when it is suspended - >- services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#suspends the active and degraded connections of the installation when it is suspended - >- services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#is refused while a connection is not disconnected, naming each by id, name and status - >- services-platform:modules/integrations/tests/integration/services/installations/history-and-security-trail.integration.spec.js#writes the narrowing to the history and to the security trail controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-PRV-004, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Adopt, suspend, resume and uninstall an integration ## What It Does Customer adoption retains settings and accepted access separately from provider accounts. Pausing adoption cascades to usable accounts; restoring it reverses only that pause. Removal waits for account closure and deletes subscription definitions. ## The Flow ```mermaid sequenceDiagram participant P0 as Integration administrator participant P1 as Integrations service P0->>P0: 1. Submit installation settings and accepted access P1->>P1: 2. Validate availability P1->>P1: 3. Suspend the installation with a reason P1->>P1: 4. Resume only accounts attributed to this installation’s suspension and restore bindings that qualify again. P1->>P1: 5. Uninstall after every account link is disconnected P1->>P1: 6. Commit both audit entries with the change ``` ## When Something Fails Show the service’s validation or refusal details. Rejected input changes no installation record. Reject invalid input or an out-of-date version. The existing settings, access and subscription states remain. Any cascade error aborts suspension. The installation and its dependants retain their prior state. Abort the resumption if its cascade fails. No partial account restoration commits. Return the remaining account links when the guard fails. The installation stays installed and subscriptions remain. Log mail failures after commit. The audited change remains even if administrators receive no message. ## Open Design Questions Product must resolve restored access against the recorded narrowing policy and deleted subscriptions against the earlier stop-only decision. Administrator lifecycle actions also lack the standard version precondition.