This tool lets you represent Jira tasks as mermaid diagrams. For example, the CSV file epic-1.csv is represented as:
graph TD;
CCXDEV_0("CCXDEV-0 (In Progress)\nTool to generate diagrams based on Jira epics"):::IN_PROGRESS
CCXDEV_1["CCXDEV-1 (Closed)\nCreate the repository"]:::CLOSED
CCXDEV_1 -- Blocks --> CCXDEV_5
CCXDEV_2(("CCXDEV-2 (To Do)\nImporting mermaid diagrams into drawio doesn't inherit the styling")):::TODO
CCXDEV_2 -- Blocks --> CCXDEV_4
CCXDEV_3{"CCXDEV-3 (To Do)\nInvestigate how to group tasks in subgraphs"}:::TODO
CCXDEV_4("CCXDEV-4 (Code Review)\nAs a user I want to be able to move the nodes manually in a UI"):::CODE_REVIEW
CCXDEV_5["CCXDEV-5 (To Do)\nPush the code to the repo"]:::TODO
classDef TODO fill:#ff9933
classDef CLOSED fill:#33cc33
classDef IN_PROGRESS fill:#33ccff
classDef CODE_REVIEW fill:#ffff66
classDef REVIEW fill:#ffcc00
You don't need any dependencies apart from Python. I've used Python 3.11, but any version > 3.10 should work.
Install and authenticate the Atlassian CLI:
acli jira auth login
Then generate a diagram directly from Jira with a JQL query or saved filter:
❯ ./csv-to-mermaid.py --jql "project = MYPROJECT AND 'Epic Link' = MYPROJECT-123" > generated_mermaid_code.mmd
❯ ./csv-to-mermaid.py --filter 10001 > generated_mermaid_code.mmd
You can still pass a CSV export if you already have one:
❯ ./csv-to-mermaid.py --csv_file examples/epic-1.csv > generated_mermaid_code.mmd
Running the tool is as simple as this:
❯ ./csv-to-mermaid.py --help
usage: csv-to-mermaid.py [-h] [--csv_file CSV_FILE] [--ignore_links IGNORE_LINKS] [--task__shape_left TASK__SHAPE_LEFT] [--task__shape_right TASK__SHAPE_RIGHT]
[--bug__shape_left BUG__SHAPE_LEFT] [--bug__shape_right BUG__SHAPE_RIGHT] [--spike__shape_left SPIKE__SHAPE_LEFT] [--spike__shape_right SPIKE__SHAPE_RIGHT]
[--default__shape_left DEFAULT__SHAPE_LEFT] [--default__shape_right DEFAULT__SHAPE_RIGHT] [--todo__color TODO__COLOR] [--closed__color CLOSED__COLOR]
[--in_progress__color IN_PROGRESS__COLOR] [--code_review__color CODE_REVIEW__COLOR] [--review__color REVIEW__COLOR] [--default__color DEFAULT__COLOR]
[--graph_direction GRAPH_DIRECTION]
Generate Mermaid code from Jira issues.
options:
-h, --help show this help message and exit
--csv_file CSV_FILE Path to a Jira CSV file (default: issues.csv when no Jira query is provided)
--jql JQL JQL query used to fetch issues with acli
--filter FILTER Jira filter ID used to fetch issues with acli
--ignore_links IGNORE_LINKS
Links to ignore (default: ['Cloners'])
--task__shape_left TASK__SHAPE_LEFT
The task node's left shape (default: [)
--task__shape_right TASK__SHAPE_RIGHT
The task node's right shape (default: ])
--bug__shape_left BUG__SHAPE_LEFT
The bug node's left shape (default: (()
--bug__shape_right BUG__SHAPE_RIGHT
The bug node's right shape (default: )))
--spike__shape_left SPIKE__SHAPE_LEFT
The spike node's left shape (default: {)
--spike__shape_right SPIKE__SHAPE_RIGHT
The spike node's right shape (default: })
--default__shape_left DEFAULT__SHAPE_LEFT
The default node's left shape (default: ()
--default__shape_right DEFAULT__SHAPE_RIGHT
The default node's right shape when the task is not a task, spike or bug (default: ))
--todo__color TODO__COLOR
The TODO node color (default: #ff9933)
--closed__color CLOSED__COLOR
The CLOSED node color (default: #33cc33)
--in_progress__color IN_PROGRESS__COLOR
The IN PROGRESS node color (default: #33ccff)
--code_review__color CODE_REVIEW__COLOR
The CODE REVIEW node color (default: #ffff66)
--review__color REVIEW__COLOR
The REVIEW node color (default: #ffcc00)
--default__color DEFAULT__COLOR
The default node color (default: #f9f)
--graph_direction GRAPH_DIRECTION
The graph direction. Must be one of 'TD' or 'LR' (default: TD)
You can specify an input CSV and some links to ignore. By default it ignores the
Cloners because I personally find them quite useless. Regarding the node shapes,
you can find all the available shapes in https://mermaid.js.org/syntax/flowchart.html#node-shapes.
The code is then printed to the stdout, so you can retrieve it with pbcopy or
pipe it into a file:
❯ ./csv-to-mermaid.py > generated_mermaid_code.mmd
The recommended way is to pass --jql or --filter so the tool fetches issues with acli.
It uses:
acli jira workitem search --json --paginate --fields issuetype,key,status,summary ...
acli jira workitem view <KEY> --fields issuelinks --json
You need to be authenticated with acli jira auth login.
If you prefer a CSV export, the columns this tool needs are:
- Issue key
- Issue Type
- Status
- Summary
Any column like {Outward|Inward} issue link ({TYPE}) will be treated as an in/out
link of type TYPE. You can better understand this by checking the
epic-1.csv file.