Steps And Output
View SourceOverview
A Step calls one Action. Its parameter expression maps Flow data to Action input.
Run the cells from top to bottom.
Install The Package
Inline Steps require 3.0.0-beta.5 or later.
Mix.install([{:jido_action, "~> 3.0.0-beta.11"}])Write An Inline Body
Bind Flow data in the header. Write normal Elixir in the body and return an
Action result. This example shows a single binding, binding lists,
a sole map pattern, and the explicit no-input form [].
defmodule FlowSteps.Inline do
use Jido.Flow, name: "inline_steps"
flow do
step "ready", [] do
{:ok, %{ready: true}}
end
step "normalize", name <- input(:name), needs: "ready", meta: %{owner: "guide"} do
{:ok, %{name: String.trim(name)}}
end
step "greet", [name <- result("normalize", :name), prefix <- context(:prefix)] do
{:ok, %{message: prefix <> ", " <> name <> "!"}}
end
step "label", [name <- result("normalize", :name), city <- input(:city), ctx <- context()] do
{:ok, %{label: name <> " / " <> city, language: ctx.language}}
end
step "profile", %{name: name, active: true} <- input(:profile) do
{:ok, %{name: name}}
end
output(%{
greeting: result("greet", :message),
label: result("label"),
profile: result("profile")
})
end
end
{:ok,
%{
greeting: "Hello, Ada!",
label: %{label: "Ada / London", language: "en"},
profile: %{name: "Ada"}
}} =
Jido.Exec.run(
FlowSteps.Inline,
%{name: " Ada ", city: "London", profile: %{name: "Ada", active: true}},
%{prefix: "Hello", language: "en"}
)Named bindings create an atom-keyed parameter map. For example,
name <- input(:name) supplies %{name: ...} to the compiled Action. A sole
map pattern receives its source as the complete parameter map. [] supplies
%{}. When you reuse the target in data definitions, supply a new mapping with the
same parameter shape. The target does not retain the original source mapping.
Step header options are needs:, meta:, and inline:. Use one binding
argument: a single binding or a list. Two or more named bindings require a list. Do not mix map patterns with named bindings or use more
than one map pattern. Duplicate names, bare _, pins, header guards, and
top-level struct patterns are not supported. Bind a value by name and match
inside the body when you need a more complex pattern.
The right side of <- uses the restricted Flow expression grammar. It cannot
call application functions or read another binding variable. Put those
operations in the body. Read context with an explicit binding such as
ctx <- context(); there is no implicit context variable.
Exec requires map-shaped parameters and a map success result, unless you use
Jido.Action.Output.
A pattern mismatch becomes a structured execution failure. It is not field
schema validation. A missing reference fails before the body runs.
Use inline: for an explicit Action name, description, field schemas, or
context: ctx. Keep needs: and meta: at the Step level. Map, Reduce,
Choice targets, Iterate, and Dispatch use Action modules.
See Inline Actions
for runnable examples.
Keep a named Action for custom lifecycle hooks or a separate public module API. All forms use the same Exec errors, telemetry, timeout, concurrency, and lifecycle rules. A normal Step cannot return a continuation.
Define An Action
defmodule FlowSteps.Echo do
use Jido.Action, name: "flow_steps_echo"
@impl true
def run(params, _context), do: {:ok, params}
endUse Short Or Block Form
The inline, short, and field-block forms all lower to Jido.Flow.Step.
defmodule FlowSteps.Example do
use Jido.Flow, name: "flow_steps_example"
flow do
step("first",
action: FlowSteps.Echo,
params: %{value: input(:value)},
meta: %{owner: "guide"}
)
step "second" do
action(FlowSteps.Echo)
params(%{value: result("first", :value), tag: :complete})
meta(%{owner: "guide"})
end
output(%{
first: result("first"),
second: result("second")
})
end
end{:ok, output} = Jido.Exec.run(FlowSteps.Example, %{value: 7})
outputThe result reference creates the dependency on first. Use the short form
needs: "first" option only for control order that does not move data.
Step Fields
A canonical Step has these fields:
| Field | Meaning |
|---|---|
name | Unique string component name. |
action | Action module. |
params | Canonical expression for Action input. |
needs | Explicit control dependencies. |
meta | Portable author metadata with no execution meaning. |
The Action must satisfy the Jido.Executable Action contract. A step that
targets a Flow module becomes Jido.Flow.Subflow instead.
Declare Output
output is a Flow expression, not an Action call. Shape the final result with
a map. A module Flow must declare output as its final declaration.
output(%{
value: result("second", :value),
source: :guide
})Normal Flow output must be a map. Use an Action Output envelope when the Flow intentionally returns a raw, stream, batch, or opaque value.
Use {:ok, output, requests} for deferred effects.
Flow returns the complete batch separately from output after success. It
requires a proper list for the third success element. See Execution.