Throw

Throw

Type: throw  ·  Package: Core Activities v1.0.8

Throws an error on purpose with the message you set. It is used to stop the automation when you detect a situation that should not go on — invalid data, a business condition that is not met, an unexpected result. Instead of continuing and failing later in a confusing way, you fail right there with a clear message.

How it works

When it runs, it stops the flow with the given error. From there:

• If it is inside the try of a Try / Catch, it jumps to that catch (the error is caught). In the error variable, .Message is your message and .Type is the errorType you set (or PlaybookException).
• If no Try/Catch contains it, the execution ends in the failed state and the message appears in the logs.
• If it is thrown inside an invoked playbook, the error goes up to the caller keeping its type: a business exception is still a business exception in the parent playbook.
• If it rethrows a caught error —the same message (error.Message) with the same type (error.Type) or no type, inside the catch or later from variables, as the included templates do—, the error is still located where the original happened: the Designer, the execution summary and the flow case monitor show that file, step and activity (for example main.play › Pasos.play · step 2), not this Throw. A new error (another message or another type) is located at this Throw.

Business error and technical error

errorType	Treated as…	Effect
BusinessRuleException	Business error: the data does not allow going on.	Retry and Process Queue do not retry it; Zoan Cloud reports it as a business error.
Empty (PlaybookException) or any other text	Technical error.	It is retried normally and reported as a technical error.

The comparison with BusinessRuleException is case-sensitive: type it exactly like that (or pick it from the Designer’s list).

Required parameters

Parameter	Type	Default	Description
message	string	—	The error message. Fixed text in quotes or an expression. E.g. "Invalid total: " + total. If it evaluates to empty (null), the message is “Error thrown from playbook.”.

Optional parameters

Parameter	Type	Default	Description
errorType	string	"PlaybookException"	The error type, so a catch can tell it apart with errorVar.Type. In the Designer you pick it from a list: Technical error (empty), Business exception (stores BusinessRuleException) or Other type (write it), for example "SelectorException". Use the business exception for a business error: it is not retried, it reaches Zoan Cloud as a business error and, in a flow, the case can take the step’s error route instead of becoming an incident. Leading and trailing spaces are removed.

Output

This activity does not return a value: it always ends in an error.

Example

Validate a value and abort with a useful message if it is invalid; the catch tells the business error apart from the rest:

Try / Catch   errorVariable = error
 ├─ try:
 │    If   condition = num(row["Total"]) <= 0
 │     └─ then:
 │          Throw   message = "Invoice " + str(row["Number"]) + " has an invalid total"
 │                  errorType = "BusinessRuleException"
 │    ... record the invoice ...
 └─ catch:
      If   condition = error.Type == "BusinessRuleException"
       ├─ then:
       │    Log   level = warning   message = "Invoice rejected: " + error.Message
       └─ else:
            Throw   message = error.Message   errorType = error.Type   // technical: let it fail

Messages that help diagnose

Include context in the message (which record, which value): "Customer 304 has no tax ID" is much more useful than "Missing data". That message is what you will see in the logs and, if there is a Try / Catch, what ends up in its errorVariable.

Common errors

Throw does not fail by itself: its job is to produce the error. If the message you expected does not show, check the message expression: fixed text goes in quotes, variables without them.

Related activities

• Try / Catch — catch a thrown error (your own or another activity’s).
• Retry — does not retry business errors.
• Log — log a warning without stopping the execution.
• If — decide when to throw the error.