Create Jira (PDK) plugin procedures

CreateIssues

Creates one or more Jira issues.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Required. Jira project key. For example, an issue prefix such as MYPROJ.

The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key is MYPROJ.

Issue type

Required. Jira issue type. Examples include: Bug, Task, Sub-task, Story, or Epic.

Valid issue types depend on your Jira project, and can be found in your Jira project settings. If you provide an issue type that is not available in your project, the procedure fails.

Issue summary

Issue short description/title. Maximum length of the summary is 255 characters by default, but may be different depending your Jira project settings.

If the Issue summary field is provided, only one issue is created.

Assignee name

For servers up to Jira version 8.0: Provide the username of the assignee for the issue. A user with the specified username must already exist in the system.
For cloud services: Provide either the email address or display name of the assignee to search for the user. The specified assignee must already exist in the system.

If multiple users are found, the first match is assigned, and a warning is included in the log.

Labels

Comma-separated list of issue labels. For example, MyLabel1, MyLabel2.

Jira does not allow spaces in labels.

Affects versions

Comma-separated list of affected versions. For example, 7.0, 8.0.

The specified versions must already exist in the project.

Fix versions

Comma-separated list of versions where the issue will be resolved. For example, 7.0, 8.0.

The specified versions must already exist in the project.

Description

Full description of the issue, the steps to reproduce, and the expected results. Markup can be used here, for example:

  Something is broken
  {color:red}
  test case 1
  {color}▼

For more information on the markup supported in descriptions, refer to Jira Formatting.

Additional parameters

Additional parameters for the Jira issue must be specified in JSON. For example:

{ "customfield_70000": [ "jira-administrators", "jira-software-users" ] }▼

Example formats for this field are:

Single value field:
```
{"customfield_1212": "Epic Name"}▼
```
Where customfield_1212 is a custom field for Epic Name.

Multiple values field:

{"customfield_10042": [{"value": "first"}, {"value": "second"}]}▼

Link to another object:
```
{"parent": {"id": "TEST-1"}}▼
```
Where TEST-1 is the parent of a subtask being created by the procedure.

Result property

Property sheet to store results. /myJob/createdIssues is the default.

Result format

Format to store results, JSON or property sheet. Property sheet is used by default. For more information, refer to Result format.

Create Summary Link?

If selected, a report with a summary and links are attached to the pipeline summary and job summary.

Summary link property

Property to store the generated report and attached to the pipeline summary and job summary. The default value is Jira Created Issues Report.

Summary link title

Title for the link to download the report. The default title is Download Report.

Output parameters

Table 2. CreateIssues output parameters
Parameter	Description
jirareporturl	URL to the HTML Jira report.
jiraids	Comma-separated list of issue IDs that were involved in the request.

CreateNewVersion

Creates a new version in the specified project.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Required. Jira project key. For example, an issue prefix such as MYPROJ.

The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key would be MYPROJ.

Version name

Required. Jira version to be created.

CreateProject

Creates Jira Project.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Required. Jira project key. For example, an issue prefix such as MYPROJ.

The project key must meet Jira requirements. The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key would be MYPROJ.

Project name

Required. The name of the project.

Project description

A brief description of the project.

Project category ID

The ID of the project’s category.

Assignee

Required. The default user assigned when creating issues for this project.

Project type key

Required. The project type, which defines the application-specific feature set. If you do not specify the project template you must specify the project type. Valid values are software, service_desk, and business.

Project template key

Required. A predefined configuration for a project. The project template key must be compatible with the project type entered in Project type key.

For more information, refer to:

Project info URL

A link to information about this project, such as project documentation.

Avatar ID

An integer value for the project avatar.

Project lead

Required. * For servers up to Jira version 8.0: Provide the username of the project lead. A user with the specified username must already exist in the system.

For cloud services: Provide either the email address or display name of the project lead to search for the user. The specified user must already exist in the system.

If multiple users are found, the first match is assigned, and a warning is included in the log.

GetIssues

Retrieves issues from Jira using the provided JQL or previously saved filter.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Jira filter ID

The ID of an existing Jira filter to use for querying.

Either this parameter or the Jira Query (JQL) parameter must be specified.

Jira Query (JQL)

JQL to search issues. For more information on JQL queries, refer to the Jira JQL documentation.

Either this parameter or the Jira filter ID parameter must be specified.

Max results

Maximum number of Jira issues to retrieve.

The default value is defined by your Jira instance.

Result format

Format to store results, JSON or property sheet. Property sheet is used by default. For more information, refer to Result format.

Result property

Property sheet to store results. Retrieved Jira issues are saved under this property if Result Format is selected. By default, this is /myJob/getIssuesResult.

Create summary link?

If selected, a report with a summary and links are attached to the pipeline summary and job summary.

Summary link property

Property to store the generated report and attached to the pipeline summary and job summary. The default value is Jira Get Issues Report.

Summary link title

Title for the link to download the report. The default title is Download Report.

Field list to save?

Additional comma-separated fields that should be saved within issue property. For example, fixVersions.

Output parameters

Table 6. GetIssues output parameters
Parameter	Description
jirareporturl	URL to the HTML Jira report.
jiraids	Comma-separated list of issue IDs that were involved in the request.

GetProjectVersions

Returns one or more Jira project versions based on user-specified criteria.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Required. Jira project key. For example, an issue prefix such as MYPROJ.

The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key would be MYPROJ.

Version names

Comma-separated list of version names. This can be useful if you want to retrieve information about specific versions (for example, 1.0 or 1.0, 2.0, 3.0).

Version status

Retrieves only the versions with the specified status.

Max results

Maximum number of Jira issues to retrieve.

The default value is defined by your Jira instance.

Order by

Name of the field to sort the result list by. Prepend a minus sign to use descending order. Values: description, -description, name, -name, releaseDate, -releaseDate, sequence, -sequence, startDate, and -startDate.

Show issues count by status

If selected, a count of issues is included in the version’s info and HTML report, in order by status.

Result format

Format to store results, JSON or property sheet. Property sheet is used by default. For more information, refer to Result format.

Result property

Property sheet to store results. Retrieved Jira issues are saved under this property if Result Format is selected. By default, this is /myJob/getProjectVersionsResult.

Create summary link?

If selected, a report with a summary and links are attached to the pipeline summary and job summary.

Summary link property

Property to store the generated report and attached to the pipeline summary and job summary. The default value is Jira Queried Versions Report.

Summary link title

Title for the link to download the report. The default title is Download Report.

Field list to save?

Additional comma-separated fields that should be saved within issue property. For example, fixVersions.

Output parameters

Table 8. GetProjectVersions output parameters
Parameter	Description
jirareporturl	URL to the HTML Jira report.
jiraids	Comma-separated list of version names that were involved in the request.

LinkIssues

Links Jira issues to jobs and pipelines based on provided Jira issue properties.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Provide the project key used by the Jira project. For example, if an issue ID in the project is PROJ-1, the Project key entry is PROJ.

If Project key is blank, a regular expression is used to attempt to match the project key.

Perl regex filter

Perl-compatible regular expression to filter issue IDs from source control logs. For example, Fixed (\w+-\d) retrieves issue ID TEST-1 from the Fixed TEST-1 commit summary. For more information, refer to Perl regular expressions. Examples:

\w+\-\d+ matches a sequence of word characters followed by - and a sequence of digits (for example, MYJIRA-2, ANOTHER-2).
(MYPROJ|ANOTHERPROJ)\-\d+ matches the word MYPROJ or ANOTHERPROJ followed by - and a sequence of digits.

Property to parse

Provide the property or property sheet used to search for issue IDs. If this field is blank, the default property /myJob/ecscm_changeLogs is used. The property content may look similar to the following:

Commit # commit number
Closed ECTEST-1▼

CloudBees SCM-based plugins can be used to generate such logs.

Result format

Format to store results, JSON or property sheet. Property sheet is used by default. For more information, refer to Result format.

Result property

Property sheet to store results. Retrieved Jira issues are saved under this property if Result Format is selected. By default, this is /myJob/issueLinks.

Summary link property

Property to store the generated report and attached to the pipeline summary and job summary. The default value is Jira Linked Issues Report.

Summary link title

Title for the link to download the report. The default title is Download Report.

Output parameters

Table 10. LinkIssues output parameters
Parameter	Description
jirareporturl	URL to the HTML Jira report.
jiraids	Comma-separated list of issue IDs that were collected in the request.

MarkVersionAsReleased

Marks a specified version as released in the specified project.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project key

Required. Jira project key. For example, an issue prefix such as MYPROJ.

The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key would be MYPROJ.

Version name

Required. Jira version to be marked as released.

UpdateIssues

Updates one or more Jira issues or add comments to them. When the procedure runs, the first issue key parameter is checked. If it is provided, the single Jira issue is updated. If JQL is provided, the procedure queries the issues and updates them, and then searches for the issues in the property. If no issues were found with the provided JQL, the procedure finishes and does not update any Jira issues.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Property to read defects

Provide the path to the property if the property containing the list of defects to update is somewhere other than /myJob/defectsToUpdate. This parameter is left for compatibility only. The property should contain issue IDs with their desired transitions, For example, MYJIRA-1=Done.

To set this property, run:

ectool setProperty /myJob/defectsToUpdate "MYJIRA-1=Done"▼

Issue key

Provide an issue key to update one single issue. If this field is provided, JQL and Property to read defects will be ignored.

JQL

Provide JQL to search for the issues to update. If this field is left empty, the procedure looks for issues to update in the Property to read defects (the old logic is enabled). If no issues were found with the provided JQL, the procedure finishes without updating anything. For example: issuetype = Story AND project = Enter-your-jira-project.

Issue summary

Issue short description/title. Maximum length of the summary is 255 characters by default, but may be different depending your Jira project settings.

If several issues are queried, they won’t be updated and the procedure fails.

Issue type

Jira issue type. Examples include: Bug, Task, Sub-task, Story, or Epic.

If several issues are queried, they won’t be updated and the procedure fails.

Assignee name

For servers up to Jira version 8.0: Provide the username of the assignee for the issue. A user with the specified username must already exist in the system.
For cloud services: Provide either the email address or display name of the assignee to search for the user. The specified assignee must already exist in the system.

If multiple users are found, the first match is assigned, and a warning is included in the log.

Labels

Comma-separated list of issue labels. For example, MyLabel1, MyLabel2.

Jira does not allow spaces in labels.

Affects versions

Comma-separated list of affected versions. For example, 7.0, 8.0.

The specified versions must already exist in the project.

Fix versions

Comma-separated list of versions where the issue will be resolved. For example, 7.0, 8.0.

The specified versions must already exist in the project.

Description

Full description of the issue, the steps to reproduce, and the expected results. Markup can be used here, for example:

  Something is broken
  {color:red}
  test case 1
  {color}▼

For more information on what markup can be used in descriptions, refer to Jira Formatting.

Additional parameters

Additional parameters for the Jira issue must be specified in JSON. For example:

{ "customfield_70000": [ "jira-administrators", "jira-software-users" ] }▼

Example formats for this field are:

Single value field:
```
{"customfield_1212": "Epic Name"}▼
```
Where customfield_1212 is a custom field for Epic Name.

Multiple values field:

{"customfield_10042": [{"value": "first"}, {"value": "second"}]}▼

Link to another object:
```
{"parent": {"id": "TEST-1"}}▼
```
Where TEST-1 is the parent of a subtask being created by the procedure.

Transition action

Action to change the Jira issue status, for example: Close, Reopen. For more information on workflows, refer to Working with workflows documentation.

Comment

Comment to add to the found Jira issues. If left blank, no comment will be added. Markup can be used here. For example:

  Something is broken
  {color:red}
  test case 1
  {color}▼

For more information on what markup can be used in descriptions, refer to Jira Formatting.

Add field values

If selected, issue fields that can contain multiple items (for example, Labels or Affect Versions) are extended with new values instead of being replaced. Custom fields are not supported.

Result property

Property sheet to store results. /myJob/updatedIssues is the default.

Result format

Format to store results, JSON or property sheet. Property sheet is used by default. For more information, refer to Result format.

Create Summary Link?

If selected, a report with a summary and links are attached to the pipeline summary and job summary.

Summary link property

Property to store the generated report and attached to the pipeline summary and job summary. The default value is Jira Updated Issues Report.

Summary link title

Title for the link to download the report. The default title is Download Report.

Output parameters

Table 13. UpdateIssues output parameters
Parameter	Description
jirareporturl	URL to the HTML Jira report.
jiraids	Comma-separated list of issue IDs that were involved in the request.

UpdateProject

Updates the details of a Jira project.

Input parameters

Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Project ID or key

Required. The Jira project ID or project key (case-sensitive).

Project key

Jira project key. For example, an issue prefix such as MYPROJ.

The project key must meet Jira requirements. The project key is the prefix before the Jira issue number, and not the name of the Jira project. For example, for a project with an issue such as MYPROJ-123, the Project key would be MYPROJ.

Project name

The name of the project.

Project description

A brief description of the project.

Project category ID

The ID of the project’s category.

Assignee

The default user assigned when creating issues for this project.

Project type key

Required. The project type, which defines the application-specific feature set. If you do not specify the project template you must specify the project type. Valid values are software, service_desk, and business.

Project template key

Required. A predefined configuration for a project. The project template key must be compatible with the project type entered in Project type key.

For more information, refer to:

Project info URL

A link to information about this project, such as project documentation.

Avatar ID

An integer value for the project avatar.

Project lead

For servers up to Jira version 8.0: Provide the username of the project lead. A user with the specified username must already exist in the system.
For cloud services: Provide either the email address or display name of the project lead to search for the user. The specified user must already exist in the system.

If multiple users are found, the first match is assigned, and a warning is included in the log.