@spec add_transition(Toolbox.Workflow.t(), Keyword.t()) :: Toolbox.Workflow.t()

Adds a new transition to incident workflow definition.

Incident workflow transition can be defined by:

• from (source status)
• to (target status)
• when (predicate used to select transition which will be executed)
  • there can be multiple when definitions in list, all definitions are connected with && relation
  • possible when definitions:
    • {Module, function}, where function accepts transition, instance and message as args, returns boolean
    • {:timeout, timeout}, where timeout is defined in milliseconds (transition is then automatically executed when time elapses the specified value)
    • {:=, [path, to, state, key], value} (transition is executed if the specified field of state reaches the specified value)
• then (callback used to update workflow instance state during transition execution)
  • there can be multiple then definitions in list, all definitions are executed in given order
  • possible then definitions:
    • {Module, function}, where function accepts transition, instance and message as args, and returns {:ok, state()} to update the instance state
• side_effects (callback used to generate output actions during transition execution)
  • there can be multiple definitions in list, all definitions are executed in given order
  • possible definitions:
    • {Module, function}, where function accepts transition, instance and message as args, and returns {:ok, [OA | Msg | OtherSideEffect]}
• update_history_entry (callback used to modify transition execution history entry stored in asset map)
  • there can be multiple definitions in list, all definitions are executed in given order
  • this is usually used to interpolate description texts, or to add additional attributes to history
  • possible definitions:
    • {Module, function}, where function accepts history entry, transition, instance and message as args and returns {:ok, history_entry}
• update_possible_transition (callback used to modify possible future transitions stored in asset map)
  • there can be multiple definitions in list, all definitions are executed in given order
  • the callback is executed for each possible future transition
  • note this only modifies the items of future attribute of the incident asset, this has no effect on definition transitions
  • possible definitions:
    • {Module, function}, where function accepts possible transition, transition, instance and message as args, and returns {:ok, future_transition}
• user_actions (specifies all possible user actions from the target state)
  • a map of user actions that should be enabled once the transition is executed and incident is in the target state
  • user actions are automatically deleted if not present in the next transition
  • keys are strings
  • values are {module, function}, this specifies the function to be called to generate the user action token (since tokens are not known in advance, they are generated by the specified function)
    • the function takes transition, instance, message as arguments and is expected to return {:ok, binary_token} to register the user action token
• upsert_attributes (specifies additional attributes to be added to the incident asset)
  • list of callbacks to compute the additional attributes
  • each callback produces a map of additional attributes and this is merged into a single map where the latter has priority over the former
  • attributes cannot override attributes handled by this workflow incl. user actions, only other attributes can be added
  • possible definitions:
    • {Module, function}, where function accepts transition, instance and message as args, and should return {:ok, attribute_map}

When a message is evaluated the callbacks above are run in the following order.

1. when callbacks are evaluated to see if the current transition is ready to be executed. If not the next transition is tried.
2. then callbacks are evaluated to update the instance state.
3. user_actions is evaluated, all callbacks specified inside are executed and all user action tokens are calculated.
4. update_history_entry callbacks are evaluated to update the new history entry
5. update_possible_transition callbacks are evaluated to update the new possible future transitions
6. upsert_attributes callbacks are evaluated to gather additional attributes
7. side_effects callbacks are evaluated to acquire the list of all additional output actions

All text bearing attributes (such as subject, name, description_before, description_after) has access to incident metadata dictionary. This dictionary contains these, keys:

• id, which contains incident id
• transition, transition attributes dictionary containing from, to, severity keys
• state, dictionary containing user defined state
• message, altworx message which triggered given transition

Metadata can be accessed via interpolation defined as {{}}, e.g. {{state.foo.bar}}, {{message.body.foo}}.

@spec handle_message(
  Toolbox.Workflow.t(),
  Toolbox.Workflow.Instance.t(),
  Toolbox.Message.t()
) ::
  {:ok, [Runbox.Scenario.OutputAction.t()], Toolbox.Workflow.Instance.t()}
  | {:terminated, [Runbox.Scenario.OutputAction.t()],
     Toolbox.Workflow.Instance.t()}
  | {:error, :not_built_yet}
  | {:error, :status_mismatch}

Uses given incident workflow definition and message to update state of given instance.

If no configured workflow transition matches, nothing will happen = instance state will remain the same.

Order of callback execution:

1. when definitions of transitions in definition order
2. then definitions of matching transition
3. update history entry definitions of matching transition
4. update possible transition definitions of matching transition
5. side effects definitions of matching transition

@spec new() :: Toolbox.Workflow.t()

Creates new blank incident workflow definition

@spec new_instance(
  Toolbox.Workflow.t(),
  Toolbox.Workflow.status(),
  String.t(),
  map(),
  Toolbox.Message.t(),
  Keyword.t()
) ::
  {:ok, [Runbox.Scenario.OutputAction.t()], Toolbox.Workflow.Instance.t()}
  | {:terminated, [Runbox.Scenario.OutputAction.t()],
     Toolbox.Workflow.Instance.t()}
  | {:error, :unknown_status}
  | {:error,
     {:user_actions_invalid | :upsert_attributes_invalid, reason :: String.t()}}

Creates new incident instance for given workflow.

params can be used to specify additional transition-like parameters. For available options see add_transition/2.