--- id: WF-PFM-QRY-008 title: Deliver a scheduled query or report to its recipients trigger: 'A recurrence is due, or an authorized person requests an immediate schedule run.' product_area: platform module: queries revision: 1 status: draft design_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f inference: [] implements: - CAP-PFM-QRY-015 - CAP-PFM-QRY-014 - CAP-PFM-QRY-013 moves: - STATE-PFM-QRY-007 - STATE-PFM-QRY-008 - STATE-PFM-QRY-006 crosses: - SVC-PFM-QRY-queries idempotency: >- Occurrence uniqueness protects admission. Retries reuse the run’s file and recipient communication keys, which coordinate duplicate submission without recalling any message already sent. concurrency: >- The dispatcher is single-concurrency. Three delivery consumers run separately from interactive export work, and a report run occupies its consumer while polling the renderer. hops: - 'n': 1 actor_or_service: Schedules dispatcher (scheduling library) action: >- Claim due recurrences, insert unique occurrence runs, advance recurrence and publish delivery work. anchor: 'services-platform:modules/queries/aws/logic/query-schedules.lambda.ts' seam: schedule on_failure: A later dispatcher pass handles missed due work. left_inconsistent: A due run may wait for successful dispatch. observer: the dispatcher's silence alarm provenance: observed source: 'services-platform:modules/queries/db/schedules.table.ts' - 'n': 2 actor_or_service: Run Now route (alternative entry) action: 'For manual execution, commit the run and its export request, then publish after commit.' anchor: 'services-platform:modules/queries/services/schedules/schedule-run-publisher.ts' seam: queue on_failure: Observed publication rejection releases the offered run for dispatch. left_inconsistent: A crash between commit and publication can leave an offered queued run awaiting recovery. observer: the run history provenance: observed source: >- services-platform:modules/queries/services/persistence/query-schedules.ts:insertRunNow, releaseRunNow - 'n': 3 actor_or_service: Schedule consumer action: >- Start the occurrence using the owner for automatic work or manual runner for immediate work. Resolve the pinned query or current report. anchor: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' seam: queue on_failure: Source access loss fails the run; applicable automatic occurrences pause their schedule. left_inconsistent: Manual-run access failure does not by itself pause the owner’s recurrence. observer: the schedule's history and pause reason provenance: observed source: 'services-platform:modules/queries/services/schedules/scheduled-report-delivery.ts' - 'n': 4 actor_or_service: Schedule consumer action: >- Generate query files in the receive, or dispatch a report render and poll its file for up to twelve minutes. anchor: 'services-platform:modules/queries/services/exports/run-query-export.ts:runQueryExport' seam: queue on_failure: >- Permanent refusals settle; infrastructure or unfinished-render failures retry within three receives. left_inconsistent: A report file can complete after the delivery run has already failed. observer: run history; the queue's dead-letter alarm provenance: observed source: 'services-platform:modules/queries/services/schedules/scheduled-report-delivery.ts' - 'n': 5 actor_or_service: Schedule consumer action: Suppress delivery for an empty query when its empty-result option is enabled. anchor: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' seam: sync on_failure: The skip outcome is recorded rather than retried as a delivery error. left_inconsistent: No communication is requested for the skipped occurrence. observer: history shows skipped_empty provenance: observed source: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' - 'n': 6 actor_or_service: Schedule consumer and Communications action: >- Resolve each current recipient address, record skip reasons where needed and submit the template and personal signed link through Communications. anchor: 'services-platform:modules/queries/services/schedules/scheduled-delivery.ts' seam: queue on_failure: Submission failure retries the run while retaining completed recipient outcomes. left_inconsistent: Some recipients can already have messages while others await another attempt. observer: delivery rows; the communication message states read beside them provenance: observed source: 'services-platform:modules/queries/db/query-schedule-deliveries.table.ts' - 'n': 7 actor_or_service: Scheduling library action: >- Settle success, skip or failure through recurrence tracking, resetting or incrementing the streak and applying the five-failure pause. anchor: >- services-platform:node_modules/@rhythmsoftware/macroservice-schedules/dist/schedule-repository.js seam: sync on_failure: A persistence error remains subject to the consumer’s failure handling. left_inconsistent: Delivered external messages remain delivered even if later settlement fails. observer: schedule_run_failed and schedule_auto_paused log metrics provenance: observed source: 'services-platform:node_modules/@rhythmsoftware/macroservice-schedules/dist/schedule-states.js' branches: - Manual execution uses the clicking person’s access. - Report schedules render the current report and flag a changed source version. waits: - Renderer polling can consume twelve minutes of the delivery worker’s fifteen-minute receive. evidence: - >- services-platform at ad3f6a6: modules/queries/services/schedules/*.ts; aws/logic/query-schedules.lambda.ts; aws/resources/query-schedules.sqs.ts; db/schedules.table.ts, schedule-runs.table.ts, query-schedules.table.ts, query-schedule-deliveries.table.ts; @rhythmsoftware/macroservice-schedules; docs/migrations/query-scheduling-exports/README.md (D2–D13) controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, 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-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Deliver a scheduled query or report to its recipients ## What It Does A recurrence is due, or an authorized person requests an immediate schedule run. Manual execution uses the clicking person’s access. ## The Flow ```mermaid sequenceDiagram participant C as Request or schedule participant H0 as Schedules dispatcher scheduling library participant H1 as Run Now route alternative entry participant H2 as Schedule consumer participant H3 as Schedule consumer participant H4 as Schedule consumer participant H5 as Schedule consumer and Communications participant H6 as Scheduling library opt Automatic due occurrence C-)H0: Claim due recurrences, insert unique occurrence runs, advance recurrence and publish delivery work end opt Manual run request C-)H1: For manual execution, commit the run and its export request, then publish after commit end H1-)H2: Start the occurrence using the owner for automatic work or manual runner for immediate work H2-)H3: Generate query files in the receive, or dispatch a report render and poll its file for up to twelve H3->>H4: Suppress delivery for an empty query when its empty-result option is enabled H4-)H5: Resolve each current recipient address, record skip reasons where needed and submit the template and H5->>H6: Settle success, skip or failure through recurrence tracking, resetting or incrementing the streak an ``` Claim due recurrences, insert unique occurrence runs, advance recurrence and publish delivery work. For manual execution, commit the run and its export request, then publish after commit. Start the occurrence using the owner for automatic work or manual runner for immediate work. Resolve the pinned query or current report. Generate query files in the receive, or dispatch a report render and poll its file for up to twelve minutes. Suppress delivery for an empty query when its empty-result option is enabled. Resolve each current recipient address, record skip reasons where needed and submit the template and personal signed link through Communications. Settle success, skip or failure through recurrence tracking, resetting or incrementing the streak and applying the five-failure pause. ## When Something Fails A later dispatcher pass handles missed due work. A due run may wait for successful dispatch. Observed publication rejection releases the offered run for dispatch. A crash between commit and publication can leave an offered queued run awaiting recovery. Source access loss fails the run; applicable automatic occurrences pause their schedule. Manual-run access failure does not by itself pause the owner’s recurrence. Permanent refusals settle; infrastructure or unfinished-render failures retry within three receives. A report file can complete after the delivery run has already failed. The skip outcome is recorded rather than retried as a delivery error. No communication is requested for the skipped occurrence. Submission failure retries the run while retaining completed recipient outcomes. Some recipients can already have messages while others await another attempt. A persistence error remains subject to the consumer’s failure handling. Delivered external messages remain delivered even if later settlement fails. ## Idempotency and Concurrency Occurrence uniqueness protects admission. Retries reuse the run’s file and recipient communication keys, which coordinate duplicate submission without recalling any message already sent. The dispatcher is single-concurrency. Three delivery consumers run separately from interactive export work, and a report run occupies its consumer while polling the renderer.