FlowRunner.Contract behaviour (flow_runner v6.15.1)

Copy Markdown

Specify the callback functions to run a Flow.

Summary

Callbacks

create_context(t, flow_uuid, language, mode, var)

Create a fresh context for a flow.

evaluate_expression(t, t)
evaluate_expression_as_string!(t, t)
evaluate_expression_block(t, t)
evaluate_next_block(t, t, t, t)

If the current block is not waiting on user input then FlowRunner proceeds automatically to the next block with the the context of the previous block by calling this callback.

fetch_flow_by_uuid(t, flow_uuid)

Retrieves a flow from a container by its given UUID. Used internally by create_context/5 to load the flow when creating a new context

next_block(t, t, user_input)

next_block transitions us from one block to the next block in a flow. It requires a flow, a run context and optionally user input requested from the previous block. It returns an updated container, flow, block, and context.

Callbacks

create_context(t, flow_uuid, language, mode, var)

@callback create_context(
  FlowRunner.Spec.Container.t(),
  flow_uuid :: String.t(),
  language :: String.t(),
  mode :: String.t(),
  var :: map()
) :: {:ok, FlowRunner.Context.t()} | {:error, String.t()}

Create a fresh context for a flow.

It takes a flow_uuid rather than a %Flow{} because blocks always refer to the next block by the UUID which should then be retrieved from the container.

evaluate_expression(t, t)

@callback evaluate_expression(String.t(), FlowRunner.Context.t()) :: [term()]

evaluate_expression_as_string!(t, t)

@callback evaluate_expression_as_string!(String.t(), FlowRunner.Context.t()) :: String.t()

evaluate_expression_block(t, t)

@callback evaluate_expression_block(String.t(), FlowRunner.Context.t()) :: term()

evaluate_next_block(t, t, t, t)

@callback evaluate_next_block(
  FlowRunner.Spec.Container.t(),
  FlowRunner.Spec.Flow.t(),
  FlowRunner.Spec.Block.t(),
  FlowRunner.Context.t()
) ::
  {:ok, FlowRunner.Spec.Container.t(), FlowRunner.Spec.Flow.t(),
   FlowRunner.Spec.Block.t(), FlowRunner.Context.t()}
  | {:end, FlowRunner.Spec.Container.t(), FlowRunner.Spec.Flow.t(),
     FlowRunner.Spec.Block.t(), FlowRunner.Context.t()}
  | {:error, String.t()}

If the current block is not waiting on user input then FlowRunner proceeds automatically to the next block with the the context of the previous block by calling this callback.

This is where we evaluate the block we have transitioned to and return updated container, flow, block, and context.

fetch_flow_by_uuid(t, flow_uuid)

@callback fetch_flow_by_uuid(FlowRunner.Spec.Container.t(), flow_uuid :: String.t()) ::
  {:ok, FlowRunner.Spec.Container.t(), FlowRunner.Spec.Flow.t()}
  | {:error, String.t()}

Retrieves a flow from a container by its given UUID. Used internally by create_context/5 to load the flow when creating a new context

next_block(t, t, user_input)

@callback next_block(
  FlowRunner.Spec.Container.t(),
  FlowRunner.Context.t(),
  user_input :: nil | String.t()
) ::
  {:ok, FlowRunner.Spec.Container.t(), FlowRunner.Spec.Flow.t(),
   FlowRunner.Spec.Block.t() | nil, FlowRunner.Context.t()}
  | {:end, FlowRunner.Spec.Container.t(), FlowRunner.Spec.Flow.t(),
     FlowRunner.Spec.Block.t() | nil, FlowRunner.Context.t()}
  | {:error, reason :: String.t()}

next_block transitions us from one block to the next block in a flow. It requires a flow, a run context and optionally user input requested from the previous block. It returns an updated container, flow, block, and context.

The updated context may have context.waiting_for_user_input set to true. If so the next call of next_block must have user_input != nil.

If the block was a Core.RunFlow, ie. a flow called from a flow, and it's reached its end then return the context of the parent flow.