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.
A Workflow is a collection of Steps. Its interface is very straightforward, but it is responsible for handling some very important tasks such as:
The Workflow class has the following attributes:
The verbose name for this workflow which will be displayed to the user. Defaults to the class name.
The unique slug for this workflow. Required.
Read-only access to the final ordered set of step instances for this workflow.
A list of Step classes which serve as the starting point for this workflow’s ordered steps. Defaults to an empty list ([]).
The name which will appear on the submit button for the workflow’s form. Defaults to "Save".
A string which will be displayed to the user upon successful completion of the workflow. Defaults to "{{ workflow.name }} completed successfully."
A string which will be displayed to the user upon failure to complete the workflow. Defaults to "{{ workflow.name }} did not complete."
A roll-up list of all the depends_on values compiled from the workflow’s steps.
A roll-up list of all the contributes values compiled from the workflow’s steps.
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".
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.
The name of a parameter used for tracking the URL to redirect to upon completion of the workflow. Defaults to "next".
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.
Whether to present the workflow as a wizard, with “prev” and “next” buttons and validation after every step.
Adds an error to the workflow’s Step with the specified slug based on API issues. This is useful when you wish for API errors to appear as errors on the form rather than using the messages framework.
Finalizes a workflow by running through 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.)
Hook to allow customization of the message returned to the user upon successful or unsuccessful completion of the workflow.
By default it simply inserts the workflow’s name into the message string.
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.
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.
Returns the instantiated step matching the given slug.
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.
Handles any final processing for this workflow. Should return a boolean value indicating success.
Verified that all required data is present in the context and calls the validate method to allow for finer-grained checks on the context data.
Renders the workflow.
Hook for custom context data validation. Should return a boolean value or raise WorkflowValidationError.
A step is a wrapper around an action which defines its context in a workflow. It knows about details such as:
A Step class has the following attributes:
A list of context data keys which this step requires in order to begin interaction.
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.
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.
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.
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.
A string of simple help text which will be prepended to the Action class’ help text if desired.
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".
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.
Inherited from the Action class.
Inherited from the Action class.
Inherited from the Action class.
Adds an error to the Step based on API issues.
Adds the data listed in contributes to the workflow’s shared 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.
Returns the help text for this step.
Returns the ID for this step. Suitable for use in HTML markup.
Returns True if action contains any required fields.
Allows for customization of 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.
Renders the step.
An Action represents an atomic logical interaction you can have 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:
Action classes may define the following attributes in a Meta class within them:
The verbose name for this action. Defaults to the name of the class.
A semi-unique slug for this action. Defaults to the “slugified” name of the class.
A list of permission names which this action requires in order to be completed. Defaults to an empty list ([]).
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.
A string of simple help text to be displayed alongside the Action’s fields.
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.
Adds an error to the Action’s Step based on API issues.
Returns the help text for this step.
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.
A generic class-based view which handles the intricacies of workflow processing with minimal user configuration.
The template to use when rendering this view via standard HTTP requests. Required.
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".
The key which should be used for the workflow object in the template context. Defaults to "workflow".
Handler for HTTP GET requests.
Returns the template context, including the workflow class.
This method should be overridden in subclasses to provide additional context data to the template.
Returns initial data for the workflow. Defaults to using the GET parameters to allow pre-seeding of the workflow context values.
returns classes for the workflow element in template based on the workflow characteristics
Returns the template name to use for this request.
Returns the instantiated workflow class.
Handler for HTTP POST requests.
Validates the workflow steps from start to end, inclusive.
Returns a dict describing the validation state of the workflow.