Guide - JIRA workflow designer

Summary

JIRA's workflow designer JavaScript component renders an editable visual representation of a workflow in the browser. Users can add, edit, and remove statuses and transitions, inspect the workflow by panning and zooming, and position elements on the canvas. Changes are periodically saved to the server without prompting the user.
 
To edit a workflow, the user must be an administrator and have an active WebSudo session. If the user's WebSudo session expires an error message appears prompting them to refresh the page. The workflow designer also supports a read-only mode in which the workflow can be inspected but not modified — this requires the user to be a project administrator or have the view workflow permission.

Availability

The workflow designer component is available in JIRA 6.1 and above, it works in all supported browsers, except Internet Explorer 8, and on mobile devices.

Limitations

The workflow designer component has the following limitations:

  • it will not display an editable workflow designer in a dialog as JIRA doesn't support dialog stacking, and
  • prior to JIRA 6.2 it doesn't support creation of common transitions (though they are rendered correctly).

Usage

To use the workflow designer in your plugin you must add a dependency on one of the web resources listed in the table below. You can then create an instance of the JIRA.WorkflowDesigner.Application class, passing appropriate options for the desired behavior.

Web resource key Description
com.atlassian.jira.plugins.jira-workflow-designer:workflow-designer The full workflow designer, including resources related to modifying workflows (dialogs, etc.).
com.atlassian.jira.plugins.jira-workflow-designer:workflow-designer-read-only The resources required for a read-only workflow designer. Use this if you don't need to modify workflows as it results in a smaller page size.

Methods

Method Description
destroy() Destroy the workflow designer, removing it from the page. You must call this method when you no longer need the workflow designer; it stops periodically executing jobs, unbinds event handlers, and so on.

Options

Option Required Description Possible values Default
actions (error) Whether to show the actions bar (add/create status, etc.) boolean true
currentStepId (error) The step ID of the status that is to be highlighted as "current" number undefined
draft (error) Whether the draft version of the workflow should be loaded boolean false
element (tick) The element to show the workflow designer in element undefined
fullScreenButton (error) Whether the full screen button should be shown (providing actions is true) boolean true
immutable (error) Whether the workflow designer should be read-only boolean false
workflowId (tick) The ID of the workflow to load (its name as shown on the global workflows page) string undefined

Examples

Creating a read-only workflow designer

new JIRA.WorkflowDesigner.Application({
  element: AJS.$("#workflow-designer"),
  immutable: true,
  workflowId: "My Workflow"
});

Creating an editable workflow designer

new JIRA.WorkflowDesigner.Application({
  element: AJS.$("#workflow-designer"),
  workflowId: "My Workflow"
});

Showing a workflow designer in a dialog

Because it is not possible to display an editable workflow designer in a dialog (see above), the immutable option must be true. We must also ensure that the workflow designer is destroyed when the dialog is hidden.

function createDialogContent(callback) {
  callback([
    "<div class='aui-dialog-content'>",
      "<h2 class='dialog-title'>My Workflow</h2>",
      "<div class='form-body'></div>",
    "</div>"
  ].join(""));
}

function showWorkflowDesigner() {
  this._workflowDesigner = new JIRA.WorkflowDesigner.Application({
    actions: false,
    element: this.get$popup().find(".form-body"),
    immutable: true,
    workflowId: "My Workflow"
  });
 
  this._positionInCenter();
}
 
var dialog = new JIRA.FormDialog({
  content: createDialogContent,
  onContentRefresh: showWorkflowDesigner,
  widthClass: "large"
});

AJS.$(dialog).one("Dialog.hide", function () {
  this._workflowDesigner.destroy();
});
 
dialog.show();
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport