Page Comparison

Visualize with AWS (Atlassian Forge) is a Utoolity Labs app for Codegeist 2020 – we are very excited about the prospects of the Atlassian Forge platform and wanted to explore it with a project that helps with our own project and business planning and documentation. Joining the new wave of declarative chart and diagram rendering grammars with the power of AWS based serverless workflow automation to make these rendering engines available to every Jira and Confluence users seemed to check all the boxes.

The first iteration supports Vega and Vega-lite, PlantUML (incl. AWS and C4 modes), Mermaid, Graphviz, BPMN, and for the fun of it we’ve thrown in Svgbob for ASCII graphics. Unfortunately we failed to finish the arguably most important XKCD style rendering engine via Charts.xkcd, something to aspire too 🙃

Diagrams can be provided and edited inline, or referenced via URL for more complex ones or dynamically updating charts and diagrams (down the road we want to separate the so far combined visualization and data source declaration) – let’s see how it works:

Table of Contents

maxLevel	3
exclude	Requests from this source .*

Note

Registration required

You currently need to be registered to edit and view charts and diagrams via Visualization with AWS – feel free to sign-in with your Atlassian ID so that you can test the app.

Info

Rendering engines and editor support

Refer to Visualize with AWS - supported chart and diagram types for details and links to examples, online playground, and Visual Studio Code extensions.

Tip

Relative vs. absolute URLs

Please be aware that many online examples reference the data via relative URLs – to make these work with this app you need to convert the URLs to absolute ones.

How it works – Confluence

In Confluence the app provides a macro via the Macro module:

You can then select from a variety of declarative chart and diagram rendering engines:

You can see in action right here with a small PlantUML example:

A PlantUML use case diagram

We don't have a way to export this macro've encountered an issue exporting this macro. Please try exporting this page again later.

Here’s the inline source:

Expand

title	PlantUML use case diagram source

Code Block
top to bottom direction actor Author actor User rectangle "Visualize with AWS" { Author --> (define diagram) (define diagram) .> (diagram) : renders (diagram) --> User } @enduml

Let’s try something more fancy via the impressive Vega renderer:

A Vega volcano contours visualization

We don't have a way to export this macro've encountered an issue exporting this macro. Please try exporting this page again later.

This time I’ve provided the data and diagram as an URL via a Bitbucket Snippet for ease of use, even though it could still be defined via JSON inline in principle:

Expand

title	Vega volcano contours diagram URL

Code Block
https://bitbucket.org/!api/2.0/snippets/utoolitylabs/MKLe9j/e03ee4996eec6566130666433ae2897f1f384ff8/files/snippet.json

Expand

title	Vega volcano contours diagram source

Code Block

language	json

{
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "description": "A contour plot of the Maungawhau volcano in New Zealand.",
  "width": 960,
  "autosize": "none",

  "signals": [
    {
      "name": "grid",
      "init": "data('volcano')[0]"
    },
    {
      "name": "height",
      "update": "round(grid.height * width / grid.width)"
    },
    {
      "name": "smooth", "value": true,
      "bind": {"input": "radio", "options": [true, false]}
    }
  ],

  "data": [
    {
      "name": "volcano",
      "url": "https://vega.github.io/vega/data/volcano.json"
    },
    {
      "name": "contours",
      "source": "volcano",
      "transform": [
        {
          "type": "isocontour",
          "scale": {"expr": "width / datum.width"},
          "smooth": {"signal": "smooth"},
          "thresholds": {"signal": "sequence(90, 195, 5)"}
        }
      ]
    }
  ],

  "scales": [
    {
      "name": "color",
      "type": "linear",
      "domain": [90, 190],
      "range": {"scheme": "blueorange"}
    }
  ],

  "marks": [
    {
      "type": "path",
      "from": {"data": "contours"},
      "encode": {
        "enter": {
          "stroke": {"value": "#ccc"},
          "strokeWidth": {"value": 1},
          "fill": {"scale": "color", "field": "contour.value"}
        }
      },
      "transform": [
        {
          "type": "geopath",
          "field": "datum.contour"
        }
      ]
    }
  ]
}

Now that syntax is certainly already a bit complex, which is why the sister project Vega-Lite offers a more concise one too:

A Vega-Lite bubble plot example

We don't have a way to export this macro've encountered an issue exporting this macro. Please try exporting this page again later.

Expand

title	Vega-Lite bubble plotb diagram source

Code Block

language	json

{
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "data": {
    "url": "https://vega.github.io/vega-lite/examples/data/disasters.csv"
  },
  "width": 600,
  "height": 400,
  "transform": [
    {"filter": "datum.Entity !== 'All natural disasters'"}
  ],
  "mark": {
    "type": "circle",
    "opacity": 0.8,
    "stroke": "black",
    "strokeWidth": 1
  },
  "encoding": {
    "x": {
      "field": "Year",
      "type": "ordinal",
      "axis": {"labelAngle": 0}
    },
    "y": {"field": "Entity", "type": "nominal", "axis": {"title": ""}},
    "size": {
      "field": "Deaths",
      "type": "quantitative",
      "legend": {"title": "Annual Global Deaths", "clipHeight": 30},
      "scale": {"range": [0, 5000]}
    },
    "color": {"field": "Entity", "type": "nominal", "legend": null}
  }
}

The app also supports the popular Mermaid renderer:

A Mermaid sequence diagram

We don't have a way to export this macro've encountered an issue exporting this macro. Please try exporting this page again later.

Expand

title	Mermaid state diagram source

Code Block

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

How it works – Jira

In Jira the app provides an issue panel via the IssuePanel module – you can trigger it in the issue byline, for example the initial epic for this app https://utoolity.atlassian.net/browse/UAA-447:

An applicable example might be an architecture overview via the PlantUML with AWS mode:

The app currently only supports one diagram per issue, we are looking into the right data model to make this more flexible.

Testing

Usage - Confluence

Info

Usage testing requires playground space

Regular usage can be readily tested within the /wiki/spaces/UPLAY/pages/1746010343 (refer to the preceding sections for details).

Note

Forge macro configuration persistence issue

We discovered a rather weird Forge issue that loses the macro configuration on page publish if the visualization type was modified – refer to https://ecosystem.atlassian.net/browse/FRGE-118 for details.

As a workaround, please make a small change (whitespace is sufficient) on the surrounding page content in addition to the macro edit.

Usage - Jira

Info

Usage testing requires playground project

Regular usage can be readily tested within the Utoolity Playground Software Project (UPSP), specifically the following issue (refer to the preceding sections for details):

https://utoolity.atlassian.net/browse/UPSP-2

Versions Compared

Old Version 29

New Version Current

Key

Registration required

Rendering engines and editor support

Relative vs. absolute URLs

How it works – Confluence

How it works – Jira

Testing

Usage - Confluence

Usage - Jira