#Statuses

Draft, Active, Suspended, Cancelled, Expired

Agreement lifecycle

flowchart TB
  Start((Create)) --> Draft[Draft]
  Draft -->|Activate| Active[Active]
  Active -->|Suspend| Suspended[Suspended]
  Suspended -->|Resume| Active
  Active -->|Cancel| Cancelled[Cancelled]
  Active -->|End date reached| Expired[Expired]
  Active -->|Auto-renew| Active

  class Start egkStart
  class Draft egkDraft
  class Active egkSuccess
  class Suspended egkWarn
  class Cancelled egkError
  class Expired egkTerminal

#Header fields that drive generation

An agreement needs at least one line to activate. Lines carry description, quantity, unit price, optional catalog product, discount, and ETA-aware tax rows (fractions, e.g. 0.14).

#Actions

#Statuses

Scheduled, Due, Processing, Generated, Submitted, Completed, Failed, PendingReview, Cancelled, Expired

Occurrence lifecycle — lease, pre-checks, generate

flowchart TB
  Sch[Scheduled] -->|Run date reached| Due[Due]
  Due -->|Lease claimed| Proc[Processing]
  Proc -->|Pre-check blocks| Failed[Failed]
  Proc -->|Needs a person| Review[PendingReview]
  Proc -->|Documents created| Gen[Generated]
  Gen -->|ETA accepted or no bridge| Done[Completed]
  Gen -->|ETA submitted| Sub[Submitted]
  Sub --> Done
  Failed -->|Retry window| Due
  Review -->|Run manually| Proc
  Due -->|Grace elapsed| Exp[Expired]
  Sch -->|Agreement cancelled| Can[Cancelled]

  class Sch egkDraft
  class Due,Proc,Gen,Sub egkActive
  class Done egkSuccess
  class Review egkWarn
  class Failed egkError
  class Exp,Can egkTerminal

#Business key and idempotency

Every occurrence carries IdempotencyKey = REC:{agreementId}:{periodStart:yyyyMMdd}. The key is unique in the database and is handed to the AR invoice factory or the AP bill factory (ExternalIdempotencyKey) or stamped as the sales-order Reference; supplier purchase orders use the deterministic number RPO-{agreement}-{yyyyMMdd}. A replayed job, a second worker, or a double click therefore finds the existing documents and links them instead of generating again. An occurrence that already has an AR or AP invoice is closed as already generated without touching the ledgers.

#Pre-checks (before any document is created)

A credit-limit refusal raised by the AR factory during generation is also parked as PendingReview.

#What gets generated

The generated AR invoice then follows the normal cycle: ArInvoiceSentEvent → GL journal (Dr AR control / Cr revenue / Cr tax), ArInvoicePostedIntegrationEvent → ETA e-invoice draft when the company has an enabled ETA bridge setting. ETA status events (Valid, Cancelled, Rejected) close or flag the occurrence through the AR ↔ ETA sync.

On the supplier side the engine never books stock or a liability by itself: the goods receipt stays Draft until Purchasing posts it on physical receipt (that posting moves stock and raises the GRN journal), and the AP bill goes through the normal AP approval before its journal (Dr expense or GR/IR / Cr AP control) is posted. The occurrence is Completed once the three documents exist; the open receipt shows in the Purchasing worklists, not in the recurring review queue.

#Actions

• Scheduler job (ScheduleRecurringOccurrencesCommand): materialises periods up to ScheduleHorizonDays for every active agreement in every tenant.
• Processor job (ProcessDueRecurringOccurrencesCommand): claims due occurrences with a database lease (ExecuteUpdate, LeaseMinutes, worker id), executes them one by one, writes a RecurringExecutionLog row per attempt and releases the lease. A crashed worker's lease expires and another worker takes over — never generating twice because the business key is checked first.
• Retry: Failed (retryable) occurrences are picked up again after the retry delay; Failed (permanent) and Expired are not.
• Notifications: failures, insufficient stock, expired periods and ETA refusals raise operator notifications; the dashboard at /sales/recurring shows due / processing / review / failed counters, next runs and the last execution log per agreement.
• Multi-tenant: jobs fan out per tenant (TenantFanOutJob); every command runs inside the tenant's scope and company.
• Legacy AR recurring templates were migrated into agreements (MigrateArRecurringTemplates); the old template screen remains read-only.