Implementing the 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	Description
`actions`	Whether to show the actions bar (add/create status, etc.) Possible values: boolean. Default: true.
`currentStepId`	The step ID of the status that is to be highlighted as "current". Possible values: number. Default: undefined.
`draft`	Whether the draft version of the workflow should be loaded. Possible values: boolean. Default: false.
`element`	The element to show the workflow designer in. Possible values: element. Default: undefined.
`fullScreenButton`	Whether the full screen button should be shown (providing `actions` is `true`). Possible values: boolean. Default: true.
`immutable`	Whether the workflow designer should be read-only. Possible values: boolean. Default: false.
`workflowId`	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.

Examples

Creating a read-only workflow designer

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

Creating an editable workflow designer

1
2
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.

1
2
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();