Steps And Output

View Source

Overview

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}
end

Use 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})
output

The 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:

FieldMeaning
nameUnique string component name.
actionAction module.
paramsCanonical expression for Action input.
needsExplicit control dependencies.
metaPortable 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.