Lifecycle

A shipment is not created from scratch every time its status changes. The previous lesson’s instances give each shipment a stable id. A state machine now moves those same instances from packed to in transit to delivered.

Follow two shipments

This scenario combines two instances with three lifecycle states. We want the following six event values:

{"shipmentId":"SHP-00","status":"PACKED"}
{"shipmentId":"SHP-01","status":"PACKED"}
{"shipmentId":"SHP-00","status":"IN_TRANSIT"}
{"shipmentId":"SHP-01","status":"IN_TRANSIT"}
{"shipmentId":"SHP-00","status":"DELIVERED"}
{"shipmentId":"SHP-01","status":"DELIVERED"}

Packed, in transit, delivered

generators:
  - name: shipments
    config:
      maxEvents: 10
    instances:
      count: 2
      fields:
        shipmentId: =seq(format=SHP-%02d)
    value:
      shipmentId: $shipmentId
    stateMachine:
      initial: packed
      states:
        packed:
          emit:
            status: PACKED
          next: inTransit
        inTransit:
          emit:
            status: IN_TRANSIT
          next: delivered
        delivered:
          emit:
            status: DELIVERED

Press Try it. Each shipmentId appears once in every state.

Although config.maxEvents allows ten events, the generator stops after six because both instances have reached a state with no next.

How a state machine moves

The state machine has three parts:

• initial names the first state for every new instance.
• emit adds that state’s fields to the event.
• next names the state the instance enters after emitting.

The delivered state omits next, so it is terminal. Once every instance is terminal, that generator is finished.

A generator can also use a state machine without instances; it then follows one lifecycle. Instances are what let several independent shipments progress through the same states.

Keep base and state fields separate

The event combines fields from value and the current state’s emit. In this example, value supplies shipmentId and emit supplies status.

Do not define the same output name in both places:

value:
  status: current
stateMachine:
  states:
    packed:
      emit:
        status: PACKED

That collision is an error. Give each field one clear source.

For branching or probabilistic transitions, next can use an expression that returns a state name. See selection expressions after you are comfortable with the fixed sequence above.

Run this file

Save the example as shipment-lifecycle.yaml. Request ten events and notice that the terminal states finish the scenario after six.

sample prints a short preview to your terminal. It does not wait for real-time pacing, and it never opens Kafka, PostgreSQL, or other destinations.

synthtraffic sample shipment-lifecycle.yaml --events 10 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/shipment-lifecycle.yaml:/work/shipment-lifecycle.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/shipment-lifecycle.yaml --events 10 --seed 42

Next: build nested data with collections.