** An Atlassian Gold Partner **
STM for Jira Data Center
Sub Tasks, Linked issue, and Epic Issues are a common method for breaking up the work involved in a JIRA Issue. STM
Templates can either be created for a specific project or globally (for all projects or a set of projects). These can then be used to create multiple Sub Tasks / Linked Issues / Epic Issues either manually or automatically (on Issue creation or a transition to another status)
Important: The fields that are displayed and the fields that can be copied from the parent are dependent on having been set up for the Create Issue screen in the project (Project Administration -> Screens -> Create Issue). If, for example, the due date is not in the Projects create screen then it will not appear as an entry field in the Create Issue view or as a copy from parent checkbox.
Warning: Creating issues during transitions or the creation of other Issues is a powerful feature. You need to be careful that you don't set up loops (Issue A's creation causes Issue B to be created which causes Issue C to be created...).
New Features:
-
New Wizard user interface to make creating a template simpler.
-
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.
-
Global Executors to create issues automatically for one or more projects
Sections:
Defining Templates for creating Issues
For this section, the details apply to creating sub-tasks, Epic Issues, linked Issues and unconnected Issues (Issues with no relationship to the parent).
Templates for creating Issues are defined either globally for an individual project.
Project Templates
You can define Templates, for creating Issues, for each Project. The Project Templates screen is available as a Project tab and can be accessed by Project Admins only or those users defined in the Project Template Access group list in the configuration screen. You can get to the page by going to the general Project pages and then clicking on the T icon with the letters STM above it.
The image below shows the page where templates can be added and edited
Once a template has been defined you can hover over it to see the icons. You can sort the Issues in the template by using the up/down arrow icon, edit it using the pencil icon, duplicate it by using the copy icon or delete it using the trash can icon.
New templates can be added by clicking on the Add button (the plus icon in the top right-hand corner) and this will open the create page shown below.
Details Section
The details section of the template has a name that will help identify the issues to create that belong to it, an "Add current user as watcher" checkbox to add the current user as a watcher for every issue created and optional documentation fields. Clicking on the "Show more documentation options" link will show the description and documentation link fields.
Create Issues Section
This section allows you to select fields that you want copied from the parent issue. You can select as many fields as you want. For the example above just the Fix versions and Labels fields will be copied from the parent Issue to all of the newly created issues. The fields to copy also include a list of custom fields.
The only time any of these fields will NOT be copied is if the field's value is set in the Create Issues section that is being created.
Cascade Template
The Cascade Template section allows you to create other templates (and their issues) for each of the issues being created in this template. This functionality is only available for creating linked and unconnected issues because the cascaded template has the same relationship (linked or unconnected) as the parent template.
For example, if you have two templates, A and B. Template A will create two issues with the summaries Development and Testing. Template B will create a single issue with a summary Security Check. If template A has a cascade template of B then if template A is created as linked issues then each of those linked issues (Development and Testing) will also have new linked issue from template B (Security Check). So a total of four issues are created.
Repeat 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 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 there are no components then no 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).
Global Create Issue Templates
Global templates are templates that can be used in any project. The global template page can be navigated to through the menu at the topmost Jira menu (click on the Jira symbol in the top left of the screen) and clicking on the STM Global Templates option.
Clicking on the Global Template menu item will navigate you to the following page.
Adding a new Template will show the page below. This is almost identical to the project template dialog except for the "Show in Issues for Bulk Create pages" checkbox. If this is checked then the template will be shown when creating bulk sub tasks, linked issues, unconnected issues or Epic issues. Either way, global templates are always available for creating as part of an executor (see below).
Apart from the addition of the checkbox, all functionality is identical except that select dialogs such as issue types, priorities, etc will show every possible value from all Projects. This is because global templates are not associated with a particular project and hence cannot show a subset of these lists.
Because these lists show all possible selections, the template that is created may cause an error. This is because the item has a valid value but not for the current Project. If it is used in the correct Project then it will work.
There is a Create Issue section for every issue the template needs to create. The examples above have two different issues to create 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 these will give you helpful information about the field.
The following fields are available in the Create Issue sections:
-
Summary: the summary of the Issue. You can refer to parent fields here by using one of: ${Summary}, ${Description}, ${Type}, ${Assignee}, ${Reporter}, ${Priority} 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.
-
Components: 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 (i.e. ${Reporter} etc)
-
Due Date: either the word today (for the day the Issue is created), a date (in the format YYYY-MM-DD) or the number of days, weeks and months (in this order) from the day the Issue 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 (is this order i.e. 3d 4h, 1w 10m ....), a percentage of the parent's original estimate (20%) or as a multiplier of the parent estimate (*0.25)
-
Fix Versions: The fix versions for this issue.
-
Issue Type: Tthe issue type that the newly created Issue will have
-
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 Fields: you can specify any custom field (up to five total) of type single-line text, multi-line text, number, and single select item, multi-item select, URL. 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 subtasks).
-
Add Watcher: Adds the specified users to the as watchers of the Issue created
-
Add Comment: Adds a comment to the issue created
You can add more fields to set by selecting them from the "Fields to display" dropdown menu. You can also remove fields by clicking the X next to their name. The fields in each Create Issue section can be different for each Create Issue.
The fields that are showing don't necessarily have to have values in them. In the example above the second-row description and assignee fields are visible but empty. This allows the user, using the template to manually create bulk Issues, to easily enter those fields without having to select them.
Copy From Parent
Defining Templates for Updating Issues
For this section, the details apply to updating Issues. Templates for updating Issues are defined either globally for an individual project.
Project Update Templates
You can define Templates, for updating Issues for each Project. The Projects Template screen is available as a Project tab and can be accessed by Project Admins only or those users defined in the Project Template Access group list in the configuration screen. You can get to the page by going to the general Project pages, Add-ons, STM Templates and then changing to the Update Issue Templates tab
The image below shows the page where templates can be added and edited
Once a template has been defined you can hover over it to see the icons. You can move the template to a different Project or be global, edit it using the pencil icon, duplicate it by using the copy icon or delete it using the trash can icon.
New templates can be added by clicking on the Add button (the plus icon in the top right-hand corner) and this will open the create page shown below.
Details Section
The details section of the template has a name that will help identify the issues to create that belong to it, an "Add current user as watcher" checkbox to add the current user as a watcher for every issue created and optional documentation fields. Clicking on the "Show more documentation options" link will show the description and documentation link fields.
Update Issues Section
There is an Update Issue section that specifies which fields in the Issue are updated and what the new values of the field are. The example above has two different fields to update 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, at the end of a field, are help for the field to the left of the question mark. Hovering over these will give you helpful information about the field.
NOTE: All fields except Add Comment and Add Watchers replace the current value with the new value. For example, if the current label for the Issue is 'Java' and your update template specifies 'Python' and 'ReactJS' then the update will replace Java with Python and ReactJS.
The following fields are available in the Update Issue sections:
-
Summary: the summary of the Issue. You can refer to parent fields here by using one of: ${Summary}, ${Description}, ${Type}, ${Assignee}, ${Reporter}, ${Priority} 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.
-
Components: 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 (i.e. ${Reporter} etc)
-
Due Date: either the word today (for the day the Issue is created), a date (in the format YYYY-MM-DD) or the number of days, weeks and months (in this order) from the day the Issue 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 (is this order i.e. 3d 4h, 1w 10m ....), a percentage of the parent's original estimate (20%) or as a multiplier of the parent estimate (*0.25)
-
Fix Versions: The fix versions for this issue.
-
Issue Type: The issue type that the updated Issue will have
-
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 Fields: you can specify any custom field (up to five total) of type single-line text, multi-line text, number, and single select item, multi-item select, URL. 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 subtasks).
-
Add Watcher: Adds the specified users to the as watchers of the updated Issue
-
Add Comment: Adds a comment to the updated issue
You can add more fields to set by selecting them from the "Fields to display" dropdown menu. You can also remove fields by clicking the X next to their name. There is only one Update Issue section
Global Update Issue Templates
Global templates are templates that can be used in any project. The global template page can be navigated to through the menu at the topmost Jira menu (click on the Jira symbol in the top left of the screen) and clicking on the STM Global Templates option.
The content of global Update Issue Templates are identical to the Project ones. Please see the Project Update Issue Templates section for more details
Creating/Deleting Bulk Issues
In the Issue pages More menu there are options to create bulk sub-tasks, linked Issues, Epic Issues, unconnected issues and to delete sub-tasks, linked issues or Epic issues. Epic Issue creation and deletion are only available if you are running the "JIRA-Software" version of JIRA.
If you select one of the create bulk Issue menu items then a dialog similar to that below will be displayed.
The main difference between the create bulk pages is the Issue Type that you can select.
There are two ways of using this dialog: creating Issues from a template or creating Issues from scratch.
Create bulk Issues from a template
To create bulk Issues from a template the user selects a template from the Template To Create dropdown. The dropdown has a list of all templates the belong to the current Project and global templates are visible to the bulk create pages. Once a template is selected then all of the details from that template are shown below
The minimum a user has to do is select an Issue Type and press the Create button. Optionally the user can also customize the fields used, enter or change the value and even add new sections if they wish. Once all changes are made then the Create button can be pressed. Any changes performed in this screen are NOT updated to the template.
Create bulk Issues manually
To create bulk Sub Tasks / Linked Issues / Epic Issues manually you either leave "Template to create" empty or select "Don't use Template". This will reset all of the fields back to a blank template. The user can add details the same as they could do from the Template screen. Once they have finished they just click on the Create button.
Delete Bulk Issue
To delete bulk Issue, select the appropriate delete bulk menu item. That will display a dialog like that shown below. Check the boxes of the Sub Tasks you want to delete and press "Delete Sub Tasks". You can also click on the circle containing three dots to display more information about the Issue.
Project Executors - Automatic template creation
To automatically create bulk sub-tasks, Linked Issues, Epic Issues or Unconnected Issues you need to use an Executor. A Projects Executor page is available as a Project tab by clicking on the E icon with the letters STM above it. The image below shows the page where executors can be added and edited.
Executor (when enabled) will create issues automatically, based on the specified template and criteria. If you don't want a template to run then edit the Executor and uncheck the Enabled checkbox.
If you hover over an Executor three icons will be shown on the right-hand side. The pencil icon allows you to edit the Executor, the copy icon will duplicate the Executor and show it in a new Executor dialog and trash can icon will delete the Executor.
New Executors can be added by clicking on the add button (plus icon, top right-hand corner) and this will show the add Executor page shown below
To start with you are asked to enter the name of the Executor and whether it is enabled or not. Click on the Next button to go to the next section.
You now need to decide when the executor will run: when the issue is created or when it is transitioned. Click on "On Create Issue" or "On Transition" to continue. For the purposes of this documentation, we clicked "On Transition"
For On Transition we need to enter the To Status of the transition and optionally select the From Status. We then click Next. When Next is clicked we get the option of either creating a Condition or Action.
For this example we will add a condition to the Executor. Clicking on Condition will give us the choice of either testing a fields value or testing who is the current user. For this example we will choose to test a fields value.
We add a test to make sure that the Issue type is an Epic and click Next. We get to choose the between another Condition and an Action.
This time we choose to create an action
Now we get presented with a list of different actions to perform.
We choose to create a Sub Task.
We then select the template to use and the default issue type. After that, we click save and return to the Executors page.
NOTE: The items in the left-hand panel can be clicked on to change which part of the Executor you are looking at.
Transition Issues
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 that transition takes just to step).
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 have 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 From Status and 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 with just one transition.
The next type of transition is the most complicated one and also the most powerful. We same have the fields shown above (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 PAYROLL project will transition to In Progress only if they currently have the To Do status and the current project will transition to In Progress status no matter what status they currently have.
Transitioning Parent/Related Issues
Transition Parent/Related issues 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.
In 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 subtasks.
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.
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 issue A will be automatically transitioned to Done.
The screenshot below shows the settings to accomplish this.
Lastly, we have an example of transitioning a parent/related issue when connected as an Epic issue.
For the example above, the Executor is designed to 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.
Global Executors - Automatic template creation
Global Executors are very similar to Project Executors. The only difference is that you have to either choose if it applies to all projects or for a select group of projects it will apply to. See Project Executors, above, for the general usage of an Executor.
The screenshot below shows the difference for the Global Executor. This includes a selection of whether this is for all or selected projects and if it is for selected projects then which ones.
Automatic issue creation - In Action
When an Issue completes a transition that creates issues through an Executor a message box is displayed to inform the user that processing is occurring in the background. STM will keep checking in the background to see when the Issues have been created.
When they are created then the Issue is refreshed to display them and a message is displayed to show that they have been created. Below are examples of the pending and created messages
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 STM errors are also available in a project admin area (see below). In this area there is also a STM Audit page that will show what was create and why a template was not created.
Errors
Any errors that occur during the creation of sub tasks or Epic Issues in a workflow transition can be viewed under the "STM Errors" tab in a project administration screen. Details are kept for up to two weeks after the error occurs (at which time they are deleted).
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 the Analysis and Development template was create on the 29th Sep 2021 and updated the next day. The change log also includes deleted templates.
Configuration
The configuration screen allows you to define access to the global and project Template and Executor screens.
For the global Template and Executor pages, system admins always have access. For the project Template and Executor pages, project admins always have access. Use one of the two fields (shown below) to specify which additional users will also have access by entering one or more user groups. All users in those groups will then have access.
Getting Started
The Getting Started page is a good starting point for users unfamiliar with STM. It specifies commonly used terms and allows the user to create examples of Templates and Executors.
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 get the App to choose for you. This plugin comes with three languages pre-installed: English, French and German.
Import/Export
This section allows to import and export STM configurations. The importing and exporting will import/export the configuration for all project and global executors and templates.
To import a configuration just click on the "Choose file" button and select the configuration file you want to import. When the file is selected, click on the Import button. Messages will be displayed telling you what is going on.
To Export the STM configuration just click on the Export button. That will start downloading a file with the STM configuration.