.. image:: https://img.shields.io/hexpm/l/plug.svg
:target: http://www.apache.org/licenses/LICENSE-2.0
=============================
JIRA to TaskJuggler Convertor
=============================
Tool for converting a set of JIRA tasks to TaskJuggler (TJ3) syntax, with support for hierarchical task structures including Epics, Stories, and Sub-tasks.
----
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 <http://taskjuggler.org/>`_ 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:
.. code::
pip install mlx.jira-juggler
-----
Usage
-----
See help from python module:
.. code::
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:**
.. code::
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:
.. code::
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:**
.. code::
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
}
}
}
.. note::
To include resolved **and** unresolved tasks while excluding invalid tasks, you can add the following logic to the
value for the `--query` argument: `(resolution != Invalid OR resolution = Unresolved)`.
.. warning::
The generated tj3-file, can at the moment not be parsed by TaskJuggler directly. Only the tasks are exported
to the tj3-file. The list of tasks needs to be embedded in a complete tj3-file. See the
`TaskJuggler website <http://taskjuggler.org/>`_ for more details.
.. note::
Unresolved tasks with logged time, i.e. time spent, will have their 'start' property set to the set current date
and time minus the logged time, calculated with 8 hours per workday and a default of 5 allocated workdays per week
with the day(s) off ending on Sunday. The latter number can be changed.
.. note::
**Epic and Hierarchy Detection**: The tool automatically detects hierarchical relationships through:
- **Epic relationships**: Stories/Tasks linked to Epics via ``epic``, ``epiclink``, or custom fields like ``customfield_10014``
- **Parent-child relationships**: Sub-tasks linked to their parent Stories/Tasks via the ``parent`` field
- **Issue types**: Automatic detection of Epic and Sub-task issue types
Only tasks included in your query results will be part of the hierarchy. Child tasks without their parents in
the query results will appear as standalone top-level tasks.
--------------------
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "mlx.jira-juggler",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Jira, taskjuggler, gantt, project planning, planning, software engineering",
"author": null,
"author_email": "Jasper Craeghs <jce@melexis.com>",
"download_url": null,
"platform": null,
"description": ".. image:: https://img.shields.io/hexpm/l/plug.svg\n :target: http://www.apache.org/licenses/LICENSE-2.0\n\n=============================\nJIRA to TaskJuggler Convertor\n=============================\n\nTool for converting a set of JIRA tasks to TaskJuggler (TJ3) syntax, with support for hierarchical task structures including Epics, Stories, and Sub-tasks.\n\n----\nGoal\n----\n\nWhen using JIRA to track your project, and tasks/issues are estimated using the time-tracking plugin, this python\nmodule can convert the JIRA tasks to a gantt chart using the `TaskJuggler <http://taskjuggler.org/>`_ tool.\n\nThe tool supports both flat task lists and hierarchical task structures. With the hierarchical mode enabled,\nEpics become parent tasks containing their child Stories and Sub-tasks, creating properly nested TaskJuggler\ntask structures with automatic effort rollup from children to parents.\n\n------------\nInstallation\n------------\n\nInstallation from PyPI:\n\n.. code::\n\n pip install mlx.jira-juggler\n\n-----\nUsage\n-----\n\nSee help from python module:\n\n.. code::\n\n jira-juggler -h\n\nBy default, the following endpoint for the JIRA API is used: *https://melexis.atlassian.net*.\nThe script will ask you to input your email address (or username) and API token (or password). These three\nvariables can be configured by setting them in a *.env* file. This *.env* file shall be located in the directory where\npip has installed the package. You can find an example configuration in *.env.example*. JIRA Cloud requires the\ncombination of email address and API token, while JIRA Server might accept a username and password.\n\n**Basic Usage:**\n\n.. code::\n\n jira-juggler -q \"project = MYPROJECT\" -o output.tjp\n\n**Hierarchical Epic Support:**\n\nTo enable hierarchical task structures with Epics, Stories, and Sub-tasks, use the ``-E`` or ``--enable-epics`` flag:\n\n.. code::\n\n jira-juggler -q \"project = MYPROJECT\" -E -o hierarchical_output.tjp\n\nThis will create nested TaskJuggler tasks where:\n\n- Epics become parent tasks containing their child Stories\n- Stories become parent tasks containing their child Sub-tasks\n- Effort is automatically rolled up from children to parents\n- Proper indentation is used for nested task structures\n\n**Example Hierarchical Output:**\n\n.. code::\n\n task EPIC_123 \"User Management\" {\n Jira \"EPIC-123\"\n allocate product_owner\n effort 5.0d\n\n task STORY_456 \"User Authentication\" {\n Jira \"STORY-456\"\n allocate backend_dev\n effort 3.0d\n\n task SUB_789 \"Login API\" {\n Jira \"SUB-789\"\n allocate backend_dev\n effort 1.0d\n }\n }\n }\n\n.. note::\n\n To include resolved **and** unresolved tasks while excluding invalid tasks, you can add the following logic to the\n value for the `--query` argument: `(resolution != Invalid OR resolution = Unresolved)`.\n\n.. warning::\n\n The generated tj3-file, can at the moment not be parsed by TaskJuggler directly. Only the tasks are exported\n to the tj3-file. The list of tasks needs to be embedded in a complete tj3-file. See the\n `TaskJuggler website <http://taskjuggler.org/>`_ for more details.\n\n.. note::\n\n Unresolved tasks with logged time, i.e. time spent, will have their 'start' property set to the set current date\n and time minus the logged time, calculated with 8 hours per workday and a default of 5 allocated workdays per week\n with the day(s) off ending on Sunday. The latter number can be changed.\n\n.. note::\n\n **Epic and Hierarchy Detection**: The tool automatically detects hierarchical relationships through:\n\n - **Epic relationships**: Stories/Tasks linked to Epics via ``epic``, ``epiclink``, or custom fields like ``customfield_10014``\n - **Parent-child relationships**: Sub-tasks linked to their parent Stories/Tasks via the ``parent`` field\n - **Issue types**: Automatic detection of Epic and Sub-task issue types\n\n Only tasks included in your query results will be part of the hierarchy. Child tasks without their parents in\n the query results will appear as standalone top-level tasks.\n\n--------------------\nCommand-line Options\n--------------------\n\nKey command-line options include:\n\n- ``-q, --query``: **Required**. JQL query to fetch issues from JIRA\n- ``-o, --output``: Output .tjp file (default: jira_export.tjp)\n- ``-E, --enable-epics``: **NEW**. Enable hierarchical Epic/Story/Sub-task support\n- ``-D, --depend-on-preceding``: Make tasks depend on preceding task with same assignee\n- ``-s, --sort-on-sprint``: Sort tasks by sprint field (e.g., customfield_10851)\n- ``-w, --weeklymax``: Workdays per week for time calculations (default: 5.0)\n- ``-L, --links``: Specify issue link types for dependencies\n- ``-l, --loglevel``: Logging level (default: warning)\n\nRun ``jira-juggler -h`` for complete help.\n\n**Comparison Example:**\n\nWithout ``-E`` (flat output):\n::\n\n task EPIC_123 \"User Management\" { ... }\n task STORY_456 \"User Authentication\" { ... }\n task SUB_789 \"Login API\" { ... }\n\nWith ``-E`` (hierarchical output):\n::\n\n task EPIC_123 \"User Management\" {\n task STORY_456 \"User Authentication\" {\n task SUB_789 \"Login API\" { ... }\n }\n }\n\n-----------\nLimitations\n-----------\n\n- When two tasks end on the same date and time, TaskJuggler won't necessarily preserve the order in which the tasks\n appear in jira-juggler's output.\n\n- **Hierarchical mode**: Epic hierarchy is only enabled with the ``-E`` flag. By default, all tasks are output as a flat list\n to maintain backward compatibility.\n\n- **Effort rollup**: When using hierarchical mode, parent task efforts are automatically calculated from their children.\n Manual effort estimates on parent tasks (Epics/Stories with children) may be overridden by the rollup calculation.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python script for extracting data from Jira, and converting to TaskJuggler (tj3) output",
"version": "3.5.0",
"project_urls": {
"Homepage": "https://github.com/melexis/jira-juggler",
"Repository": "https://github.com/melexis/jira-juggler"
},
"split_keywords": [
"jira",
" taskjuggler",
" gantt",
" project planning",
" planning",
" software engineering"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ecfd2eb33898a07d74e69f80b9af4ed7382e5443328f1ff343b2ae1ba18c34f2",
"md5": "79bb4b7c87344aab7565dbf3e045fbf8",
"sha256": "22c333e2c1ef48f57a9c20e4acb6fbbfd2b419d84fb10547fd526445f4f9e060"
},
"downloads": -1,
"filename": "mlx_jira_juggler-3.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "79bb4b7c87344aab7565dbf3e045fbf8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 20787,
"upload_time": "2025-09-15T10:23:51",
"upload_time_iso_8601": "2025-09-15T10:23:51.916265Z",
"url": "https://files.pythonhosted.org/packages/ec/fd/2eb33898a07d74e69f80b9af4ed7382e5443328f1ff343b2ae1ba18c34f2/mlx_jira_juggler-3.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-15 10:23:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "melexis",
"github_project": "jira-juggler",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mlx.jira-juggler"
}
JSON
