Magic Software
Lesson 13Concepts · ~25 min read

Error Handling

An integration application has very little control over the systems it depends on. Errors are inevitable; what matters is how you detect, report, and recover from them. This lesson covers Magic xpi's three layers of error handling — the step, the flow, and the dedicated error flow.

Context Error Variables

Magic xpi exposes a set of predefined context variables that carry error information. The current error variables can only be read in the condition that immediately follows the failing step — they are cleared before the next step runs:

C.sys.ErrorCodeThe error code raised by the step.
C.sys.ErrorDescriptionThe error description.

To trace the origin of an error, use:

C.sys.LastErrorFlowNameThe flow where the last error occurred.
C.sys.ErrorStepNameThe step that raised it.

The "last error" set is updated only when a new error is raised:

C.sys.LastErrorCodeLast error code; survives until the next error.
C.sys.LastErrorDescriptionDescription of the last error.
C.sys.LastErrorInfoBLOB with full info — SQL statements, Java stack traces, etc.

Step-Level Error Handling

By default, when a step errors it exits — even if it had more methods to run. Two components are exceptions: Data Mapper and SAP B1 have an Error Behavior property you can set to either Exit or Continue.

The simplest way to handle an error is to put a step or branch behind a condition that tests C.sys.ErrorCode:

  1. On the Scan for New Requests flow, add an Email child of Extract Details from Request; name it Send Thank You Email; processing mode Parallel; method interface Quick Send.
  2. Use F.CustomerEmail as To, "We received your request." as Subject, and "Thank you for your request..." as Body. Use ASCIIChr (10) for line breaks.
  3. Add another Email step as a child — name it Send Error Email. Send to postmaster@magic.xpi.course.com with subject "Email to the customer was returned".
  4. Set the condition on Send Error Email to C.sys.ErrorCode = 102 — only fire on the Email "send mail error".

Flow-Level Error Handling

Step-level conditions get repetitive when the same handling is needed across many steps. Error Policies let you declare automatic handling for an entire range of error codes. Open the policies by double-clicking Error Policies under a flow.

AbortStop the flow.
IgnoreContinue as if nothing happened.
Restart FlowStart the flow over from the top.
RetryRe-execute the failing step.
JumpContinue from a specific step that may not normally be reachable.
Component types matter. Error codes are scoped to the component type that raised them. Two different components can use the same numeric code; C.sys.LastErrorComponentType tells you which one fired.

To wire up a Jump policy:

  1. Place a "handler" step somewhere in the flow with the condition 'FALSE'Log so it can't be reached normally.
  2. Open Error Policies and click Add.
  3. Use the zoom button on From to pick the component (e.g. Email) and the error code (e.g. 102 Send Mail Error). Repeat for To.
  4. Set Error Policy to Jump and pick the handler step.

When the matching error fires, control jumps directly to that step — bypassing the false condition.

Dedicated Error Flows

For sophisticated handling, define an error flow — an ordinary Magic xpi flow assigned to handle errors raised by another flow. You associate the error flow via the External section of the parent flow's properties; an icon then appears next to that flow's Trigger area.

An example skeleton:

  1. Create a flow named Errors.
  2. Drop an Email step named Send Email to Administrator; configure Quick Send to postmaster@magic.xpi.course.com with the appropriate subject and body.
  3. Set its condition to C.sys.LastErrorCode = 102 — only handle that specific error.

When the error flow ends, control returns to the failing flow at the step after the one that errored, and the error is cleared.

Multi-record steps. When the failing step is a Data Mapper or any component supporting multiple operations, each record can invoke the error flow. After it ends, the step's Error Behavior decides whether to advance to the next record or exit.

Returning Errors From an Error Flow

By default, an error flow ends without re-raising. If you want it to re-raise — the same error or a different one — finish the flow with a Flow Data utility:

  1. Add a Flow Data step at the end of the error flow.
  2. Update C.sys.ErrorCode with a value compatible with the original component (Email accepts 100, 101, 102, 103).
  3. Or, to re-raise the same code, set C.sys.ErrorCode from C.sys.LastErrorCode.

When control returns to the parent flow, that error will be raised and handled by the flow-level mechanism.

Exercise

Handle missing files gracefully.

In the previous lesson you used the File Management component to copy a static HTML response file. What happens if the file or folder doesn't exist?

  • If the file or folder is missing, return an error to the browser by sending the Error.tpl template from the templates folder.
  • This is a single specific case — consider declaring an Error Policy for it rather than a step-level condition.

Summary

Magic xpi resolves an error in this order:

  1. If a dedicated error flow is defined, it is invoked.
  2. If the error flow re-raises (or there's no error flow), the flow's Error Policy applies.
  3. Any step-level condition referencing C.sys.ErrorCode sees the surviving value.

You should now be able to:

  • Read the context error variables and condition steps on them.
  • Build flow-level Error Policies that abort, ignore, retry, restart, or jump.
  • Define and assign a dedicated error flow to handle complex scenarios.
  • Re-raise errors deliberately when business rules require it.