Skip to main content

Case Guide

In the Marketplace edition, one run of a workflow with registered agents placed is called a case. Each case holds its settings and artifacts as versions, and a review step decides by looking at those versions. This mechanism does not exist in the SaaS edition.

Starting a case​

In a workflow with registered agents placed, the button at the top of the project screen is “Start case” rather than “Run now”. Press it and a screen for starting the case opens.

  1. For each placement, enter the parameters, connectors and instruction files. Parameters left blank run with the values marked “Defaults”. Only people the administrator has allowed “File attachment” under feature permissions can add files such as instruction files
  2. If needed, open “Advanced” and check “Environment passed to the Agent” and the settings files generated from the parameters. The environment variables are derived from the parameters and do not include Secret values or container settings
  3. Press “Start”. The agent on the first step starts

While required inputs that cannot be entered on the screen remain, it cannot start (“Required inputs cannot be entered on this screen”). This appears when a required input file is not bound under “Input bindings” in the step settings. Bind the output of a preceding step.

It also cannot start while an administrator has stopped the project or suspended the account of the user it runs as (“Stopping and resuming” in the Trigger Guide).

Project participants (owners, operators and members) and people with the organization operations role can start a case (people with the organization operations role can start cases without taking part in the project). Up to 3 cases can be in progress at once, counting those running and those awaiting review.

Cases can also be started from the external API and from time triggers. When starting a run through the external API, you can pass the same parameters, connectors and input files as “Start case” at the start (config). Time triggers and webhook trigger calls cannot pass parameters; the case runs on the contract's defaults and the step settings alone (Trigger Guide).

The case screen​

The case screen opens from “Case details” on a row in Workflow history, from “Case details” in a run record, or from “Open the case” on a review request. It has three tabs.

TabWhat you see
ProgressEach step's agent, the number of attempts and the launch status. When awaiting review, the state of that review
Settings & filesThe versions of the case settings, and the artifacts and files
RecordsThe audit record of this case. The run record for each step opens from Execution history

Launch status​

ShownMeaning
Waiting to launchWaiting its turn to be launched
LaunchingThe launch has been requested from the runtime
LaunchedThe runtime has accepted the launch (this does not necessarily mean the agent has started working)
Launch failedIt could not be launched. The reason is given. The case ends there as failed
CancelledBecause the case was cancelled, it was not launched, or the launched step was told to stop

Settings versions​

The case settings (each placement's parameters, connectors and instruction files) are kept as versions. Each is numbered, as in “Settings revision 3”, and shows who changed it and when.

  • The settings can be changed only while awaiting review. While running, “Settings cannot be changed while running. You can change them at the next review” appears. The settings of a finished case cannot be changed
  • Change them with “Edit settings” and press “Save as a new revision” to make a new version. Saving also replaces the content of the open review with the new version
  • “Revision history” shows earlier versions. Only the latest version can be edited. Past versions are read-only, and the review made at the time was made against that version
  • “Differences from the Agent defaults” shows only the items changed from the contract's defaults

If someone else saved the settings first, “Someone else updated the settings” appears and the latest content is loaded.

Artifacts and files​

“Artifacts & files” lists the agent's outputs and the versions people have edited.

  • Open an agent's output and press “Edit as a new version” to correct the contents and “Save version”. Only text up to 1 MiB can be edited. For YAML and JSON, the syntax and the shape set by the agent's contract are checked first when you save, and a version that does not match is not saved. People the administrator has not allowed “File attachment” under feature permissions do not see “Edit as a new version”
  • A saved version is marked “Edited by a person”, along with the version it was edited from
  • What passes to the next step is the “Version passed to the next step”. If the version you edited from was the one to be passed, it switches to the new version you saved. Otherwise, “The next step still uses the previous version” appears, so choose the version you want to pass in the case settings
  • Artifacts, too, can be edited only while awaiting review

Artifacts can be up to 20 MiB per file, and up to 100 MiB and 100 files in total per execution.

Only owners can edit the settings and artifacts. Even someone named as a reviewer cannot edit them unless they are an owner. Members can see the case.

Fixing things while awaiting review, then proceeding​

A case stopped at a review step can be fixed and then moved on as follows.

  1. Open the review request and check the “Review content version”, the “Next Agent” and the artifacts
  2. If there is something to fix, an owner makes a new version of the settings or artifacts on the case screen. For settings, the review content is replaced with the new version too. An artifact switches when the version passed to the next step was the one that was edited
  3. The reviewer decides whether to proceed to the next step, send it back or reject it

How a review is decided is in the Review Guide.

Deadline and review approvers​

In the header of the case screen, owners, operators and people with the organization operations role can do the following for a running case.

  • Deadline: Choose a date and time with "Set a deadline". The deadline is shown on the case screen, and "Past deadline" appears once it passes. You can change it with "Change the deadline" or remove it with "Remove the deadline"
  • Reassign approvers: While awaiting review, replace the approvers of the pending review requests in this case with the members you select. Newly assigned people are notified. Only members can be assigned

Cancelling a case​

Stop it with “Cancel case” on the case screen. Owners, operators and people with the organization operations role, and the person who started that case, can use it.

  • Steps not yet launched are not launched
  • Open review requests are cancelled
  • Running agents are told to stop. Once the stop of the running step is recorded, it becomes “Cancelled”. Until then, “Cancellation requested” is shown

Easy to get wrong​

  • Thinking you can correct settings or artifacts while a case is running. You can only while it awaits review. While running, it says “Settings cannot be changed while running. You can change them at the next review”
  • Thinking a reviewer can correct settings or artifacts. Only the owner can. A reviewer sends it back or asks the owner
  • Thinking a previous step's artifacts are passed to the next step automatically. What is passed is the “version passed to the next step”, and only for files you have connected (Agent Guide)
  • Thinking “Dispatched” means the agent has started. It means the execution platform accepted the launch; the agent has not necessarily started
  • Thinking you can resume a closed case. To redo it, start a new case (Review Guide)
  • Review Guide — How reviewers are chosen, and external wait
  • Trigger Guide — Starting with the external API or a time trigger
  • Record Guide — Action needed, and reading execution records