Jira plugin

This plugin integrates with Atlassian JIRA. It creates and updates issues automatically and supports reports.

This plugin uses the JIRA Server platform REST API.

Plugin Version 2.3.0.2023100452

Revised on October 05, 2023

Updated Perl version required

This plugin is using an updated version of Perl, cb-perl shell (instead of old ec-perl). This means that it needs CloudBees CD/RO agent version 10.3+ in order to work.

Supported versions

The following JIRA versions are supported:

Configuration

Plugin configurations

Plugin configurations are sets of parameters that apply across some or all of the plugin procedures. They reduce repetition of common values, create predefined parameter sets for end users, and securely store credentials where needed. Each configuration is given a unique name that is entered in designated parameters on procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, do these steps:

Go to Administration > Plugins to open the Plugin Manager.
Find the EC-JIRA row.
Click Configure to open the EC-JIRA Configurations page.
Click Create Configuration.
To enable CloudBees CD/RO server to communicate with the API, enter the following information:

The EC-JIRA Configurations page now shows the new configuration.

Editing plugin configurations

To edit plugin configurations in CloudBees CD/RO, do these steps:

Go to Administration > Plugins to open the Plugin Manager.
Find the EC-JIRA row.
Click Configure to open the Configurations page.
Find the configuration that you want to edit.
Click Edit.
Edit the parameters in the configuration.
Click OK to save the modified configuration.

Procedures

CreateIssues

Creates one or several JIRA issues.

This procedure is compatible with the old procedure "CreateDefects" from EC-DefectTracking-JIRA plugin. If no summary is provided, it looks for the property sheet named /myJob/ecTestFailures. The property sheet should have the following format:

/myJob
    /ecTestFailures
        /Test Case Name, e.g. "My Case"
            /stepName -> Step Name (e.g. My Step)
            /testSuitName -> Test Suite Name (e.g. My Test Suite)
            /testCaseName -> Test Case Name (e.g. My Case)
            /testCaseResult -> Error (e.g. "Something failed")
            /log -> Log (e.g. Test "My test" failed)
            /defectId -> ID
            /defectResult -> DefectResult

At least one of the properties should be provided. The best way to fill the properties is to use Post Processors. Look at the example of a Post Processor for JUnit.

If the "Summary" field is filled, only one issue is created.

If there is no summary and no predefined properties, no issues are created and the procedure finishes successfully.

Parameter Description

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
Project Key	Provide the key of the JIRA project, e.g. MYPROJ. (Please notice, this is not a name of the project).
Issue Type	Provide the type of the issue, e.g. Bug. The most common types are Bug, Task, Sub-task, Story, Epic. Available types depend on project. To view the list of the available types, please use REST API (Get project API. Example of the call: curl -u user:password http://myinstance/rest/api/2/project/TEST { "issueTypes" : [ { "name" : "Task", "id" : "10001", "description" : "A task that needs to be done.", .... }, { "id" : "10000", "description" : "The sub-task of the issue", "name" : "Sub-task", ... } ], ... ]
Summary	Short description of the issue. If this field is provided, only one issue is created. Maximum length of the summary is 255 by default and managed by JIRA instance itself.
Assignee Name	Indicate the assignee login for the issue. Please provide the login of the existing user, e.g. "myuser".
Labels	Issue labels, comma-separated, e.g. MyLabel1, MyLabel2. JIRA does not allow spaces in labels.
Affects versions	Affected versions, comma-separated, e.g. 7.0, 8.0. Versions should exist in the project.
Description	Full description of the issue, steps to reproduce, expected results, etc. Markup can be used here, e.g. {code} my code; {code}
Additional parameters	Any additional parameters to be specified for the JIRA issue in JSON format. E.g.: `{ "customfield_70000": [ "jira-administrators", "jira-software-users" ]}`. Refer to the JIRA REST API for supported parameters for create issue API. Example formats for this parameter are: Single value field: `{"customfield_10000": "value"}` (e.g. `{"customfield_1212": "Epic Name"}` where `customfield_1212` is a custom field for Epic Name; Multiple values field: `{"customfield_10042": [{"value": "8.0"}, {"value": "8.0.1"}]}`; Link to another object: `{"parent": {"id": "TEST-1"}}` (for creating sub-task, for exampple).
Result Property	Property sheet to store results. /myJob/createdIssues by default. Refer to Result Format section for the detailed description.
Result Format	Format to store results, JSON or property sheet. Property sheet by default.
Create Summary Link?	If checked, a report with summary and links will be attached to a pipeline and job summary.
Summary link property	Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Created Issues Report
Summary link title	Title for a link to download a report. Default value: Download Report

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

Project Key

Provide the key of the JIRA project, e.g. MYPROJ. (Please notice, this is not a name of the project).

Issue Type

Provide the type of the issue, e.g. Bug.

The most common types are Bug, Task, Sub-task, Story, Epic. Available types depend on project.

To view the list of the available types, please use REST API (Get project API. Example of the call:

curl -u user:password http://myinstance/rest/api/2/project/TEST

{
   "issueTypes" : [
      {
         "name" : "Task",
         "id" : "10001",
         "description" : "A task that needs to be done.",
         ....
      },
      {
         "id" : "10000",
         "description" : "The sub-task of the issue",
         "name" : "Sub-task",
         ...
      }
   ],
   ...
]

Summary

Short description of the issue. If this field is provided, only one issue is created. Maximum length of the summary is 255 by default and managed by JIRA instance itself.

Assignee Name

Indicate the assignee login for the issue. Please provide the login of the existing user, e.g. "myuser".

Labels

Issue labels, comma-separated, e.g. MyLabel1, MyLabel2. JIRA does not allow spaces in labels.

Affects versions

Affected versions, comma-separated, e.g. 7.0, 8.0. Versions should exist in the project.

Description

Full description of the issue, steps to reproduce, expected results, etc. Markup can be used here, e.g.

{code}
my code;
{code}

Additional parameters

Any additional parameters to be specified for the JIRA issue in JSON format. E.g.: { "customfield_70000": [ "jira-administrators", "jira-software-users" ]}.

Refer to the JIRA REST API for supported parameters for create issue API. Example formats for this parameter are:

Single value field: {"customfield_10000": "value"} (e.g. {"customfield_1212": "Epic Name"} where customfield_1212 is a custom field for Epic Name;
Multiple values field: {"customfield_10042": [{"value": "8.0"}, {"value": "8.0.1"}]};
Link to another object: {"parent": {"id": "TEST-1"}} (for creating sub-task, for exampple).

Result Property

Property sheet to store results. /myJob/createdIssues by default. Refer to Result Format section for the detailed description.

Result Format

Format to store results, JSON or property sheet. Property sheet by default.

Create Summary Link?

If checked, a report with summary and links will be attached to a pipeline and job summary.

Summary link property

Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Created Issues Report

Summary link title

Title for a link to download a report. Default value: Download Report

Procedure form:

Job has finished successfully:

Report sample:

Output Parameter (CloudBees CD/RO 8.3+)	Description
jirareporturl	URL (CloudBees CD/RO relative) to HTML JIRA Report
jiraids	Comma-separated list of issue IDS that were involved into the request

Output Parameter (CloudBees CD/RO 8.3+)

Description

jirareporturl

URL (CloudBees CD/RO relative) to HTML JIRA Report

jiraids

Comma-separated list of issue IDS that were involved into the request

GetIssues

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

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
JIRA Filter ID	JIRA filter used to find the issues in JIRA. Either this parameter or "JIRA query" parameter" must be specified.
JIRA Query (JQL)	JQL to search issues. Either this parameter or "JIRA filter ID" must be specified. Please refer to JQL documentation.
Max Results	Max number of issues to retrieve. Default value is defined by the JIRA instance.
Result Format	Format to store results, JSON, property sheet or none ( do not save the result). Please refer to Result Format documentation.
Result Property	Property to store results. Retrieved jiras will be saved under this property if Result Format is chosen. By default, /myJob/getIssuesResult.
Create Summary Link?	If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.
Summary link property	Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Queried Issues Report
Summary link title	Title for a link to download a report. Default value: Download Report
Field List to Save?	Additional comma-separated fields that should be saved within issue property. E.g. 'fixVersions,Epic Status'.

Parameter

Description

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

JIRA Filter ID

JIRA filter used to find the issues in JIRA. Either this parameter or "JIRA query" parameter" must be specified.

JIRA Query (JQL)

JQL to search issues. Either this parameter or "JIRA filter ID" must be specified. Please refer to JQL documentation.

Max Results

Max number of issues to retrieve. Default value is defined by the JIRA instance.

Result Format

Format to store results, JSON, property sheet or none ( do not save the result). Please refer to Result Format documentation.

Result Property

Property to store results. Retrieved jiras will be saved under this property if Result Format is chosen. By default, /myJob/getIssuesResult.

Create Summary Link?

If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.

Summary link property

Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Queried Issues Report

Summary link title

Title for a link to download a report. Default value: Download Report

Field List to Save?

Additional comma-separated fields that should be saved within issue property. E.g. 'fixVersions,Epic Status'.

Sample form:

Sample job has finished:

Sample logs:

Sample report:

Output Parameter (CloudBees CD/RO 8.3+)	Description
jirareporturl	URL (CloudBees CD/RO relative) to HTML JIRA Report
jiraids	Comma-separated list of issue IDS that were involved into the request

Output Parameter (CloudBees CD/RO 8.3+)

Description

jirareporturl

URL (CloudBees CD/RO relative) to HTML JIRA Report

jiraids

Comma-separated list of issue IDS that were involved into the request

LinkIssues

Parses a provided property for Issues keys and links them to the job/pipeline.

Parameter Description

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
Prefix	Provide the key used by JIRA as the prefix for defects within a project. If this field is blank, a regular expression is used to try to match defect IDs.
Regular Expression	Perl compatible regular expression to retrieve issues IDs from SCM logs. E.g. 'Fixed `(\w+-\d)`' will retrieve issue ID TEST-1 from commit summary "Fixed TEST-1". More on Perl regular expressions Perl Regular Expressions. Examples: \w+\-\d+ - will match a sequence of word chars followed by "-" and a sequence of digits, e.g. MYJIRA-2, ANOTHER-2 (MYPROJ\|ANOTHERPROJ)\-\d+ will match a word "MYPROJ" or "ANOTHERPROJ" followed by "-" and a sequence of digits
Property to Parse	Provide the property or propertysheet used to search for defect IDs. If this field is blank, the default property "/myJob/ecscm_changeLogs" is used. The property content may look like below: Commit # commit number Closed ECTEST-1 ECSCM plugins can be used to generate those logs.
Result Property	Property sheet or property name to store results. /myJob/issueLinks by default.
Result Format	Format to store results, JSON or property sheet. Retrieved jiras will be saved under this property. Please refer to Result Format documentation.

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

Prefix

Provide the key used by JIRA as the prefix for defects within a project. If this field is blank, a regular expression is used to try to match defect IDs.

Regular Expression

Perl compatible regular expression to retrieve issues IDs from SCM logs. E.g. 'Fixed (\w+-\d)' will retrieve issue ID TEST-1 from commit summary "Fixed TEST-1". More on Perl regular expressions Perl Regular Expressions.

Examples:

\w+\-\d+ - will match a sequence of word chars followed by "-" and a sequence of digits, e.g. MYJIRA-2, ANOTHER-2

(MYPROJ|ANOTHERPROJ)\-\d+ will match a word "MYPROJ" or "ANOTHERPROJ" followed by "-" and a sequence of digits

Property to Parse

Provide the property or propertysheet used to search for defect IDs. If this field is blank, the default property "/myJob/ecscm_changeLogs" is used. The property content may look like below:

Commit # commit number
Closed ECTEST-1

ECSCM plugins can be used to generate those logs.

Result Property

Property sheet or property name to store results. /myJob/issueLinks by default.

Result Format

Format to store results, JSON or property sheet. Retrieved jiras will be saved under this property. Please refer to Result Format documentation.

Sample form:

Sample job has finished:

Sample logs:

Processed changelog:

Sample report:

Output Parameter (CloudBees CD/RO 8.3+)	Description
jirareporturl	URL (CloudBees CD/RO relative) to HTML JIRA Report
jiraids	Comma-separated list of issue IDS that were involved into the request

Output Parameter (CloudBees CD/RO 8.3+)

Description

jirareporturl

URL (CloudBees CD/RO relative) to HTML JIRA Report

jiraids

Comma-separated list of issue IDS that were involved into the request

UpdateIssues

This procedure can be used to update one or several issues or add comments to them.

First Issue Key parameter is checked. If it is provided, the one single issue is updated. If JQL is provided, the procedures queries the issues and updates them, and finally the procedure looks for the issues in the property. If no issues were found with the provided JQL, the procedure finishes without updating anything.

Parameter Description

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
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, e.g. MYJIRA-1=Done. To set this property, run ectool setProperty /myJob/defectsToUpdate "MYJIRA-1=Done,MYJIRA-2=In Progress" If no issue key and JQL is provided, the procedure switches to compatibility mode. It parses the input property, updated issue statuses and adds a technical comment with text "ElectricFlow Job ID: $[/myJob/id]".
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 backward compatibility logic is enabled).
Summary	Short description of the issue, e.g. "Something is broken". If several issues are queried, they won’t be updated and the procedure will fail. The value from this field will override the current summary of the issue.
Issue Type	Issue type, e.g. Bug. If several issues are queried, they won’t be updated and the procedure will fail.
Assignee Name	Indicate the assignee for the issue. The login of an existing user should be provided here.
Labels	Issue labels, comma-separated, e.g. MyLabel1, MyLabel 2. JIRA does not allow spaces in the labels. Labels will replace the current labels of an issue, unless "Add Field Values" is checked.
Affects Version(s)	Affected versions, comma-separated, e.g. 7.0, 8.0. The version should exist in the project. Versions will replace the current versions of an issue, unless "Add Field Values" is checked.
Description	Full description of the issue, steps to reproduce, expected results, etc. JIRA markup can be used here, e.g. Added by Job {color:red} $[/myJob/id] {color} (Works in a Job context, for a pipeline please use /myPipelineRuntime etc.) Please refer to JIRA Formatting documentation. If several issues are queried, they won’t be updated and the procedure will fail. The value from this field will override current description of the issue.
Additional Parameters	Any additional parameters to be specified for the JIRA issue in JSON format. The parameters are placed under "fields" key in the request. The values in JIRA will be overridden. E.g.: `{ "customfield_70000": [ "jira-administrators", "jira-software-users" ]}`. Refer to the JIRA REST API for supported parameters for create issue API. Example formats for this parameter are: Single value field: `{"customfield_10000": "value"}` (e.g. `{"customfield_1212": "Epic Name"}` where `customfield_1212` is a custom field for Epic Name; Multiple values field: `{"customfield_10042": [{"value": "8.0"}, {"value": "8.0.1"}]}`; Link to another object: `{"parent": {"id": "TEST-1"}}` (for creating sub-task, for exampple).
Transition Action	Action to change issue status, e.g. "Close", "Reopen". To read more about workflows, please refer to Working with workflows documentation. To get a list of available transitions for a particular issue, use Get Transitions REST API call. A sample call: curl -u user:password http://myinstance:8080/rest/api/2/issue/TEST-1/transitions { "transitions" : [ { "to" : { ... }, "name" : "Start Progress" }, { "to" : { ... }, "id" : "21", "name" : "Done" } ] }
Comment	Comment to add to the found issues. If left blank, no comment will be added. JIRA markup can be used here, e.g. Added by Job {color:red} $[/myJob/id] {color} Please refer to JIRA Formatting documentation.
Add Field Values	If checked, issues fields that can contains multiple items (e.g. Labels, Affect Versions), except the custom ones, will be extended with new values instead of being replaced.
Result Property	Property sheet or property name to store results. /myJob/updatedIssues by default.
Result Format	Format to store results, JSON or property sheet. Retrieved jiras will be saved under this property. Please refer to Result Format documentation.
Create Summary Link?	If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.
Summary link property	Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Updated Issues Report
Summary link title	Title for a link to download a report. Default value: Download Report

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

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, e.g. MYJIRA-1=Done. To set this property, run

ectool setProperty /myJob/defectsToUpdate "MYJIRA-1=Done,MYJIRA-2=In Progress"

If no issue key and JQL is provided, the procedure switches to compatibility mode. It parses the input property, updated issue statuses and adds a technical comment with text "ElectricFlow Job ID: $[/myJob/id]".

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 backward compatibility logic is enabled).

Summary

Short description of the issue, e.g. "Something is broken". If several issues are queried, they won’t be updated and the procedure will fail. The value from this field will override the current summary of the issue.

Issue Type

Issue type, e.g. Bug. If several issues are queried, they won’t be updated and the procedure will fail.

Assignee Name

Indicate the assignee for the issue. The login of an existing user should be provided here.

Labels

Issue labels, comma-separated, e.g. MyLabel1, MyLabel 2. JIRA does not allow spaces in the labels. Labels will replace the current labels of an issue, unless "Add Field Values" is checked.

Affects Version(s)

Affected versions, comma-separated, e.g. 7.0, 8.0. The version should exist in the project. Versions will replace the current versions of an issue, unless "Add Field Values" is checked.

Description

Full description of the issue, steps to reproduce, expected results, etc. JIRA markup can be used here, e.g.

Added by Job
{color:red}
$[/myJob/id]
{color}

(Works in a Job context, for a pipeline please use /myPipelineRuntime etc.)

Please refer to JIRA Formatting documentation. If several issues are queried, they won’t be updated and the procedure will fail. The value from this field will override current description of the issue.

Additional Parameters

Any additional parameters to be specified for the JIRA issue in JSON format. The parameters are placed under "fields" key in the request. The values in JIRA will be overridden. E.g.: { "customfield_70000": [ "jira-administrators", "jira-software-users" ]}.

Refer to the JIRA REST API for supported parameters for create issue API. Example formats for this parameter are:

Single value field: {"customfield_10000": "value"} (e.g. {"customfield_1212": "Epic Name"} where customfield_1212 is a custom field for Epic Name;
Multiple values field: {"customfield_10042": [{"value": "8.0"}, {"value": "8.0.1"}]};
Link to another object: {"parent": {"id": "TEST-1"}} (for creating sub-task, for exampple).

Transition Action

Action to change issue status, e.g. "Close", "Reopen". To read more about workflows, please refer to Working with workflows documentation.

To get a list of available transitions for a particular issue, use Get Transitions REST API call.

A sample call:

curl -u user:password http://myinstance:8080/rest/api/2/issue/TEST-1/transitions

{
   "transitions" : [
      {
         "to" : { ... },
         "name" : "Start Progress"
      },
      {
         "to" : { ... },
         "id" : "21",
         "name" : "Done"
      }
   ]
}

Comment

Comment to add to the found issues. If left blank, no comment will be added. JIRA markup can be used here, e.g.

Added by Job
{color:red}
$[/myJob/id]
{color}

Please refer to JIRA Formatting documentation.

Add Field Values

If checked, issues fields that can contains multiple items (e.g. Labels, Affect Versions), except the custom ones, will be extended with new values instead of being replaced.

Result Property

Property sheet or property name to store results. /myJob/updatedIssues by default.

Result Format

Format to store results, JSON or property sheet. Retrieved jiras will be saved under this property. Please refer to Result Format documentation.

Create Summary Link?

If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.

Summary link property

Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Updated Issues Report

Summary link title

Title for a link to download a report. Default value: Download Report

LinkIssues and UpdateIssues procedures can be used together to update issues, that were mentioned in the SCM logs.

Sample Form:

Job has finished:

Sample Log:

Sample report:

Output Parameter (CloudBees CD/RO 8.3+)	Description
jirareporturl	URL (CloudBees CD/RO relative) to HTML JIRA Report
jiraids	Comma-separated list of issue IDS that were involved into the request

Output Parameter (CloudBees CD/RO 8.3+)

Description

jirareporturl

URL (CloudBees CD/RO relative) to HTML JIRA Report

jiraids

Comma-separated list of issue IDS that were involved into the request

GetProjectVersions

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

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
Project Key	Specify JIRA project key or id to retrieve versions from.
Version Name(s)	List of comma-separated version names to be showed. Useful if you want receive info about specific version or versions. Example: '1.0' or '1.0, 2.0, 3,0'.
Version Status	Retrieve only versions with specified status.
Max Results	Max number of versions to retrieve. Default value is defined by the JIRA instance (usually it is 50).
Order By	Name of the field to sort result list by. Prepend minus sign to use descending order. Values: description, name, releaseDate, sequence, startDate.
Show Issues Count by Status	If checked, count of issues by statuses will be included to version’s info and HTML report.
Result Format	Format to store results. This can be either a JSON or a property sheet. If you do not want to store results choose "Do not save the result". Please refer to Result format documentation.
Result Property Name	Name of the Property to store results, when the Result Format is chosen to be either JSON or a property sheet. By default the name is /myJob/getProjectVersionsResult.
Create Summary Link?	If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.
Summary link property	Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Queried Versions Report
Summary link title	Title for a link to download a report. Default value: Download Report

Parameter

Description

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

Project Key

Specify JIRA project key or id to retrieve versions from.

Version Name(s)

List of comma-separated version names to be showed. Useful if you want receive info about specific version or versions. Example: '1.0' or '1.0, 2.0, 3,0'.

Version Status

Retrieve only versions with specified status.

Max Results

Max number of versions to retrieve. Default value is defined by the JIRA instance (usually it is 50).

Order By

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

Show Issues Count by Status

If checked, count of issues by statuses will be included to version’s info and HTML report.

Result Format

Format to store results. This can be either a JSON or a property sheet.

If you do not want to store results choose "Do not save the result".

Please refer to Result format documentation.

Result Property Name

Name of the Property to store results, when the Result Format is chosen to be either JSON or a property sheet. By default the name is /myJob/getProjectVersionsResult.

Create Summary Link?

If checked, a report will be generated and a link will be attached to the job summary and to the pipeline summary.

Summary link property

Property to store a report will be generated and attached to the job/pipeline summary. Default value: JIRA Queried Versions Report

Summary link title

Title for a link to download a report. Default value: Download Report

Sample form:

Sample job has finished:

Sample logs:

Output Parameter (CloudBees CD/RO 8.3+)	Description
jirareporturl	URL (CloudBees CD/RO relative) to HTML JIRA Report
jiraids	Comma-separated list of version names that were involved into the request

Output Parameter (CloudBees CD/RO 8.3+)

Description

jirareporturl

URL (CloudBees CD/RO relative) to HTML JIRA Report

jiraids

Comma-separated list of version names that were involved into the request

CreateNewVersion

This procedure creates a new version in the specified project.

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
Project Key	JIRA project Key. A project key is the all capitals part before the issue number in JIRA.
Version Name	JIRA version to be created.

Parameter

Description

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

Project Key

JIRA project Key. A project key is the all capitals part before the issue number in JIRA.

Version Name

JIRA version to be created.

MarkVersionAsReleased

This procedure marks a specified version as released in the specified project.

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
Project Key	JIRA project Key. A project key is the all capitals part before the issue number in JIRA.
Version Name	JIRA version to be marked as released.

Parameter

Description

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

Project Key

JIRA project Key. A project key is the all capitals part before the issue number in JIRA.

Version Name

JIRA version to be marked as released.

CollectReportingData

Gathers reports from the specified JIRA instance.

Parameter	Description
Configuration Name	Provide the name of your EC-JIRA plugin configuration.
JIRA Filter ID	JIRA filter used to find the issues or defects in JIRA.
JIRA query	JQL to select issues. Either this parameter or "JIRA filter ID" must be specified.
Field mapping	JIRA fields that identify the release that the feature or defect is associated with. E.g., "fixVersions.name:releaseName, projectName:releaseProjectName". The identified fields will be used to populate the target fields identified in the report object association from feature to release. The record projectName:releaseProjectName means that field "projectName" from the JIRA will be mapped to field "releaseProjectName" into the reporting system.
Report object type	The type of the report object. Available values are feature, defect.
Fields to aggregate	The JIRA fields to aggregate on. For each group based on the status field and additional group by fields, the sum of each of the specified fields will be calculated and stored as separate fields. These fields are expected to be numeric fields. Each field can be optionally specified as "fieldName:featureFieldName" in which case the value will be stored as "featureFieldName".
Allow missing fields	If checked, the missing fields in Fields to aggregate the value will be considered as 0. For missing fields in Field Mapping the value will be set to null.
Metadata property path	Property sheet where run metadata will be stored. Optional field. If omited, /mySchedule/EC-JIRA-%JobName%-%Report Object Type% will be used for schedule contest. For all other contexts root is /myProject.
Transformation script	Allows user to provide perl script for payload customization. This method will be invoked by plugin with 3 parameters. 1st parameter is context object, 2nd is payload object, 3rd is the refined issue fields. Method should be named "transform", and should return payload object. In this example myTimestamp field will be added to payload object: # This method will be called for each payload after aggregate and mappings processing sub transform { my ($context, $payload, $refined) = @_; $payload->{myTimestamp} = $context->one(); return $payload; } # Example of the method added to the transformScript context object sub one { my ($context) = @_; return time(); }
Preview	If checked, no data will be sent to the reporting system. Use this option to preview gathered data.
Debug	If checked, the debug level will be set to "Debug".

Parameter

Description

Configuration Name

Provide the name of your EC-JIRA plugin configuration.

JIRA Filter ID

JIRA filter used to find the issues or defects in JIRA.

JIRA query

JQL to select issues. Either this parameter or "JIRA filter ID" must be specified.

Field mapping

JIRA fields that identify the release that the feature or defect is associated with. E.g., "fixVersions.name:releaseName, projectName:releaseProjectName". The identified fields will be used to populate the target fields identified in the report object association from feature to release. The record projectName:releaseProjectName means that field "projectName" from the JIRA will be mapped to field "releaseProjectName" into the reporting system.

Report object type

The type of the report object. Available values are feature, defect.

Fields to aggregate

The JIRA fields to aggregate on. For each group based on the status field and additional group by fields, the sum of each of the specified fields will be calculated and stored as separate fields. These fields are expected to be numeric fields. Each field can be optionally specified as "fieldName:featureFieldName" in which case the value will be stored as "featureFieldName".

Allow missing fields

If checked, the missing fields in Fields to aggregate the value will be considered as 0. For missing fields in Field Mapping the value will be set to null.

Metadata property path

Property sheet where run metadata will be stored. Optional field. If omited, /mySchedule/EC-JIRA-%JobName%-%Report Object Type% will be used for schedule contest. For all other contexts root is /myProject.

Transformation script

Allows user to provide perl script for payload customization. This method will be invoked by plugin with 3 parameters. 1st parameter is context object, 2nd is payload object, 3rd is the refined issue fields. Method should be named "transform", and should return payload object. In this example myTimestamp field will be added to payload object:

# This method will be called for each payload after aggregate and mappings processing
sub transform {
    my ($context, $payload, $refined) = @_;
    $payload->{myTimestamp} = $context->one();
    return $payload;
}

# Example of the method added to the transformScript context object
sub one {
    my ($context) = @_;
    return time();
}

Preview

If checked, no data will be sent to the reporting system. Use this option to preview gathered data.

Debug

If checked, the debug level will be set to "Debug".

The procedure retrieves issues from the JIRA, groups them by the specified fields, creates report payload and sends the payload into the reporting system. To associate issues with Feature or Defect object, "Field mapping" parameter must be specified.

Field mapping has a format of "jiraField:featureField", where "jiraField" is the name of the field in JIRA (e.g. "projectName") and the "featureField" is the name of the field in Feature/Defect, e.g. "releaseProjectName". Most common fields are:

projectName - the name of the JIRA project
statusName - string representation of the issue status, e.g. Opened
versions.name - string representation of Fix Versions field, e.g. 8.0
epicName - The name of the bound Epic, e.g. Reporting
issueTypeName - string representation of the issue type, e.g. Bug

Field names are case-insensitive. All available JIRA fields can be seen in the procedure logs, but some of them has type that is not compatible with mappings. If you need special handling, use transformScript with an additional (third) parameter.

Custom fields defined by the user will apear in the list of JIRA Fields based on the custom field name, lower cased and without spaces. In example, if custom field is:

    {"id": "customfield_10100",
    "key": "customfield_10100",
    "name": "TEST Custom Field",
    "custom": true,
    ...

It will appear as testcustomfield in the list of JIRA Fields.

To gather some summary data, like sum of storyPoints in the grouped issues, "Fields to aggregate" parameter must be specified. In case the parameter is empty, each issue will be sent as a separare report payload. Any field with numeric data can be used in this parameter. Mostly used fields are:

storyPoints - story points of the issues (stories, epics)
timeEstimate - estimated time for the issue

A refined issue can look like below:

$VAR1 = {
'acceptancecriteria' => undef,
'aggregateprogressprogress' => '',
'aggregateprogresstotal' => '',
'aggregatetimeestimate' => undef,
'aggregatetimeoriginalestimate' => undef,
'aggregatetimespent' => undef,
'assigneeactive' => 'true',
'businessvalue' => undef,
'components' => [],
'created' => '2017-07-10T08:52:04.000-0700',
'creatoractive' => 'true',
'creatorname' => 'name',
'customer' => undef,
'customeremail' => undef,
'description' => undef,
'docimpactid' => '10850',
'docimpactvalue' => 'Not Set',
'duedate' => '2017-07-12',
'engcategory' => undef,
'environment' => undef,
'epic/theme' => undef,
'epiclink' => undef,
'fixversions' => [
     {
       'archived' => bless( do{\(my $o = 0)}, 'JSON::XS::Boolean' ),
       'id' => '16703',
       'name' => '1.0.0',
       'released' => $VAR1->{'fixversions'}[0]{'archived'},
       'self' => 'http://some-jira.company.com/rest/api/2/version/16703'
     }
   ],
'flagged' => undef,
'id' => '80952',
'installerimpactid' => '10851',
'installerimpactself' => 'http://some-jira.company.com/rest/api/2/customFieldOption/10851',
'installerimpactvalue' => 'Not Set',
'issuelinks' => [],
'issuetypedescription' => 'Test jira',
'issuetypeiconurl' => 'http://some-jira.company.com/images/icons/issuetypes/story.png',
'issuetypeid' => '9',
'issuetypename' => 'Story',
'issuetypeself' => 'http://some-jira.company.com/rest/api/2/issuetype/9',
'issuetypesubtask' => '',
'key' => 'ECJIRA-12',
'keywords' => undef,
'labels' => [],
'lastviewed' => '2017-07-13T06:37:53.720-0700',
'milestoneid' => '10872',
'milestoneself' => 'http://some-jira.company.com/rest/api/2/customFieldOption/10872',
'milestonevalue' => 'Unassigned',
'operatingsystem' => [
     {
       'id' => '10031',
       'self' => 'http://some-jira.company.com/rest/api/2/customFieldOption/10031',
       'value' => 'All'
     }
   ],
'perforcejob' => 'true',
'priorityiconurl' => 'http://some-jira.company.com/images/icons/P2.gif',
'priorityid' => '2',
'priorityname' => 'P2',
'priorityself' => 'http://some-jira.company.com/rest/api/2/priority/2',
'progress' => '',
'progresstotal' => '',
'projectcategoryid' => '10030',
'projectcategoryname' => 'Sample project',
'projectcategoryself' => 'http://some-jira.company.com/rest/api/2/projectCategory/10030',
'projectid' => '12770',
'projectkey' => 'ECJIRA',
'projectname' => 'Jira Plugin',
'projectself' => 'http://some-jira.company.com/rest/api/2/project/12770',
'rank' => '1|i034ev:',
'rank(obsolete)' => '9223372036854775807',
'releaseversionhistory' => undef,
'reporteractive' => 'true',
'reporterdisplayname' => 'Someone',
'reporteremailaddress' => 'someone@mycompany.com',
'reportername' => 'Someone',
'resolution' => undef,
'resolutiondate' => undef,
'self' => 'http://some-jira.company.com/rest/api/2/issue/80952',
'severityid' => '10003',
'severityself' => 'http://some-jira.company.com/rest/api/2/customFieldOption/10003',
'severityvalue' => 'normal',
'sprint' => undef,
'statuscategorycolorname' => 'blue-gray',
'statuscategoryid' => '2',
'statuscategorykey' => 'new',
'statuscategoryname' => 'New',
'statuscategoryself' => 'http://some-jira.company.com/rest/api/2/statuscategory/2',
'statusdescription' => 'The issue is open and ready for the assignee to start work on it.',
'statusiconurl' => 'http://some-jira.company.com/images/icons/statuses/open.png',
'statusid' => '1',
'statusname' => 'Open',
'statusself' => 'http://some-jira.company.com/rest/api/2/status/1',
'subtasks' => [],
'summary' => 'Sample jira with delivery date',
'timeestimate' => undef,
'timeoriginalestimate' => undef,
'timespent' => undef,
'updated' => '2017-07-13T06:37:53.000-0700',
'versions' => [],
'votes' => '',
'voteshasvoted' => '',
'votesself' => 'http://some-jira.company.com/rest/api/2/issue/ECJIRA-12/votes',
'watchesiswatching' => 'true',
'watchesself' => 'http://some-jira.company.com/rest/api/2/issue/ECJIRA-12/watchers',
'watcheswatchcount' => '1',
'workratio' => -1
};

To put a top-level field into a payload, simply use its name, e.g. "projectkey:projectKey". To put a value from an array, use the dot syntax: "operatingsystem.value:operatingSystem" will result in {"operatingSystem": "All"} in the payload.

Result format

Several procedures support result saving. They save the list of issues created/updated/queried in two formats: JSON and Property Sheet.

If "Property Sheet" format is chosen, the result will be saved in form

%property%
    /issues
        /key -> MYJIRA-1
        /summary -> "Some summary"
        /type -> Bug
        /status -> Closed
        /assignee -> Admin
    /issueKeys -> MYJIRA-1

If there are no issues to save, the property is not created.

Here is the sample:

If JSON is chosen, the raw JSON response from JIRA API will be saved, e.g.

[
   {
      "fields" : {
         "versions" : [],
         "labels" : [],
         "duedate" : null,
         "timespent" : null,
         "timeoriginalestimate" : null,
         "updated" : "2017-10-24T00:32:32.000+0000",
         "description" : null,
         "lastViewed" : "2017-10-25T18:17:39.778+0000",
         "status" : {
            "name" : "To Do",
            "description" : "",
            "statusCategory" : {
               "name" : "To Do",
               "key" : "new",
               "colorName" : "blue-gray",
               ...
            }
         },
         "creator" : {
            "name" : "admin",
            "emailAddress" : "someone@mycompany.com",
            "key" : "admin",
            ...
         },
         "aggregatetimespent" : null,
         "resolution" : null,
         "issuelinks" : [],
         "summary" : "my summary",
         "aggregatetimeoriginalestimate" : null,
         "assignee" : { ... },
         "resolutiondate" : null,
         "fixVersions" : [],
         "subtasks" : [
            { ... }
         ],
         "issuetype" : {
            "name" : "Sub-task",
            "description" : "The sub-task of the issue",
            ....
         },
         "aggregateprogress" : { ... },
         "components" : [],
         "timeestimate" : null,
         "progress" : { ... },
         "watches" : { ... },
         "project" : { ... },
         "workratio" : -1,
         "aggregatetimeestimate" : null,
         "priority" : { ... },
         "reporter" : { ... },
         "created" : "2017-10-24T00:32:32.000+0000",
         "environment" : null,
         "votes" : { ... }
      },
      "id" : "10100",
      "self" : "http://myinstance/rest/api/2/issue/10100",
      "key" : "TEST-2"
   }
]

Here is the example of full JSON.

Examples

Updating issues based on SCM logs

Create a procedure with three steps:

The first steps checks out code from Git
The second step is LinkIssues procedure from EC-JIRA plugin:

It reads the property "/myJob/ecscm_changeLogs", which is to be set by the previous step, and writes it’s results into "/myJob/issueLinks" property sheet. . The third step is UpdateIssues procedure from EC-JIRA plugin:

It reads issue keys from the property "/myJob/issueLinks/issueKeys", which is to be set by the previous step and uses these keys as a part of JQL.

Run the procedure:

View the logs:

View the report:

Release notes

EC-JIRA 2.3.0

Added the possibility to customize properties and titles for attached reports in the pipeline summary.
Fixed an issue when the plugin could not assign a new ticket or update an existing one to a user in cloud-based JIRA.
Fixed an issue with processing redirection HTTP response status codes.

EC-JIRA 2.2.0

Added Personal Access Token authentication support.

EC-JIRA-2.1.2

Fixed issue with resolvedOn field not being retrieved for DevOps Insight configurations created for RCC.

EC-JIRA 2.1.1

Fixed parsing assignees received from Jira Cloud.
Fixed the "ignore SSL errors" flag for reporting.

EC-JIRA 2.1.0

Resource for checking connection has been added.

EC-JIRA 2.0.4

Fixed updating subtasks with additional parameters.

EC-JIRA 2.0.3

Updated the documentation about testing on v8.x environment.

EC-JIRA 2.0.2

Added "ignore SSL errors" flag and allowed accepting self-signed certificates.

EC-JIRA 2.0.1

Set minimal required server version to 10.3 to avoid issues with the old perl.

EC-JIRA 2.0.0

The plugin is switched to Perl version 5.31. No backward compatibility with releases prior 10.3. Starting from this release new agent is required to run this plugin’s procedures.

EC-JIRA 1.10.1

Fixed support for the new plugin configurations created with UI.

EC-JIRA 1.10.0

Added support for the new plugin configurations.

EC-JIRA 1.9.0

New procedure: Create New Version has been added to the plugin.
New procedure: Mark Version As Released has been added to the plugin.

EC-JIRA 1.8.3

The issue when UpdateIssue procedure did not work correctly on some environments with custom fields has been fixed.
Adapt procedure CreateIssues for changes in Jira versions 8.4 and later

EC-JIRA 1.8.2

A bug when the Collect Reporting Data procedure was sending the incorrect configuration name in the DOIS payload has fixed.

EC-JIRA 1.8.1

Fixed an issue when on some old setups EditConfiguration did not work properly.

EC-JIRA 1.8.0

Plugin configuration has been improved to support external credentials.

EC-JIRA 1.7.1

Migrated documentation to the documentation site.

EC-JIRA 1.7.0

Added Fix Versions: To procedures CreateIssues and UpdateIssues.

EC-JIRA 1.6.8

Enhancement for the CollectReportingData procedure:
- The transform() method receives additional parameter - refined issue fields.

EC-JIRA 1.6.7

The error-resistant design for the PEM RSA private key handling:
- Checking the correctness of the base64 key body.
- Checking and correcting the begin and end markers.
- Checking and correcting the number of pads.
Renaming to "CloudBees CD/RO".

EC-JIRA 1.6.6

Provide details on the expected RSA key format.

EC-JIRA 1.6.5

CreateConfiguration: improve check connection, add diagnostics and capturing errors.

EC-JIRA 1.6.4

User experience for CreateConfiguration/EditConfiguration was enhanced.
Updated check connection logic due to changes in JIRA REST API.

EC-JIRA 1.6.3

Fixed bugs with UTF-8 characters in CreateIssues, UpdateIssues and GetIssues procedures.

EC-JIRA 1.6.2

Fixed minor issue with a configuration form when warning was displayed when the widget was opened.

EC-JIRA 1.6.1

Renaming to "CloudBees"
Fixed the issue with lost output parameters for 9.0: upon upgrade or clean install of 9.0 output parameters were not created for the plugin’s procedures.

EC-JIRA 1.6.0

A new parameter "Add Field Values" has been added to the UpdateIssues procedure to allow appending values for the fields 'Labels' and 'Versions'.

EC-JIRA 1.5.0

Promotion time has been improved.
Support of Release Command Center 9.0 has been added.

EC-JIRA 1.4.0

A new procedure called GetProjectVersions which returns one or more versions of a project based on different criteria has been added.
GetIssues procedure now has an option allowing users choose not to save results to a properties, that can be used for performance optimization when query results are huge.

EC-JIRA 1.3.0

Support for Authentication to JIRA using OAUTH 1.0 has been provided. Refer to link:https://datatracker.ietf.org/doc/html/rfc5849 for OAUTH 1.0 and Atlassian REST API OAuth Configuration. for JIRA’s implementation of OAUTH.
Procedure GetIssues can now retrieve additional issue fields as part of the existing HTML report, based on what the user specifies in a new parameter called "Field List to Save?".
For better usability and consistency non-required procedure parameters which were earlier showing placeholder values in text areas have been now made blank.
Gaps where output parameters 'jiraids' and 'jirareporturl' are not set in certain places, have been fixed.
Previously deprecated procedures CreateIssue and UpdateIssue procedures are now officially removed.

EC-JIRA 1.2.0

Support for HTTP Proxy has been provided. Customers who use HTTP proxy can specify Proxy Information (Host, Port and Credentials at the configuration level) and all procedures will use the Proxy as second credentials for authentication.

EC-JIRA 1.1.4

JIRA URL was fixed in the issues report (for URLs with path segments). E.g., if jira endpoint is represented in way http://endpoint:port/jira, "jira" part was omitted.
Plugin uptake for certain Electric Flow 8.4 features. Changes include adding an icon for Dashboards and ability to create configurations inline.

EC-JIRA 1.1.3

Fixed logic for processing fields with the symbol '=' in them (Reporting).
LinkIssues procedure now can process issues with summary longer than 255 symbols.
Plugin uptake for all the following features which are available with Electric Flow versions beginning 8.3.
- Rendering of Procedure Parameters entirely based on configured form XMLs and ability to manage plugin configurations inline as part of a process step or pipeline stage task.
- Setting output parameter jiraids as part of plugin procedures
- Setting output parameter jirareporturl with URL to generated HTML reports, as part of plugin procedures.

EC-JIRA 1.1.2

Parameter "Create Link" was renamed to "Create Summary Link".

EC-JIRA 1.1.1

CreateIssues, GetIssues, UpdateIssues and LinkIssues procedures were added.
CreateIssue and UpdateIssue procedures were deprecated.
Test Connection and Log Level support were added into configuration.

EC-JIRA 1.0.1

Drill-down feature was added for CollectReportingData.

EC-JIRA 1.0.0

Jira integration and Reporting, first release.