3 minutes to read
exportJiraIssues
At a Glance
About This Task
This task exports all issues for a given query or queries from Jira as either an AsciiDoc table, an Excel file or both.
The configuration for this task can be found within Config.gradle
(gradle.properties
can be used as a fallback).
Username/password is deprecated, so you need to use username/API-token instead.
An API-token can be created through https://id.atlassian.com/manage/api-tokens. We recommend that you keep username and API-token out of your GitHub repository, and instead pass them as environment variables to docToolchain.
Migrate configuration to version >= 3.2.0
Since version 3.2.0, the configuration requests
is deprecated. Please migrate to and use exports
instead. The old configuration will be removed in the near future.
To migrate your configuration, replace the JiraRequest class with a Map. The following example shows how to migrate a configuration with a single JiraRequest to the new configuration:
jira.requests = [
new JiraRequest(
filename: 'jiraIssues',
jql: 'project = %jiraProject% AND labels = %jiraLabel%',
customfields: [
'customfield_10026': 'StoryPoints'
]
)
]
will be migrated to:
jira.exports = [
[
filename: 'jiraIssues',
jql: 'project = %jiraProject% AND labels = %jiraLabel%',
customfields: [
'customfield_10026': 'StoryPoints'
]
]
]
Configuration
Jira configuration support list requests to Jira where results of each requests will be saved in a file with specifies filename. Flags saveAsciidoc & saveExcel allow you to easily configure the format in which results should be saved.
Deprecation Notice
-
The old configuration was based on the single Jira query is deprecated (single 'jql' parameter). Support for it will be removed in the near future. Please migrate to the new configuration which allows multiple Jira queries.
-
Since version 3.2.0, the configuration
requests
is deprecated. Please migrate to and useexports
instead. The old configuration will be removed in the near future.
Configuration Options
exports (since 3.2.0), List of Maps that contains the following keys:
-
filename
: The filename of the exported file. The file extension will be added automatically. -
jql
: The Jira query to be executed. Can have placeholders that are interpolated. Allowed placeholders are:%jiraProject%
(interpolated withjira.project
),%jiraLabel%
(interpolated withjira.label
) -
customfields
: A Map of custom fields to be included in the export. Key is the technical name of the custom field in Jira, value is the name of the column in the export.
rateLimit (since 3.2.0), The rate limit for Jira requests. Default is 10 requests per second.
requests (deprecated since 3.2.0, please use exports
instead),
List of JiraRequest that has the following properties:
class JiraRequest {
String filename //filename (without extension) of the file in which JQL results will be saved. Extension will be determined automatically for Asciidoc or Excel file
String jql // Jira Query Language syntax
Map<String,String> customfields // map of customFieldId:displayName values for Jira fields which don't have default names, i.e. customfield_10026:StoryPoints
}
Full configuration options:
// Configuration for Jira related tasks
jira = [:]
jira.with {
// endpoint of the JiraAPI (REST) to be used
api = 'https://your-jira-instance'
// requests per second for Jira API calls
rateLimit = 10
/*
WARNING: It is strongly recommended to store credentials securely instead of commiting plain text values to your git repository!!!
Tool expects credentials that belong to an account which has the right permissions to read the JIRA issues for a given project.
Credentials can be used in a form of:
- passed parameters when calling script (-PjiraUser=myUsername -PjiraPass=myPassword) which can be fetched as a secrets on CI/CD or
- gradle variables set through gradle properties (uses the 'jiraUser' and 'jiraPass' keys)
Often, Jira & Confluence credentials are the same, in which case it is recommended to pass CLI parameters for both entities as
-Pusername=myUser -Ppassword=myPassword
*/
// the key of the Jira project
project = 'PROJECTKEY'
// the format of the received date time values to parse
dateTimeFormatParse = "yyyy-MM-dd'T'H:m:s.SSSz" // i.e. 2020-07-24'T'9:12:40.999 CEST
// the format in which the date time should be saved to output
dateTimeFormatOutput = "dd.MM.yyyy HH:mm:ss z" // i.e. 24.07.2020 09:02:40 CEST
// the label to restrict search to
label = 'label1'
// Legacy settings for Jira query. This setting is deprecated & support for it will soon be completely removed. Please use JiraRequests settings
jql = "project='%jiraProject%' AND labels='%jiraLabel%' ORDER BY priority DESC, duedate ASC"
// Base filename in which Jira query results should be stored
resultsFilename = 'JiraTicketsContent'
saveAsciidoc = true // if true, asciidoc file will be created with *.adoc extension
saveExcel = true // if true, Excel file will be created with *.xlsx extension
// Output folder for this task inside main outputPath
resultsFolder = 'JiraRequests'
/*
List of requests to Jira API:
These are basically JQL expressions bundled with a filename in which results will be saved.
User can configure custom fields IDs and name those for column header,
i.e. customfield_10026:'Story Points' for Jira instance that has custom field with that name and will be saved in a coloumn named "Story Points"
*/
exports = [
[
filename:"File1_Done_issues",
jql:"project='%jiraProject%' AND status='Done' ORDER BY duedate ASC",
customfields: [customfield_10026:'Story Points']
],
[
filename:'CurrentSprint',
jql:"project='%jiraProject%' AND Sprint in openSprints() ORDER BY priority DESC, duedate ASC",
customfields: [customfield_10026:'Story Points']
]
]
}
Source
task exportJiraIssues(
description: 'exports all jira issues from a given search',
group: 'docToolchain'
) {
doLast {
config.targetDir = targetDir
new ExportJiraIssuesTask(config).execute()
}
}
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.