Limit EspoCRM Workflow Runs per Record

Use a hidden Boolean or Integer field to prevent an EspoCRM Workflow from running more times than intended on the same record.

An after-update Workflow can match the same record more than once. When a business action must run only once—or no more than a fixed number of times—store that execution state on the target record and include it in the Workflow condition.

Requirements

Workflows are provided by EspoCRM Advanced Pack. Only administrators can configure them. Test update-triggered workflows carefully because record updates can cause additional automation.

Choose the correct control field

Use:

• a Boolean field when the action must complete only once;
• an Integer field when the action may run up to a defined limit.

These are internal control fields and do not need to be added to normal user layouts.

Option 1: Run once with a Boolean field

Step 1: Create the completion field

Open Administration → Entity Manager → Your Entity → Fields and create:

Setting	Value
Label	Workflow Completed
Internal name	workflowCompleted
Type	Boolean
Default	No

Do not make the field editable by normal users unless manually resetting the Workflow is an intentional business operation.

Step 2: Add the Workflow condition

In the Workflow condition builder, require:

Workflow Completed is false

Add all normal business conditions as well. The historical condition workflowCompleted = true is reversed and would select records already marked complete.

Step 3: Set the flag after the business action

Add an Update Target Record action at the end of the successful action path and set:

workflowCompleted = true

If an earlier action is asynchronous or can fail independently, decide what “completed” means before setting the flag. Do not mark the record complete before the required operation has succeeded.

Option 2: Allow a fixed number of runs

Step 1: Create the counter

Create an Integer field:

Setting	Value
Label	Workflow Run Count
Internal name	workflowRunCount
Type	Integer
Default	0
Minimum	0

Step 2: Add a bounded condition

For a maximum of three executions, use this Formula condition:

(workflowRunCount ?? 0) < 3

A Workflow Formula condition must evaluate to true or false.

Step 3: Increment after success

In an Update Target Record action, calculate:

workflowRunCount = (workflowRunCount ?? 0) + 1;

Keep the business action and counter update in a predictable order. For operations that require strict exactly-once processing across concurrent workers, a simple field is not enough; implement server-side locking or an idempotency record in a reviewed extension.

Choose the trigger deliberately

• After record created already runs only for creation, but other automation may still save the record afterward.
• After record updated should normally include a relevant field-change condition.
• After record created or updated needs the strongest guard because it can match many saves.
• Scheduled workflows run against records returned by a List Report; include the control field in the report or Workflow condition.
• Manual workflows may need a visible condition that explains when the action is no longer available.

EspoCRM includes safeguards for basic loops, but Workflow design should not depend on those safeguards as its execution policy.

Test the Workflow

1. Create a record that meets the business conditions.
2. Confirm the action and control field after the first run.
3. Save an unrelated field and confirm that a one-time Workflow does not repeat.
4. For a counter, trigger the action up to the limit and once more.
5. Test a failed action and confirm whether the flag or counter reflects the intended result.
6. Test any API, import, scheduled, or concurrent update path that can trigger the Workflow.
7. Review the Workflow Log when behavior differs from the expected path.

Common problems

The one-time Workflow never runs

Confirm that the condition checks for false, not true, and that existing records have a false or empty value.

The Workflow stops one run too early

Use < maximum when the counter starts at zero and increment it after each successful run.

Users can reset the control field

Remove it from user layouts and restrict field-level access. If a reset is needed, provide a controlled administrator process and document its effect.