--- id: CAP-PFM-INT-006 title: Recognize integration problems and trace changes feature: FEAT-PFM-INT-02 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-INT-CAT-011 - CAP-INT-CAT-013 - CAP-INT-CAT-014 - CAP-INT-CAT-015 - CAP-INT-LIB-002 - CAP-INT-LIB-018 - CAP-INT-SEC-012 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D6' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#A12' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S10' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S17' - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S18' - 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D8' - 'services-platform:docs/milestones/INTG-M8-payrix-card-payments.md#M8-D6' purpose: 'Staff identify unhealthy connections, review changes and find the work that requires intervention.' outcomes: - Healthy green distinguishes a working connection from one merely paused. - Attention lists and notices direct staff to connection failures. - History identifies the actor and time of integration changes. concepts: - CON-PFM-INT-002 actors: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-006 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: platform.integrations.read where_checked: api scope: tenant - key: platform.integrations.manage where_checked: api scope: tenant - key: platform.integrations.read where_checked: console scope: tenant rules: - id: BR-CAP-PFM-INT-006-01 proved_by: [ATS-PFM-INT-006-01, TST-PFM-INT-456] statement: >- The console uses green for active passing connections, amber for degraded or failing health, red for failed verification or required re-authorization and grey for suspended, disconnected or unfinished connections. kind: calculation enforced_at: - console must_prove: true provenance: test source: >- react-console:lib/integrations/connection-dot.test.ts#is grey for suspended and disconnected, whatever the last health check said origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D6' - id: BR-CAP-PFM-INT-006-02 proved_by: [ATS-PFM-INT-006-02, TST-PFM-INT-548] statement: >- Initial creation triggers verification; the daily pass verifies active and degraded connections, and fifteen-minute checks probe degraded connections or recent health failures within a day, excluding suspended connections. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/health/health-pass.integration.spec.js#submits a health job for each eligible connection with a recent failure, and for a degraded one origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#A12' - id: BR-CAP-PFM-INT-006-03 proved_by: [ATS-PFM-INT-004-12, ATS-PFM-INT-006-03, ATS-PFM-INT-006-13, TST-PFM-INT-364, TST-PFM-INT-520] statement: >- Health failure degrades an active connection, recovery restores a degraded one, and credential refusal requires re-authorization with a notice; only active or degraded connections are probed. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/connection-jobs.integration.spec.js#degrades an active connection whose provider is unhealthy origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S10' - id: BR-CAP-PFM-INT-006-04 proved_by: [ATS-PFM-INT-006-04, TST-PFM-INT-573] statement: >- Last-hour figures report the success share and 95th-percentile latency of completed calls that reach the provider, excluding admission refusals and calls still in flight and leaving figures empty without eligible calls. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/unit/services/connection-figures.spec.ts#does not count an execution refused before the adapter, whatever its status origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D6' - id: BR-CAP-PFM-INT-006-05 proved_by: [] statement: >- The workspace health read counts connection states and includes degraded, failed-verification, re-authorization-required and suspended connections with their health and reason. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/health/tenant-integration-health.integration.spec.js#lists a suspended connection, a degraded one and one needing re-authorization, and no active one origin: none - id: BR-CAP-PFM-INT-006-06 proved_by: [ATS-PFM-INT-005-15, ATS-PFM-INT-006-05, ATS-PFM-INT-006-09, ATS-PFM-INT-006-12, TST-PFM-INT-517] statement: >- After commit, feature loss or required re-authorization sends each administrator one e-mail; gains send none and mail failure cannot reverse the saved change. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/connection-feature-changes.integration.spec.js#INT-ACC-0113 step 3: the loss tells each administrator of the tenant once, two notices in all, each with the features-lost subject origin: none - id: BR-CAP-PFM-INT-006-07 proved_by: [ATS-PFM-INT-006-06, TST-PFM-INT-538] statement: >- Successful calls can retain connector warnings as one thirty-day notice per kind with a recurrence count; relevant setting or configuration changes and disconnection clear it, and recording failure cannot fail the call. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/connection-notices.integration.spec.js#records the warnings of a succeeded call with the setting, and the call is answered as it always was origin: 'services-platform:docs/milestones/INTG-M8-payrix-card-payments.md#M8-D6' - id: BR-CAP-PFM-INT-006-08 proved_by: [ATS-PFM-INT-003-15, ATS-PFM-INT-006-07, TST-PFM-INT-483] statement: >- Integration history returns installation, connection, credential, binding and subscription changes newest first, with a maximum page of one hundred and protection against rewriting. kind: invariant enforced_at: - api - database must_prove: true provenance: test source: >- services-platform:modules/integrations/tests/e2e/audit-events-paging.e2e.spec.js#INT-ACC-0530 step 2: the pages run newest first across the boundary origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S17' - id: BR-CAP-PFM-INT-006-09 proved_by: [] statement: >- The scheduled health walk resumes from its last completed workspace and continues past a workspace failure to avoid starving later workspaces. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-platform:modules/integrations/tests/integration/services/health/health-pass-walk.integration.spec.js#INT-ACC-0112 step 4: after two invocations every tenant has had a health job (no starvation) origin: none - id: BR-CAP-PFM-INT-006-10 proved_by: [ATS-PFM-INT-006-08, ATS-PFM-INT-006-10, ATS-PFM-INT-006-11, ATS-PFM-INT-010-09, ATS-PFM-INT-014-11, TST-PFM-INT-145, TST-PFM-INT-343, TST-PFM-INT-457] statement: >- Needs Attention includes failed, degraded or re-authorization-required connections, calls whose settlement has stopped, dead deliveries and connector notices with fixing actions, while excluding calls still being reconciled regardless of age. kind: policy enforced_at: - console must_prove: true provenance: test source: >- react-console:lib/integrations/needs-attention.test.ts#leaves a settling (unknown) execution out however long it has been unknown origin: 'services-platform:docs/milestones/INTG-M2-calls-through-the-gateway.md#M2-D8' scenarios: - id: SC-CAP-PFM-INT-006-01 given: The test provider’s health probe is failing. when: An administrator checks Health on the connection. then: 'The connection appears degraded and shows recent figures, then recovers after a passing check.' provenance: test source: 'react-console:acceptance/integrations/playwright/journeys/library/INT-ACC-0023.spec.ts#INT-ACC-0023' - id: SC-CAP-PFM-INT-006-02 given: A connector rejects the configured statement name but completes the payment. when: The successful call reports its warning. then: A connection notice directs the administrator to the statement-name setting. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/executions/connection-notices.integration.spec.js#records the warnings of a succeeded call with the setting, and the call is answered as it always was edge_cases: [] constraints: [] depends_on: - CAP-PFM-INT-004 related: - CAP-PFM-INT-007 - CAP-PFM-INT-010 - CAP-PFM-INT-014 journeys: - JNY-PFM-INT-001 open_questions: - OQ-PFM-INT-003 evidence: - >- services-platform source inventory: modules/integrations/services/health/* (health-pass.ts, tenant-integration-health.ts), connections/probe-connection-health.ts, notices/connection-notices.ts, notices/connection-warning-notices.ts, persistence/integration-execution-figures.ts, integration-audit-events.ts, aws/logic/integrations-health.schedule.ts; rule-level automated test references; docs/milestones/INTG-M1-find-install-connect.md (D6), INTG-M8-payrix-card-payments.md (M8-D6). - >- react-console source inventory: lib/integrations/connection-dot.ts, needs-attention.ts, components/integrations/library-home.tsx, needs-attention-screen.tsx, connection-notices.tsx; acceptance journeys INT-ACC-0002, 0023, 0118. - >- Operation coverage: checkIntegrationConnectionHealth, getTenantIntegrationHealth, listIntegrationAuditEvents, listIntegrationConnectionNotices. - >- Persistent record coverage: integration_health_jobs, integration_health_job_steps, integration_health_job_events, integration_health_cursors, integration_connection_notices, integration_audit_events. - 'End-to-end definition inventory: audit-events-paging.e2e.spec.js, reader-access.e2e.spec.js.' controls: [TC-AVL-001, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, 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-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] exercised_by: [FAS-PFM-INT-02-01, FAS-PFM-INT-02-02, FAS-PFM-INT-02-03, FAS-PFM-INT-02-04, FAS-PFM-INT-02-05] suites: [TST-PFM-INT-145, TST-PFM-INT-343, TST-PFM-INT-364, TST-PFM-INT-456, TST-PFM-INT-457, TST-PFM-INT-483, TST-PFM-INT-517, TST-PFM-INT-520, TST-PFM-INT-538, TST-PFM-INT-548, TST-PFM-INT-573] --- # Recognize integration problems and trace changes ## Purpose Staff identify unhealthy connections, review changes and find the work that requires intervention. ## How It Works Staff open the Library to understand whether provider accounts are usable. Connection detail offers checks and recent activity figures for investigation. Scheduled checks reduce the need for staff to inspect every account manually. Integration history explains changes rather than only shows the present state. Connector warnings point back to the configuration that may need correction. Needs Attention collects work requiring a person and links to its fixing action. Notifications follow committed changes so message delivery cannot undo configuration. The health summary and console disagree about deliberately suspended connections. The product should resolve that discrepancy before relying on their counters and queues as one view. ## Relationships - Requires maintain a verified provider account connection to supply the prerequisite configuration or operation. - Connects with assign provider connections to business needs through shared integration records. - Connects with determine the result of uncertain or overdue calls through shared integration records. - Connects with deliver subscribed rhythm changes to integrations through shared integration records.