Guide - JIRA workflow designer


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.


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.


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).


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.


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.


Option Description

Whether to show the actions bar (add/create status, etc.)

Possible values: boolean.

Default: true.


The step ID of the status that is to be highlighted as "current".

Possible values: number.

Default: undefined.


Whether the draft version of the workflow should be loaded.

Possible values: boolean.

Default: false.


The element to show the workflow designer in.

Possible values: element.

Default: undefined.


Whether the full screen button should be shown (providing actions is true).

Possible values: boolean.

Default: true.


Whether the workflow designer should be read-only.

Possible values: boolean.

Default: false.


The ID of the workflow to load (its name as shown on the global workflows page).

Possible values: string.

Default: undefined.

*element and workdlowId options are required.


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 (Limitations), the immutable option must be true. We must also ensure that the workflow designer is destroyed when the dialog is hidden.

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

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

AJS.$(dialog).one("Dialog.hide", function () {
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport