Table of Contents

Running a Replay

How a script resets, starts and polls a mission on the web service without stopping someone else's run. Signing in and reading a reply are on Driving the Web Service over HTTP, the one-project rule on One Service, One Project. Editing the setup the run is built from is Editing Objects by Key.

A scripted replay is reset, start, then poll by run id:

  1. GET /api/Execution/status. If executionStatus is Running or Paused, a run is live — do not reset, start or stop it; a reset stops a live run too.
  2. POST /api/Execution/reset. Start does not reset. After a finished run the session stays open, holding the machined workpiece, its steps and its messages, and POST /api/Execution/start plays the mission again on top of it. Every Read On First Or Write record then sees steps already produced and writes instead of reading, so the stage-0 record overwrites the cached stock with the machined part — and every later run, reset or not, starts from stock that has already been cut until that file is deleted. Setup edits made through child keys are not picked up by such a play either. Reset before every start. While an NC program plays on the session outside the player's run — a POST /api/SessionShell/PlayNcFile request, for one, which executionStatus does not show — the reset answers 409 { success: false, code: "Reset--Busy", message } and resets nothing: wait for that play to end, then reset. A write under the machine tool's or the fixture's solids answers 409 { success: false, code: "SolidEditRefusedWhileRunning" } during such a play as during a run, only with no banner on the Equipment page. A workpiece export, a Diff or a step-physics recompute that a request runs on an idle player owns the player while it runs, as a run does: tool-house, cutter, holder, solid and topology writes answer 409 with ToolEditRefusedWhileRunning or SolidEditRefusedWhileRunning meanwhile, and a setup edit waits for the next start.
  3. POST /api/Execution/start, and read the body. An enabled Script command that does not compile refuses the start with HTTP 200, success: false and code: "script_compile_error", naming the script and the error. A start while a run is live — running or paused — answers alreadyRunning: true and starts nothing; the runId beside it is the live run's, and the service cannot tell whether it is yours (a client whose own start answer was lost may compare it with the last runId it knew) — do not poll for it as your own. A start while an NC program plays on the session outside the player's run — a POST /api/SessionShell/PlayNcFile or PlayNc request, for one — answers 409 { success: false, code: "Start--BusyAnotherThread", message } and starts nothing: wait for that play to end, then start. While a project is being changed, or another request's ResetRuntime or EndSession runs, it answers the same with Start--BusyReset; run-line and run-step answer both the same way. While another request opens or closes a play result review (POST /api/LocalProjectService/OpenNcResultReview or CloseNcResultReview), it answers the same with Start--BusyReview, and run-line with RunLine--BusyReview: wait for that request's response, then start. While a workpiece call or a step-physics recompute that another request asked for runs on an idle player — an export or a Diff over api/SessionShell, for one — executionStatus reads Running, a start or a run-step answers 409 with Start--BusyOneShot and run-line with RunLine--BusyOneShot: wait for that request's response, then start. That response can come while the player is still held for another request's work — a call made during a recompute is done between two of the recompute's chunks and answers there, and a request answers before work another request queued behind its own — so a start may still answer Start--BusyOneShot after it: start again once executionStatus reads Ready or Finished. A real start answers alreadyRunning: false with the runId of your run and the instanceId of the service process it counts in: keep both. It also says whether the run began on a fresh session. continuesSession: true, with a note saying so, means nothing came between the last play — finished or stopped — and this start to end its session, neither a Reset nor a project load or reload: the run replays the mission on the session that play left, its steps, its messages and the machined workpiece kept. continuesSession: false, with no note, is a start on a fresh session. A true on a replay meant to be fresh says step 2 was skipped: reset, which stops the run, and start again.
  4. Poll GET /api/Execution/status until it reports that runId, under the same instanceId, with executionStatus either Finished or Ready. After a Reset, Ready is how a run that was stopped, or that ended in an exception, reports itself, so a poller that waits for Finished alone never returns from a failed run. Without a Reset in between, such a run inherits the previous run's Finished and passes for a completed one — one more reason to reset before every start. The exception behind a Ready is in the service log, which GET /api/Project/logs returns for the current day. A mission script's own error does not end the run: it is reported as ScriptCommand-Run--Fault in the shell list of GET /api/Execution/messages and the mission goes on, so read that list for a Finished run as well. A higher runId means another caller has started a run since, so this one is over. A different instanceId means the service restarted: a new process counts its runs from 1 again, so the run is gone whatever the runId and the status beside it say.
  5. Read what the run produced before anything resets the session: a Reset empties the step strip, the meshed workpiece and the session's message lists. Check each answer's status, and that it is JSON, before reading it (Reading a Reply): a misspelt evidence route answers 404. The checks that tell a finished run from a passing one are in Replay Acceptance over the HTTP API.

If the poller gives up, let it give up. A timeout is not a reason to call POST /api/Execution/stop: stop ends whatever run is current, which on a shared instance may not be this caller's, and a stopped run skips everything below the point it reached — no Post-Execution output, no end-of-stage record.

See Also