Skip to content

About

Represent Jira tasks as mermaid diagrams

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

Jira to Mermaid

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

Loading

How tu run

You don't need any dependencies apart from Python. I've used Python 3.11, but any version > 3.10 should work.

Fetch issues with acli (recommended)

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

Use a CSV file

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

Getting Jira issues

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.

CSV format (optional)

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.

About

Represent Jira tasks as mermaid diagrams

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages