Horizon Workflows

One of the most challenging aspects of building a compelling user experience is crafting complex multi-part workflows. Horizon’s workflows module aims to bring that capability within everyday reach.

See also

For usage information, tips & tricks and more examples check out the Workflows Topic Guide.

Workflows

class horizon.workflows.Workflow(request=None, context_seed=None, entry_point=None, *args, **kwargs)

A Workflow is a collection of Steps.

Its interface is very straightforward, but it is responsible for handling some very important tasks such as:

• Handling the injection, removal, and ordering of arbitrary steps.

• Determining if the workflow can be completed by a given user at runtime based on all available information.

• Dispatching connections between steps to ensure that when context data changes all the applicable callback functions are executed.

• Verifying/validating the overall data integrity and subsequently triggering the final method to complete the workflow.

The Workflow class has the following attributes:

name

The verbose name for this workflow which will be displayed to the user. Defaults to the class name.

slug

The unique slug for this workflow. Required.

steps

Read-only access to the final ordered set of step instances for this workflow.

default_steps

A list of Step classes which serve as the starting point for this workflow’s ordered steps. Defaults to an empty list ([]).

finalize_button_name

The name which will appear on the submit button for the workflow’s form. Defaults to "Save".

success_message

A string which will be displayed to the user upon successful completion of the workflow. Defaults to "{{ workflow.name }} completed successfully."

failure_message

A string which will be displayed to the user upon failure to complete the workflow. Defaults to "{{ workflow.name }} did not complete."

depends_on

A roll-up list of all the depends_on values compiled from the workflow’s steps.

contributions

A roll-up list of all the contributes values compiled from the workflow’s steps.

template_name

Path to the template which should be used to render this workflow. In general the default common template should be used. Default: "horizon/common/_workflow.html".

entry_point

The slug of the step which should initially be active when the workflow is rendered. This can be passed in upon initialization of the workflow, or set anytime after initialization but before calling either get_entry_point or render.

redirect_param_name

The name of a parameter used for tracking the URL to redirect to upon completion of the workflow. Defaults to "next".

object

The object (if any) which this workflow relates to. In the case of a workflow which creates a new resource the object would be the created resource after the relevant creation steps have been undertaken. In the case of a workflow which updates a resource it would be the resource being updated after it has been retrieved.

wizard

Whether to present the workflow as a wizard, with “prev” and “next” buttons and validation after every step.

add_error_to_step(message, slug)

Adds an error message to the workflow’s Step.

This is useful when you wish for API errors to appear as errors on the form rather than using the messages framework.

The workflow’s Step is specified by its slug.

finalize()

Finalizes a workflow by running through all the actions.

It runs all the actions in order and calling their handle methods. Returns True on full success, or False for a partial success, e.g. there were non-critical errors. (If it failed completely the function wouldn’t return.)

format_status_message(message)

Hook to allow customization of the message returned to the user.

This is called upon both successful or unsuccessful completion of the workflow.

By default it simply inserts the workflow’s name into the message string.

get_absolute_url()

Returns the canonical URL for this workflow.

This is used for the POST action attribute on the form element wrapping the workflow.

For convenience it defaults to the value of request.get_full_path() with any query string stripped off, e.g. the path at which the workflow was requested.

get_entry_point()

Returns the slug of the step which the workflow should begin on.

This method takes into account both already-available data and errors within the steps.

get_step(slug)

Returns the instantiated step matching the given slug.

get_success_url()

Returns a URL to redirect the user to upon completion.

By default it will attempt to parse a success_url attribute on the workflow, which can take the form of a reversible URL pattern name, or a standard HTTP URL.

handle(request, context)

Handles any final processing for this workflow.

Should return a boolean value indicating success.

is_valid()

Verifies that all required data is present in the context.

It also calls the validate method to allow for finer-grained checks on the context data.

classmethod register(step_class)

Registers a Step with the workflow.

render()

Renders the workflow.

classmethod unregister(step_class)

Unregisters a Step from the workflow.

validate(context)

Hook for custom context data validation.

Should return a booleanvalue or raise WorkflowValidationError.

Steps

class horizon.workflows.Step(workflow)

A wrapper around an action which defines its context in a workflow.

It knows about details such as:

• The workflow’s context data (data passed from step to step).

• The data which must be present in the context to begin this step (the step’s dependencies).

• The keys which will be added to the context data upon completion of the step.

• The connections between this step’s fields and changes in the context data (e.g. if that piece of data changes, what needs to be updated in this step).

A Step class has the following attributes:

action_class

The Action class which this step wraps.

depends_on

A list of context data keys which this step requires in order to begin interaction.

contributes

A list of keys which this step will contribute to the workflow’s context data. Optional keys should still be listed, even if their values may be set to None.

connections

A dictionary which maps context data key names to lists of callbacks. The callbacks may be functions, dotted python paths to functions which may be imported, or dotted strings beginning with "self" to indicate methods on the current Step instance.

before

Another Step class. This optional attribute is used to provide control over workflow ordering when steps are dynamically added to workflows. The workflow mechanism will attempt to place the current step before the step specified in the attribute.

after

Another Step class. This attribute has the same purpose as before() except that it will instead attempt to place the current step after the given step.

help_text

A string of simple help text which will be prepended to the Action class’ help text if desired.

template_name

A path to a template which will be used to render this step. In general the default common template should be used. Default: "horizon/common/_workflow_step.html".

has_errors

A boolean value which indicates whether or not this step has any errors on the action within it or in the scope of the workflow. This attribute will only accurately reflect this status after validation has occurred.

slug

Inherited from the Action class.

name

Inherited from the Action class.

permissions

Inherited from the Action class.

add_step_error(message)

Adds an error to the Step based on API issues.

allowed(request)

Determines whether or not the step is displayed.

Step instances can override this method to specify conditions under which this tab should not be shown at all by returning False.

The default behavior is to return True for all cases.

contribute(data, context)

Adds the data listed in contributes to the workflow’s context.

By default, the context is simply updated with all the data returned by the action.

Note that even if the value of one of the contributes keys is not present (e.g. optional) the key should still be added to the context with a value of None.

get_help_text()

Returns the help text for this step.

get_id()

Returns the ID for this step. Suitable for use in HTML markup.

has_required_fields()

Returns True if action contains any required fields.

prepare_action_context(request, context)

Hook to customize how the workflow context is passed to the action.

This is the reverse of what “contribute” does to make the action outputs sane for the workflow. Changes to the context are not saved globally here. They are localized to the action.

Simply returns the unaltered context by default.

render()

Renders the step.

Actions

class horizon.workflows.Action(request, context, *args, **kwargs)

An Action represents an atomic logical interaction with the system.

This is easier to understand with a conceptual example: in the context of a “launch instance” workflow, actions would include “naming the instance”, “selecting an image”, and ultimately “launching the instance”.

Because Actions are always interactive, they always provide form controls, and thus inherit from Django’s Form class. However, they have some additional intelligence added to them:

• Actions are aware of the permissions required to complete them.

• Actions have a meta-level concept of “help text” which is meant to be displayed in such a way as to give context to the action regardless of where the action is presented in a site or workflow.

• Actions understand how to handle their inputs and produce outputs, much like SelfHandlingForm does now.

Action classes may define the following attributes in a Meta class within them:

name

The verbose name for this action. Defaults to the name of the class.

slug

A semi-unique slug for this action. Defaults to the “slugified” name of the class.

permissions

A list of permission names which this action requires in order to be completed. Defaults to an empty list ([]).

policy_rules

list of scope and rule tuples to do policy checks on, the composition of which is (scope, rule)

• scope: service type managing the policy for action

• rule: string representing the action to be checked

for a policy that requires a single rule check:

policy_rules should look like
    "(("compute", "compute:create_instance"),)"

for a policy that requires multiple rule checks:

rules should look like
    "(("identity", "identity:list_users"),
      ("identity", "identity:list_roles"))"

where two service-rule clauses are OR-ed.

help_text

A string of simple help text to be displayed alongside the Action’s fields.

help_text_template

A path to a template which contains more complex help text to be displayed alongside the Action’s fields. In conjunction with get_help_text() method you can customize your help text template to display practically anything.

add_action_error(message)

Adds an error to the Action’s Step based on API issues.

get_help_text(extra_context=None)

Returns the help text for this step.

handle(request, context)

Handles any requisite processing for this action.

The method should return either None or a dictionary of data to be passed to contribute().

Returns None by default, effectively making it a no-op.

property media

Return all media required to render the widgets on this form.

WorkflowView

class horizon.workflows.WorkflowView

A generic view which handles the intricacies of workflow processing.

workflow_class

The Workflow class which this view handles. Required.

template_name

The template to use when rendering this view via standard HTTP requests. Required.

ajax_template_name

The template to use when rendering the workflow for AJAX requests. In general the default common template should be used. Defaults to "horizon/common/_workflow.html".

context_object_name

The key which should be used for the workflow object in the template context. Defaults to "workflow".

get(request, *args, **kwargs)

Handler for HTTP GET requests.

get_context_data(**kwargs)

Returns the template context, including the workflow class.

This method should be overridden in subclasses to provide additional context data to the template.

get_initial()

Returns initial data for the workflow.

Defaults to using the GET parameters to allow pre-seeding of the workflow context values.

get_layout()

Returns classes for the workflow element in template.

The returned classes are determied based on the workflow characteristics.

get_template_names()

Returns the template name to use for this request.

get_workflow()

Returns the instantiated workflow class.

post(request, *args, **kwargs)

Handler for HTTP POST requests.

validate_steps(request, workflow, start, end)

Validates the workflow steps from start to end, inclusive.

Returns a dict describing the validation state of the workflow.