2.2.3 About Idempotent Workflows and Tasks

Idempotency ensures that repeated attempts to process the same logical request do not create duplicate workflow executions or duplicate task side effects. This is useful in distributed systems where clients, schedulers, workers, or AI agents may retry an operation after a timeout, network failure, or partial failure.

MicroTx Workflows applies idempotency at two levels: workflow level and task level.

Workflow-level idempotency

Workflow-level idempotency prevents the same workflow from being started more than once for the same logical request. MicroTx Workflows identifies an idempotent workflow request by using a combination of idempotency key, workflow name, and workflow version.

When you run a workflow, you can provide an idempotency key. If you do not provide one, MicroTx Workflows automatically generates a unique idempotency key for that execution. The generated key is included in the workflow output so that you can track the execution.

If you submit another request with the same idempotency key, workflow name, and workflow version, MicroTx Workflows handles the request based on the status of the existing workflow execution:

Existing Workflow Status	Behavior
Running	MicroTx Workflows rejects the duplicate request because the workflow is already in progress.
Completed	MicroTx Workflows returns the existing workflow execution instead of starting a new one.
Failed, terminated, or timed out	MicroTx Workflows rejects the request and reports that a previous workflow with the same idempotency key already exists in that status.

If there is no matching execution, MicroTx Workflows starts a new workflow execution.

To make client-side retries idempotent, use the same idempotency key when retrying the same logical request. If you leave the idempotency key empty each time, MicroTx Workflows generates a new key for each request, and each request is treated as a new workflow execution.

Let's understand how MicroTx Workflows provides idempotency at the workflow level with an example. Consider a workflow that contains a SQL Task to update the account balance in a table. The workflow has already been executed successfully once. If you submit another request to run the workflow again with the same idempotency key which was used in the previous execution, MicroTx Workflows checks if the account balance was already updated. If the account balance was already updated, MicroTx Workflows retrieves the balance stored in the database and returns the result without performing the operation again. In such a scenario, idempotency at the workflow level ensures that the account balance is not updated a second time and the workflow is not executed again.

Task-level idempotency

Task-level idempotency prevents supported tasks from applying the same side effects more than once during retries, restarts, reruns, or agent-driven re-invocations. MicroTx Workflows scopes task idempotency under the workflow idempotency context and the task reference name.

For supported task implementations, the effective task identity is based on the workflow idempotency context and the task reference name. For database-backed task idempotency, MicroTx Workflows uses a fenced token lock to ensure that only one executor can own and complete the task result for a given idempotency identity.

Agentic task and Agentic Planner task idempotency

Agentic task and Agentic Planner task use fenced token lock idempotency for every execution. They store the task execution state by using the workflow idempotency key and the task reference name. If a matching completed task result already exists, MicroTx Workflows restores the stored output instead of invoking the agent or planner again.

This prevents duplicate LLM calls, repeated tool invocations, and repeated MCP or external tool side effects when an agentic task is retried or resumed.

SQL Task, GenAI Ingestion Task, and TxEventQ Task idempotency

SQL task, GenAI Ingestion task, and TxEventQ task support task-level idempotency through task input options. To enable task-level idempotency for these tasks, set the enableIdempotency property to true.

You can also provide the name of an idempotent table to specify the database table used for the fenced idempotency lock. If you do not provide a table name, MicroTx Workflows uses the default table name, fenced_task_idempotency_lock.

For SQL task and GenAI Ingestion task, the idempotency table must exist in the customer database where the task performs its database operation. MicroTx Workflows uses the table to acquire a fenced lock and store the task outcome. The database operation and idempotency result are committed together. If the operation fails, the transaction is rolled back so that partial changes are not committed.

For SQL Task, you can enable idempotency when the task is enlisted in an XA transaction.

Simple tasks and worker tasks

MicroTx Workflows does not automatically enforce task-level idempotency for custom simple tasks or worker tasks. If your worker task performs side effects, such as updating a database, calling an external API, or publishing a message, you must provide custom code to implement idempotency in the worker or downstream service.

Advantages

• Prevents duplicate workflow starts for the same logical request.
• Prevents duplicate side effects for supported system tasks.
• Makes retries safer when clients, schedulers, workers, or agents re-submit the same request.
• Reduces operational risk from duplicate inserts, repeated notifications, repeated message publishing, double charging, or repeated AI/tool calls.
• Provides a consistent idempotency model for workflow execution and supported task execution.