Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Workflow modules

Purpose of this Module Type

The workflow plugin modules allow you to add new capabilities to JIRA's workflow engine.

JIRA uses OSWorkflow as its workflow engine. The web-based workflow editor has a number of plugin modules which allow you to build workflows more easily.

The modules are:

Condition Configuration - check whether or not a given workflow transition can be executed by a given user
Function Configuration - perform actions after a workflow transition has been executed
Validator Configuration - check that the data given to a workflow transition is valid

Condition Configuration

The root element for the workflow condition plugin module is workflow-condition. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the workflow condition, which must implement com.atlassian.jira.plugin.workflow.WorkflowPluginConditionFactory. This class is used to provide context for the rendered Velocity templates that supply the condition's views. Required: - Defaut: -
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. I.e. the identifier of the workflow condition. Required: yes Defaut: N/A
i18n-name-key	The localisation key for the human-readable name of the plugin module. Required: - Defaut: -
name	The human-readable name of the plugin module. I.e. the human-readable name of the workflow condition. Required: - Defaut: The plugin key.

Elements

Name	Description
description	A human-readable description of this workflow condition module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system. Required: -
condition-class	Determines whether the user is allowed to perform this workflow transition. Must implement the OSWorkflow class com.opensymphony.workflow.Condition, but JIRA extensions are strongly recommended to extend com.atlassian.jira.workflow.condition.AbstractJiraCondition; this implementation provides efficient access to the Issue object. Required: yes
resource type="velocity"	Used to render the views for the condition. The template contexts are populated by the `workflow-condition`'s `class`. Required: -

Name

Description

description

A human-readable description of this workflow condition module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.

Required: -

condition-class

Determines whether the user is allowed to perform this workflow transition. Must implement the OSWorkflow class com.opensymphony.workflow.Condition, but JIRA extensions are strongly recommended to extend com.atlassian.jira.workflow.condition.AbstractJiraCondition; this implementation provides efficient access to the Issue object.

Required: yes

resource type="velocity"

Used to render the views for the condition. The template contexts are populated by the workflow-condition's class.

Required: -

Example

The following condition prohibits all users other than the issue assignee from performing transitions on any given issue. The following code should be placed in atlassian-plugin.xml.

1
2
<workflow-condition key="onlyassignee-condition" name="Only Assignee Condition"
    i18n-name-key="admin.workflow.condition.onlyassignee.display.name"
    class="com.atlassian.jira.plugin.workflow.WorkflowAllowOnlyAssigneeConditionFactoryImpl">

    <description key="admin.workflow.condition.onlyassignee">Condition to allow only the assignee to execute a transition.</description>

    <condition-class>com.atlassian.jira.workflow.condition.AllowOnlyAssignee</condition-class>

    <resource type="velocity" name="view"
        location="templates/jira/workflow/com/atlassian/jira/plugin/onlyassignee-condition-view.vm"/>
</workflow-condition>

Function Configuration

Workflow functions always execute after the workflow transition is executed; they might be more properly named _post-_workflow functions.

The root element for the workflow function plugin module is workflow-function. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the workflow function. Functions that don't require input should use com.atlassian.jira.plugin.workflow.WorkflowNoInputPluginFactory; those that do must implement com.atlassian.jira.plugin.workflow.WorkflowPluginFunctionFactory. Required: - Defaut: -
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. I.e. the identifier of the workflow function. Required: yes Defaut: N/A
i18n-name-key	The localisation key for the human-readable name of the plugin module. Required: - Defaut: -
name	The human-readable name of the plugin module. I.e. the human-readable name of the workflow function. Required: - Defaut: The plugin key.

Elements

Name	Description
description	A human-readable description of this workflow function module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system. Required: -
function-class	Class that implements the function's logic. Must extend com.atlassian.jira.workflow.function.issue.AbstractJiraFunctionProvider. Required: yes
resource type="velocity"	Used to render the views for the function. Required: -
orderable	(true/false) Specifies if this function can be re-ordered within the list of functions associated with a transition. The postion within the list determines when the function actually executes. Required: -
unique	(true/false) Specifies if this function is unique; i.e., if it is possible to add multiple instances of this post function on a single transition. Required: -
deletable	(true/false) Specifies if this function can be removed from a transition. Required: -
addable	Valid values are the `ACTION_TYPE` constants of the com.atlassian.jira.workflow.JiraWorkflow; multiple values can be specified through comma-delineation. Required: -
JIRA:weight	An integer value indicating where this function should be called if it is default (see below). Required: -
JIRA:default	(true/false) Specifies if this function should be applied to all workflows. Required: -

Example

1
2
<workflow-function key="update-issue-field-function" name="Update Issue Field"
    class="com.atlassian.jira.plugin.workflow.UpdateIssueFieldFunctionPluginFactory">
    <description>Updates a simple issue field to a given value.</description>

    <function-class>
        com.atlassian.jira.workflow.function.issue.UpdateIssueFieldFunction
    </function-class>

    <orderable>true</orderable>
    <unique>false</unique>
    <deletable>true</deletable>

    <resource type="velocity" name="view"
        location="templates/jira/.../update-issue-field-function-view.vm"/>
    <resource type="velocity" name="input-parameters"
        location="templates/jira/.../update-issue-field-function-input-params.vm"/>
</workflow-function>

Validator Configuration

The root element for the workflow validator plugin module is workflow-validator. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the workflow validator, which must implement com.atlassian.jira.plugin.workflow.WorkflowPluginValidatorFactory. This class is used to provide context for the rendered Velocity templates that supply the validator's views. Required: - Defaut: -
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. I.e. the identifier of the workflow validator. Required: yes Defaut: N/A
i18n-name-key	The localisation key for the human-readable name of the plugin module. Required: - Defaut: -
name	The human-readable name of the plugin module. I.e. the human-readable name of the workflow validator. Required: - Defaut: The plugin key.

Elements

Name	Description
description	A human-readable description of this workflow validator module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system. Required: -
validator-class	Class that performs the validation logic. Must implement `com.opensymphony.workflow.Validator`. Required: yes
resource type="velocity"	Used to render the views for the validator. Required: -

Name

Description

description

A human-readable description of this workflow validator module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.

Required: -

validator-class

Class that performs the validation logic. Must implement com.opensymphony.workflow.Validator.

Required: yes

resource type="velocity"

Used to render the views for the validator.

Required: -

Example

1
2
<workflow-validator key="permission-validator" name="Permission Validator"
    class="com.atlassian.jira.plugin.workflow.WorkflowPermissionValidatorPluginFactory">
    <description>Validates that the user has a permission.</description>

    <validator-class>
        com.atlassian.jira.workflow.validator.PermissionValidator
    </validator-class>

    <resource type="velocity" name="view"
        location="templates/jira/.../permission-validator-view.vm"/>
    <resource type="velocity" name="input-parameters"
        location="templates/jira/.../permission-validator-input-params.vm"/>
</workflow-validator>

Notes

The weight and default parameters for workflow functions should not be used by plugin authors and should be considered reserved for JIRA's use.

For more details, see Tutorial - How to create custom workflow elements for JIRA 3.x.