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)[source]¶ 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 ([]
).
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
orrender
.
-
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)[source]¶ 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.
-
finalize
()[source]¶ Finalizes a workflow by running through all the actions in order and calling their
handle
methods. ReturnsTrue
on full success, orFalse
for a partial success, e.g. there were non-critical errors. (If it failed completely the function wouldn’t return.)
-
format_status_message
(message)[source]¶ 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.
-
get_absolute_url
()[source]¶ 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
()[source]¶ 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_success_url
()[source]¶ 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)[source]¶ Handles any final processing for this workflow. Should return a boolean value indicating success.
-
is_valid
()[source]¶ 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.
-
validate
(context)[source]¶ Hook for custom context data validation. Should return a boolean value or raise
WorkflowValidationError
.
Steps¶
-
class
horizon.workflows.
Step
(workflow)[source]¶ A step is 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:-
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 currentStep
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 asbefore()
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.
-
contribute
(data, context)[source]¶ 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 ofNone
.
-
prepare_action_context
(request, context)[source]¶ 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.
Actions¶
-
class
horizon.workflows.
Action
(request, context, *args, **kwargs)[source]¶ 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’sForm
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 likeSelfHandlingForm
does now.
Action
classes may define the following attributes in aMeta
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.
-
handle
(request, context)[source]¶ Handles any requisite processing for this action. The method should return either
None
or a dictionary of data to be passed tocontribute()
.Returns
None
by default, effectively making it a no-op.
WorkflowView¶
-
class
horizon.workflows.
WorkflowView
[source]¶ A generic class-based view which handles the intricacies of workflow processing with minimal user configuration.
-
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_context_data
(**kwargs)[source]¶ 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
()[source]¶ Returns initial data for the workflow. Defaults to using the GET parameters to allow pre-seeding of the workflow context values.
-