Robots dentro de un flujo

Un paso de robot ejecuta un proceso publicado normal: el mismo que puedes lanzar desde Ejecuciones o con un disparador. El flujo le pasa los datos del caso, guarda lo que devuelve y decide qué sigue. El robot no necesita saber nada del resto del proceso.

Qué entra y qué sale

Entradas. Las entradas del proceso (sus argumentos de entrada) reciben los valores que configuraste en el paso, fijos o con {{variable}}.
Salidas. Las salidas del proceso se guardan en las variables del caso que elegiste en el paso. Si el robot no devuelve una salida mapeada, la variable queda como estaba y se registra un aviso en los eventos del caso.
Si el robot falla, no se guarda ninguna salida parcial.

Si el proceso publica su contrato (sus entradas y salidas declaradas), el lienzo te muestra la lista para asignarlas; ver Publicar y versionar.

Tipos de las entradas

Cada entrada del proceso declara un tipo (texto, número, entero, sí/no…). Si el valor del caso es de otro tipo, Zoan Cloud lo convierte antes de lanzar el robot, siempre que no se pierda información:

El caso tiene	La entrada espera	Qué recibe el robot
Un número, por ejemplo de un campo de moneda (`3500000`)	Texto	`"3500000"`: sin notación científica y con punto decimal (`"1234.5"`).
Sí/no	Texto	`"true"` o `"false"`.
Un texto con un número (`"12.5"`)	Número	`12.5`.
Un texto con un número sin decimales (`"3"`)	Entero	`3`.
`"true"` o `"false"`	Sí/no	`true` o `false`.

No se convierte nada que cambie el dato o lo deje incompleto: una lista o un objeto nunca se convierten en texto, un número con decimales no pasa a entero, un texto como "3.500.000" o "1,5" no pasa a número y un número con más de 15 cifras significativas tampoco, porque se redondearía. En esos casos el robot no corre y el paso queda como incidente con el motivo.

Las entradas de otros tipos (fechas, tablas, listas, objetos) llegan tal cual; el proceso las interpreta.

Mensajes cuando el robot no puede correr

El incidente dice qué pasó y cómo corregirlo. Hay dos clases de problema:

Un dato del caso no sirve para la entrada. Ejemplos:
- «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.»
- «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.»
Cuando la entrada se asigna con una sola variable ({{variable}}), el mensaje la nombra. Si la variable es sensible, el mensaje dice solo el tipo de lo recibido, nunca el valor.
El proceso cambió desde que publicaste el flujo. El mensaje empieza por «El proceso cambió y no es compatible con el flujo publicado» y dice qué cambió: una entrada requerida nueva que el flujo no asigna, una entrada que el proceso ya no recibe, una salida que ya no devuelve o un contrato que desapareció. Se corrige ajustando el paso y publicando una versión nueva del flujo.

Aviso al publicar

Al publicar, el lienzo compara el tipo de cada variable con el de la entrada que alimenta y avisa cuando la conversión no es segura:

Nunca funciona: por ejemplo, una variable de tipo lista en una entrada de texto.
Solo funciona con algunos valores: una variable de texto en una entrada numérica (solo si el texto es un número), un número en una entrada entera (solo si no tiene decimales), o un texto armado con varias variables en una entrada numérica o sí/no.
Un valor fijo que no encaja: por ejemplo, doce en una entrada entera.

Si la conversión es segura (un número en una entrada de texto, un entero en una numérica), no hay aviso. Puedes publicar confirmando el aviso, pero lo recomendable es corregir el tipo de la variable o de la entrada.

Errores de negocio y errores técnicos

El flujo distingue dos tipos de error, porque se atienden distinto:

Error de negocio: el robot detecta un caso que no debe procesar (el proveedor no existe, el pedido ya se registró, falta un documento). Repetirlo daría el mismo resultado. Si el paso tiene activo Atender los errores de negocio en otro camino, el caso sigue por esa ruta (por ejemplo, a una persona que lo revisa); si no, queda como incidente.
Error técnico: algo falló en el camino (la aplicación no abrió, se cayó la red). Puede tener sentido reintentarlo.

Para señalar un error de negocio, usa Throw y en su tipo de error elige Excepción de negocio en la lista (guarda BusinessRuleException). La tarjeta del lienzo del Designer lo marca para que se vea a simple vista:

If   condition = proveedor == null
 └─ then:
      Throw   message   = "El proveedor " + nit + " no está registrado"
              errorType = "BusinessRuleException"

El tipo se conserva aunque el Throw esté dentro de un playbook invocado. En todos los pasos de la ruta de error, el mensaje está disponible como {{_error.mensaje}} (ver Errores de negocio en otra ruta). En el monitor, el paso queda como Error de negocio y el caso muestra por qué ruta siguió.

Variables del sistema del robot

Cuando un paso de un flujo lanza el robot, el proceso recibe cuatro variables del sistema de solo lectura. Fuera de un flujo (o al ejecutar desde el Designer) están vacías.

Variable	Contiene
`$system_instance_id`	El identificador del caso que lanzó esta ejecución.
`$system_step_id`	El identificador del paso del flujo.
`$system_idempotency_key`	La clave de idempotencia del paso: la misma en todos sus reintentos automáticos.
`$system_business_key`	La clave de negocio del caso (por ejemplo, el número de factura).

Úsalas en cualquier expresión, por ejemplo para dejar rastro en un log:

Log   message = "Factura " + $system_business_key + " · caso " + $system_instance_id

No duplicar trabajo en un sistema externo

Un paso puede repetirse: por un reintento automático, porque una persona lo reintentó desde el monitor o porque el robot se desconectó a mitad. Si el robot crea algo en otro sistema (un registro en el ERP, un pago, un correo), repetirlo podría crearlo dos veces. La clave de idempotencia evita eso.

Cómo funciona. $system_idempotency_key identifica «este trabajo de este caso». Es la misma cada vez que el paso se reintenta automáticamente, y distinta para cada caso y cada paso. Si una persona reintenta el paso después de cambiar sus datos de entrada, la clave cambia, porque ya es otro trabajo.

Cómo usarla. Hay dos maneras, según lo que permita el sistema destino:

El sistema acepta una clave de idempotencia. Muchas APIs aceptan una cabecera Idempotency-Key: si reciben dos veces la misma, devuelven el resultado de la primera en vez de repetir la operación. Envíala en tu actividad HTTP POST:
```
HTTP POST
  url     = "https://erp.ejemplo.com/api/facturas"
  body    = { "numero": = numero_factura, "total": = total }
  headers = { "Idempotency-Key": = $system_idempotency_key }
```

El sistema no la acepta. Guarda la clave junto con lo que creas (en un campo de referencia u observaciones) y, antes de crear, busca si ya existe:

Buscar en el ERP una factura con referencia = $system_idempotency_key
If   ya existe
 └─ then:  devolver sus datos como salida (no crear otra)
 └─ else:  crear la factura con referencia = $system_idempotency_key

Con eso, repetir el paso es seguro: el robot encuentra lo que ya hizo y continúa. Cuando el robot es así de seguro, puedes activar en el paso Reintentar también ante error técnico del robot para que Zoan Cloud lo reintente solo.

Buenas prácticas

Robots cortos y con un solo propósito. Cada paso de robot hace una cosa (leer la factura, registrarla). Así, si uno falla, solo se repite esa parte, y el caso guarda lo demás.
Cada paso abre lo que necesita. El robot no guarda estado entre pasos: si necesita una aplicación, la abre e inicia sesión en su propio paso.
Errores de negocio claros. Un mensaje como "El proveedor 900123456 no está registrado" le dice a quien atiende el caso qué hacer.
Un límite de tiempo razonable. En Tiempos y errores, un Límite (minutos) hace que un robot que se quedó colgado aparezca como incidente en lugar de esperar indefinidamente.

Siguientes pasos

Diseñar en el lienzo: la configuración del paso de robot.
Monitor e incidentes: cómo se decide si un reintento puede duplicar.