JIRA 4.3 : How to create Custom Workflow Elements for JIRA 3
This page last changed on Feb 21, 2010 by andreask@atlassian.com.
OverviewJIRA 3 provides the ability to create fully customized workflows - giving the user full control over the life cycle of a JIRA issue. This powerful feature allows the workflow designer to specify:
This tutorial focuses on the Condition and Post Function elements of a workflow - with an example of creating a custom condition and post function, and how they are integrated with JIRA through the plugin system. The JIRA documentation contains further detailed information on workflows. Also, the following documents expand on working with the JIRA plugin system:
Plugin StructureIn order to make a custom workflow element (e.g condition, post-function) available within JIRA, it is necessary to create a workflow plugin module. As with all plugin modules, the workflow plugin will consist of the following components:
all contained within a single JAR file. Each element is further discussed in the examples below. Jira Plugin Development KitThe full source for each example is available in the JIRA Plugin Development Kit. Using the JIRA Plugin Development Kit, it is possible to navigate to the workflow example directory and build the workflow example JAR file with the command: maven jar The resulting JAR file contains all the workflow examples discussed here. The workflow example plugin becomes available once the JAR file is copied to the JIRA lib directory. Workflow ConditionsA Condition restricts the execution of a workflow transition until certain criteria are met. If the Condition fails, the transition link will not be available on the 'View Issue' page. This section of the tutorial focuses on the Condition element and provides an example custom Condition which can be plugged into JIRA. JIRA 3 System ConditionsJIRA 3 provides a number of system conditions available on setup - DisallowIfInStepCondition, AllowOnlyAssignee, IssueAssignedCondition, etc - each allowing the user to define when a worklfow transition becomes available. The SubTaskBlockingCondition (another system condition) determines if a transition is available for an issue based on the status of its associated sub-tasks. The user specifies a list of statuses that will permit the transition to be available. For example, the 'Close Issue' workflow transition link for an issue can be conditioned to be only available if all related sub-tasks are associated with the 'Closed' status. In effect, this transition link is not available for the parent issue until all sub-tasks are closed. Custom Workflow ConditionsFor developers designing a custom workflow condition, we recommend that the custom condition class extend the JIRA AbstractJiraCondition class. In order to avoid multiple database calls to retrieve the original issue object for the condition check, there are two possibilities available to the condition designer. Firstly, the custom condition class can overwrite the following method: Issue getIssue(Map transientVars) Alternatively, if the getIssue method is not overwriten, it is possible to pass the original issue object to the transientVars map, for example: GenericValue origianlIssueGV = ComponentManager.getInstance().getIssueManager().getIssue(issue.getId()); fields.put(AbstractJiraCondition.ORIGNAL_ISSUE_KEY, IssueImpl.getIssueObject(origianlIssueGV)); This ensures that the original issue is examined during the condition check and minimal database calls are made. Example - Parent Issue Blocking ConditionThis example provides the reverse condition of the SubTaskBlockingFunction - in that it determines if a transition is available for a sub-task based on the status of its associated parent issue. In this example, the condition has been configured to display the workflow transition 'Reopen' for a sub-task, only if the parent issue is associated with an unresolved status (e.g. 'Open', 'In Progress' , Unresolved'). The condition is applied to the 'Reopen' transition in a copy of the default JIRA workflow associated with the 'Sub-Task' issue type. In effect, the condition will prevent the transition for any sub-task from the 'Closed' to the 'Reopened' status, if the parent issue is not associated with an unresolved status. Condition LogicThe condition logic is contained in the class ParentIssueBlockingCondition class that implements the interface Condition. The only method requiring implementation is the passesCondition(...) method. Within this example, this method retrieves the parent issue and then determines if its associated status is contained in the user specified list of statuses. The condition passes if the specified list of statuses contains the status associated with the parent issue. The list of statuses is specified when adding the workflow condition to a transition. The class WorkflowParentIssueBlockingConditionFactoryImpl is also included - this class manages passing the required parameters to the resource templates. Condition ResourcesThe workflow condition requires a number of resources in order to display the input, edit and view screens. In this example, a velocity template is provided for each screen:
allowing the user to initially specify the statuses which will result in a 'pass', to edit these statuses and also a screen displaying the selected statuses. Plugin DescriptorAs with all plugins, the workflow condition must be defined in a file named atlassian-plugin.xml and be located in the root of the JAR file. The definition of the ParentIssueBlockingCondition condition is as follows: <atlassian-plugin key="com.atlassian.jira.plugin.workflow.example" name="Workflow Examples Plugin"> <plugin-info> <description>Example JIRA Workflow Elements</description> <version>1.0</version> <application-version min="3.0" max="3.0"/> <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com"/> </plugin-info> <workflow-condition key="issueblocking-condition" name="Parent Issue Blocking Condition" class="com.atlassian.jira.plugin.workflow.example.WorkflowParentIssueBlockingConditionFactoryImpl"> <description>Condition to block sub-task issue transition depending on parent issue status.</description> <condition-class> com.atlassian.jira.plugin.workflow.example.condition.ParentIssueBlockingCondition</condition-class> <resource type="velocity" name="view" location="templates/issueblockingcondition/issueblocking-condition-view.vm"/> <resource type="velocity" name="input-parameters" location="templates/issueblockingcondition/issueblocking-condition-input-params.vm"/> <resource type="velocity" name="edit-parameters" location="templates/issueblockingcondition/issueblocking-condition-edit-params.vm"/> </workflow-condition> </atlassian-plugin> The class containing the condition logic, ParentIssueBlockingCondition, is specified next in the <condition-class> tag. Finally, the location of the resource templates are specified - with an individual template for input, edit and view screens. Parent Issue Blocking Condition - In ActionOnce the workflow example JAR file has been placed in the JIRA lib directory, the Parent Issue Blocking Condition is now available as a condition within the workflow editor. Workflow Post FunctionsA Post Function executes specifed actions immediately after a transition is executed (hence the name post-function). Example possible actions include updating issue fields, generating change history, adding a comment, generating an event that signals that an issue has been progressed through workflow, etc. This section of the tutorial focuses on the Post Function element and provides an example Post Function which can be plugged into JIRA. JIRA 3 System Post FunctionsJIRA 3 provides a number of system post functions available on setup - UpdateIssueStatusFunction, CreateCommentFunction, etc - each allowing the user to specify that certain actions should be executed following a specific workflow transition. Note: Certain JIRA system post functions cannot be edited, deleted or ordered, as they must be executed during every transition. These post functions are essential for JIRA's issue life cycle, and would compromise other functionality if not executed. Example - Close Parent Issue Post FunctionThis example post function will close the parent issue once the final sub-task is closed (all other associated sub-tasks are already closed). The post function will ensure that the parent issue is still open and that all other associated sub-tasks are also closed before attempting to close the parent issue. The post function can be applied to the 'Close Issue' transition in a copy of the default JIRA workflow associcated with the 'Sub-Task' issue type. Post Function LogicThe post function logic is contained in the class CloseParentIssueFunction class that implements the interface FunctionProvider. The execute method retrieves the sub-task from the parameters. From this, the parent issue is determined and a check is made as to whether the parent issue is closed or not. If the parent issue is not closed, the statuses of the rest of the associated sub-tasks are also checked. If all sub-tasks are closed, the parent issue can be closed. This function does not require any input or configuration - the action to be executed is defined within the post function logic. The only user input required is to associate the post function with a particular transition within a workflow. Post Function ResourcesThis post function only requires a view template as there is no configuration or editing required. The velocity template is provided for the view screen:
Plugin DescriptorAs with all plugins, the post function condition must be defined in a file named atlassian-plugin.xml and be located in the root of the JAR file. The definition of the CloseParentIssueFunction condition is as follows: ... <workflow-function key="closeparentissue-function" name="Close Parent Issue Function" class="com.atlassian.jira.plugin.workflow.WorkflowNoInputPluginFactory"> <description>Closes the parent issue on closing final associated sub-task (all other sub-tasks are closed).</description> <function-class> com.atlassian.jira.plugin.workflow.example.function.CloseParentIssueFunction</function-class> <orderable>true</orderable> <unique>true</unique> <deletable>true</deletable> <default>true</default> <resource type="velocity" name="view" location="templates/closeparentfunction/closeparentissue-function-view.vm"/> </workflow-function> ... The post function entry specifies the key, name and the Post Function Factory for this condition. The factory class provides methods for passing parameters to the view templates - in this case, no parameter passing is required. The post function description is also specified. The class containing the post function logic, CloseParentIssueFunction, is specified next in the <function-class> tag. It is also possible to configure the post function as it appears in the workflow editor. The following options can be specified:
It is also possible to specify a weight configuration parameter - however this is mainly intended for JIRA system post function elements. This parameter is used in conjunction with the default parameter - if the post function is to be added to all new transitions, the weight parameter is used to determine the post function position within the post function list. Finally, the location of the resource view template is specified. Close Parent Issue Post Function - In ActionOnce the workflow example JAR file has been placed in the JIRA lib directory, the Close Parent Issue Post Function is now available as a post function within the workflow editor. |
![]() |
Document generated by Confluence on Mar 27, 2011 18:54 |