--- id: CAP-PFM-INT-007 title: Assign provider connections to business needs feature: FEAT-PFM-INT-03 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-INT-BND-001 - CAP-INT-BND-002 - CAP-INT-BND-003 - CAP-INT-BND-004 - CAP-INT-BND-008 - CAP-INT-BND-010 - CAP-INT-BND-013 - CAP-INT-BND-014 - CAP-INT-BND-015 - CAP-INT-LIB-011 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D9' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S01' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S03' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S21' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4' purpose: Administrators associate a business need with the provider connection that should serve it. outcomes: - A business scope retains a single current connection choice. - Invalid choices expose their cause and notify administrators. - Historical call records retain the choice that actually served them. concepts: - CON-PFM-INT-003 actors: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-020 - ACT-PFM-006 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: platform.integrations.manage where_checked: api scope: tenant - key: platform.integrations.read where_checked: api scope: tenant - key: platform.integrations.manage where_checked: console scope: tenant rules: - id: BR-CAP-PFM-INT-007-01 proved_by: [ATS-PFM-INT-007-01, ATS-PFM-INT-007-11, TST-PFM-INT-488, TST-PFM-INT-554] statement: >- A binding selects a capability major, scope and connection; each record, business unit, application or workspace scope has one current binding, and replacement advances its revision. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/persistence/integration-bindings.integration.spec.js#leaves one active binding at the scope origin: none - id: BR-CAP-PFM-INT-007-02 proved_by: [ATS-PFM-INT-007-02, TST-PFM-INT-488, TST-PFM-INT-554] statement: >- Binding creation preserves the existing choice on refusal and requires a bindable contract, valid allowed scope, matching record application, known and verified required features and a usable workspace connection implementing that major. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/persistence/integration-bindings.integration.spec.js#refuses a required feature the connection has not verified origin: none - id: BR-CAP-PFM-INT-007-03 proved_by: [ATS-PFM-INT-007-03, TST-PFM-INT-554, TST-PFM-INT-571] statement: >- Sensitive money-moving capabilities default to refusal on an ineligible connection, while other capabilities default to continuing to a broader binding. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/binding-migration-rules.spec.ts#gives a sensitive capability the refusing default origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D4' - id: BR-CAP-PFM-INT-007-04 proved_by: [ATS-PFM-INT-007-04, ATS-PFM-INT-007-11, ATS-PFM-INT-007-12, TST-PFM-INT-488, TST-PFM-INT-554] statement: >- Removing a binding supersedes it without replacement, exposes broader scope resolution and retains the removed choice in history. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/e2e/integration-bindings.e2e.spec.js#supersedes it, and the scope resolves without it origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.plan.md#INTG-M2-S03' - id: BR-CAP-PFM-INT-007-05 proved_by: [ATS-PFM-INT-007-05, TST-PFM-INT-488, TST-PFM-INT-495, TST-PFM-INT-554] statement: >- Binding changes append immutable snapshots in newest-first scope history, retaining at most two hundred recent revisions per binding. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/db/integration-binding-revisions.table.integration.spec.js#refuses an UPDATE of a revision by the application role, so a history cannot be rewritten origin: none - id: BR-CAP-PFM-INT-007-06 proved_by: [ATS-PFM-INT-006-09, ATS-PFM-INT-007-06, ATS-PFM-INT-007-11, ATS-PFM-INT-007-13, TST-PFM-INT-513, TST-PFM-INT-570] statement: >- A binding becomes invalid with a reason when connection state, installation suspension, capability support or required features prevent use, and reactivates when eligibility returns. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/invalidation.integration.spec.js#invalidates its active bindings with connection_suspended, at the next revision origin: none - id: BR-CAP-PFM-INT-007-07 proved_by: [ATS-PFM-INT-007-07, TST-PFM-INT-513] statement: >- Invalidating active bindings sends one post-commit e-mail per connection naming affected choices and reasons, while restoration sends none. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/invalidation.integration.spec.js#tells the administrators once, after the commit, naming both bindings and why origin: none - id: BR-CAP-PFM-INT-007-08 proved_by: [ATS-PFM-INT-004-13, ATS-PFM-INT-007-08, ATS-PFM-INT-007-14, TST-PFM-INT-106, TST-PFM-INT-511] statement: >- An administrator can move at most two hundred active bindings to another active connection under normal eligibility rules; dry run saves nothing and one failed move does not roll back successful moves. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/binding-move.integration.spec.js#replaces every active binding of the source with one choosing the target, at the same scope, policy and note origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D9' - id: BR-CAP-PFM-INT-007-09 proved_by: [ATS-PFM-INT-007-09, TST-PFM-INT-510] statement: >- Migration copies bindings to another capability major under normal validation, optionally supersedes the source, writes nothing in dry run and identifies previously completed copies on repetition. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/binding-migration.integration.spec.js#refuses each ineligible binding with its reason and leaves the already migrated one alone origin: none note: >- The implementation includes contract-major migration, although the recorded call milestone defers it. That record does not confirm the implemented outcome. - id: BR-CAP-PFM-INT-007-10 proved_by: [ATS-PFM-INT-007-10, TST-PFM-INT-488] statement: 'Integration read permits binding and revision reads, and integration manage is required for changes.' kind: permission enforced_at: - api - console must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/e2e/integration-bindings.e2e.spec.js#is refused a reader of integrations (403) origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4' - id: BR-CAP-PFM-INT-007-11 proved_by: [] statement: >- Binding operations also record before-and-after scope, connection, status and revision in security history, marking creation, replacement, restoration and copying as widening. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/binding-operations.integration.spec.js#writes the creation, the replacement and the removal to the security trail origin: none scenarios: - id: SC-CAP-PFM-INT-007-01 given: Two merchant accounts serve different business scopes. when: Staff assign Payrix to one account and Stripe to the other business unit. then: Resolution uses the record choice for the first and the business-unit choice for the second. provenance: test source: >- services-platform:modules/integrations/tests/e2e/integration-bindings.e2e.spec.js#explains a tender on B: Stripe, by its business unit, after finding no resource binding - id: SC-CAP-PFM-INT-007-02 given: Two business units select Main account. when: Staff move both choices to Events account before disconnecting Main account. then: The business units use the replacement and the former account ends disconnected. provenance: test source: 'react-console:acceptance/integrations/playwright/journeys/bindings/INT-ACC-0262.spec.ts#INT-ACC-0262' edge_cases: [] constraints: [] depends_on: - CAP-PFM-INT-004 related: - CAP-PFM-INT-008 - CAP-PFM-INT-009 journeys: - JNY-PFM-INT-002 - JNY-PFM-INT-003 open_questions: [] evidence: - >- services-platform source inventory: modules/integrations/services/bindings/binding-operations.ts, invalidation.ts, binding-notices.ts, services/persistence/integration-bindings.ts, db/integration-bindings.table.ts, db/integration-binding-revisions.table.ts; rule-level automated test references; docs/integrations/README.md (Bindings, Bindings history and migration); docs/milestones/INTG-M2-calls-through-the-gateway.md and .plan.md. - >- react-console source inventory: components/integrations/bindings-screen.tsx, lib/integrations/move-bindings.ts, binding-suggestions.ts; acceptance journey INT-ACC-0262. - 'macroservice-libraries source inventory: packages/integration-contracts/src/binding-policies.ts.' - >- Operation coverage: listIntegrationBindings, putIntegrationBinding, deleteIntegrationBinding, listIntegrationBindingRevisions, migrateIntegrationBindings, moveIntegrationConnectionBindings. - 'Persistent record coverage: integration_bindings, integration_binding_revisions.' - 'End-to-end definition inventory: integration-bindings.e2e.spec.js, reader-access.e2e.spec.js.' controls: [TC-AVL-001, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CHG-007, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-INT-03-01, FAS-PFM-INT-03-04] suites: [TST-PFM-INT-106, TST-PFM-INT-488, TST-PFM-INT-495, TST-PFM-INT-510, TST-PFM-INT-511, TST-PFM-INT-513, TST-PFM-INT-554, TST-PFM-INT-570, TST-PFM-INT-571] --- # Assign provider connections to business needs ## Purpose Administrators associate a business need with the provider connection that should serve it. ## How It Works An administrator chooses which account serves a business scope. A choice belongs to the scope that needs it rather than to a particular screen. More specific choices let a workspace distinguish record or business-unit needs. Staff inspect earlier revisions when they need to explain past routing. Connection changes can make an existing choice unusable. The resulting reason and notification help staff repair configuration. A move operation supports retirement of an old account while leaving individual failures visible. Major-version migration exists beyond the approved gateway milestone. The product should keep that deferred operation distinct from the approved move-before-disconnect flow. ## Relationships - Requires maintain a verified provider account connection to supply the prerequisite configuration or operation. - Connects with explain and select the connection for a call through shared integration records. - Connects with run provider operations safely through the gateway through shared integration records.