Formula Branching ExecModule

Overview

FormulaBranchingModule version 2.0 evaluates one boolean expression against workflow variables and selects the canonical DEFAULT, CONDITIONAL, or FAILURE graph outcome. It is a deterministic, local control module: it does not call an API, mutate business data, resolve an approval, or dispatch a task itself.

The v2 contract declares the expression context and every output, rejects invalid outcome names, requires a target for a selected conditional branch, clears stale output before each run, and emits content-free failures without copying expressions or variable values.

Use Formula Branching when one expression should control graph flow. For ordered rule sets, multiple destinations, labels, or field-operator forms, use ConditionalBranchModule instead of duplicating those rules in a formula.

Usage

1. Configure a bounded expression using variable names from the workflow input map.
2. Choose the onTrue and onFalse graph outcomes.
3. Set nextTaskId whenever the branch that may be selected is CONDITIONAL.
4. Pass variables directly in workflow input, or put the exact expression context in the optional variables object.
5. Route using getBranchOutcome() and, for a conditional edge, branch_taskId.

The engine-compatible output key remains branch_taskId. Version 2 preserves that key for saved workflows while correcting its catalog type from object to string.

Inputs

Input	Type	Required	Default	Description
variables	object	No	{}	Explicit expression context with at most 1,000 properties. If omitted, the complete workflow input map is used.

Every variable key must be a non-empty string. When variables is present, sibling workflow input fields are deliberately excluded from the expression context so the evaluated scope is explicit.

Outputs

Output	Type	Condition	Description
status	string	Always	success after evaluation and routing, otherwise error.
conditionResult	boolean	Successful evaluation	Boolean value returned by the condition evaluator.
branchOutcome	string	Always	Selected DEFAULT, CONDITIONAL, or FAILURE outcome.
branch_taskId	string	Selected outcome is CONDITIONAL	Configured workflow task identifier for the conditional edge.
error	object	Failure	Safe code, generic or field-specific message, and retryable: false.

The error object never contains the expression text, evaluated variable values, or an evaluator exception message.

IntegrationAccount Requirements

No IntegrationAccount is required or read. Formula Branching performs no credential lookup, network request, persistence, or external delivery.

Any downstream module selected by the branch remains responsible for its own authorization, IntegrationAccount, idempotency, rate limits, approvals, and side effects.

Configuration

Field	Type	Required	Default	Description
expression	string	Yes	—	Non-empty boolean expression, at most 4,096 characters.
onTrue	select	No	CONDITIONAL	Outcome when the evaluator returns true.
onFalse	select	No	DEFAULT	Outcome when the evaluator returns false.
nextTaskId	string	Conditional	—	Non-empty, control-character-free task identifier of at most 255 characters. Required when the selected outcome is CONDITIONAL.

The supported outcomes are exactly DEFAULT, CONDITIONAL, and FAILURE, matched case-insensitively. Unknown values fail closed rather than silently becoming DEFAULT.

Operations

Each execution follows the same bounded sequence:

1. Clear the prior output map and reset the in-memory outcome.
2. Validate expression text, routing outcomes, and optional task identifier.
3. Resolve either the explicit variables object or the direct workflow input map.
4. Require at most 1,000 top-level variables with non-empty string keys.
5. Evaluate through the repository ConditionService, which prefers OpenXLS when available and otherwise uses the JEXL-compatible evaluator.
6. Select onTrue or onFalse from the boolean result.
7. Require nextTaskId if the selected outcome is CONDITIONAL.
8. Emit the routing receipt and the canonical BranchOutcome.

Identical configuration and variables produce identical routing output.

Errors and Failure Modes

Error code	Cause	Retryable	Recovery
INVALID_CONFIGURATION	Missing, non-string, oversized, or control-bearing configuration; invalid outcome; malformed variable context; or missing selected conditional target.	No	Correct the named contract field and rerun.
EVALUATION_FAILED	The condition evaluator throws while parsing or evaluating the expression.	No automatic retry	Validate syntax and referenced variable names without relying on prior output.

Both failures clear earlier success data, select FAILURE, and omit conditionResult and branch_taskId. The module never routes from a stale prior result.

Some legacy evaluator syntax errors may normalize to a boolean false rather than throw. Validate critical expressions in a non-production workflow and configure the false branch conservatively.

Example

Configuration:

{
  "expression": "score >= 80",
  "onTrue": "CONDITIONAL",
  "onFalse": "DEFAULT",
  "nextTaskId": "task-qualified"
}

Workflow input:

{
  "variables": {
    "score": 91
  }
}

Expected result:

{
  "status": "success",
  "conditionResult": true,
  "branchOutcome": "CONDITIONAL",
  "branch_taskId": "task-qualified"
}

The result selects the conditional graph edge. It does not execute task-qualified; the workflow engine applies the routing outcome.

Notes

• Pagination: not applicable; evaluation consumes one bounded context with at most 1,000 top-level variables.
• Limits: expression length is 4,096 characters and nextTaskId length is 255 characters.
• Idempotency: natural and deterministic for identical configuration, evaluator version, and variable context.
• Rate limits: none; no external service is called.
• API constraints: expressions use the repository ConditionService syntax. OpenXLS availability can affect which evaluator handles a compatible formula.
• Destructive behavior: none. The module only returns graph-routing state.
• Secret handling: expressions and variable values are not logged or copied into failure output. Do not place credentials in workflow expression context.
• Observability: success and failure emit content-free module events; failure logs only the safe error code.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio metadata until a backend release exposes version 2 through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• Spreadsheet conditions
• Workflow architecture
• Module authoring and testing