Set Transaction Status

Set Transaction Status

Type: queue-set-transaction-status  ·  Package: Queue Activities v1.2.9

Closes the transaction of an item: it marks it as successful (processed fine) or failed (processed with an error). It’s what the performer does when it’s done with each item. The item must be in_progress and have been taken by this execution with Get Queue Item or Add Transaction Item.

How it works

• successful: the item moves to successful, stores output in item.Output and releases the lock.
• failed: stores exception in item.Exception, releases the lock and decides the final status:
  • if exception has "type": "BusinessRuleException" (or "BusinessException"), it’s a business error: the item ends in business_exception (“Exception”) and is not retried, even if the queue has retries;
  • if the queue has automatic retry, attempts remain and you didn’t set retryable = false, it goes back to new with a growing wait (1, 2, 4, 8… minutes, up to 30) before it’s handed out again;
  • otherwise, it ends failed, or abandoned if it already used up the queue’s retries.

Required parameters

Parameter	Type	Default	Description
item	ZoanQueueItem	—	The item returned by Get Queue Item (e.g. item), or a dictionary with its id.
status	string	—	successful (success) or failed (error). Case-insensitive.

Optional parameters

Parameter	Type	Default	Description
output	Dictionary	—	JSON object with the processing result. Only for status = successful. Stored in item.Output.
exception	Dictionary	—	JSON object with the error detail (e.g. { "type": "...", "message": "..." }). Only for status = failed. With type = BusinessRuleException the failure is a business one and isn’t retried.
retryable	bool	true	Only for failed. true = honors the queue’s automatic retry. false = fails right away, without retry.

Output

This activity does not return a value.

Common errors

Message	Cause and fix
'item' is required. / 'status' is required.	A required parameter is missing.
'item' must be a ZoanQueueItem or an object with an 'id' field.	item isn’t the queue item.
'status' must be 'successful' or 'failed', got '…'.	status has another value.
… HTTP 400: …Cannot complete an item in status '…' / …Cannot fail an item in status '…'	The item is no longer in_progress: it was already closed (for example, twice in a row) or postponed.
… HTTP 400: …This item is not locked by your execution	Another execution holds the item (its lock expired and another robot took it).
… HTTP 404: …Queue item not found	The item doesn’t exist in the environment.
Queue activities require a Zoan Automation runtime context. Missing: …	The process isn’t running from Zoan Cloud or from the Designer signed in.

Zoan Cloud errors arrive with the prefix “Could not set the item status: ”.

When to use retryable = false

By default, a failed item is retried if the queue has auto-retry and retries remain. That’s right for system errors (the website went down, a timeout). But for business errors —invalid data, a missing field— retrying would give exactly the same error: use retryable = false there, or better yet an exception with "type": "BusinessRuleException", so the item is recorded as a business exception. See retries.

Example

Process the item inside a Try / Catch and report based on the result:

Try
  └─ body:
       (… process the invoice …)
       Set Transaction Status
         item = item   status = successful
         output = { "validated": true, "reviewedBy": "bot" }
  └─ catch (err):
       Set Transaction Status
         item = item   status = failed
         exception = { "type": err.Type, "message": err.Message }
         retryable = true

If the error came from a Throw with the business exception, err.Type is BusinessRuleException and the item isn’t retried.

Related activities

• Get Queue Item — take the item before closing it.
• Postpone Transaction — defer the item instead of closing it.
• Try / Catch — catch the error to report it.