Workflows (Workflows v0.2.0) View Source

Workflows implements an Amazon States Language interpreter using event-sourcing, this has the added benefit that workflows can be suspended and later recovered.

Workflows are created by parsing a map with the workflow definition that conforms to the Amazon States Language specification.

workflow_definition = %{
  "StartAt" => "Start",
  "States" => %{
    "Start" => %{
      "Type" => "Wait",
      "Seconds" => 10,
      "Next" => "End"
    },
    "End" => %{
      "Type" => "Succeed"
    }
  }
}
{:ok, workflow} = Workflows.parse(workflow_definition)

You can then start the workflow by calling the Workflows.start function and passing a context (a map containing data that is shared between all states), and the arguments passed to the initial state. The function returns {:continue, state, events} if the workflow execution has to stop to wait for an external command, or {:success, result, events} if the workflow executes to termination.

ctx = %{"environment" => "staging"}
args = %{"user" => "alfred@example.org"}
{:continue, execution, events} = Workflows.start(workflow, ctx, args)
IO.inspect events

The interpreter does not execute side effects like waiting for a timer or executing a task, instead it returns an event (for example, Event.WaitStarted or Event.TaskStarted) and pauses the execution. To resume execution, you should call the Workflows.resume function with a Command containing the side effect result (for example, the result of a Task).

wait_event = events |> get_wait_event()
finish_wait = Workflows.Command.finish_waiting(wait_event)
{:succeed, result, events} = 
  Workflows.resume(execution, finish_wait)

Link to this section Summary

Functions

parse(definition)

Parses a workflow definition.

recover(workflow, events)

Recovers a workflow execution from events.

resume(execution, cmd)

Resumes an execution waiting for cmd to continue.

start(workflow, ctx, args)

Starts a workflow execution with the given ctx and args.

Link to this section Functions

parse(definition)

Specs

parse(map()) :: {:ok, Workflows.Workflow.t()} | {:error, term()}

Parses a workflow definition.

A workflow is defined by a map-like structure that conforms to the Amazon States Language specification.

Examples

iex> {:ok, wf} = Workflows.parse(%{
...>   "Comment" => "A simple example",
...>   "StartAt" => "Hello World",
...>   "States" => %{
...>     "Hello World" => %{
...>       "Type" => "Task",
...>       "Resource" => "do-something",
...>       "End" => true
...>     }
...>   }
...> })
iex> wf.start_at
"Hello World"

recover(workflow, events)

Specs

recover(Workflows.Workflow.t(), [Workflows.Event.t()]) ::
  Workflows.Execution.execution_result() | {:error, term()}

Recovers a workflow execution from events.

resume(execution, cmd)

Specs

resume(Workflows.Execution.t(), Workflows.Command.t()) ::
  Workflows.Execution.execution_result() | {:error, term()}

Resumes an execution waiting for cmd to continue.

start(workflow, ctx, args)

Specs

start(
  Workflows.Workflow.t(),
  Workflows.Activity.ctx(),
  Workflows.Activity.args()
) :: Workflows.Execution.execution_result() | {:error, term()}

Starts a workflow execution with the given ctx and args.