Start cases

Every case of a flow starts on the published version with its input variables (the ones marked «Se pide al iniciar», asked at start, on the canvas). There are five ways to start one, depending on where the work comes from:

Way	Best for
By hand	Testing, or cases someone registers one at a time.
Through the API	Your own application that already works with a Zoan Cloud session.
Scheduled trigger	A case at a fixed time: the daily close, Monday’s report.
Webhook	Another system signals a new case (a form, a bot, the ERP).
Queue	Many cases of the same kind: one case per item that lands in the queue.

In the monitor, each case shows how it began: A mano (by hand), Por API, Programado (scheduled), Webhook or Cola (queue).

No duplicate cases

If the caller sends an idempotency key (a unique value per request, such as order-2024-0001), repeating the same call returns the same case instead of creating another. That way, a system that retries because it never got an answer does not duplicate the work. If the same key arrives with different data, it is rejected. Each key is remembered for 30 days.

By hand

1. Open the flow on the canvas and click Iniciar (Start). It shows up once the flow has a published version and you are allowed to start cases.
2. In Iniciar un caso (Start a case), fill in the input data the published version asks for. Required fields are marked with *.
3. Optionally enter a Clave de negocio (opcional) (business key) to find the case later; if you leave it empty, the one defined by the flow is used.
4. Click Iniciar. You get the case ID, its title, key and status. Iniciar otro (start another) begins the next one.

Through the API

An application that already uses a Zoan Cloud session can start cases with a single call. The session must belong to someone allowed to start flows. For an external system to start cases without a user, use a webhook.

curl -s -X POST "https://<your-api>/environments/<environment>/orchestrations/<flow>/instances" \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2024-0001" \
  -d '{"variables": {"order_number": "ORD-0001", "total": 250000}, "businessKey": "ORD-0001"}'

• variables: only the input variables of the published version. A variable that is not an input, a wrong type or a missing required one returns 422 with details per variable.
• businessKey (optional): the case’s business key. If you leave it out, the flow’s template is used.
• Idempotency key (optional): in the Idempotency-Key header or the idempotencyKey field, up to 500 characters.

Response	When
201	Case created. The body includes id, status, business_key and title.
200	The idempotency key was already used with the same data: you get that case back.
409	The flow has no published version or is archived.
422	Invalid variables, or the idempotency key was already used with different data.
429	The plan’s monthly case quota has been reached.

To check on a case: GET https://<your-api>/environments/<environment>/orchestrations/<flow>/instances/<id>.

With a scheduled trigger

1. In the environment, open Disparadores (Triggers) and click Nuevo disparador (New trigger).
2. Under ¿Qué inicia? (What does it start?), choose Flujo (Flow), and Programado (scheduled) as the type.
3. Pick the Flujo (only those with a published version are listed), the cron expression and the Zona horaria (time zone).
4. If the version asks for input variables, enter their values as JSON: every case will start with them.
5. Adjust the limits (see Trigger limits) and save.

Each scheduled time starts exactly one case: even if the tick is processed twice, it is not duplicated.

By webhook

A webhook lets another system start a case with an HTTP call, with no user or token: the URL carries a key that is the authentication.

1. In Centro › Robots › Disparadores › Nuevo disparador (Center › Robots › Triggers › New trigger), choose Flujo and the Webhook type.
2. Pick the flow, the maximum wait of a synchronous call (0 to 60 seconds) and, optionally, default values for the input variables.
3. Save. The trigger row shows the URL with a copy button; the Cómo llamarlo (how to call it) button shows a ready-to-paste example.

curl -s -X POST "https://<your-api>/public/triggers/wk_...?wait=25" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-0001" \
  -d '{"request_number": "REQ-0001", "customer": "Sample customer"}'

• Body: each key arrives as an input variable. Values saved on the trigger are defaults; whatever comes in the body wins. A key that is not an input variable is rejected.
• Idempotency-Key: send a unique value per request; if the call is repeated, you get the same case back instead of a new one.
• ?wait=N (or the X-Zoan-Wait header): seconds the call waits for the case to finish or stop on an incident, up to the trigger’s cap.

The response includes instance_id, status and business_key:

Response	When
200	The case finished within the wait (completed or cancelled) or stopped on an incident (incident).
202	The case is still going (running or waiting), or no wait was requested.
404	The key does not exist or was regenerated.
409	The trigger is off or paused, the flow has no published version, or the plan does not include flows.
422	Invalid variables, or the idempotency key was already used with different data.
429	Too many calls, the trigger reached its maximum in progress, or the plan’s monthly quota ran out.

Checking the status. With the response’s instance_id: GET https://<your-api>/public/triggers/wk_.../instances/<instance_id>. It only answers for cases started by that same trigger.

Treat the URL like a password

Anyone with the URL can start cases. If it leaks, click Regenerar clave (Regenerate key): the old URL stops working right away.

What it returns at the end

When the case finishes, the response adds outputs containing only the variables the flow declares as webhook outputs, never the rest of its data. For now, that list (webhookOutput) is set in the flow’s JSON definition: download it from the canvas, add the list and import it back.

From a queue

With a queue, each item that arrives starts a case with its data. It is the natural way to process batches: invoices, orders or requests that another process or system keeps dropping into a work queue.

1. In Centro › Robots › Disparadores › Nuevo disparador (Center › Robots › Triggers › New trigger), choose Flujo and the Cola (queue) type.
2. Pick the flow and the Cola vigilada (watched queue).
3. Set Máximo en curso (maximum in progress) so you do not overload the systems and people the process depends on, and save.

How it behaves:

• Case data. Fields in the item content named after an input variable arrive as that variable; the rest are ignored. Anything missing falls back to the trigger’s default value. The item’s reference becomes the case’s business key.
• The queue is dedicated to the flow. Robots no longer take items from it, and it does not accept a second trigger.
• The item closes with the case result. If the case reaches a Completado end, the item succeeds; if it reaches a Rechazado por una regla de negocio end or is cancelled, the item fails. While the case has an incident, the item stays in progress and shows Con incidente (with incident) until someone resolves it.
• Each retry is a new case. If you retry an item from the queue, another case starts with its data.
• Invalid data. If the item content does not fit the input variables, the item fails with the reason and nothing starts.
• Out of quota. If the plan’s monthly quota runs out, items wait in the queue and start once there is room again.

In the queue view, each item shows the status of its case (Flujo en curso, Con incidente, Flujo terminado…; flow running, with incident, flow finished) with a link to its detail.

Trigger limits

Triggers that start flows have two limits, set when you create them or later with Valores por defecto y topes (defaults and limits):

• Máximo en curso (maximum in progress, optional): no new cases start while this many are running or waiting. Empty means no limit. With a queue, items keep waiting; with a webhook, the call gets 429.
• Pausar con incidentes (pause on incidents, 20 by default): once this many cases are in incident, the trigger pauses so they do not pile up. Resolve the incidents in the monitor and turn it back on.

When a trigger cannot start a case for a reason of its own (the flow was archived, lost its published version, the environment is inactive, the quota ran out), the trigger row shows a warning with the date.

Next steps

• Monitor and incidents: follow each case and fix whatever stopped.
• Webhook and scheduled triggers for RPA processes.