Robots in a flow

A robot step runs an ordinary published process: the same one you can launch from Ejecuciones (Executions) or with a trigger. The flow hands it the case data, keeps what it returns and decides what comes next. The robot does not need to know anything about the rest of the process.

What goes in and what comes out

Inputs. The process inputs (its input arguments) receive the values you set on the step, fixed or with {{variable}}.
Outputs. The process outputs are stored in the case variables you chose on the step. If the robot does not return a mapped output, the variable stays as it was and a notice is added to the case events.
If the robot fails, no partial output is stored.

If the process publishes its contract (its declared inputs and outputs), the canvas lists them for you to map; see Publish and version.

Input types

Each process input declares a type (text, number, integer, yes/no…). When the case value has a different type, Zoan Cloud converts it before starting the robot, as long as no information is lost:

The case has	The input expects	What the robot receives
A number, for example from a currency field (`3500000`)	Text	`"3500000"`: no scientific notation, with a decimal point (`"1234.5"`).
Yes/no	Text	`"true"` or `"false"`.
Text holding a number (`"12.5"`)	Number	`12.5`.
Text holding a whole number (`"3"`)	Integer	`3`.
`"true"` or `"false"`	Yes/no	`true` or `false`.

Nothing is converted if that would change the data or leave it incomplete: a list or an object never becomes text, a number with decimals does not become an integer, text such as "3.500.000" or "1,5" does not become a number, and neither does a number with more than 15 significant digits, because it would be rounded. In those cases the robot does not run and the step becomes an incident with the reason.

Inputs of other types (dates, tables, lists, objects) are passed as they are; the process interprets them.

Messages when the robot cannot run

The incident says what happened and how to fix it. There are two kinds of problem:

A case value does not fit the input. Examples:
- “La entrada «valorEstimado» del proceso espera un número entero y recibió el número 3.5 (variable valor_estimado). Corrige el mapeo o el tipo de la entrada y reintenta.” (the input expects an integer and received 3.5 from the variable valor_estimado).
- “Falta la entrada requerida «soporte» del proceso: la variable soporte no tiene valor en el caso. Corrige el mapeo o el dato del caso y reintenta.” (a required input is empty because its variable has no value).
When the input is mapped from a single variable ({{variable}}), the message names it. If the variable is sensitive, the message only states the type received, never the value.
The process changed since you published the flow. The message starts with “El proceso cambió y no es compatible con el flujo publicado” and says what changed: a new required input the flow does not map, an input the process no longer accepts, an output it no longer returns, or a contract that disappeared. Fix it by adjusting the step and publishing a new version of the flow.

Warning on publish

On publish, the canvas compares each variable’s type with the type of the input it feeds and warns when the conversion is not safe:

It never works: for example, a list variable feeding a text input.
It only works with some values: a text variable feeding a numeric input (only if the text is a number), a number feeding an integer input (only if it has no decimals), or text built from several variables feeding a numeric or yes/no input.
A fixed value that does not fit: for example, twelve in an integer input.

Safe conversions (a number into a text input, an integer into a numeric one) raise no warning. You can publish by confirming the warning, but the better fix is to correct the type of the variable or the input.

Business errors and technical errors

The flow tells two kinds of error apart, because they are handled differently:

Business error: the robot finds a case it should not process (the supplier does not exist, the order was already entered, a document is missing). Repeating it would give the same result. If the step has Atender los errores de negocio en otro camino turned on, the case takes that route (for example, to a person who reviews it); otherwise it becomes an incident.
Technical error: something broke along the way (the application did not open, the network dropped). Retrying may make sense.

To flag a business error, use Throw and pick Excepción de negocio (business exception) from its error type list (it stores BusinessRuleException). The card on the Designer canvas marks it so it stands out at a glance:

If   condition = supplier == null
 └─ then:
      Throw   message   = "Supplier " + tax_id + " is not registered"
              errorType = "BusinessRuleException"

The type is kept even when the Throw sits inside an invoked playbook. In every step of the error route, the message is available as {{_error.mensaje}} (see Business errors on another route). In the monitor, the step shows as Error de negocio (business error) and the case shows which route it took.

The robot’s system variables

When a flow step launches the robot, the process gets four read-only system variables. Outside a flow (or when running from the Designer) they are empty.

Variable	Holds
`$system_instance_id`	The ID of the case that launched this run.
`$system_step_id`	The ID of the flow step.
`$system_idempotency_key`	The step’s idempotency key: the same across all its automatic retries.
`$system_business_key`	The case’s business key (for example, the invoice number).

Use them in any expression, for example to leave a trail in a log:

Log   message = "Invoice " + $system_business_key + " · case " + $system_instance_id

Never do the work twice in an external system

A step can run more than once: through an automatic retry, because someone retried it from the monitor, or because the robot disconnected halfway. If the robot creates something in another system (an ERP entry, a payment, an email), repeating it could create it twice. The idempotency key prevents that.

How it works. $system_idempotency_key identifies “this piece of work for this case”. It stays the same every time the step is retried automatically, and differs for every case and every step. If someone retries the step after changing its input data, the key changes, because it is now different work.

How to use it. There are two ways, depending on what the target system supports:

The system accepts an idempotency key. Many APIs accept an Idempotency-Key header: when they receive the same one twice, they return the first result instead of repeating the operation. Send it from your HTTP POST activity:
```
HTTP POST
  url     = "https://erp.example.com/api/invoices"
  body    = { "number": = invoice_number, "total": = total }
  headers = { "Idempotency-Key": = $system_idempotency_key }
```

The system does not accept one. Store the key alongside whatever you create (in a reference or notes field) and, before creating, look for it:

Search the ERP for an invoice with reference = $system_idempotency_key
If   it already exists
 └─ then:  return its data as output (do not create another)
 └─ else:  create the invoice with reference = $system_idempotency_key

With that, repeating the step is safe: the robot finds what it already did and carries on. Once the robot is that safe, you can turn on Reintentar también ante error técnico del robot (also retry on a technical robot error) on the step so Zoan Cloud retries it on its own.

Good practices

Short, single-purpose robots. Each robot step does one thing (read the invoice, enter it). If one fails, only that part is repeated, and the case keeps the rest.
Each step opens what it needs. The robot keeps no state between steps: if it needs an application, it opens it and signs in within its own step.
Clear business errors. A message like "Supplier 900123456 is not registered" tells whoever handles the case what to do.
A sensible time limit. Under Tiempos y errores, a Límite (minutos) makes a stuck robot show up as an incident instead of waiting forever.

Next steps

Design on the canvas: the robot step settings.
Monitor and incidents: how Zoan Cloud decides whether a retry could duplicate.