# Jira to Confluence gantt chart generator
[](https://github.com/cledouarec/jira2confluence-gantt/actions/workflows/lint.yaml)
[](https://github.com/cledouarec/jira2confluence-gantt/actions/workflows/test.yaml)
**Table of Contents**
* [Overview](#Overview)
* [Installation](#Installation)
* [Usage](#Usage)
* [Configuration](#Configuration)
* [Server configuration](#Server-configuration)
* [Project configuration](#Project-configuration)
## Overview
This module has the objective to create a gantt chart from Jira data and
publish and publish the resulting chart and status on Confluence.
It provides different render engines, but it is easy to add its own custom
engine :
## Installation
### From PyPI (Recommended)
You can install the exporter easily with the following command or insert into
your requirements file :
```shell
pip install jira2confluence-gantt
```
### From sources
All the project is managed with **Poetry**. To install it, please visit the
[official page](https://python-poetry.org/docs/#installation) and follow these
instructions :
```shell
poetry shell
poetry install --without dev
```
For the developers, it is useful to install extra tools like :
* [commitizen](https://commitizen-tools.github.io/commitizen/)
* [pre-commit](https://pre-commit.com)
* [pytest](http://docs.pytest.org)
* [ruff](https://docs.astral.sh/ruff/)
These tools can be installed with the following command :
```shell
poetry install
```
The Git hooks can be installed with :
```shell
poetry run pre-commit install
```
The hooks can be run manually at any time :
```shell
poetry run pre-commit run --all-file
```
## Usage
The script with required argument can be started by executing the following
command :
```shell
jira2confluence-gantt my_config.yaml
```
The full list of arguments supported can be displayed with the following
helper :
```shell
jira2confluence-gantt -h
usage: jira2confluence-gantt [-h] [-v] [config.yaml]
positional arguments:
config.yaml Configuration file
options:
-h, --help show this help message and exit
-v, --verbose Verbose mode
```
## Configuration
The configuration file support 2 formats :
- [YAML format](https://yaml.org) (Recommended format)
- [JSON format](https://www.json.org)
In the configuration file, there are 2 main sections required :
- Server
- Projects
### Server configuration
The **server** node will configure the URL of the Jira and Confluence server.
For the moment, only the username/token authentication is supported.
The credentials could be defined with environment variables or `.env` file.
```
ATLASSIAN_USER=<your login>
ATLASSIAN_TOKEN=<your token>
```
**_In Yaml :_**
```yaml
server:
jira: "https://my.jira.server.com"
confluence: "https://my.confluence.server.com"
```
**_In Json :_**
```json
{
"server": {
"jira": "https://my.jira.server.com",
"confluence": "https://my.confluence.server.com"
}
}
```
| Attribute | Required | Description |
|------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------|
| server | ✅ | Main configuration node for server. |
| jira | ✅ | Jira server URL to retrieve tickets information. |
| confluence | ❌ | Confluence server URL to publish the report. If the confluence server isn't set, only the gantt chart will be generated if the engine permit it. |
### Project configuration
The `projects` node will provide the configuration for each project.
**_In Yaml :_**
```yaml
projects:
- name: "Project name"
jql: "project = TEST"
report:
space: "SPACE"
parent_page: "My Parent Page"
engine: "PlantUML"
legend: True
template: "report.jinja2"
fields:
start_date: "Start date (WBSGantt)"
end_date: "Finish date (WBSGantt)"
progress: "Progress (WBSGantt)"
link: "is blocked by"
```
**_In Json :_**
```json
{
"projects": [
{
"name": "Project name",
"jql": "project = TEST",
"report": {
"space": "SPACE",
"parent_page": "My Parent Page",
"engine": "PlantUML",
"legend": true,
"template": "report.jinja2"
},
"fields": {
"start_date": "Start date (WBSGantt)",
"end_date": "Finish date (WBSGantt)",
"progress": "Progress (WBSGantt)",
"link": "is blocked by"
}
}
]
}
```
| Attribute | Required | Description |
|-----------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------|
| projects | ✅ | Main configuration node for all projects. |
| name | ✅ | Name of the project.<br/>This name will be used as a title in the Gantt chart and also as a name in Snake case format for the output gantt file. |
| jql | ✅ | [JQL](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) query to retrieve the list of tickets. |
| report | ✅ | Main configuration node for report generation. |
| fields | ✅ | Main configuration node for fields. |
Some attributes could use double quotes to preserve space in their names. The
YAML syntax provides a solution by replacing with simple quote or escaping
like JSON :
**_In Yaml :_**
```yaml
jql: 'project = "MY TEST"'
```
**_In Json :_**
```json
{
"jql": "project = \"MY TEST\""
}
```
#### Report configuration
Configuration node for all attributes related to report generation.
| Attribute | Required | Description |
|-------------|:--------:|----------------------------------------------------------------------------|
| space | ✅ | Confluence destination space. |
| parent_page | ✅ | Confluence parent page of the report page. |
| engine | ❌ | Engine used to create gantt report. **`Confluence` is the default engine** |
| legend | ❌ | Add a legend in the gantt chart. **By default the legend is not added. |
There are several engines available to produce Gantt chart :
- `Confluence` chart macro : Produce a chart with a builtin macro. The graph
will not include the dependency link.
- `PlantUML` macro : Produce a PlantUML graph which will be included in the
Confluence page with the PlantUML macro.
#### Fields
Configuration node for all Jira fields used to construct Gantt chart.
**It is a mandatory field.**
**_In Yaml :_**
These fields are most of the time the same for all projects and like all others
fields they could be aliased to avoid redefinition.
In the following example, we define an anchor `WbsFields` :
```yaml
Server:
# ...
Fields: &WbsFields
Start date: "Start date (WBSGantt)"
End date: "Finish date (WBSGantt)"
Progress: "Progress (WBSGantt)"
Projects:
Project name:
JQL: "project = TEST"
Fields: *WbsFields
Second project name:
JQL: "project = TEST2"
Fields: *WbsFields
```
**_In Json :_**
```json
{
"Projects": {
"Project name": {
"Fields": {
"Start date": "Start date (WBSGantt)",
"End date": "Finish date (WBSGantt)",
"Progress": "Progress (WBSGantt)",
}
}
}
}
```
#### Start date
Define the Jira field to use as a start date for task in Gantt chart.
**It is a mandatory field.**
#### End date
Define the Jira field to use as a start date for task in Gantt chart.
**It is a mandatory field.**
#### Progress
Define the Jira field to use as a percent of work done for task in Gantt chart.
**It is an optional field.**
#### Link
Define the Jira inward link to use in order to define how the tasks could be
blocked by others tasks task in Gantt chart.
**It is an optional field. By default, the link used is "is blocked by"**
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, shall be as defined in the Apache-2.0 license
without any additional terms or conditions.
See [CONTRIBUTING.md](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/cledouarec/jira2confluence-gantt",
"name": "jira2confluence-gantt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "project,management,visualization,gantt,jira,confluence,atlassian",
"author": "Christophe Le Douarec",
"author_email": "christophe.ledouarec@qorvo.com",
"download_url": "https://files.pythonhosted.org/packages/4f/de/3742f8a46dc86bf368a04dac625afe87a747f1bca5a18f01b92e43185229/jira2confluence_gantt-0.3.3.tar.gz",
"platform": null,
"description": "# Jira to Confluence gantt chart generator\n\n[](https://github.com/cledouarec/jira2confluence-gantt/actions/workflows/lint.yaml)\n[](https://github.com/cledouarec/jira2confluence-gantt/actions/workflows/test.yaml)\n\n**Table of Contents**\n* [Overview](#Overview)\n* [Installation](#Installation)\n* [Usage](#Usage)\n* [Configuration](#Configuration)\n * [Server configuration](#Server-configuration)\n * [Project configuration](#Project-configuration)\n\n## Overview\n\nThis module has the objective to create a gantt chart from Jira data and\npublish and publish the resulting chart and status on Confluence.\nIt provides different render engines, but it is easy to add its own custom\nengine :\n\n\n\n## Installation\n\n### From PyPI (Recommended)\n\nYou can install the exporter easily with the following command or insert into\nyour requirements file :\n```shell\npip install jira2confluence-gantt\n```\n\n### From sources\n\nAll the project is managed with **Poetry**. To install it, please visit the\n[official page](https://python-poetry.org/docs/#installation) and follow these\ninstructions :\n```shell\npoetry shell\npoetry install --without dev\n```\n\nFor the developers, it is useful to install extra tools like :\n* [commitizen](https://commitizen-tools.github.io/commitizen/)\n* [pre-commit](https://pre-commit.com)\n* [pytest](http://docs.pytest.org)\n* [ruff](https://docs.astral.sh/ruff/)\n\nThese tools can be installed with the following command :\n```shell\npoetry install\n```\nThe Git hooks can be installed with :\n```shell\npoetry run pre-commit install\n```\nThe hooks can be run manually at any time :\n```shell\npoetry run pre-commit run --all-file\n```\n\n## Usage\n\nThe script with required argument can be started by executing the following\ncommand :\n```shell\njira2confluence-gantt my_config.yaml\n```\n\nThe full list of arguments supported can be displayed with the following\nhelper :\n```shell\njira2confluence-gantt -h\nusage: jira2confluence-gantt [-h] [-v] [config.yaml]\n\npositional arguments:\n config.yaml Configuration file\n\noptions:\n -h, --help show this help message and exit\n -v, --verbose Verbose mode\n```\n\n## Configuration\n\nThe configuration file support 2 formats :\n- [YAML format](https://yaml.org) (Recommended format)\n- [JSON format](https://www.json.org)\n\nIn the configuration file, there are 2 main sections required :\n- Server\n- Projects\n\n### Server configuration\n\nThe **server** node will configure the URL of the Jira and Confluence server.\nFor the moment, only the username/token authentication is supported.\nThe credentials could be defined with environment variables or `.env` file.\n\n```\nATLASSIAN_USER=<your login>\nATLASSIAN_TOKEN=<your token>\n```\n\n**_In Yaml :_**\n```yaml\nserver:\n jira: \"https://my.jira.server.com\"\n confluence: \"https://my.confluence.server.com\"\n```\n**_In Json :_**\n```json\n{\n \"server\": {\n \"jira\": \"https://my.jira.server.com\",\n \"confluence\": \"https://my.confluence.server.com\"\n }\n}\n```\n\n| Attribute | Required | Description |\n|------------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------|\n| server | \u2705 | Main configuration node for server. |\n| jira | \u2705 | Jira server URL to retrieve tickets information. |\n| confluence | \u274c | Confluence server URL to publish the report. If the confluence server isn't set, only the gantt chart will be generated if the engine permit it. |\n\n### Project configuration\n\nThe `projects` node will provide the configuration for each project.\n\n**_In Yaml :_**\n```yaml\nprojects:\n - name: \"Project name\"\n jql: \"project = TEST\"\n report:\n space: \"SPACE\"\n parent_page: \"My Parent Page\"\n engine: \"PlantUML\"\n legend: True\n template: \"report.jinja2\"\n fields:\n start_date: \"Start date (WBSGantt)\"\n end_date: \"Finish date (WBSGantt)\"\n progress: \"Progress (WBSGantt)\"\n link: \"is blocked by\"\n```\n**_In Json :_**\n```json\n{\n \"projects\": [\n {\n \"name\": \"Project name\",\n \"jql\": \"project = TEST\",\n \"report\": {\n \"space\": \"SPACE\",\n \"parent_page\": \"My Parent Page\",\n \"engine\": \"PlantUML\",\n \"legend\": true,\n \"template\": \"report.jinja2\"\n },\n \"fields\": {\n \"start_date\": \"Start date (WBSGantt)\",\n \"end_date\": \"Finish date (WBSGantt)\",\n \"progress\": \"Progress (WBSGantt)\",\n \"link\": \"is blocked by\"\n }\n }\n ]\n}\n```\n\n| Attribute | Required | Description |\n|-----------|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------|\n| projects | \u2705 | Main configuration node for all projects. |\n| name | \u2705 | Name of the project.<br/>This name will be used as a title in the Gantt chart and also as a name in Snake case format for the output gantt file. |\n| jql | \u2705 | [JQL](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) query to retrieve the list of tickets. |\n| report | \u2705 | Main configuration node for report generation. |\n| fields | \u2705 | Main configuration node for fields. |\n\nSome attributes could use double quotes to preserve space in their names. The\nYAML syntax provides a solution by replacing with simple quote or escaping\nlike JSON :\n\n**_In Yaml :_**\n```yaml\njql: 'project = \"MY TEST\"'\n```\n**_In Json :_**\n```json\n{\n \"jql\": \"project = \\\"MY TEST\\\"\"\n}\n```\n\n#### Report configuration\n\nConfiguration node for all attributes related to report generation.\n\n| Attribute | Required | Description |\n|-------------|:--------:|----------------------------------------------------------------------------|\n| space | \u2705 | Confluence destination space. |\n| parent_page | \u2705 | Confluence parent page of the report page. |\n| engine | \u274c | Engine used to create gantt report. **`Confluence` is the default engine** |\n| legend | \u274c | Add a legend in the gantt chart. **By default the legend is not added. |\n\nThere are several engines available to produce Gantt chart :\n- `Confluence` chart macro : Produce a chart with a builtin macro. The graph\n will not include the dependency link. \n \n- `PlantUML` macro : Produce a PlantUML graph which will be included in the\n Confluence page with the PlantUML macro.\n\n#### Fields\n\nConfiguration node for all Jira fields used to construct Gantt chart. \n**It is a mandatory field.**\n\n**_In Yaml :_**\n\nThese fields are most of the time the same for all projects and like all others\nfields they could be aliased to avoid redefinition. \nIn the following example, we define an anchor `WbsFields` :\n```yaml\nServer:\n # ...\n\nFields: &WbsFields\n Start date: \"Start date (WBSGantt)\"\n End date: \"Finish date (WBSGantt)\"\n Progress: \"Progress (WBSGantt)\"\n\nProjects:\n Project name:\n JQL: \"project = TEST\"\n Fields: *WbsFields\n Second project name:\n JQL: \"project = TEST2\"\n Fields: *WbsFields\n```\n\n**_In Json :_**\n```json\n{\n \"Projects\": {\n \"Project name\": {\n \"Fields\": {\n \"Start date\": \"Start date (WBSGantt)\",\n \"End date\": \"Finish date (WBSGantt)\",\n \"Progress\": \"Progress (WBSGantt)\",\n }\n }\n }\n}\n```\n\n#### Start date\n\nDefine the Jira field to use as a start date for task in Gantt chart. \n**It is a mandatory field.**\n\n#### End date\n\nDefine the Jira field to use as a start date for task in Gantt chart. \n**It is a mandatory field.**\n\n#### Progress\n\nDefine the Jira field to use as a percent of work done for task in Gantt chart. \n**It is an optional field.**\n\n#### Link\n\nDefine the Jira inward link to use in order to define how the tasks could be\nblocked by others tasks task in Gantt chart. \n**It is an optional field. By default, the link used is \"is blocked by\"**\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, shall be as defined in the Apache-2.0 license\nwithout any additional terms or conditions.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Gantt chart generator from Jira to Confluence",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://github.com/cledouarec/jira2confluence-gantt",
"Repository": "https://github.com/cledouarec/jira2confluence-gantt"
},
"split_keywords": [
"project",
"management",
"visualization",
"gantt",
"jira",
"confluence",
"atlassian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f278c1d70da94a0a3d3755b4a80f4043e7a37ca6857b9036459c01fd4ace216a",
"md5": "37fcbe4d3612c59d2645db92e894fecd",
"sha256": "288e77b2b19fc225b96c2653cee083d0ce8a11943b9a663b4d18e827a06d4961"
},
"downloads": -1,
"filename": "jira2confluence_gantt-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37fcbe4d3612c59d2645db92e894fecd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 20050,
"upload_time": "2024-03-07T23:06:33",
"upload_time_iso_8601": "2024-03-07T23:06:33.359717Z",
"url": "https://files.pythonhosted.org/packages/f2/78/c1d70da94a0a3d3755b4a80f4043e7a37ca6857b9036459c01fd4ace216a/jira2confluence_gantt-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4fde3742f8a46dc86bf368a04dac625afe87a747f1bca5a18f01b92e43185229",
"md5": "432a7fbcea6c49ac10f07a9406e97ffa",
"sha256": "cd3e11df1461fd397fa5344ba2e8dce3e5d3c75f86f5680fed488a9c2e783081"
},
"downloads": -1,
"filename": "jira2confluence_gantt-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "432a7fbcea6c49ac10f07a9406e97ffa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 19321,
"upload_time": "2024-03-07T23:06:34",
"upload_time_iso_8601": "2024-03-07T23:06:34.346929Z",
"url": "https://files.pythonhosted.org/packages/4f/de/3742f8a46dc86bf368a04dac625afe87a747f1bca5a18f01b92e43185229/jira2confluence_gantt-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-07 23:06:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cledouarec",
"github_project": "jira2confluence-gantt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jira2confluence-gantt"
}
JSON
