SIMBOT user guide
SIMBOT runs authored FIX scenarios against the simulator and records what happened. Use it to repeat a workflow, check its expectations, and inspect the resulting configuration and wire evidence.
Access SIMBOT
The guide is public, but the SIMBOT workspace is available only on the FixPortal site to signed-in users with the PlatformAdmin role. Open SIMBOT from the application navigation, then use its three sections:
- Mission Control commissions a run, shows the active run, and lists recent verdicts.
- Scenarios describes the authored coverage, supported FIX versions, and default inputs.
- Runs searches completed runs and opens their reports.
Only one run can be active in the laboratory at a time. If Mission Control shows an active run, monitor or stop it before commissioning another.
Commission a run
- Open Mission Control.
- Select a Scenario. Check the Scenarios page first if you need its expected coverage or supported protocol profiles.
- Select a supported FIX version.
- Choose a run Mode and enter its bound when required.
- Optionally enter a Seed. Leave it blank for SIMBOT to generate one.
- Review the scenario inputs, then select Commission run.
The available inputs are authored by the scenario, and they differ between scenarios: each one accepts only the contract it was written against, so the values shown for one scenario are not interchangeable with another's. Mission Control offers the authored defaults, which are also listed on the Scenarios page. Values are milliseconds and must be whole numbers of zero or more.
Not every input is consumed by every scenario. A scenario that asserts nothing about elapsed time still carries the observed-latency fields, because the commissioning contract is shared; its own description on the Scenarios page says what it actually reads.
If a request fails and you retry it without changing the form, Mission Control reuses the same run identity. This prevents an uncertain response from creating a second run for the same intent.
Choose a run mode
| Mode | Use it when | Bound |
|---|---|---|
OneShot | You need one execution of the scenario. | None |
Count | You need a fixed number of cycles. | 1 to 10,000 cycles |
Duration | You need the scenario to repeat for a time window. | 1 second to 24 hours |
A duration run finishes at a safe scenario boundary after its time limit is reached. A manual stop follows the same rule, so it may not become terminal immediately.
Use deterministic seeds
The seed controls the scenario's repeatable choices. To reproduce a run, use the same scenario version, FIX version, mode, inputs, and seed. Every report records the effective seed, including one generated by SIMBOT.
A matching seed does not make external availability or elapsed network time identical. It makes the authored choices repeatable; observer health and timing expectations still determine the verdict.
Check the scenario before running
Open Scenarios to see each source-controlled scenario's:
- name and version;
- purpose and expected coverage;
- supported FIX versions; and
- default configuration mutation.
The scenario version is part of the report. When comparing two runs, check the version as well as the seed.
Read the expected coverage before judging a report. Some scenarios exist to prove the simulator refuses an order, or holds one working without ever filling it, so a report full of rejections or an order that never trades can be the scenario passing exactly as authored. The verdict, not the traffic, is what says whether the workflow behaved.
Monitor or stop a run
Mission Control replaces the commissioning form with the active run. It shows the run ID, lifecycle, current step, and completed-step count. Updates arrive live while the page is open.
To stop the run, select Stop run, then Confirm stop. SIMBOT records the request, completes the current safe boundary, restores the configuration, removes temporary resources, and then assigns a terminal verdict. Keep the page open or return to Runs later; stopping does not require the browser to remain connected.
Find previous runs
Mission Control shows the five most recent verdicts. Select one to open its report.
For a longer list, open Runs. Filter by scenario, verdict, or FIX version. Each row includes the run ID, scenario version, mode, seed, admitted time, and current verdict. Select the run ID to inspect the evidence.
Read a report
A terminal run produces an immutable report. Its header identifies the run and records the scenario version, FIX version, cycle count, elapsed time, seed, schema version, and verdict. Use Download JSON when you need to retain or share the evidence outside SIMBOT.
The report has five sections:
- Summary shows the run timing and mode, observer health, and cleanup verification.
- Steps shows each expectation and outcome. Select a step for its diagnostic, domain identifiers, configuration mutation, and correlated redacted FIX frames.
- Wire lists the redacted inbound and outbound frames across all steps.
- Config compares requested configuration with its readback and restoration evidence.
- Cycles shows each cycle's identity, elapsed time, step count, and outcome.
A cycle begins by capturing the configuration SIMBOT will restore afterwards, so the capture step precedes the scenario's own traffic. A scenario that changes settings more than once in a cycle records a separate configuration step for each change, and Config shows every one; the restoration at the end of the cycle returns the session to the state captured at its start, whatever happened in between.
Check Summary before treating a failed expectation as a product defect. Healthy observer and cleanup indicators establish that SIMBOT could both observe the workflow and restore the laboratory afterwards.
Interpret verdicts
| Verdict | Meaning |
|---|---|
Passed | The expectations passed and SIMBOT completed its cleanup. |
Failed | At least one scenario expectation failed; inspect the failed step and its evidence. |
Inconclusive | An observer, infrastructure, recovery, restoration, or cleanup failure means the expectations cannot support a reliable conclusion. |
Stopped | An operator requested a stop and SIMBOT reached a safe boundary without a higher-priority failure. |
Step and cycle outcomes help locate the first useful diagnostic. The final run verdict also accounts for observer health and cleanup, so it is the result to report.
Troubleshooting
No scenarios are available
Refresh once to rule out a stale request. If the catalogue remains empty or reports an error, the SIMBOT service is not returning its authored catalogue; do not commission a substitute workflow manually.
A run cannot be commissioned
Check that no run is already active, the chosen FIX version is supported by the scenario, the mode bound is within its displayed limit, and the optional seed is a whole safe integer. If the error includes a code, retain both the code and the run ID when reporting it.
A run appears not to move
Check the lifecycle and current step. Provisioning, connection, restoration, and cleanup can take time. Refresh the page if live updates have stopped; the run continues on the service.
No report is available
A report is available only after the run becomes terminal. If the run is still restoring or cleaning up, wait for its final verdict. If it is terminal but the report is unavailable, retain the run ID and report the problem.
Evidence disappeared after a service restart
SIMBOT run history and reports are stored in the Initiator's local database for the lifetime of its deployed container. A container replacement can remove that local history and can prevent recovery of a run that was active at the time. Rerun the scenario after service health is restored, and download the JSON report for evidence that must be retained.
Do not use a missing historical report as evidence that a workflow passed. Retain the downloaded JSON from the terminal run you are relying on.
Updated 2026-09-08 · Edit on GitHub