Actions
View SourceAn Action is one named and validated unit of work. It is the only executable leaf in a Jido Flow.
Define An Action
defmodule MyApp.Actions.CreateGreeting do
use Jido.Action,
name: "create_greeting",
description: "Creates one greeting",
schema: Zoi.object(%{name: Zoi.string()}),
output_schema: Zoi.object(%{message: Zoi.string()})
@impl true
def run(%{name: name}, context) do
prefix = Map.get(context, :prefix, "Hello")
{:ok, %{message: prefix <> ", " <> name <> "!"}}
end
enduse Jido.Action generates these public functions:
name/0anddescription/0;schema/0andoutput_schema/0;validate_params/1andvalidate_output/1; and- the
Jido.Executabledescriptor used byJido.Exec.
The module must implement run/2. A missing implementation stops compilation.
Jido.Action declares the run/2 callback and the optional input-preparation
hook. Jido.Executable declares the descriptor, validate_params/1, and
validate_output/1 callbacks shared by Action and Flow modules. An Action
implements both behaviours. A Flow implements Jido.Executable and supplies
flow/0 as its definition. Runtime contract checks remain in place for all
module targets, including modules that do not declare the behaviours.
Use An Inline Step For Small Local Work
A Flow module can define a small Step body without a separate Action module:
defmodule ActionGuide.Greeting do
use Jido.Flow, name: "inline_greeting"
flow do
step "greet", name <- input(:name) do
{:ok, %{message: "Hello, " <> name <> "!"}}
end
output result("greet")
end
endThis form compiles the body to an ordinary Action. It does not add inline
methods to use Jido.Action or function/MFA executable targets. Its field
schemas default to empty. Use Step inline: settings for explicit schemas,
descriptions, or execution context. No schema is inferred from bindings.
Exec still owns validation, errors, timeouts, and telemetry.
The separate public Jido.Action.Inline API lets a downstream package provide
inline Actions in its own compile-time DSL.
Keep a named Action for custom lifecycle hooks or a public module API
independent of the host. Use
ActionGuide.Greeting.step_action("greet") when you only need to reuse the
compiled target. See Build Your First Flow for
the complete inline example and named-Action extraction.
Callback Results
An Action callback returns one of five shapes:
{:ok, result}
{:ok, result, effects}
{:error, reason}
{:error, reason, effects}
{:continue, input, target}A normal success result is a map. Use Jido.Action.Output when a successful
value is intentionally raw, streamed, batched, or opaque.
{:ok, Jido.Action.Output.raw("complete")}
{:ok, Jido.Action.Output.batch([%{id: 1}, %{id: 2}])}Effects are optional for both maps and Output values. Return
{:ok, result, requests} with a proper list to request deferred effects.
An empty list returns the two-element success form. Direct Actions and Flows
preserve the requests. Exec does not dispatch them or consume stream output.
Non-list third success elements fail with :invalid_effects. Put metadata in
the result map or Output.meta. Error results discard the third element.
See the effect rules.
{:continue, input, target} tells Jido.Exec what to run next. The current
Action does not return a domain result. Jido.Exec runs target with input
and the same context. The target can be an Action or a Flow. The final target
owns output validation and the final result.
Exec permits this result from a root Action and from the expander of a
Jido.Flow.Dispatch component at the end of a Flow. Other Flow positions reject
it. See Dynamic Flows.
Validation
A direct run/2 call does not validate data. Validate both boundaries when you
call the callback directly.
with {:ok, params} <- MyApp.Actions.CreateGreeting.validate_params(%{name: "Ada"}),
{:ok, result} <- MyApp.Actions.CreateGreeting.run(params, %{prefix: "Hi"}),
{:ok, result} <- MyApp.Actions.CreateGreeting.validate_output(result) do
{:ok, result}
endUse Jido.Exec.run/4 for the normal application boundary.
Jido.Exec.run(
MyApp.Actions.CreateGreeting,
%{name: "Ada"},
%{prefix: "Hi"},
timeout: 5_000
)Exec validates input, calls the Action in the current execution process, validates normal output, and converts exceptions, throws, exits, and invalid return shapes to structured errors. It does not retry the Action.
Prepare Raw Input
Implement on_before_validate_params/1 only when raw input must change before
Zoi can parse it:
@impl true
def on_before_validate_params(%{"enabled" => value} = params)
when value in ["true", "false"] do
prepared =
params
|> Map.delete("enabled")
|> Map.put(:enabled, value == "true")
{:ok, prepared}
endvalidate_params/1 and Jido.Exec.run/4 both run this callback before the
input schema. The callback must return {:ok, map} or {:error, reason}.
Prefer Zoi coercion, defaults, enums, and refinements when they can express the required rule. Keep authentication, authorization, secret lookup, I/O, retry, and compensation out of this callback.
Action Design Rules
- Keep one Action focused on one unit of work.
- Put external effects in the Action, not in a Flow expression.
- Treat context as caller-owned execution data.
- Exec reserves
context.__jido_exec__for runtime metadata. UseJido.Exec.remaining_time(context)to read its budget. Do not persist this reserved field. Other context fields remain caller-owned. - Return structured domain errors when the caller can act on them.
- Make effects idempotent when a higher-level runtime can repeat work.
See Schemas And Validation and Execution Contract for the complete boundary.