State Machine (EDI partner lifecycle)

Variant of the State Machine pattern, applied to the technical lifecycle of an EDI partner rather than to a single message's cycle. The pattern that structures partner onboarding and operation in a multi-tenant hub.

Problem

Without explicit partner-cycle state, one cannot answer: "Where is partner Acme in its onboarding?", "How many partners are awaiting certificate?", "Who has been in production active for less than a month?". Information is scattered across Salesforce, Confluence, an Excel and the heads of a few people. Drifts go unnoticed — a partner stalls 3 months without detection. Management has no steering view.

Forces

• Partner cycle is long: 2-6 weeks of onboarding, then years in production.
• Transitions must be controlled: a partner does not go to production without having passed tests.
• Auditability is required: prove who validated which step, when, on what basis.
• Error states are real states: stalled, suspended, offboarding are not exceptions, they are states a partner may stay in for weeks.
• Temporal aspect: some transitions must occur within a deadline (30-day onboarding SLA).

Solution

Model the partner cycle as an explicit persisted state machine. Each partner has a DB row with { partnerId, state, history: [{state, at, by, reason}], lastActivityAt }. Transitions are guarded (verified preconditions), actions are triggered by transitions (notification, ticket created, dashboard updated). An ops dashboard shows distribution by state, by age, by owner. Stalled, Suspended states are monitored by a timer: no activity for 14 days → automatic transition to Stalled, investigation ticket created.

EDI partner lifecycle:

   [Prospect]               ─ commercial contact initiated
       │
   discovery ok
       ▼
   [Scoped]                 ─ TPA in progress, scope defined
       │
   specs received
       ▼
   [SpecsReceived]          ─ Implementation Guide received
       │
   mapping drafted
       ▼
   [MappingDrafted]         ─ v1 mappings in internal review
       │
   certs exchanged
       ▼
   [CertsExchanged]         ─ X.509 received and installed
       │
   gateway configured
       ▼
   [Configured]             ─ AS2/AS4 ready to send/receive
       │
   tests passed
       ▼
   [Tested]                 ─ bilateral tests validated
       │
   pilot started
       ▼
   [PilotActive]            ─ 10% of target volume
       │
   ramp ok
       ▼
   [ProductionActive]       ─ cruise regime
       │
       │  (offboarding)
       ▼
   [Archived]               ─ flow closed, data retained 10 years

   Error states:
   - [Stalled]              ← prolonged inactivity (to restart)
   - [Offboarding]          ← scheduled shutdown
   - [Suspended]            ← contractual dispute

EDI implementation

Concrete case: multi-tenant EDI hub with 200 active partners and 30 in onboarding. The partner master has a typed-enum partner_state with the above states. At each action of the onboarding playbook, state transitions: spec reception → SpecsReceived, mappings drafted → MappingDrafted, etc. The workflow engine (Camunda 8 or Temporal) executes transitions, generates human tasks (review, validation), and triggers notifications. The ops dashboard displays in real time: "30 prospects, 12 in SpecsReceived, 5 stalled for > 30 days, 200 ProductionActive, 3 Suspended for contractual dispute". The PSM (Partner Success Manager) sees their portfolio. The EDI director sees onboarding throughput (on average 8 partners/month go from Prospect to ProductionActive). Tools: Camunda 8 BPMN, Temporal Workflow, Spring State Machine, Akka FSM.

Anti-patterns

• Partner state in Excel: no transactional constraint, guaranteed divergence, impossible audit.
• Implicit state across multiple systems: Salesforce says "Prospect", Jira says "Active", the hub says "Tested" — divergence without detection.
• Unguarded transitions: a partner goes to ProductionActive without test = guaranteed incident at first flow.
• No timers: stalled partners are never detected, the pipeline silently clogs.
• Too many microscopic states: 40 unmanageable onboarding sub-states without business value.

Related patterns

• State Machine (EDI message) — variant for the individual message lifecycle.
• Process Manager — parent EIP pattern, explicit state of long processes.
• Process Engine — BPMN/workflow runtime executing the state machine.
• Temporal Workflow — modern code-first implementation.
• Step Functions — AWS managed implementation.

Sources

• Hopcroft J.E., Ullman J.D. — Introduction to Automata Theory, Languages, and Computation, Addison-Wesley, 1979. The formal foundation of state machines.
• Harel D. — Statecharts: A Visual Formalism for Complex Systems, Science of Computer Programming, 1987. The hierarchical extension of the FSM model, integrated in UML.
• Camunda — BPMN State Machine. Documentation and best practices. docs.camunda.io — State Machine
• Spring State Machine. Lightweight Java implementation. spring.io — Statemachine
• Hohpe G., Woolf B. — Enterprise Integration Patterns, Addison-Wesley 2003. Process Manager (§312) — parent pattern.
• UML State Machine spec (OMG). The formal UML specification, visual support for state machines. omg.org — UML