exportJiraIssues

Pascal Euhus Jody Winter Jody Winter Ralf D. Müller Vladi Vladi Alexander Schwartz

3 minutes to read

At a Glance

exportJiraIssues

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:

Prior to 3.2.0
jira.requests = [
   new JiraRequest(
      filename: 'jiraIssues',
      jql: 'project = %jiraProject% AND labels = %jiraLabel%',
      customfields: [
         'customfield_10026': 'StoryPoints'
      ]
   )
]

will be migrated to:

From 3.2.0 onwards
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 use exports 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 with jira.project), %jiraLabel% (interpolated with jira.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:

Config.groovy
// 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

exportJiraIssues.gradle
task exportJiraIssues(
        description: 'exports all jira issues from a given search',
        group: 'docToolchain'
) {
    doLast {
        config.targetDir = targetDir
        new ExportJiraIssuesTask(config).execute()
    }
}