Create Human Task

Create Human Task

Type: human-task-create  ·  Package: Human Task Activities v1.3.3  ·  Output: object

Creates a task so a person can decide something in the Zoan Cloud Tasks inbox: approve or reject, choose among several options, fill in a piece of data. The activity doesn’t wait for the decision: it creates the task and returns its id right away. To wait for the result, combine it with Wait for Human Task, or set onCompleteProcess so another process continues when someone decides.

How it works

1. Creates the task in the environment where the execution runs, with the title, description, data (data) and decision options (options). With fewer than two options, the person chooses between Aprobar and Rechazar (approve / reject). What the person fills in is defined with standalone fields (fields) or with a form from the library (form), never both.
2. Addresses it to a person (assignUserEmail), a group (assignGroup) or a role (assignRole); one is required. Only that person, the members of that group or role (and whoever has permission to see every task) see the task and can decide it, and they get the email with the link. If you set several, the person wins, then the group, then the role.
3. If you pass attachments, it uploads the local files to Storage and attaches them to the task: the reviewer opens them from the task detail.
4. Returns the task with status = "pending".

When someone decides, the task moves to completed and stores the decision, the comment and the fields the person filled in. If you set a deadline (dueInHours) and nobody decides in time, it moves to expired.

Idempotency: with reference, if there’s already an open task (pending or claimed) with that reference in the environment, the activity returns that task instead of creating another one. Local attachments are uploaded to a folder derived from the reference (tasks/<reference>/), so repeating the call replaces them instead of duplicating them.

Forms: before creating anything (not the task, the email, the queue item or the attachment upload), the activity checks with Zoan Cloud that the form exists, is published and isn’t archived, and that formInputs contains every required input. A misspelled name therefore fails immediately without leaving anything half done. An input the form doesn’t declare only produces a warning in the log.

What happens when the task closes

Depending on the parameters in the Resume group:

• onCompleteProcess: when the task is decided, expires or is cancelled by a person in Zoan Cloud, Zoan Cloud runs that process on the same agent and robot session that created the task. The process receives these inputs, plus those in onCompleteInputs:

  Input	Content
  human_task_id	Task id.
  human_task_title	Task title.
  human_task_status	completed, cancelled or expired.
  decision	The chosen option; if the task was cancelled or expired, cancelled or expired.
  comment	Comment of whoever decided.
  fields	Fields the person filled in (dictionary).
  data	The data (data) the task was created with.

  The process does not run if a robot cancels the task —with Cancel Human Task or with cancelOnTimeout of Wait for Human Task— nor if the queue item linked to the task is deleted: in those cases the flow itself already knows it doesn’t need the decision.

• queueName: besides the task, it creates an item in that queue (with data as its specific content) that stays waiting for the decision. Once decided, the item returns to the queue with item.Decision and a performer processes it with Process Queue. If the task is cancelled, whether by a person or a robot, the item is released as well so it doesn’t stay waiting. It works the same with a form (form). See Human decisions in batches.

• webhookUrl: Zoan Cloud sends a signed JSON event to that URL when the task is decided, cancelled or expires.

Required parameters

Parameter	Type	Default	Description
title	string	—	What must be decided, in one line (up to 200 characters). E.g.: Approve refund #0001.

In addition, you must set assignUserEmail, assignGroup or assignRole (see Assignment).

Optional parameters

Task

Parameter	Type	Default	Description
description	string	—	Context for the reviewer: what happened, amounts, why it needs a decision (up to 4000 characters). Multi-line text editor.
data	Dictionary	—	Key → value data the person sees as a table (customer, amount, reference…).
options	string	"Aprobar, Rechazar"	Decision options separated by commas (; and | are accepted too). Between 2 and 6 options of up to 60 characters; with just one, the defaults are used.
form	string	—	Name of a form published in the environment. The Designer shows you the list of published forms (when signed in) and includes no form. With a form, the person sees its sections, tables, attachments and rules, and fields is not used. Since 1.3.0.
formVersion	int	—	Published version of the form (positive integer). Empty = the current version when the task is created. Pin it if you don’t want a form change to affect the robot. Only with form. Since 1.3.0.
formInputs	Dictionary	—	Values for the inputs the form declares (input → value), or an expression that returns a dictionary. A DataTable is sent as a list of rows. Only with form. Since 1.3.0.
fields	Dictionary	—	Standalone fields the person must fill in (if you don’t use form), key → Label:type[*]. Types: text, number, date, select:A|B. * = required. Up to 20 fields. E.g.: approved_amount → Approved amount:number*. The values come back in fields.
reference	string	—	Optional unique reference (e.g. the order id, up to 200 characters). If there’s already an open task with the same reference in the environment, it returns that one instead of creating a duplicate (safe on retries).
catalog	string	—	Business catalog of the task (invoices, refunds…, up to 60 characters) to filter and see metrics in the inbox. Since 1.1.0.
labels	string	—	Labels separated by commas. Since 1.1.0.
attachments	List	—	Files the person needs to decide (e.g. the invoice PDF), up to 10. Each element is a local path (uploaded to Storage, into the tasks/<reference>/ folder of the attachmentsBucket bucket) or a file already in Storage as bucket/name. A single text value is accepted too. Only people who can see the task can open them. Since 1.2.0.
attachmentsBucket	string	"human-tasks"	Storage bucket where local attachments are uploaded. Since 1.2.0.

Assignment

Parameter	Type	Default	Description
assignRole	string	—	Code of the role the task is addressed to (e.g. tenant-admin or a custom role such as accounting). The role must have at least one active person. Only its members see it, get the email and can decide. Required if you don’t set assignUserEmail.
assignUserEmail	string	—	Email of an active person in the tenant the task is addressed to. Only that person sees and decides it. Takes precedence over assignGroup and assignRole.
assignGroup	string	—	Name of a group of the organization (including groups synced from Microsoft Entra ID). Its members see it, get the email and decide it; people who join the group later see it too. Takes precedence over assignRole.
escalateToRole	string	—	If the task expires without a decision, it’s reassigned once to this role and the deadline is extended by the same duration.
escalateToUserEmail	string	—	If the task expires without a decision, it’s reassigned once to this person (email). Takes precedence over escalateToGroup and escalateToRole.
escalateToGroup	string	—	If the task expires without a decision, it’s reassigned once to this group (name). Takes precedence over escalateToRole.

Options

Parameter	Type	Default	Description
dueInHours	int	—	Hours until the task expires (business hours, if the organization defined a schedule), between 1 and 8760. Empty or 0 = never expires. On expiry, the task moves to expired and onCompleteProcess runs with decision = "expired".
priority	string	"normal"	Priority in the inbox: normal or high.

Resume

Parameter	Type	Default	Description
onCompleteProcess	string	—	Name of a process published in the same environment that runs when the task is decided, expires or is cancelled by a person in Zoan Cloud; not when a robot cancels it (see above).
onCompleteInputs	Dictionary	—	Extra inputs for onCompleteProcess (e.g. the id of the record it should continue with).
queueName	string	—	Batch alternative to onCompleteProcess: also creates an item in this queue that waits for the decision. One execution per batch instead of one per task. Since 1.1.0.
queuePriority	string	"normal"	Priority of the queue item: high, normal or low. Since 1.1.0.
webhookUrl	string	—	Public URL that receives a signed JSON event (X-Zoan-Signature header, HMAC-SHA256) when the task is decided, cancelled or expires.

Output

Returns an object (dictionary) with:

Field	Type	Description
id	string	Task id. Pass it to Wait for Human Task or Cancel Human Task.
status	string	Task status: pending when created. If reference found an open task, its current status (pending or claimed).
title	string	Task title.
decision	string	Chosen option (null until someone decides).
comment	string	Comment of whoever decided (null until someone decides).
fields	Dictionary	Fields the person filled in (empty dictionary until someone decides). With a form, tables arrive as lists of rows (dictionaries) and files as {id, name, …}: download them with Download Human Task File.
form	Dictionary	With a form: its name and the version the task was created with. Without a form, null.

Common errors

The task isn’t created (and the activity fails) in these cases:

Message	Cause and fix
'title' is required (what must be decided, in one line).	title is missing.
The task needs someone to decide it: set assignUserEmail (a person), assignGroup (a group) or assignRole (a role).	You didn’t set a recipient. Every task is addressed to a person, a group or a role.
… HTTP 400: … (ASSIGNEE_INVALID)	The email isn’t an active person in the tenant, or the role doesn’t exist or has no active people. For security, the message doesn’t say which.
Use loose fields (fields) or a form (form), not both.	You set fields and form together.
formInputs only applies with a form: set 'form'. / formVersion only applies with a form: set 'form'.	You set formInputs or formVersion without form.
formVersion must be a positive integer (got: «…»).	formVersion isn’t an integer greater than 0.
Form «…» needs the input «…» (formInputs).	A required form input is missing from formInputs.
Zoan Cloud message about the form	The form doesn’t exist, is archived or doesn’t have that version. Check the name in the form library.
The server does not support forms: update Zoan Cloud. / Tasks with a form are not available in Zoan Cloud yet.	Your Zoan Cloud doesn’t support tasks with a form yet.
Zoan Cloud did not respond while checking the form (HTTP …); the task was not created. Try again.	Transient Zoan Cloud failure. Retry with Retry.
There is already an open task with reference «…» created without form «…»: use another reference or close it.	reference matches an open task without a form.
At most 10 attachments per task.	attachments has more than 10 elements.
Attachment not found: '…'. Use a local file path or 'bucket/name' of a Storage file.	The local path doesn’t exist and the text isn’t in bucket/name form.
Could not upload attachment '…': …	Storage rejected the local file (blocked type, malware, no space). The detail follows the colon.
… HTTP 400: …Adjunto no encontrado en Storage de este ambiente: …	A bucket/name doesn’t exist in the environment’s Storage.
… HTTP 400: …El proceso '…' no está publicado en este ambiente.	onCompleteProcess isn’t a process published in the environment.
… HTTP 400: …webhookUrl must be a public http(s) URL.	webhookUrl isn’t a public URL.
… HTTP 422: …	A value exceeds Zoan Cloud’s limits (more than 6 options, an option over 60 characters, title over 200, dueInHours over 8760…). The detail names the field.
… HTTP 403: … (monthly human task limit)	The organization reached its plan’s monthly task limit.
Human task activities require a Zoan Automation runtime context. Missing: …	The process isn’t running from Zoan Cloud or from the Designer signed in.

Errors returned by Zoan Cloud arrive with the prefix “Could not create the human task: ”.

Example

Ask for approval of a refund with an amount to confirm, and resume in another process:

Create Human Task   title = "Approve refund #" + order
                    description = "The customer reports a duplicate charge."
                    data = { "Customer": "Test customer", "Order": "#0001", "Amount": "150.00" }
                    options = "Approve, Reject, Ask for more information"
                    fields = { "approved_amount": "Approved amount:number*" }
                    reference = "refund-" + order
                    assignRole = "tenant-admin"   dueInHours = 24   catalog = "refunds"
                    onCompleteProcess = "Refunds - Continue"
                    onCompleteInputs = { "order": "#0001" }
                    → output: task
Log   level = info   message = "Task created: " + str(task["id"])

The Refunds - Continue process receives decision, comment, fields["approved_amount"] and order.

With attachments

Attach the invoice PDF the person has to review:

Create Human Task   title = "Validate invoice " + number
                    attachments = ["C:/invoices/F-0001.pdf"]
                    assignUserEmail = "approver@company.com"   reference = "invoice-" + number
                    → output: task
Wait for Human Task   taskId = task["id"]   timeoutMinutes = 30   → output: result

With a form from the library

Ask for the details of an advance with a form the team already designed, instead of defining the fields in the robot:

Create Human Task   title = "Approve advance for " + requester
                    form = "Advance request"
                    formInputs = { "requester": requester, "requested_amount": amount }
                    options = "Approve, Reject"
                    assignRole = "treasury"   reference = "advance-" + request_id
                    → output: task
Wait for Human Task   taskId = task["id"]   → output: result
Download Human Task File   taskId = task["id"]   field = "receipt"
                           destination = "C:\Advances\Receipts"   → output: files

The form name matters

The robot looks the form up by its name. If someone renames it in the library, update form in the activity; the library warns which robots used it in the last 30 days. The options in options must include every decision the form’s rules use (for example, if a field is required “when the decision is Reject”, Reject must be among the options).

Use reference when the process can be retried

If the process fails after creating the task and runs again, reference keeps the person from getting two identical tasks: the activity returns the task that was already open.

Zoan Cloud requirements

• The process must run from Zoan Cloud or from the Designer signed in: the task is created in the execution’s environment.
• Reviewers need access to the Tasks inbox (permissions to see and decide tasks) in that environment.
• Every task counts towards the plan’s monthly human task limit, if it has one.

Related activities

• Wait for Human Task — wait for the decision in the same process.
• Cancel Human Task — cancel the task if it’s no longer needed.
• Download Human Task File — download the files the person attached.
• Add Queue Item — create the queue item with its task from the queue side.