Skip to main content
A custom journey is a charging journey described as JSON: the same thing the Charging Journeys builder produces, written down so a human or an agent can version it, diff it, and replay it from CI. Import one and it opens ready to run: a template-shaped file opens with every knob restored, and a file with its own hand-authored action list opens with that list shown, its values editable in the builder (more on the difference below). Either way it streams evidence and lands a report exactly like a catalogue journey. The fastest way to get a valid file is Download sample on the Charging Journeys page. It exports a ready-to-run custom journey for your selected target. Edit that, or write one from the shape below.

​
The shape

​
The knobs that matter

  • journey: the template the custom journey starts from (e.g. first-successful-charge). It selects the story; an unknown id falls back to the recommended journey.
  • ocpiVersion and targetId are advisory in the file. On import the builder runs the journey against whichever target you have selected, so a sample from one target still runs against another, and you do not need a real targetId to share a file.
  • clock.mode: accelerated compresses a session into seconds; real runs it at wall-clock cadence for long-session testing.
  • session.cadenceSeconds and jitterSeconds: how often meter updates are pushed, and how irregular they are (jitterSeconds above 0 means irregular).
  • session.updates: which fields each update carries (kwh, total_cost, status, charging_periods).
  • disturbances: faults injected mid-journey to prove the endpoint fails safely (e.g. skip_intermediate_update, duplicate_full_put, delay_cdr).
  • coverageDepth: happy-path, edge-cases, or adversarial.
  • seed: makes a run reproducible; keep it stable to replay the same story.
Unknown or malformed fields fall back to sensible defaults, so a partial file still imports and simply uses the defaults for anything you left out. One exception: a file that spells out its own timed actions list carries those hand-authored actions into the builder too, as the timeline the file wrote rather than the knob editor above. The Configure step shows each action’s time, kind, and values, in the order the file lists them. The run itself executes each action at its own time, not the list order, so keep the list chronological if you want the two to match. Click any value to change it in place: the builder shows what the value must be and, where an OCPI version defines the field, the spec file it comes from. Timing comes straight from the file; you can still change the endpoint, the clock, and the seed, and the run streams and grades exactly like any other custom journey. To change an action’s kind, its time, or the order of the list, edit the JSON and re-import. A second exception: a file that names journey: 'custom' but lists no actions is refused, with a message, rather than imported and silently emptied. That intent (a custom journey) is not something the importer discards on your behalf.

​
Import, run, and save

  1. On Charging Journeys, choose Import scenario JSON and pick your file, or Download sample to start from a working one.
  2. The custom journey opens in the builder on the Configure step with your knobs applied. Adjust anything, then Preview to compile the plan.
  3. Start the run. It streams live and lands a graded report in Runs, stored on your account, replayable and runnable from CI with the same JSON.
You can annotate a working copy with // comments and trailing commas; the importer strips them. The API and CI expect strict JSON. See also Run a charging journey for the run, follow, and recovery flow.