Give automatic roles on the start day
What It Does
This flow supplies configured automatic responsibilities when a saved future affiliation becomes due. A coordinator can enter a member’s employment before the start day without assigning current responsibilities too early. Later bounded work settles the saved pending marker and records the resulting person change.
Our reading is that the marker separates a one-time assignment decision from ongoing enforcement. Staff may remove an automatic role after settlement without every later pass restoring it. The schedule attempts eligibility; it does not establish a fixed deadline for all work when locks or backlog delay a contact.
What Starts It
Each five-minute job-reconciler pass attempts automatic roles for pending affiliations whose start date has arrived.
The system selects eligible work using the workspace calendar and pending or cursor state. Operational lifecycle and deployment conditions described in the hop contract determine whether a scheduled pass reaches it. A scheduled invocation begins an attempt; the observable result comes from the writes it actually commits.
The Flow
The diagram shows the sequence and service seams. Each synchronous stage waits for its result, while captured-event, queue and scheduled stages can run after the originating request has returned. The hop descriptions below identify the write and failure boundary, so the last arrow must not be mistaken for one atomic transaction across every participant.
Hop by Hop
1. Job reconciler (crm_job_reconciler)
The five-minute reconciler attempts automatic-role work in its own system context. A step failure is logged and eligibility can be tried on a later interval. The scheduled invocation itself neither changes the contact nor guarantees that an eligible role has been assigned.
2. Automatic role sweep
The sweep selects workspace contacts whose affiliations still have pending assignment and whose start day has arrived in that workspace’s calendar. Caught workspace-pass failures allow later passes, but obtaining a workspace execution context can fail outside that catch and stop the sweep.
3. Automatic role reconciliation (one transaction per contact)
The contact transaction locks due affiliations and chooses eligible active automatic roles allowed by organization policy. It also serializes first-contact decisions at the organization and persists assigned periods with marker clearing. Inactive or deceased people receive no new automatic responsibility; full restrictions can defer settlement.
4. Database change capture and compliance handler
Changed responsibility data enters contact capture and later compliance processing. The contact revision establishes what was assigned under system attribution, while the queue reaction updates the organization’s assessment separately. A failing compliance consumer cannot undo a responsibility already committed to the contact.
When Something Fails
Hop 1 — Job reconciler (crm_job_reconciler)
The failure boundary is: Log step failure and retry eligibility on a later pass. The remaining work or data is: Due assignments remain pending without a fixed recovery deadline. Job reconciler logs show step failures. A later attempt can be required; the scheduling or publication boundary does not establish an immediate user-visible completion.
Hop 2 — Automatic role sweep
The failure boundary is: Caught pass failures are logged and skipped. Obtaining workspace context occurs outside that catch and can abort the sweep. The remaining work or data is: Unvisited or failed workspaces retain pending affiliations. Sweep logs identify completed and failed passes.
Hop 3 — Automatic role reconciliation (one transaction per contact)
The failure boundary is: Rollback preserves pending assignment when the contact transaction fails. The remaining work or data is: Failed or locked work can remain due. System-attributed contact revisions show successful assignment.
Hop 4 — Database change capture and compliance handler
The failure boundary is: Retry failed compliance messages through SQS and dead-letter after five receives. The remaining work or data is: Assigned roles can precede updated organization compliance. Consumer logs and dead-letter messages expose reaction failure. This failure is downstream of committed input; operators investigate its own delivery rather than treating the caller’s original save as failed.
Repeats and Races
Assignment and clearing the pending marker share the contact transaction. A successful repeat sees settled work and does not reinstate a responsibility that staff later removed. An ended pending tie can be decided without assigning a role. This supports one-time settlement rather than permanent automatic repair of user corrections.
The worker locks each contact and due affiliation and coordinates destination first-contact decisions. A sixty-second sweep budget and a maximum of two hundred contacts per workspace bound each attempt. Failed or fully locked work can remain due after its start day; a later ordinary save can settle eligible work first.
What Is Observable
Job reconciler logs show step failures. Sweep logs identify completed and failed passes. System-attributed contact revisions show successful assignment. Consumer logs and dead-letter messages expose reaction failure.
Contact revisions identify successful system changes. Pass results and logs report actual work and failures; a pending marker or an open date window explains why later work remains. Reading effective dates does not establish that a worker reached the record or that every resulting notice was delivered.
Open Design Questions
The evidence does not establish a universal recovery deadline for pending assignments or absence of every cross-record deadlock. Existing findings also distinguish save-time and scheduled eligibility. The user-facing result is the committed responsibility period and system revision, rather than an assurance that a schedule ran successfully for every workspace.