User Guide

1. Getting started

After an administrator installs the app, open it from Apps in the Jira top navigation. The app opens as a global page with six tabs: Projects, Dependencies, Roadmap, Summary, BPMN, and UML.

You'll only ever see projects and issues you already have permission to view in Jira. The app does not widen your access.

2. Portfolio tabs

Projects

Lists your projects with per-project statistics. Use the search box to filter by name, and the facet controls to narrow by project lead, status, or date range.

Dependencies

Renders issue dependency links as a graph. Circular dependencies are detected automatically and flagged so you can break the loop before it stalls delivery.

Roadmap

Plots epics on a timeline using their start and due dates. Overlapping date ranges are highlighted to surface potential resource conflicts.

Summary

Aggregated metrics across the projects you can see.

3. BPMN diagrams

The BPMN tab is a full BPMN 2.0 modelling canvas. Diagrams are organised in a library on the left, each one tied to a Jira project.

1. Click + New Diagram, give it a name, and pick the project it belongs to.
2. Build your process using the palette on the left of the canvas.
3. Select any element to edit its properties in the panel on the right.
4. Enter a version name, then click Save.

Linked resources

Any diagram element can be linked to a Jira issue and a Confluence page. Once linked, the element offers one-click navigation to that resource — useful for connecting a process step to the work that implements it.

Token simulation

Use the simulation control to step a token through your process and confirm the paths behave as you expect before relying on them.

Automation rules

Each BPMN diagram has its own Automation Rules panel, where you build the rules and decision tables covered in section 6 and section 7.

4. UML diagrams

The UML tab works the same way as BPMN, but diagrams are written as text using Mermaid syntax rather than drawn on a canvas. The editor is split: Mermaid source on the left, a live preview on the right that updates as you type (briefly debounced, so it doesn't re-render on every keystroke).

Creating a diagram

1. Click + New Diagram, name it, and choose a project.
2. Replace the starter template with your own Mermaid source.
3. Fill in Save as with a version name — this is required before saving.
4. Optionally add a Message describing what changed, like a commit message.
5. Click Save.

Unlike BPMN, the Save button does not wait for you to edit the template first — you can save the starter template as-is if you just want to reserve the diagram name, then come back and flesh it out.

Supported diagram types

Anything Mermaid supports will render. The most common for UML work:

Example: class diagram

classDiagram
    classA <|-- classB : Inheritance
    classC *-- classD : Composition
    classE o-- classF : Aggregation
    classG <-- classH : Association
    classK <.. classL : Dependency

Example: sequence diagram

sequenceDiagram
    Client->>API: POST /orders
    API->>Database: insert order
    Database-->>API: order id
    API-->>Client: 201 Created

Zoom

Use the − / + buttons to zoom the preview, or click the percentage to reset to 100%. Zoom affects only your view; it isn't saved with the diagram.

What's different from BPMN

The UML tab does not currently have a properties panel, linked-resource attachments, token simulation, or automation rules — those are BPMN-specific, since Mermaid diagrams are plain text rather than a canvas of connected elements. Versioning, revert, and real-time collaboration work identically on both tabs.

5. Versions & history

BPMN and UML diagrams share the same version model. Every save creates a new, permanently numbered version — nothing is ever overwritten.

• Save as — the name for this version (for example v1-draft or approved-2026-Q3). Required.
• Message — an optional note about what changed.
• Versions — opens the history for the diagram, listing every version with its author, timestamp, and message.

Viewing an older version

Select any version from the history to open it in the editor. The version you're viewing is shown in the header so you always know whether you're looking at the latest state.

Reverting

Reverting to an older version does not delete anything. It copies that version's content forward as a brand new version at the top of the history, marked as a revert and recording which version it came from. The full trail stays intact and auditable, and a revert can itself be reverted.

Deleting

Deleting a diagram from the library removes it and its entire version history. This cannot be undone, and requires edit permission on the associated project.

6. Workflow automation

Every BPMN diagram has its own set of automation rules, managed from the diagram's Automation Rules panel. A rule has four parts, built top to bottom: a trigger (when it runs), conditions (whether it should run this time), an optional decision table (see section 7), and actions (what it does).

Creating and managing rules

1. Open a BPMN diagram and go to its Automation Rules panel.
2. Click + New Rule, then give it a name.
3. Configure the trigger, conditions, decision table, and actions (details below).
4. Click Save Rules to persist every rule on the diagram at once.

Each rule has an Enable / Disable toggle — disabling a rule keeps its configuration without deleting it. Unsaved edits are kept as a local draft in your browser and restored if you navigate away and come back, with a banner reminding you to press Save Rules to make them permanent.

Triggers

A rule fires when a matching Jira issue event occurs on its diagram's project:

Conditions

Conditions are combined with AND — every condition on the rule must be true. Each condition compares one field to a value:

Available operators: equals, does not equal, contains, does not contain, is empty, is not empty, greater than, less than.

Actions

Actions run in the order listed, after conditions pass:

A failed action (for example, transitioning to a status that isn't reachable, or an invalid account ID) is logged on the backend and simply skipped — it does not stop the rest of the rule's actions from running, and it does not surface an error anywhere in the Jira UI. If an automation seems to be partially working, check each action's value carefully rather than assuming a full failure.

7. DMN decision tables

A decision table lets one rule produce different outcomes depending on the issue, without writing a separate rule for every case. It sits between a rule's conditions and its actions, inside the Decision Table (DMN) block of the rule editor.

Building a table

1. + Add Input — a column the table reads from the issue, e.g. "Priority" or "Issue Type". Rename the column header to describe what it checks.
2. + Add Output — a column that produces a result. Rename it to include the word "Action" if you want that column to actually execute something (see below).
3. + Add Row — one row per rule you want to express. An empty cell in an input column means "matches anything" (wildcard); it doesn't need to match.

How a row matches

For each input column with a value in a given row, the app maps the column's label to an issue field — "Priority" → the issue's priority name, "Issue Type" → its issue type name, "Status" → its status, "Assignee" → the assignee's display name, "Labels" / "Components" → the joined list — and checks it for an exact, case-insensitive match against the cell's text. A row only matches if every one of its non-empty input cells matches.

Example table

Row 1 only matches Highest-priority bugs. Row 2 matches any Highest-priority issue regardless of type (empty Issue Type cell). Row 3 matches any bug regardless of priority.

Output values and the action shorthand

A cell in an output column only becomes a real action if that column's label contains the word "action" (case-insensitive) — rename output columns you want to execute to something like "Action" or "Escalation Action". Columns without "action" in the name are evaluated but ignored, which is useful for a purely informational column you just want visible in the table.

Inside an action-labelled output cell, a prefix on the value picks what kind of action it becomes:

Hit policies

The hit policy controls what happens when more than one row matches the same issue:

Decision tables vs. plain conditions

A rule's conditions (section 6) are still evaluated first, as a gate for the whole rule — the decision table only runs for issues that already passed the rule's conditions. Use conditions to scope which issues a rule looks at, and the decision table to branch the outcome for those issues.

8. Permissions & collaboration

Access to a diagram — and its automation rules — follows the Jira project it belongs to. If you can edit issues in that project, you can create, edit, revert, and delete its diagrams and rules. If you can't, diagrams open in a read-only view with editing controls hidden, and the Automation Rules panel shows only a rule count.

Working at the same time as someone else

If a teammate saves a diagram you have open, a notification appears at the top of the editor. If you have no unsaved changes, the editor refreshes to their version automatically. If you do have unsaved changes, the app will not discard them — instead you'll see a conflict warning with two choices:

• Reload remote — discard your changes and load theirs.
• Keep mine — keep editing; you can save as a new version afterwards.

Diagrams from deleted projects

If a Jira project is deleted, its diagrams remain but are marked with a warning badge and become read-only, since permissions can no longer be evaluated. Any signed-in user may delete them to clean up.

9. Troubleshooting

The Save button is greyed out

Saving requires a version name in the Save as field. For a new diagram, it also requires a diagram name that isn't already in use. If neither applies, you may not have edit permission on the project.

The UML preview shows an error

This is a Mermaid syntax error, not a saved-data problem. The error text names the line at fault. Your source text is untouched — correct the syntax and the preview re-renders.

The UML preview is blank in an older browser

Diagram rendering requires a current browser. On Safari, version 17.4 or newer is needed. Updating the browser, or switching to a recent Chrome, Edge, or Firefox, resolves it.

An automation rule or decision table isn't doing anything

Work through these in order:

1. Is the rule Enabled, and did you press Save Rules after your last edit?
2. Is the trigger one of the three that don't fire yet (Due Date Reached, Sprint Started, Sprint Completed)? See section 6.
3. Do the rule's conditions actually match the issue you're testing with?
4. If you're using a decision table with hit policy Unique or Any, do multiple rows match and disagree — causing the silent no-op described in section 7?
5. Is the output column's label missing the word "Action"?
6. For Assign To or an assign: decision-table output, did you use an account ID rather than a name?

My changes disappeared after a teammate saved

Unsaved work is never silently overwritten — a conflict prompt always appears first. If you chose Reload remote, your unsaved edits were discarded by that choice. Any version that was actually saved is still recoverable from the diagram's history.

A diagram is missing from the library

Either it was deleted, or it belongs to a project you no longer have access to. Check with your Jira administrator.

Support