Version 3.1.0 of opscotch adds error-handling helpers to the JavaScript context. You can now flag user-facing errors, capture system errors, and check whether a context (including one returned from sendToStep) is in an error state.

The JavaScript context now supports two error channels:

• User errors: use addUserError(...) for issues the end user must resolve (bad input, missing file, invalid token).
• System errors: use addSystemError(...) for internal problems developers need to fix (bugs, unexpected exceptions). Any exception thrown out of a processor is automatically captured as a system error.

Helpers to inspect state:

• isErrored() tells you if anything went wrong.
• hasUserErrors(), getUserErrors() for user-facing issues.
• hasSystemErrors(), getSystemErrors() for internal issues.
• getAllErrors() to combine both.
• getFirstError(list) to quickly grab the first item from a list (returns null if empty).

Placeholder docs: addUserError, addSystemError, getUserErrors, getSystemErrors, getAllErrors, getFirstError, isErrored.

How to add errors in a processor

// bad user input
if (!context.getProperty("token")) {
  context.addUserError("Missing token; please supply a token property.");
}

try {
  doRiskyThing();
} catch (e) {
  context.addSystemError("Processing failed: " + e.message);
  // throw e; // optional: rethrow; thrown exceptions also become system errors
}

if (context.isErrored()) {
  // decide whether to short-circuit or continue
}

Checking errors on a response from sendToStep

When you call another step, the returned context carries its errors. Inspect it before proceeding:

let response = context.sendToStep("downstream-step-id");

if (response.isErrored()) {
  if (response.hasUserErrors()) {
    let userIssue = response.getFirstError(response.getUserErrors());
    context.addUserError("Downstream issue: " + userIssue);
  }
  if (response.hasSystemErrors()) {
    let sysIssue = response.getFirstError(response.getSystemErrors());
    context.addSystemError("Downstream failure: " + sysIssue);
  }
  // decide whether to stop, retry, or bubble up
}

For more on forwarding work between steps, see How can I forward processing to another step? Do I have to wait for a response?.

Which one to use?

• Use addUserError when the fix belongs to the caller or operator. Expect these to surface to humans.
• Use addSystemError when the fix belongs to developers (code/config). These should be investigated and fixed at the source.

With these helpers, you can separate user-facing feedback from internal failures, keep workflows predictable, and make downstream handling clearer.