mlx.jira-juggler 3.5.0

Goal

When using JIRA to track your project, and tasks/issues are estimated using the time-tracking plugin, this python module can convert the JIRA tasks to a gantt chart using the TaskJuggler tool.

The tool supports both flat task lists and hierarchical task structures. With the hierarchical mode enabled, Epics become parent tasks containing their child Stories and Sub-tasks, creating properly nested TaskJuggler task structures with automatic effort rollup from children to parents.

Installation

Installation from PyPI:

pip install mlx.jira-juggler

Usage

See help from python module:

jira-juggler -h

By default, the following endpoint for the JIRA API is used: https://melexis.atlassian.net. The script will ask you to input your email address (or username) and API token (or password). These three variables can be configured by setting them in a .env file. This .env file shall be located in the directory where pip has installed the package. You can find an example configuration in .env.example. JIRA Cloud requires the combination of email address and API token, while JIRA Server might accept a username and password.

Basic Usage:

jira-juggler -q "project = MYPROJECT" -o output.tjp

Hierarchical Epic Support:

To enable hierarchical task structures with Epics, Stories, and Sub-tasks, use the -E or --enable-epics flag:

jira-juggler -q "project = MYPROJECT" -E -o hierarchical_output.tjp

This will create nested TaskJuggler tasks where:

• Epics become parent tasks containing their child Stories

• Stories become parent tasks containing their child Sub-tasks

• Effort is automatically rolled up from children to parents

• Proper indentation is used for nested task structures

Example Hierarchical Output:

task EPIC_123 "User Management" {
    Jira "EPIC-123"
    allocate product_owner
    effort 5.0d

    task STORY_456 "User Authentication" {
        Jira "STORY-456"
        allocate backend_dev
        effort 3.0d

        task SUB_789 "Login API" {
            Jira "SUB-789"
            allocate backend_dev
            effort 1.0d
        }
    }
}

Command-line Options

Key command-line options include:

• -q, --query: Required. JQL query to fetch issues from JIRA

• -o, --output: Output .tjp file (default: jira_export.tjp)

• -E, --enable-epics: NEW. Enable hierarchical Epic/Story/Sub-task support

• -D, --depend-on-preceding: Make tasks depend on preceding task with same assignee

• -s, --sort-on-sprint: Sort tasks by sprint field (e.g., customfield_10851)

• -w, --weeklymax: Workdays per week for time calculations (default: 5.0)

• -L, --links: Specify issue link types for dependencies

• -l, --loglevel: Logging level (default: warning)

Run jira-juggler -h for complete help.

Comparison Example:

Without -E (flat output):

task EPIC_123 "User Management" { ... }
task STORY_456 "User Authentication" { ... }
task SUB_789 "Login API" { ... }

With -E (hierarchical output):

task EPIC_123 "User Management" {
    task STORY_456 "User Authentication" {
        task SUB_789 "Login API" { ... }
    }
}

Limitations

• When two tasks end on the same date and time, TaskJuggler won’t necessarily preserve the order in which the tasks appear in jira-juggler’s output.

• Hierarchical mode: Epic hierarchy is only enabled with the -E flag. By default, all tasks are output as a flat list to maintain backward compatibility.

• Effort rollup: When using hierarchical mode, parent task efforts are automatically calculated from their children. Manual effort estimates on parent tasks (Epics/Stories with children) may be overridden by the rollup calculation.