Page tree

Contents

JSU for Jira Server

This is the documentation of JSU for Jira Server. If you are using JSU on Jira Cloud, you can find the documentation here.


The 'Create a Linked Issue' feature is available from JSU 2.0


Description

This post function will create a new issue. The new issue will be linked to the origin issue (the one, which triggered the 'Create a Linked Issue' post function).

Any number of fields can be copied to the new issue and within the origin issue.

See the Testing and Fixing Bugs use case for an example how several of our customers are using this post function. The video on that page shows you the following sample configuration in action.


Configuration

Create Linked Issue is a very powerful post functions. It has several sections for its configuration. See also further down.

Precondition

There are several ways in which preconditions can be evaluated in the context of a post function:

  • Ignore precondition (By default every precondition is ignored. It means that post function will be always performed)
  • True (Precondition must be true to execute a post function)
  • False (Precondition must be false to execute a post function)

You can find more generic description of precondition here


The configuration then has several sections, as describe in the following sub chapters:

Function Execution Control

Here the idea is, that you have a checkbox custom field on the transition screen, so the user can control some of the functionality.

For example a checkbox 'Create Bug?' might be configured as 'Custom Field that enables linked issue creation'. Only if it is ticked, a new issue will be created.
Typically this checkbox custom fields won't appear in the normal screen of the issue. Also at the end you might set them back to the original (default) value (see Copy within the Origin Issue).

Instead of letting the user choose to copy/move the attachments, you can also configure to never/always copy them.


(info) Tip: You might choose 'Move Attachments added during Transition'. The user then adds some attachments on the transition screen of the origin issue. However since they are moved to the newly created issue, it feels as if he added the attachments to the new issue. 

If you use 'Move Attachments added during Transition' it is important that the 'Create Linked Issue' Post-Function is before JIRA Post-Function 'Update change history for an issue and store the issue in the database'!

Due to a Bug in Jira JRASERVER-65939, 'Copy or Move Attachments' functionality, which are added through a Transition Screen, does not work in Jira 7.5.x & 7.6.0. If you require this functionality, please upgrade to minimum Jira Version 7.6.1!



Initial Mandatory Values for the new Issue

Here you must configure some always mandatory fields for an issue. These are some real basic field of JIRA. Be aware that your JIRA configuration might have additional required fields (you should set them with Copy from the Origin Issue to the New Issue .


Additionally the summary will always be copied from the origin issue to the new issue. The reporter of the new issue will always be set to the user who triggered the current transition (and thus this post function). However you might overwrite them again later with Copy from the Origin Issue to the New Issue

Target Project

Target Project can be set to:

Inside same project

A new issue will be created in this same project

Project variables

If you use the workflow with the 'Create a Linked Issue' post function in several JIRA projects, you might choose  'Project variables'. You then can configure in each of those JIRA project a different target project for the newly created issues. For more about project variables see Project Variables.

The format for those project variables is as follows:

createLinkedIssueTargetProjectKey.<Workflow Name>.<Workflow Transition Nummer>=<Projekt Key>

Workflow Name and Workflow Transition Number are optional.

Example

From project A, you might create new linked issues in project X. But from project B, you might create new linked issues in project Y. But both use the same workflow.

Project Variable in project A: createLinkedIssueTargetProjectKey=X
Project Variable in project B: createLinkedIssueTargetProjectKey=Y

(info) The new issue will be created with the same user, who triggered the transition on the origin issue. If that user does not has the necessary permissions in the target project he will get an error. Also if some validators prevent the creation of the new issue.

Selected Project


A new issue will be created in the selected project


Defined by custom field selection


A new issue will be created in a project which is defined in selected custom field. Here available are fields of types: single select, radio buttons, project pickers

Example

An administrator can create a field "Destination Project" with several different values which will represent project key (only capital letters) or project name (capital and small letters are supported) 

Create new Issue as User

If you don't specify anything here, the create operation will be performed under the same user, who triggered this post function on the origin issue. Thus that user must have the necessary permissions to create the new issue.

However, in some restrictive setup that user might not be allowed to create new issues in the target project. He might not even see the target project!

With 'Create new Issue as User' you can specify a different user account which owns the necessary permissions. Usually this user account is assumed to be only technical, with broad permissions, but not used to log into Jira by in life persons.

This Issue will be related via

Since JSU 2.1.0 the Create a Linked Issue post function allows you the create new issues, which are connected not only with an issue link, but instead also in a parent / sub-task, as well as epic / issue in epic relation.

See Related Issues for more explanation on this topic (especially for creating sub-tasks).

Issue Type

Issue type can be set to:

Selected issue type

A new issue type will have a particular issue type.

Be aware, that the issue type you configure here must be available in the target project.

Defined by custom field selection

Similar to Target Project an issue type can be defined by value selected by user in a dedicated custom field.

Be aware, that the issue type you provide in this custom field must be available in the target project.


The user will be able to select which issue type should be created.
As Jira administrator you also have to create this custom field (in the sample screenshots: Destination Issue Type). Take care of correct values of this custom field. These values have to match with the issue types available in the target project.



Copy from the Origin Issue to the New Issue

(info) Be aware, that all destination fields must also be on the create issue screen of the new issue.

You can copy the value form some source field to some destination field. Click the + Button to add additional field pairs to your configuration.

Keep in mind that not all conversions from source to destination field are supported, nor feasible. We can only ensure, that it will work if source and destination fields are of the same field type, or the destination field is a text field. (Still, some additional combinations of different field types might work as well - although not 'officially' supported.)

Overwrite / Append / Prepend

For text fields and some field that can take multiple values (like checkboxes) you can choose to overwrite, append or prepend the new value to any existing value. In the case of text field, you can also choose a separator that will be put between the values (not shown in the screen shot above).

Create version if necessary

Imagine your origin issue has a version, that you want to copy to the linked issue.

If the destination field is 'Fix Version/s', 'Affects Version/s' or some custom field of type 'Version Picker', you can choose that a new version will be created in the target project, if does not yet exist. If you don't choose this option and that version does not yet exist, the user will get an error message and the transition won't complete.

However be aware, that the version will be created, even the user does not has the 'Administer Projects' permission. (Normally a user needs that permission to be able to create a new version.)

Special 'Sources'

As source you have some additional options:

  • *** default value ***
    The default value of the destination field will be set.
  • *** empty ***
    The destination field will be cleared.
  • *** transition comment ***
    The comment, which the user entered on the transition screen.
  • *** last comment ***
    The last (most recent) comment already existing on the issue before the transition was started.

Special 'Destinations'

As destination you have some additional options:

  • *** new comment ***
    Create a new comment with the value from the source field.


Real life tips

(info) Tip: You might setup a special transition screen to mainly copy those fields to the newly created issue. So it feels more like it would be the create screen of the new issue. In that case, you won't show those fields on the origin issue, but reset them again afterwards (just empty or back to the default value), see Copy within the Origin Issue.

For 'Copy from the Origin Issue to the New Issue' append & prepend do only make sense, if the target field contains already a default value. So in practice append or prepend are more often used for 'Copy within the Origin Issue'. If at all.


Copy within the Origin Issue

You can copy the value form some source field to some destination field. Click the + Button to add additional field pairs to your configuration.

Keep in mind that not all conversions from source to destination field are supported, nor feasible. We can only ensure, that it will work if source and destination fields are of the same field type, or the destination field is a text field. (Still, some additional combinations of different field types might work as well - although not 'officially' supported.)

Overwrite / Append / Prepend

For text fields and some field that can take multiple values (like checkboxes) you can choose to overwrite, append or prepend the new value to any existing value. In the case of text field, you can also choose a separator that will be put between the values (not shown in the screen shot above).

Create version if necessary

Imagine your origin issue has a version, that you want to copy to the linked issue.

If the destination field is 'Fix Version/s', 'Affects Version/s' or some custom field of type 'Version Picker', you can choose that a new version will be created in the target project, if does not yet exist. If you don't choose this option and that version does not yet exist, the user will get an error message and the transition won't complete.

However be aware, that the version will be created, even the user does not has the 'Administer Projects' permission. (Normally a user needs that permission to be able to create a new version.)

Special 'Sources'

As source you have some additional options:

  • *** default value ***
    The default value of the destination field will be set.
  • *** empty ***
    The destination field will be cleared.
  • *** transition comment ***
    The comment, which the user entered on the transition screen.
  • *** last comment ***
    The last (most recent) comment already existing on the issue before the transition was started.

Special 'Destinations'

As destination you have some additional options:

  • *** new comment ***
    Create a new comment with the value from the source field.

Position of the Post Function

(warning) You can use this post function in the create transition (transition leading to Status "Open"), but you have to make sure to position the post function after "Creates the issue originally" and before "Re-index an issue to keep indexes in sync with database.". As the create transition behaves differently than other transition, the copying and/or moving attachment and copy field within same issue functionalities are not available in this case.

In any case, if you use 'Move Attachment' (see bellow) you must position the post function before 'Update change history for an issue and store the issue in the database.'

You can add this post function several times in one transition.

Example

See the Use Case Testing and Fixing Bugs for a nice example, how several of our customers use it. The video on that page shows you the following sample configuration in action.


Supported Field Types

In its different modules (especially those for workflows), the JSU app supports many different field types. System fields, as well as custom fields.

However you should be aware, that not all field types are supported. Also not in all combinations. We think we cover the most important field types and still are continuously adding and improving which and how different field types are supported. But the one you need, might just not (yet) work. Some custom fields of other third party app might never get supported.

For that reason you should always test anything you do with the JSU app with fields. Before you buy a license for JSU, try it with a free evaluation license, if it works for you.