Run your first real export

1. Check the bundle and choose a folder

This guide belongs to the earlier setup reference named above. Use the matching Engine and Reader bundle; the current measure snapshot is a separate documentation track. If you do not have a bundle yet, read installation and availability first.

Create a working folder and open a terminal in it. Save both files below in that folder before running any commands. The three-row example lets you check the mapping before substituting your own export.

2. Save the example as orders.csv

Copy the column headers and three event rows into orders.csv. They describe the Receive, Check and Ship steps of order A-1.

event_ref,order_id,step_no,step,started,finished,handled_by
e1,A-1,1,Receive,2026-03-02T08:00:00Z,2026-03-02T08:05:00Z,u01
e2,A-1,2,Check,2026-03-02T09:00:00Z,2026-03-02T09:20:00Z,u02
e3,A-1,3,Ship,2026-03-02T10:00:00Z,2026-03-02T10:10:00Z,u01

3. Save observatory.yaml beside the CSV

This configuration maps the source columns explicitly. The step number declares event order; timestamps do not substitute for sequence. TERMINAL_ACTIVITY_TOKENS names Ship as the activity that closes an order.

# observatory.yaml, beside orders.csv
version: 1
output: {directory: out}
sources:
- id: orders
  path: orders.csv
  source_system: generic
  role: event_log
  domain: process_flow
  grain: process_event
  authority: primary
  required: true
  system: shop
  object_type: order
  params: {trace_completeness: complete_history}
  field_map:
    event_id: event_ref
    trace_id: order_id
    activity: step
    start_ts: started
    end_ts: finished
    employee_id: handled_by
  sequence:
    fields: [{column: step_no, type: integer, direction: ascending}]
    basis: case_step_number
systems: {shop: {}}
settings:
  TIMEZONE: Europe/Stockholm
  TERMINAL_ACTIVITY_TOKENS: [Ship]

4. Validate the input

$ observatory validate --config observatory.yaml

Read the result for the orders source: its status, accepted and rejected row counts, and note. This example contains three event rows. If rows are rejected or the source is not accepted, follow the validation recovery steps before continuing. Validation does not create the result file.

5. Run the Engine and check the result

$ observatory run observatory.yaml --out out/observatory.sqlite

Continue only after the Engine exits successfully with code 0. If it reports a blocked run or another error, stop and resolve the failure; do not check or open an older result as if it came from this run.

$ observatory-reader out/observatory.sqlite --check

The result path is out/observatory.sqlite beside the configuration. Use the Reader's file check before opening it. A blocked run leaves any previous result untouched, so the presence of an old file alone does not prove that this run succeeded.

6. Open and inspect the result

Open the result only after both the Engine run and the Reader file check have succeeded.

$ observatory-reader out/observatory.sqlite --open-browser

Inspect the order's recorded path and the run's warnings. One order is enough to inspect the mapping, but not to publish every statistic: some measures require larger populations. See Reader launch options if the file check or browser launch needs attention.

7. Substitute your own export

Update the source path and field mapping to match your columns, then declare event order and the closing activity. Do not mark an incomplete export as complete history. An order without a recorded closing activity stays open and has no completed lead time. Validate again after each mapping change.

If the run stops

When a run stops explains recovery, exit codes and how to distinguish a failed run from a successful run with rejected rows.