Build Your First Flow

View Source

Overview

This Livebook builds a small Flow module. A Flow is a validated graph of Action calls with one explicit output.

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"}])

Define The Flow

input/1 reads Flow input. result/2 reads a prior component result. The result reference creates the dependency between the two Steps. Each <- binds that data to a variable in the Step body.

defmodule FirstFlow.Greeting do
  use Jido.Flow,
    name: "greeting",
    description: "Normalizes a name and creates a greeting",
    schema: Zoi.object(%{name: Zoi.string()}),
    output_schema: Zoi.object(%{message: Zoi.string()})

  flow do
    step "normalize", name <- input(:name) do
      {:ok, %{name: name |> String.trim() |> String.capitalize()}}
    end

    step "greet", name <- result("normalize", :name) do
      {:ok, %{message: "Hello, " <> name <> "!"}}
    end

    output result("greet")
  end
end

Source order does not create a dependency. References and needs: create dependencies. The body is normal Elixir code. Jido compiles it to an ordinary Action; you do not need a separate Action module for each small operation.

Inspect And Run

A Flow module exposes one canonical %Jido.Flow{} value.

flow = FirstFlow.Greeting.flow()

{:ok, dependencies} = Jido.Flow.dependencies(flow)
dependencies["greet"]

Run the module or the canonical value.

{:ok, %{message: "Hello, Ada!"}} =
  Jido.Exec.run(FirstFlow.Greeting, %{name: "  ada  "})

{:ok, %{message: "Hello, Grace!"}} =
  Jido.Exec.run(flow, %{name: "grace"})

Extract A Named Action When Needed

The Flow schemas above validate its input and output. An inline Step can declare its own schemas and description through inline:. Extract a named Action when a Step needs custom validation hooks or an independent public API.

defmodule FirstFlow.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
    {:ok, %{message: "Hello, " <> name <> "!"}}
  end
end

{:ok, %{message: "Hello, Ada!"}} =
  Jido.Exec.run(FirstFlow.CreateGreeting, %{name: "Ada"})

In a Flow, replace the inline greet declaration with the existing Action form:

step "greet",
  action: FirstFlow.CreateGreeting,
  params: %{name: result("normalize", :name)}

Next

Use Flow DSL for the complete language. Use Executing Flows for run-to-completion and step-wise execution. Flow Data Definitions shows how to reuse the compiled body without extracting an Action.