Crucial Workflow Mechanics

Why this page exists

Most production issues come from a few mechanics being misconfigured: entry readiness, slot wiring, release gating, loop bounds, and output path semantics. This page is the fast, practical reference for those mechanics.

1) How workflows start correctly

A workflow starts when at least one entry path is executable.

Checklist:

1. Entry node has valid input context.
2. Optional slots are populated (unless intentionally Optional).
3. No accidental Activated/Delay setting blocks entry execution.
4. First route is correctly connected to downstream input slot.

Typical entry nodes:

• Buffer (manual input/start payload)
• Reader (file/API/cloud ingestion)
• Global(Get) for automation parameters

2) How to connect nodes via slots

Slots are explicit data contracts.

Rules:

• output slot N should map intentionally to input slot M
• use $N references consistently with your slot map
• document slot meaning for high-impact branches

Quick example:

Reader slot 1 -> Code input 1 -> Decision input 1 -> Writer input 1

3) How Optional, Activated, Keep, and Delay actually work

These four flags control eligibility and state behavior. They should be set intentionally with explicit scope:

• Optional: per input slot
• Keep: per input slot (except Buffer nodes, where Keep applies across all slots when selected)
• Activated: per node
• Delay: per node (step/cycle based)

UI indicator note:

• Optional appears as O and is blue when selected.
• Keep appears as K and is green when selected.

Practical guidance:

1. Default to blocking slots; add Optional only with a clear reason.
2. Use Activated for release control, not as a generic troubleshooting switch. Configure Activated with a matching activation edge.
3. Use Keep only where state persistence is part of the design contract. Configure per slot except on Buffer nodes.
4. Use Delay as an explicit step-based control with documented expected behavior. Delay is configured in graph steps/cycles, not wall-clock seconds.

4) How activation edges should be used

Use activation edges when data should arrive before execution permission is granted.

Classic pattern:

• data edge carries payload to Writer
• activation edge from Decision/approval releases Writer execution

Use this for:

• customer-impacting updates
• financial or legal side effects
• any branch requiring review before mutation

5) How to keep loops bounded

NodeFox supports loops, but loops must be bounded.

Minimum controls:

1. explicit pass condition
2. explicit retry condition
3. Decision Max iteration bound
4. explicit fallback/default route when bound is reached

Avoid:

• loop branches with no Max
• loops that can re-enter high-cost side effects without gating

6) How file export/output works

For direct downloadable file output, use Writer path with ./ prefix.

Examples:

• ./summary.txt
• ./report.csv
• ./evidence-package.json

Without ./, output follows registered directory or internal path behavior.

7) How to make behavior auditable

Before production rollout:

1. verify branch outcomes are deterministic and inspectable
2. verify high-impact actions are activation-gated
3. verify loop bounds and fallback routes are present
4. verify output destinations and path semantics
5. verify acceptance/policy checks where optional

Related

• Quickstart
• Execution Model
• Edges and Data Flow
• Nodes