Create Human Task

Create Human Task

Tipo: human-task-create  ·  Paquete: Human Task Activities v1.3.3  ·  Salida: object

Crea una tarea para que una persona decida algo en la bandeja Tareas de Zoan Cloud: aprobar o rechazar, elegir entre varias opciones, completar un dato. La actividad no espera la decisión: crea la tarea y devuelve su id de inmediato. Para esperar el resultado, combínala con Wait for Human Task, o indica onCompleteProcess para que otro proceso continúe cuando alguien decida.

Cómo funciona

1. Crea la tarea en el ambiente donde corre la ejecución, con el título, la descripción, los datos (data) y las opciones de decisión (options). Con menos de dos opciones, la persona elige entre Aprobar y Rechazar. Lo que la persona llena lo defines con campos sueltos (fields) o con un formulario de la biblioteca (form), nunca con los dos.
2. La dirige a una persona (assignUserEmail), a un grupo (assignGroup) o a un rol (assignRole); uno es obligatorio. Solo esa persona, los miembros de ese grupo o de ese rol (y quien tenga permiso para ver todas las tareas) ven la tarea y pueden decidirla, y ellos reciben el correo con el enlace. Si indicas varios, manda la persona, luego el grupo y luego el rol.
3. Si pasas attachments, sube los archivos locales a Storage y los adjunta a la tarea: quien decide los abre desde el detalle.
4. Devuelve la tarea con status = "pending".

Cuando alguien decide, la tarea pasa a completed y guarda la decisión, el comentario y los campos que llenó la persona. Si defines un plazo (dueInHours) y nadie decide a tiempo, pasa a expired.

Idempotencia: con reference, si ya hay una tarea abierta (pending o claimed) con esa referencia en el ambiente, la actividad devuelve esa tarea en vez de crear otra. Los adjuntos locales se suben a una carpeta que sale de la referencia (tasks/<reference>/), así que al repetir la llamada reemplazan a los anteriores en vez de duplicarse.

Formularios: antes de crear nada (ni la tarea, ni el correo, ni el ítem de cola, ni la subida de adjuntos), la actividad comprueba con Zoan Cloud que el formulario exista, esté publicado y no esté archivado, y que formInputs traiga todas las entradas obligatorias. Así un nombre mal escrito falla al instante y sin dejar nada a medias. Una entrada que el formulario no declara solo genera una advertencia en el log.

Qué pasa cuando la tarea se cierra

Según los parámetros del grupo Resume:

• onCompleteProcess: cuando la tarea se decide, vence o la cancela una persona desde Zoan Cloud, Zoan Cloud ejecuta ese proceso en el mismo agente y la misma sesión de robot que creó la tarea. El proceso recibe estas entradas, más las de onCompleteInputs:

  Entrada	Contenido
  human_task_id	Id de la tarea.
  human_task_title	Título de la tarea.
  human_task_status	completed, cancelled o expired.
  decision	La opción elegida; si la tarea se canceló o venció, cancelled o expired.
  comment	Comentario de quien decidió.
  fields	Campos que llenó la persona (diccionario).
  data	Los datos (data) con los que se creó la tarea.

  El proceso no se ejecuta si la tarea la cancela un robot —con Cancel Human Task o con cancelOnTimeout de Wait for Human Task— ni si se elimina el item de cola ligado a la tarea: en esos casos el propio flujo ya sabe que no necesita la decisión.

• queueName: además de la tarea, crea un item en esa cola (con data como contenido específico) que queda esperando la decisión. Al decidirse, el item vuelve a la cola con item.Decision y un performer lo procesa con Process Queue. Si la tarea se cancela, la cancele una persona o un robot, el item también se libera para que no se quede esperando. Funciona igual con un formulario (form). Ver Decisiones humanas en lotes.

• webhookUrl: Zoan Cloud envía un evento JSON firmado a esa URL cuando la tarea se decide, se cancela o vence.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
title	string	—	Qué hay que decidir, en una línea (hasta 200 caracteres). Ej: Aprobar reembolso #0001.

Además, debes indicar assignUserEmail, assignGroup o assignRole (ver Asignación).

Parámetros opcionales

Tarea

Parámetro	Tipo	Por defecto	Descripción
description	string	—	Contexto para quien revisa: qué pasó, montos, por qué necesita una decisión (hasta 4000 caracteres). Editor de texto multilínea.
data	Dictionary	—	Datos clave → valor que la persona ve como una tabla (cliente, monto, referencia…).
options	string	"Aprobar, Rechazar"	Opciones de decisión separadas por coma (también se aceptan ; y |). Entre 2 y 6 opciones de hasta 60 caracteres; con una sola, se usan las de por defecto.
form	string	—	Nombre de un formulario publicado en el ambiente. El Designer te muestra la lista de los publicados (con la sesión iniciada) e incluye sin formulario. Con formulario, la persona ve sus secciones, tablas, adjuntos y reglas, y no se usa fields. Desde la versión 1.3.0.
formVersion	int	—	Versión publicada del formulario (entero positivo). Vacío = la versión vigente al crear la tarea. Fíjala si no quieres que un cambio del formulario afecte al robot. Solo con form. Desde la versión 1.3.0.
formInputs	Dictionary	—	Valores de las entradas que declara el formulario (entrada → valor), o una expresión que devuelva un diccionario. Una DataTable se envía como lista de filas. Solo con form. Desde la versión 1.3.0.
fields	Dictionary	—	Campos sueltos que la persona debe llenar (si no usas form), clave → Etiqueta:tipo[*]. Tipos: text, number, date, select:A|B. * = obligatorio. Hasta 20 campos. Ej: monto_aprobado → Monto aprobado:number*. Los valores vuelven en fields.
reference	string	—	Referencia única opcional (ej. el id del pedido, hasta 200 caracteres). Si ya hay una tarea abierta con la misma referencia en el ambiente, devuelve esa en vez de crear un duplicado (seguro ante reintentos).
catalog	string	—	Catálogo de negocio de la tarea (facturas, reembolsos…, hasta 60 caracteres) para filtrar y ver métricas en la bandeja. Desde la versión 1.1.0.
labels	string	—	Etiquetas separadas por coma. Desde la versión 1.1.0.
attachments	List	—	Archivos que la persona necesita para decidir (ej. el PDF de la factura), hasta 10. Cada elemento es una ruta local (se sube a Storage, en la carpeta tasks/<reference>/ del bucket attachmentsBucket) o un archivo que ya está en Storage como bucket/nombre. También acepta un solo texto. Solo quien puede ver la tarea los abre. Desde la versión 1.2.0.
attachmentsBucket	string	"human-tasks"	Bucket de Storage donde se suben los adjuntos locales. Desde la versión 1.2.0.

Asignación

Parámetro	Tipo	Por defecto	Descripción
assignRole	string	—	Código del rol al que va dirigida (ej. tenant-admin o un rol propio como contabilidad). El rol debe tener al menos una persona activa. Solo sus miembros la ven, reciben el correo y pueden decidir. Obligatorio si no indicas assignUserEmail.
assignUserEmail	string	—	Correo de una persona activa del tenant a la que va dirigida. Solo ella la ve y la decide. Tiene prioridad sobre assignGroup y assignRole.
assignGroup	string	—	Nombre de un grupo de la organización (también los sincronizados con Microsoft Entra ID). Sus miembros la ven, reciben el correo y la deciden; quien entre después al grupo también la ve. Tiene prioridad sobre assignRole.
escalateToRole	string	—	Si la tarea vence sin decisión, se reasigna una vez a este rol y el plazo se extiende por la misma duración.
escalateToUserEmail	string	—	Si la tarea vence sin decisión, se reasigna una vez a esta persona (correo). Tiene prioridad sobre escalateToGroup y escalateToRole.
escalateToGroup	string	—	Si la tarea vence sin decisión, se reasigna una vez a este grupo (nombre). Tiene prioridad sobre escalateToRole.

Opciones

Parámetro	Tipo	Por defecto	Descripción
dueInHours	int	—	Horas hasta que la tarea vence (laborales, si la organización definió un horario), entre 1 y 8760. Vacío o 0 = no vence. Al vencer, la tarea pasa a expired y onCompleteProcess se ejecuta con decision = "expired".
priority	string	"normal"	Prioridad en la bandeja: normal o high.

Resume

Parámetro	Tipo	Por defecto	Descripción
onCompleteProcess	string	—	Nombre de un proceso publicado en el mismo ambiente que se ejecuta cuando la tarea se decide, vence o la cancela una persona desde Zoan Cloud; no cuando la cancela un robot (ver arriba).
onCompleteInputs	Dictionary	—	Entradas adicionales para onCompleteProcess (ej. el id del registro con el que debe continuar).
queueName	string	—	Alternativa por lotes a onCompleteProcess: crea también un item en esta cola que espera la decisión. Una ejecución por lote en vez de una por tarea. Desde la versión 1.1.0.
queuePriority	string	"normal"	Prioridad del item de cola: high, normal o low. Desde la versión 1.1.0.
webhookUrl	string	—	URL pública que recibe un evento JSON firmado (cabecera X-Zoan-Signature, HMAC-SHA256) cuando la tarea se decide, se cancela o vence.

Salida

Devuelve un object (diccionario) con:

Campo	Tipo	Descripción
id	string	Id de la tarea. Pásalo a Wait for Human Task o Cancel Human Task.
status	string	Estado de la tarea: pending al crearla. Si reference encontró una tarea abierta, su estado actual (pending o claimed).
title	string	Título de la tarea.
decision	string	Opción elegida (null mientras nadie decida).
comment	string	Comentario de quien decidió (null mientras nadie decida).
fields	Dictionary	Campos que llenó la persona (diccionario vacío mientras nadie decida). Con formulario, las tablas llegan como listas de filas (diccionarios) y los archivos como {id, name, …}: descárgalos con Download Human Task File.
form	Dictionary	Con formulario: su name y la version con la que se creó la tarea. Sin formulario, null.

Errores comunes

La tarea no se crea (y la actividad falla) en estos casos:

Mensaje	Causa y solución
'title' es obligatorio (qué hay que decidir, en una línea).	Falta title.
La tarea necesita a alguien que la decida: indica assignUserEmail (una persona), assignGroup (un grupo) o assignRole (un rol).	No indicaste destino. Toda tarea va dirigida a una persona, un grupo o un rol.
… HTTP 400: …El destinatario «…» no es válido para este ambiente.	El correo no es de una persona activa del tenant, o el rol no existe o no tiene personas activas. Por seguridad, el mensaje no dice cuál de los dos casos es.
Usa campos sueltos (fields) o un formulario (form), no ambos.	Indicaste fields y form a la vez.
formInputs solo aplica con un formulario: indica 'form'. / formVersion solo aplica con un formulario: indica 'form'.	Pusiste formInputs o formVersion sin form.
formVersion debe ser un entero positivo (recibido: «…»).	formVersion no es un número entero mayor que 0.
El formulario «…» necesita la entrada «…» (formInputs).	Falta una entrada obligatoria del formulario en formInputs.
Mensaje de Zoan Cloud sobre el formulario	El formulario no existe, está archivado o no tiene esa versión. Revisa el nombre en la biblioteca de formularios.
El servidor no soporta formularios: actualiza Zoan Cloud. / Las tareas con formulario todavía no están disponibles en Zoan Cloud.	Tu Zoan Cloud aún no admite tareas con formulario.
Zoan Cloud no respondió al comprobar el formulario (HTTP …); no se creó la tarea. Intenta de nuevo.	Fallo pasajero de Zoan Cloud. Reintenta con Retry.
Ya hay una tarea abierta con la referencia «…» creada sin el formulario «…»: usa otra referencia o ciérrala.	reference coincide con una tarea abierta sin formulario.
Como máximo 10 adjuntos por tarea.	attachments trae más de 10 elementos.
No se encontró el adjunto: '…'. Usa una ruta de archivo local o 'bucket/name' de un archivo de Storage.	La ruta local no existe y el texto no tiene forma bucket/nombre.
No se pudo subir el adjunto '…': …	Storage rechazó el archivo local (tipo bloqueado, malware, sin espacio). El detalle va después de los dos puntos.
… HTTP 400: …Adjunto no encontrado en Storage de este ambiente: …	Un bucket/nombre no existe en el Storage del ambiente.
… HTTP 400: …El proceso '…' no está publicado en este ambiente.	onCompleteProcess no corresponde a un proceso publicado en el ambiente.
… HTTP 400: …webhookUrl must be a public http(s) URL.	webhookUrl no es una URL pública.
… HTTP 422: …	Un valor no cumple los límites de Zoan Cloud (más de 6 opciones, una opción de más de 60 caracteres, title de más de 200, dueInHours mayor que 8760…). El detalle indica el campo.
… HTTP 403: …Se alcanzó el límite de … tareas humanas por mes del plan.	La organización llegó al tope mensual de tareas de su plan.
Las actividades de tareas humanas necesitan el contexto de ejecución de Zoan Automation. Falta: …	El proceso no corre desde Zoan Cloud ni desde el Designer con sesión iniciada.

Los errores que devuelve Zoan Cloud llegan con el prefijo “No se pudo crear la tarea humana: ”.

Ejemplo

Pedir la aprobación de un reembolso con un monto a confirmar, y retomar en otro proceso:

Create Human Task   title = "Aprobar reembolso #" + pedido
                    description = "El cliente reporta un cobro duplicado."
                    data = { "Cliente": "Cliente de prueba", "Pedido": "#0001", "Monto": "150.000" }
                    options = "Aprobar, Rechazar, Pedir más información"
                    fields = { "monto_aprobado": "Monto aprobado:number*" }
                    reference = "reembolso-" + pedido
                    assignRole = "tenant-admin"   dueInHours = 24   catalog = "reembolsos"
                    onCompleteProcess = "Reembolsos - Continuar"
                    onCompleteInputs = { "pedido": "#0001" }
                    → output: tarea
Log   level = info   message = "Tarea creada: " + str(tarea["id"])

El proceso Reembolsos - Continuar recibe decision, comment, fields["monto_aprobado"] y pedido.

Con adjuntos

Adjuntar la factura en PDF que la persona debe revisar:

Create Human Task   title = "Validar factura " + numero
                    attachments = ["C:/facturas/F-0001.pdf"]
                    assignUserEmail = "aprobador@empresa.com"   reference = "factura-" + numero
                    → output: tarea
Wait for Human Task   taskId = tarea["id"]   timeoutMinutes = 30   → output: resultado

Con un formulario de la biblioteca

Pedir los datos de un anticipo con un formulario que ya diseñó el equipo, en vez de definir los campos en el robot:

Create Human Task   title = "Aprobar anticipo de " + solicitante
                    form = "Solicitud de anticipo"
                    formInputs = { "solicitante": solicitante, "valor_solicitado": valor }
                    options = "Aprobar, Rechazar"
                    assignRole = "tesoreria"   reference = "anticipo-" + id_solicitud
                    → output: tarea
Wait for Human Task   taskId = tarea["id"]   → output: resultado
Download Human Task File   taskId = tarea["id"]   field = "soporte"
                           destination = "C:\Anticipos\Soportes"   → output: archivos

El nombre del formulario importa

El robot busca el formulario por su nombre. Si alguien lo renombra en la biblioteca, actualiza form en la actividad; la biblioteca avisa qué robots lo usaron en los últimos 30 días. Las opciones de options deben incluir todas las decisiones que usan las reglas del formulario (por ejemplo, si un campo es obligatorio «cuando la decisión es Rechazar», Rechazar debe estar entre las opciones).

Usa reference cuando el proceso pueda reintentarse

Si el proceso falla después de crear la tarea y se vuelve a ejecutar, reference evita que la persona reciba dos tareas iguales: la actividad devuelve la tarea que ya estaba abierta.

Requisitos en Zoan Cloud

• El proceso debe ejecutarse desde Zoan Cloud o desde el Designer con la sesión iniciada: la tarea se crea en el ambiente de la ejecución.
• Quienes deciden necesitan acceso a la bandeja Tareas (permisos para ver y decidir tareas) en ese ambiente.
• Cada tarea cuenta para el tope mensual de tareas humanas del plan, si lo tiene.

Actividades relacionadas

• Wait for Human Task — esperar la decisión en el mismo proceso.
• Cancel Human Task — cancelar la tarea si ya no hace falta.
• Download Human Task File — bajar los archivos que adjuntó la persona.
• Add Queue Item — crear el item de cola con su tarea desde el lado de la cola.