** An Atlassian Gold Partner **
Transition Manager for Jira Cloud
Sub Tasks, Epic Issues, and Linked Issues are a common method for breaking up the work involved in a Jira Issue. Transition Manager makes the creation of these issues a lot easier.
Transition Manager can also update an issue or transition-related issues (i.e. linked issues). All of these features can be can save considerable time when automated.
Templates are created that can be used to create multiple Sub Tasks / Epic Issues / Linked Issues or update an issue. An Executor is added to indicate when during a workflow transition you wish to create/update.transition issue(s). Optional conditions can be provided to narrow down the number of applicable issues. Executors can also be added to transition-related issues when the current issue is transitioned.
The optional conditions allow you to specify expected field values for various fields, including custom fields. Conditions can also test who the current user is.
Important: The fields that can be used to create an Issue (in a template) and the fields that can be copied from the parent are limited to those that appear on the Create Issue screen for a project (Project Administration -> Screens -> Create Issue). If, for example, the due date is not in the Create Issues screen then it will not appear as an entry field, as a show field checkbox or as a "copy from parent" checkbox. If you use due date in a global template that is run against a project that does not have due date on the create screen then an error will occur.
Warning: Creating issues during transitions in the workflow is incredibly powerful. You need to be careful that you don't set up loops.
New Features:
-
Cascading Templates allow you to create templates in sequence. Choose the advanced feature set and at the bottom of the template, you can select one or more templates to create after this one.
-
You can now create templates that are just for a project.
-
You can use the getting started page (Admin -> Apps -> Transition Manager -> Getting Started) to create examples of templates and executors
-
Able to automatically transition parent issues when the first/last child changes to a new status.
-
Executors to easily automate issue creation/updating/transition
-
Repeating Templates. Repeat each row/issue in a template for every component/version.
-
Who and when a template was changed is now audited and can be viewed in the admin section
-
In the Reporter and Assignee fields you can now enter ${Reporter} or ${Assignee} to specify the reporter or assignee from the parent (when creating a new issue) or from the current issue (when updating)
Sections:
Defining Templates - Project and Global
This section deals with the creation of templates that can be used in workflow transitions (through Executors). There are two pages for creating templates. The first is TM Global Templates for templates that can be used in every project and the menu item can be found dashboard page. All system admins have access to this page and other users can be given access through the Configuration screen (see below).
At the top right of the tab is a + button that can be used for adding new Create Issue templates. Under this, you can see three templates. To the right of the template name are icons for editing, duplicating and deleting the template. Clicking the edit icon will open the dialog shown below.
Each template has a name that will help identify the Sub Tasks etc that belong with it, a list of fields to show (Show Fields) and a list of fields to copy from the parent.
Mode
At the top right of the dialog is the Mode selector. This has three options: Basic, Advanced and Advanced Static. Basic mode gives you the features shown above. Advanced mode has the basic feature plus for every template line (which defines an issue) there is also a "Show Fields" selection. This allows you to show or hide fields on a per line basis. These options are only visible if you hover over the line with the mouse.
Advanced Static mode has the same feature as Advanced but the extra Show Fields options are always displayed, not just when you hover over it
Show Fields
These checkboxes define which fields should be shown below in the Sub Task list (the area under the Show Fields line and above the text "NOTE: Fields....). You can have as many or as few fields as you like. There is a More select box that allows you to show additional fields like Components, Custom Field (five different instances), Label and Original Estimate.
Sub Task / Epic Issue / Linked Issue List
The Sub Task list is a list of all Sub Tasks that would be created for a template. The example above has three but you are free to define any number you like as long as you have at least one. Occurrences of question marks in a circle are help for the field to the left of the question mark. Hovering over this will give you helpful information about the field.
The following fields are available in the Sub Task list:
-
Summary: the summary of the Issue. You can refer to parent fields here by using one of: ${Summary}, ${Description}, ${Type}, ${Assignee}, ${Reporter}, ${Priority}, ${DueDate}1 , ${CreatedDate}2, ${UpdatedDate}2 or to a custom field, i.e. ${My Custom Field Name}. If no value is present then the word null show unless an ! is placed after the $ symbol (i.e. $!{Description} will show the description if it is present otherwise it will show nothing). Field references are case sensitive. If this is a Repeating Template (see below) then you can refer to the repeated field value by using ${RepeatItem}
-
Assignee: The user that the issue will be assigned to. You can also refer to the parent issues reporter or assignee by entering ${Reporter} or ${Assignee} respectively.
-
Component: The component(s) that the issue should have
-
Description: a description of the Issue. You can also refer to the same fields as defined for the Summary
-
Due Date: either the word today (for day the Sub Task is created), a date (in the format YYYY-MM-DD) or the number of days, weeks and months from the day the Sub Task is created (i.e. 1m 2w 3d for one month, two weeks and three days, 2d for two days ...)
-
Original Estimate: the number of minutes, hours, days and weeks (i.e. 3d 4h, 1w 10m ....)
- Fix Versions: The fix versions for the issue
- Issue Type: Defined the issue type for this issue
- Labels: Any labels you wish to add
-
Priority: one of the pre-defined priorities for an Issue
-
Reporter: start typing the user's name and a selection of matching names will appear. You can also refer to the parent issues reporter or assignee by entering ${Reporter} or ${Assignee} respectively.
-
Custom Field: you can specify any custom field (up to five total) of type single-line text, multi-line text, number, and single select item. The value for that selected field can be specified.
-
Project Key: The key of the project this issue belongs to (can't be used for sub tasks)
1. DueDate is shown in the format 2018-09-28 but can also be shown in different formats by appending _dmy (i.e. ${DueDate_dmy}) mdy to be displayed as 28-09-2018 and 28-09-2018 respectively
2. CreatedDate is shown in the format 2018-10-19 but can also be shown in different formats like: ${CreatedTime} = 13:15, ${CreatedTime_12} = 01:15 PM, ${CreatedDate_dmy} = 19-10-2018, ${CreatedDate_mdy} = 10-19-2018,.
When you first create a template and add a Sub Task you only have the Summary showing. Clicking on the "Show Fields" checkboxes will show that field for all existing Sub Tasks and any Sub Tasks added in the future. You can also (in advanced mode) add fields for a particular Sub Task by hovering over the Sub Task row and clicking on one or more of checkboxes that show.
The fields that are showing don't necessarily have to have values in them. In the example above there are fields that are visible but empty. These fields just won't be set when the issue is created.
Copy From Parent
These checkboxes signify that the values (for the fields they represent) should be copied from the parent Issue to the Sub Task issues. For the example above the Affected Versions, Assignee, Component, Description, Due Date, Environment, Fix Version, Labels, Original Estimate, Priority and Reporter attributes are copied from the parent Issue to all of the Sub Tasks. There can also be a list of custom fields (these also have to be in the Create Issue screen) that can be copied from the parent Issue. The only time these fields will NOT be copied is if the value of the field is set for the Sub Task in the Sub Task list.
Repeating Template
This section allows you to repeat the template creation based on the selected field (Components or Fix Versions). So if your template has two rows (two issues to create) and you specify that you want it repeated for Components then two issues will be created for each component that the issue has (i.e. if the template has three issues and there are two components then a total of six issues will be created).
If "Set Repeating fields value in Issue" is checked then the current field value being iterated over will be set in the issue created (i.e. if the template has one issue definition, a repeating field of Fix Versions (V1 and V2) and the parent issue has two fix versions then two issues will be created where the first issue has a Fix version of V1 and the second of V2).
NOTE: The fields that are displayed and the fields that can be copied from the parent are dependant on having been setup for the Create Issue screen in the project (Project Administration -> Screens -> Create Issue). If, for example, the due date is not in the Create Issues screen then it will not appear as an entry field, as a show field checkbox or as a copy from parent checkbox.
Templates To Create (for Linked and Unconnected Issues ONLY)
This feature will only work if it is used when creating Linked or Unconnected Issues from an Executor. The feature allows you to create any templates selected in this section after this template has been created. The templates selected will be created for every issue created using this template.
Update Issue
Update Issue templates can be used to update an issue at various transitions of the workflow. The templates are accessed through the "Update Issue Templates" tab of the Transition Templates screen.
This tab looks and behaves the same as the "Create Issue Templates" tab. Adding a new template or clicking on edit will show the dialog below.
This dialog is similar to the Create Issue Template dialog except that you can only define the details for just one issue and there is no copy from parent fields. For setting of fields, you can also add watchers or a comment to the issue. Click on any of the Show Fields radio buttons to show the fields.
Because these templates are separate from the Executor setup you can modify them without editing the Executor. For the example above you could make it that when the issue has the testing completed it automatically set the fix version and adds the release lead as a watcher. When that version has been released the template can be edited to have the new fix version.
Please refer to the Create Issue section for details on the individual fields.
There are two types of templates: Create Issue, Update Issue and Transition.
Create Issue
Create Issue template can be used to create sub-tasks, Epic issues or linked issues. For this section whenever sub-tasks are mentioned the same will also apply for Epic Issues and linked issues. Templates are generic (can be used for sub-task, Epic issues or linked issues) so when creating a template you do not need to specify what the template will be used for. It is possible to use a single template for the creation of all three types.
The image below shows the "Create Issue Templates" tab in the Transition Templates screen.
The second is the project TM Templates pages. There is one of these pages on every project and any templates defined here can be used only for the project they are in. The menu item for this is found by going to the project page, Add-ons and then TM Templates.
Project Executors - Automatic template creation
To automatically create bulk Sub Tasks, create Linked Issues, create Epic Issues or update the current issue you need to create an Executor. The Executor screen is available as a Project tab (go to the project -> Add-ons -> TM Executors) The image below show the screen where executors can be added and edited.
Executors (when enabled) will create/update issues automatically, based on the specified template and criteria. To stop an Executor from running just edit it and unclick the Enabled checkbox.
Once an Executor has been defined it can be edited (pencil icon), duplicated (copy icon) or deleted (trash can icon).
New Executors can be added by clicking on the add button (plus icon, top right-hand corner) and this will open the dialog below.
At the top of the dialog (on the header bar) is the Feature Level. This allows you to have different levels of functionality for the Executor. There are two options: Lite and Basic. The difference between these is that the basic feature level adds the option to guarantee the order when creating issues and it also adds a new Executor type of Transition Parent. Both of these are discussed below.
Next, we have the name of the Executor. This should descriptive enough to understand what is does. Under this is the enabled checkbox which allows you to enable/disable an Executor.
Transition Details
In the Transition Details section allows you to specify if the Executor will be executed when an Issue is created or transitioned. If you select "On Transition" then you need to specify which transition you are interested in. You must select a To Status and optionally a From Status. The status is the text that is displayed for the Status fields within an Issue. Start typing to get the list of allowable Statuses.
For the above example, the Executor will only work when you are transitioning from any status to the In Progress status. The "From
Status" is an optional field that can be used to narrow down the paths that this Executor will be called for. If you specified "To Do" for
from From Status then only a transition from the To Do status to In Progress would execute this Executioner.
Executor Details
In the Executor Details section, you get to specify whether you want to create, update or transition issues.
Below is the Executor Details section for creating Epic Issues, Linked Issues, and Sub Tasks.
All of the above sections have a template (from the TM Templates page) and a default issue type. The template is the description of what will be created and the default issue type specifies the issue type to use when creating issues (unless specified in the template).
Creating linked issues also has a Link Type field to specify what type of link will be between the parent and the newly created issues.
Transitions
Transitioning Child Issues
Rules:
-
Issues in the same project can only be transitioned to the same status as the parent issue is going to. This is a safety mechanism to stop recursive transitions from going out of control.
-
If there is a "from status" then the issue will ONLY be transitioned if it currently has the "from status".
-
An issue will be transitioned ONLY IF the "to status" is one transition away
For Transitions, there are three variations that can be used to set up an Executor. The simplest is for transitioning issues to the same status as the parent issue (issues can be in any project). You select the child type (subtask or linked issue), and which of the child issues you want to transition (for linked issues you say which link types you want and for subtask you specify which issue types). The Transition To field is left as the "Same Status". The example below will transition all linked issues of the type "relates to" to the same status as the parent issue, but only if this can be done with a single transition.
The next type of transition is when you want to transition related issues from one status to another regardless of what status the parent has. As you can see below we are the same fields as above (see above for an explanation of those fields) plus three more. The first, Status Set To, is left at One Status. We then have the Child From Status and Child To Status fields. They specify what status the child issues must start on (this is optional) and what status they will be transitioned to. The example below will transition "relates to" linked issues to In Progress regardless of their initial status but only if In Progress can be transitioned to directly from the issues current status.
The next type of transition is the most complicated one and also the most powerful. We have the fields above (Child from and to status is now default from and to status) and we also have the ability to specify from and to statuses for individual projects. For the example below "relates to" issues in the TM2 project will transition In Progress only if the issue has a status of To Do, issues in the current project will transition to the same status as the parent and all other issues will transition to In Progress.
Transitioning Parent/Related Issues
If you have a feature level of Basic you will also have an executor type of "Transition Parent/Related". This can be used in three different scenarios where you have a parent/related issue with either epic issues, subtasks or linked issues. You can transition the parent in two ways: when the first child is transitioned or when the last child is transitioned.
For the first option, when the first child issue is transitioned to a new status then the parent issue is also transitioned. For example, you have a parent issue A with two subtasks B and C, all are on the status To do. When the first child (either B or C) is transitioned to In Progress then issue A is automatically transitioned to In Progress.
The screenshot below shows an example of scenario one when the children are sub tasks.
For the example above the Executor is designed to run when the children are subtasks and you want the parent to go to the same status as the transitioned child.
For the second option is for when the parent is transitioned after the last child is transitioned. For example, you have a parent issue A and two linked issues B and C (on the same link type), issues A and C are on status To do and B is on the status In Progress. When issue C is transitioned to In Progress then issue A will be automatically transitioned to Done.
The screenshot below shows the settings to accomplish this.
Update Issues
Updating an issue is the simplest of all of the Executors. As shown below you just need to specify the template you want to use to update the issue.
For the example above the Executor is designed to run when the last child (linked from the parent by "is duplicated by") is transitioned. When this occurs the parent is transitioned to Done.
Lastly, we have an example of transitioning a parent/related issue when connected as an Epic issue.
Processing
If the feature level for an Executor is set to Basic then there will be a Processing section that allows you to specify that you want all children created to be in the same order as the template. This only really makes a difference if you are creating more than 34 issues, that is the current batch size for creating issues. If the batch size is over 34 then this will slow down processing since the batches are created sequentially rather than asynchronously.
For the example above the Executor is designed run when the last child (an Epic issue) is transitioned. When this occurs the parent can be transitioned to one of two statuses. If the Epic is in the TEST project then the parent is transitioned to Done, otherwise it is transitioned to In Progress.
Conditions
Conditions allow you to refine when an Executor will be run. Below is an example of conditions on a project.
You can specify any number of conditions and they are anded together. So the example above would be the components includes FIR Executor AND the issue type is Bug AND the current user is Paul Clark. If any of these are false then the Executor won't run.
Field Value gives you the most common Issue fields and custom fields of type number, string, user, label and select list.
Global Executors - Automatic template creation
Global Executors are very similar to Project Executors. The only difference is that you have to enter one or more projects that the executor will apply to. See Project Executors, above, for the general usage of an Executor.
The screenshot below shows what a Global Executor looks like. Note the "For Projects" field below "Enabled" that allows for the entry of the projects that the executor will run for.
Workflow - Automatic issue creation
Post functions are deprecated, please do not use them. Use Executors for all creation/updating and transitioning of issues. Post Function will only be available to legacy users. If you need to see the documentation please go to this link.
Automatic issue creation - In Action
When an Issue completes a transition that creates/updates/transitions sub tasks / linked issues / Epic issues through an Executor or workflow post function a message box is displayed to inform the user that processing is occurring in the background.
Transition Manager will keep checking in the background (for a maximum of a minute) to see when the issues are created/updated/transtioned. When they have the parent Issue is refreshed to display the changes and a message is displayed to show that they have been created.
If an error occurs during the creation process then an alert dialog will be displayed telling the user what happened.
As well as being displayed in the popup dialog all workflow errors are also available in a project administration (see below).
Permissions Error: If you get errors saying that the user does not have permission to view or edit an Epic then you will need to give edit and viewing permission of the plugin's user (addon_com.redmoon.transitionmanager.jira).
Automatic issue creation - Errors
Any errors that occur during the creation, updating or transitioning of Issues can be viewed under the "TM Errors" tab in a projects administration screen. Details are kept for up to two weeks after the error occurs (at which time they are deleted).
Automatic issue Creation - Audit
Each time a transition related to a Transition Manager Executor (or post function) occurs an audit record is created. These audit records are displayed in the TM Audit screen under a projects admin section.
On this page you can see:
-
What Executors have run
-
Number of issues created, updated or skipped
-
See the number of errors and error messages.
-
Start time and how long it took
-
The template that was used
-
The issue key the transition happened on
-
What transition happened (by hovering over the row)
-
Whether the Executors condition passed or failed (by hovering over the row)
If you hover over a row and click on the ... button more details are shown about the audited call.
Configuration
Change Log
The change log page allows you to audit changes that have been done to templates in the last three months. The example below shows seven templates of which two have audit data. The audit data also includes deleted templates.
Note: Audit data is only collected from the date this release was installed.
Creating Template
The configuration page allows you to define who, apart from system admins, has access to the template screen. You can specify one or more user groups. If a user is in at least one of those groups then they will have access to the template screen.
Language Support
NOTE: Translations apply to all text EXCEPT the menu text, tab text, and panel heading text.
The Langauge Support section allows you to choose a language to use This plugin comes with two languages pre-installed.
