Run a charging journey

A conformance suite checks that each endpoint obeys the specification. A charging journey drives a whole story against your partner: a session that starts, meters energy, completes and produces a CDR, with the tester judging the sequence as well as each exchange. Journeys run against a registered connection, take minutes rather than seconds, and stream evidence while they go. Command journeys send START_SESSION, STOP_SESSION, UNLOCK_CONNECTOR or RESERVE_NOW to chargers your partner serves, so a real charger may start, stop, unlock or reserve. Run them against a test system. The flow is always the same four steps: browse the catalogue, preview a plan, start the run, follow it to a verdict.

Journeys do not run over a connector. They execute in a separate worker process that cannot reach the socket a connector holds, so the app will not offer a connector-backed endpoint for a journey and the API refuses one. Conformance runs are what a connector carries today. If you are testing a local service and want journeys, use a tunnel instead.

1. Browse the catalogue

Operation reference: GET /testing/journeys.

curl -fsS "https://chargerdojo.com/api/v1/testing/journeys?targetId=$CONNECTION_ID" \
  -H "Authorization: Bearer $DOJO_KEY"

Returns the journey packs, scenarios and templates. With targetId, the list is filtered to what that connection can actually run, based on its OCPI version, its role and the modules it advertises, and the response includes the target’s capability summary. Omit targetId to see the full catalogue.

2. Preview a plan

A journey is described by a manifest: which template, against which target, on what clock. Previewing compiles it into an immutable plan and tells you whether it can run, before anything touches your partner. This example needs a registered eMSP target on OCPI 2.2.1. Operation reference: POST /testing/journeys/preview.

curl -fsS -X POST "https://chargerdojo.com/api/v1/testing/journeys/preview" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "journey": "first-successful-charge",
    "targetId": "'"$CONNECTION_ID"'",
    "roleUnderTest": "EMSP",
    "journeyPack": "core-charging",
    "topology": { "kind": "direct", "profile": "core-ocpi" },
    "ocpiVersion": "2.2.1",
    "clock": { "mode": "accelerated", "durationSeconds": 1800, "accelerationFactor": 60 },
    "session": { "cadenceSeconds": 60, "strategy": "put-and-patch", "updates": ["kwh", "status"] },
    "completion": { "cdrDelaySeconds": 0 },
    "seed": "ci-2026-07-16"
  }'

The response carries the compiled plan and the two values the start call needs:

{
  "success": true,
  "data": {
    "planId": "...",
    "planHash": "...",
    "expiresInSeconds": 3600,
    "runAllowed": true,
    "plan": {}
  }
}

A plan expires after an hour. runAllowed: false means the preflight found a reason the run cannot proceed (an unregistered target, a module the target does not advertise); the plan spells out which.

3. Start the run, idempotently

Operation reference: POST /testing/journey-runs.

curl -fsS -X POST "https://chargerdojo.com/api/v1/testing/journey-runs" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-${CI_JOB_ID}-journey" \
  -d "{\"planId\": \"$PLAN_ID\", \"planHash\": \"$PLAN_HASH\"}"

A 202 means the run was admitted and is active work, not a verdict:

{
  "success": true,
  "data": {
    "runId": "...",
    "reportId": "...",
    "status": "queued",
    "repeated": false,
    "statusUrl": "/api/v1/testing/journey-runs/...",
    "eventsUrl": "/api/v1/testing/journey-runs/.../events",
    "streamUrl": "/api/v1/testing/journey-runs/.../stream"
  }
}

Always send Idempotency-Key from CI. A repeated start with the same key returns the original run with repeated: true instead of creating a second one, so a start request that is retried cannot double-charge your quota or hit your partner twice. The same key with a different body answers 409. Every preview compiles a new plan, so key a start by the job that compiled its plan: a job that is run again starts a new run. The starts that do not admit a run:

Status	Meaning
`402`	The journey needs a capability your plan does not include, such as the Direct Payment or Booking packs, or more than one session in parallel. The body names the capability. Nothing was admitted and nothing reached the target.
`409`	The plan expired or its hash changed. Preview again and start with the fresh `planId` and `planHash`.
`429`	Your plan’s run quota is full. Each in-flight journey holds one run slot until it finishes, and a run waiting on a recovery decision keeps holding its slot until you decide. The `Retry-After` header says when to try again.
`503`	Our runner is unavailable. This is a statement about our service, never about your partner. Nothing was admitted and nothing reached the target. Start again later with the same `Idempotency-Key`; the key makes that safe.

4. Follow it to a verdict

Operation reference: GET /testing/journey-runs/{id}.

curl -fsS "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID?wait=55" \
  -H "Authorization: Bearer $DOJO_KEY"

?wait=<seconds> long-polls until the run reaches a terminal state, pauses for a recovery decision, or the wait expires. The response carries status, the compiled plan, the current stage, the run’s verdicts once they exist, and the two fields the next two sections explain: runIntegrity and recoveryOptions.

What each status means

Status	Meaning
`queued`	Admitted, waiting for a runner.
`running`	The journey is executing against your partner.
`recovering`	Our runner restarted and is resuming from its checkpoint. No request is repeated; you do not need to do anything.
`recovery_required`	The delivery of one action is uncertain and the run is paused for your decision. See below.
`completed`	The journey finished and the verdicts are in. Finished is not the same as passed: read the verdicts.
`failed`	The journey could not finish.
`cancelled`	You cancelled it.
`interrupted`	The run ended early with its evidence preserved, for example because you chose to stop it during recovery.

Run integrity is about our evidence, not their conduct

runIntegrity states how complete our record of the run is:

Value	Meaning
`valid`	Our record has no delivery gap. Missing evidence can still leave checks not tested; read coverage and the verdict lanes.
`degraded`	Part of the run could not be tested, for example because you chose to continue past an uncertain action. Verdicts that depend on the gap say so.
`invalid`	The evidence cannot support verdicts.

coverage.outcome is nothing_graded when no assertion reached a verdict, partial when a check or planned step was not exercised, and graded when every planned step and check ran. Missing premises do not fail your partner. A degraded or invalid run is never a statement that your partner failed. Target failures show up as failed verdicts with the exchange attached, exactly as in a conformance run.

How a journey verdict is graded

Every check in a journey answers to one of five authorities, and the authority decides what the check may do to your verdict. An expanded row in the report names it beside the rule id.

Authority	The report shows	What it may do
Conformance requirement	`OCPI SHALL`	Fail. It grades a `SHALL` or `MUST`, a required field, a required header or a closed list of values that binds your side of the exchange.
Recommendation	`OCPI SHOULD`	Warn. It grades a `SHOULD` or “advised”, which you may decline. It never fails.
Partner profile	`Partner profile`	Nothing yet. No partner profile names a rule that can run, so this lane reports not tested.
Business check	`Business checks`	Fail against a term your manifest sets, such as how soon a CDR must arrive. It is your contract, not OCPI’s.
Robustness observation	`Robustness observation`	Warn. It reports how your endpoint copes with something OCPI does not settle. It never fails.

The OCPI keyword distinction follows OCPI 2.2.1 requirement keywords. Partner-profile and business rules have their own authority; they are not additional OCPI requirements. Not tested is never a pass. The report marks a check not tested when a step it needs was refused or never answered, or the response carried nothing to grade. Each row says what was missing. A run with no tested checks proves nothing either way. The clause is one click from the verdict. Under the rule id and authority, an expanded row prints the address of the clause the check was graded on and, where its rule records the clause, what binds in it (the modal word, or “required by its table” for a schema row) and the clause itself. Reports saved before clauses were recorded show the address alone. When a rule’s grading changes, the changelog says which rules moved; an old report keeps the verdict it was given, so run the journey again to grade it under the current rules. Read your report explains the verdict words and why a warning is not a failure.

Stream the events

Page through events with the sequence number as the cursor: Operation reference: GET /testing/journey-runs/{id}/events.

curl -fsS "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID/events?after=0&limit=100" \
  -H "Authorization: Bearer $DOJO_KEY"

The response’s meta.nextAfter tells you where to resume; pass it as the next after. Or hold one connection open with server-sent events: Operation reference: GET /testing/journey-runs/{id}/stream.

curl -fsSN "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID/stream" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Accept: text/event-stream"

Every SSE message carries its sequence as the event id. If the connection drops, resume without a gap by reconnecting with the standard Last-Event-ID header set to the last id you saw; the stream replays from there and closes itself when the run reaches a terminal state.

Cancel a run

Operation reference: POST /testing/journey-runs/{id}/cancel.

curl -fsS -X POST "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID/cancel" \
  -H "Authorization: Bearer $DOJO_KEY"

Answers 202: cancellation is a request, and the run winds down at the next safe point rather than mid-exchange.

When a run pauses for a recovery decision

Sometimes the runner sends a mutating OCPI request and cannot learn whether it arrived: the connection died between dispatch and response. Resending it automatically could duplicate a session or a CDR on your partner’s side, so the tester never replays an uncertain mutation on its own. The run pauses as recovery_required, holds its slot, and asks you to choose. Read the run to see the choices. They are computed by the server for that specific uncertain action; only what the run read offers is valid: Operation reference: GET /testing/journey-runs/{id}.

curl -fsS "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID" \
  -H "Authorization: Bearer $DOJO_KEY" | jq '{status: .data.status, recoveryVersion: .data.recoveryVersion, options: .data.recoveryOptions}'

Decision	What it does
`reconcile`	Issue a safe read to find out whether the uncertain object reached the target, then continue on complete evidence. Offered when the action has a safe read.
`continue_without_replay`	Carry on without resending. The affected stage cannot be tested and the run’s integrity becomes `degraded`.
`stop`	End the run as `interrupted`, preserving all evidence collected so far.
`rerun_plan`	Start a separate, fresh run from the same immutable plan. The paused run keeps its evidence.

Apply one with the recoveryVersion from the same read: Operation reference: POST /testing/journey-runs/{id}/recovery.

curl -fsS -X POST "https://chargerdojo.com/api/v1/testing/journey-runs/$REPORT_ID/recovery" \
  -H "Authorization: Bearer $DOJO_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"recoveryVersion\": $RECOVERY_VERSION, \"decision\": \"reconcile\"}"

A 409 means your recoveryVersion is stale: the run moved on since you read it, perhaps because a colleague decided first. Re-read the run and decide against the current state. This is deliberate; two people cannot apply conflicting decisions to the same uncertain action.

Put it in CI

A journey grades conformance, business checks and observations separately. Gate on conformance, which is the one that says your partner broke a rule; read the rest on the report. A passing CI gate requires explicit full coverage with complete, consistent check and step counts. Graded checks come from planned actions, so a pass also requires at least one planned action. Historical reports may omit step counts; those reports exit 2 because full coverage is unknown. That is a reporting prerequisite, not a failed OCPI requirement. Operation reference: POST /testing/journeys/preview, POST /testing/journey-runs, GET /testing/journey-runs/{id}.

#!/usr/bin/env bash
set -euo pipefail

# Exit 2 says there is no answer about the target. Exit 1 is kept for a broken rule.
no_verdict() {
  echo "$*" >&2
  exit 2
}

[ -n "${DOJO_KEY:-}" ] ||
  no_verdict 'DOJO_KEY is required.'
[ -n "${CI_JOB_ID:-}" ] ||
  no_verdict 'CI_JOB_ID is required.'

API="https://chargerdojo.com/api/v1/testing"
AUTH="Authorization: Bearer $DOJO_KEY"
[ -f journey-manifest.json ] && [ -r journey-manifest.json ] ||
  no_verdict 'The journey manifest must be a readable regular file.'
# One key per job. A start request this job retries returns the same run. A job that is
# run again compiles a new plan, so it needs a new key and starts a new run.
IDEMPOTENCY_KEY="ci-${CI_JOB_ID}-journey"

# 1. Compile the plan. HTTP errors fail; the status check rejects every other non-2xx.
#    --retry waits out a 429 by its Retry-After header; --max-time bounds each read.
HTTP_STATUS=$(curl -sS --fail-with-body --retry 3 --max-time 65 --write-out "%{http_code}" -o preview.json \
  -X POST "$API/journeys/preview" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d @journey-manifest.json) ||
  no_verdict 'Could not compile the plan.'
case "$HTTP_STATUS" in
  2[0-9][0-9]) ;;
  *) no_verdict 'Could not compile the plan.' ;;
esac
jq -e -s 'length == 1 and (.[0] | .success == true)' preview.json > /dev/null ||
  no_verdict 'The API answered something that is not a plan.'
PLAN_ID=$(jq -er '.data.planId | strings | select(length > 0)' preview.json) ||
  no_verdict 'The compiled plan has no id.'
PLAN_HASH=$(jq -er '.data.planHash | strings | select(length > 0)' preview.json) ||
  no_verdict 'The compiled plan has no hash.'

# 2. Start it, pinned to that hash.
HTTP_STATUS=$(curl -sS --fail-with-body --retry 3 --max-time 65 --write-out "%{http_code}" -o start.json \
  -X POST "$API/journey-runs" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{\"planId\": \"$PLAN_ID\", \"planHash\": \"$PLAN_HASH\"}") ||
  no_verdict 'Could not start the run.'
case "$HTTP_STATUS" in
  2[0-9][0-9]) ;;
  *) no_verdict 'Could not start the run.' ;;
esac
jq -e -s 'length == 1 and (.[0] | .success == true)' start.json > /dev/null ||
  no_verdict 'The API answered something that is not a run.'
REPORT_ID=$(jq -er '.data.reportId | strings | select(length > 0)' start.json) ||
  no_verdict 'The started run has no id.'

# 3. Long-poll to a terminal state. A 200 with a non-terminal status is active work, not an
#    outcome, and 60 waits of up to a minute each is where this stops asking.
POLLS=0
while true; do
  # -o keeps a retried read from joining two response bodies into one.
  HTTP_STATUS=$(curl -sS --fail-with-body --retry 3 --max-time 65 --write-out "%{http_code}" -o run.json \
    "$API/journey-runs/$REPORT_ID?wait=55" -H "$AUTH") ||
    no_verdict 'Could not read the run.'
  case "$HTTP_STATUS" in
    2[0-9][0-9]) ;;
    *) no_verdict 'Could not read the run.' ;;
  esac
  jq -e -s 'length == 1 and (.[0] | .success == true)' run.json > /dev/null ||
    no_verdict 'The API answered something that is not a run.'
  RUN_STATUS=$(jq -er '.data.status | strings' run.json) ||
    no_verdict 'The run reported no status.'
  case "$RUN_STATUS" in
    completed) break ;;
    failed|cancelled|interrupted)
      no_verdict 'Journey ended without a verdict:' "$RUN_STATUS" ;;
    recovery_required)
      no_verdict 'Journey paused for a recovery decision. Decide, then re-run this job.' ;;
    queued|running|recovering)
      POLLS=$((POLLS + 1))
      [ "$POLLS" -lt 60 ] || no_verdict 'The journey did not finish in time.'
      sleep 5 ;;
    *) no_verdict 'The run reported an unknown status:' "$RUN_STATUS" ;;
  esac
done

# 4. Gate on the evidence. Each of the four lanes must carry whole counts.
jq -e '
  def count: type == "number" and isfinite and . >= 0 and floor == .;
  .data.verdicts as $v |
  [$v.conformance, $v.partnerCompatibility, $v.customerContract, $v.observations] |
  all(.[]; type == "object" and ([.passed, .failed, .warned, .unobservable] | all(.[]; count)) and
    (.serverErrors | count) and (.serverErrors <= .warned))' run.json > /dev/null ||
  no_verdict 'The run reported no usable verdicts.'
jq -r '.data.verdicts | to_entries[] | select(.value | type == "object") | "\(.key) \(.value | tojson)"' run.json

INTEGRITY=$(jq -er '.data.runIntegrity | strings' run.json) ||
  no_verdict 'The run reported no usable integrity.'
[ "$INTEGRITY" = "valid" ] ||
  no_verdict 'Our record of the run is incomplete. Run integrity:' "$INTEGRITY"

FAILED=$(jq '.data.verdicts.conformance.failed' run.json)
if jq -e '.data.verdicts.conformance.failed > 0' run.json > /dev/null; then
  echo "$FAILED required checks failed."
  exit 1
fi

# A declined recommendation was graded and stays advisory. A server error and a
# check marked not tested graded nothing, and a pass needs something graded.
jq -e '.data.verdicts.conformance | .passed + .failed + .warned - .serverErrors |
  type == "number" and isfinite and . > 0 and floor == .' run.json > /dev/null ||
  no_verdict 'Nothing was graded in the conformance lane.'
NOT_GRADED=$(jq '.data.verdicts | [.conformance, .partnerCompatibility, .customerContract, .observations] |
  any(.[]; .unobservable > 0 or .serverErrors > 0)' run.json)
# Historical reports may omit step counts. They give no answer about full coverage.
# Graded assertions come from planned actions, so a pass needs a positive plan.
COVERAGE=$(jq -er '
  def count: type == "number" and isfinite and . >= 0 and floor == .;
  .data as $d |
  [$d.verdicts.conformance, $d.verdicts.partnerCompatibility,
   $d.verdicts.customerContract, $d.verdicts.observations] as $lanes |
  $d.coverage | select(type == "object") |
  select([.graded, .notGraded, .plannedSteps, .stepsNotExercised, .stepsNotReached] |
    all(.[]; count)) |
  select(.stepsNotExercised + .stepsNotReached <= .plannedSteps) |
  select(.graded == ($lanes | map(.passed + .failed + .warned - .serverErrors) | add)) |
  select(.notGraded == ($lanes | map(.unobservable + .serverErrors) | add)) |
  select(.outcome != "graded" or
    (.graded > 0 and .plannedSteps > 0 and .notGraded == 0 and .stepsNotExercised == 0 and .stepsNotReached == 0)) |
  .outcome | strings |
  select(. == "graded" or . == "partial" or . == "nothing_graded")' run.json) ||
  no_verdict 'The run reported no usable coverage.'
if [ "$NOT_GRADED" = "true" ] || [ "$COVERAGE" != "graded" ]; then
  no_verdict 'Partial coverage: some checks or steps were not graded.'
fi

echo 'Charging journey: no conformance check failed. Every planned step was graded. Partner compatibility and business checks do not gate this job.'

Exit 1 is “the target broke a rule”. Exit 2 is “we do not have an answer”, which covers our own unavailability, a cancellation, a pending recovery decision, a run that did not finish within the loop’s sixty polls, and a run that graded nothing or only part of its plan. Missing or malformed verdict counters or coverage also exit 2; only an explicit graded coverage outcome can pass. A build log should never turn “we do not know” into “your partner is broken”, or into a pass. The script needs DOJO_KEY and CI_JOB_ID. Save the manifest as a readable JSON file named journey-manifest.json beside the script. It writes preview.json, start.json and run.json into the working directory, so a failed job keeps the response it stopped on.

Read your report, and see Troubleshooting for the status codes journeys can answer. When the catalogue has no journey for the case you are chasing, author a custom one: the same JSON the builder produces, written down so you can version it, diff it and replay it from CI.

Get started

Guides

Changelog

API reference

Run a charging journey

1. Browse the catalogue

2. Preview a plan

3. Start the run, idempotently

4. Follow it to a verdict

What each status means

Run integrity is about our evidence, not their conduct

How a journey verdict is graded

Stream the events

Cancel a run

When a run pauses for a recovery decision

Put it in CI

Next