Versions Compared

Old Version 12

changes.mady.by.user Rino Jose

Saved on

compared with

New Version Current

changes.mady.by.user Rino Jose

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

OrgJQL adds integrates your org data with Jira so you can create queries using orgOfand create manager-specific reports and notifications using Rovo.

Getting Started

Start here to set up your org data and create your first reports.

Expand
titleQuick Start

Quick Start

https://youtu.be/0tfasoF8V8Q

Step 1: Create a spreadsheet of the users and managers you want to include

If you don’t have any headings, the first column will be treated as the users and the second column their managers.

Panel
panelIconIdatlassian-note
panelIcon:note:
bgColor#FFBDAD

NOTE: These must be Jira display names

If you do use headings, the user heading must be user and the manager heading must be manager. Here’s an example Google Spreadsheet:

image-20240614-170336.png

Step 2: Click on Update Org Data and add org data

Click on the “Update Org Data” card

image-20240614-171221.png

Then click on the “Add Org Data” button:

image-20240614-171334.png

Copy your spreadsheet data and paste into the editor and click “Save”

image-20241010-195336.png

Step 3: Test your data

Click on the “Test Org Data” tab and enter a query using your org data. OrgJQL defines an orgOf JQL function that takes a manager’s name and returns a list of everyone who rolls up to them. Here’s an example query:

Code Block
assignee in orgOf("William MacLane")

Verify the expansion is correct.

image-20240614-171622.png
Expand
titleUsing Rovo to create manager-specific one-off reports

Using Rovo to create manager-specific reports

In OrgJQL, all one-off reports are built for a given “root manager”. This is the top level manager for the report. Every report has an “Org Chart Control” that allows you to drill up and down into the org:

image-20241010-201333.png

When you select a manager, all issues in the report are filtered to that manager.

Creating a basic report

To get to the OrgJQL Assistant, click on “Chat” at the upper right of the window, then on “Browse Agents”, and then select “OrgJQL Assistant”.

To create a basic report for a manager (essentially, just the org information) you can enter the following into the Rovo chat:

Code Block
Create a new report for William MacLane

The OrgJQL Assistant will return a link that shows you the org control for that manager

Adding issues to your report

To add issues to an existing report, type something like:

Code Block
Add this JQL to the report: labels=2024-Q4

The OrgJQL Assistant will create a new link to a report using that JQL to pull issues.

If there are issues in your report, you’ll see an “Issues Table” bottom in sidebar at the left:

image-20241010-205425.png

Clicking this will display an issues table filtered by the selected manager. The selected manager is shown in purple at the top of the Issue Table:

image-20241010-205535.png

The shortcut for toggling the issue table is: t.

Expand
titleUsing Rovo to create Leaderboards

Using Rovo to Create Leaderboards

A Leaderboard is a component that rolls issues up by manager and slices them by another dimension. By default, the values in a leaderboard are issue counts, but that can be changed to another statistic (e.g., Story Points, Average Days Late, Max Days Late, etc.)

To add a leaderboard to an existing report, type something like this into the OrgJQL Assistant chat:

Code Block
Add leaderboard to this report

Rovo will response with a new link that has the leaderboard in it.

image-20241011-165416.pngImage Added

Clicking on a pie slice or cell will select all issues in that go into that. These will be highlighted in orange.

image-20241011-165740.pngImage Added

If some but not all issues in an element are selected, the label will be shown in italics:

image-20241011-165923.pngImage Added

All selected issues are indicated in the sidebar

image-20241011-170239.pngImage Added

Clicking on this control brings up the Issue Table:

image-20241011-170327.pngImage Added

Expand
titleUsing Rovo to create Issue Graphs

Using Rovo to Create Issue Graphs

Issue Graphs show the critical path for a set of issues that are linked by “blocked on” relationships and which have time estimates. To add a leaderboard to a report, type something like this for any of the linked issues:

Code Block
Add an issue graph for BIZDEV-246

NOTE: OrgJQL traverses the graph by pulling prerequisite and dependent issues in steps. Picking an issue in the center of the issue graph will cut the traversal time in half.

image-20241011-171752.pngImage Added

Selecting a manager will drills down into the Issue Graph for that manager. For instance, if we select “Leo Moore”, we’ll see this:

image-20241011-172112.pngImage Added

Issues can be selected by clicking on a node or by selecting issues in the issue table:

image-20241011-173219.pngImage Added

Tweaking an OrgJQL Report

All OrgJQL reports are constructed in the Forthic language. Rovo understands how to construct this Forthic. You can also construct this Forthic on your own (or tweak the Forthic that Rovo comes up with).

Expand
titleDocumentation on tweaking OrgJQL Reports

  • Understanding Forthic

  • Tweaking a Leaderboard

  • Tweaking an Issue Graph

Administration

Go deeper into OrgJQL and look at JQL Executions and customize your own org functions.

Expand
titleReview JQL Executions

Review JQL Executions

In this section, we'll go over how to view and manage OrgJQL executions. These "expansions" are stored by Jira for performance, but they are updated when issues are created or updated or when org data is changed. You can also force update any or all OrgJQL executions here.

https://youtu.be/DivmtPQViM0

Background on JQL Executions

When a JQL function is executed, it expands into a JQL fragment that is substituted into the query.

image-20240614-185515.png

Jira stores these expansions in a pre-computations database to improve performance. The expansions for OrgJQL are listed in the table of the “Review JQL Executions” page.

Searching for clauses

You can filter the table by clauses:

image-20240614-185711.png

Refreshing expansions

You can click on the “Refresh” control for each clause to force update an expansion:

image-20240614-185839.png

When are Precomputations Updated?

The following trigger OrgJQL precomputation updates:

  • Ticket is created (after 15 minutes of inactivity)

  • Ticket is updated (after 15 minutes of inactivity)

  • OrgJQL data is updated

  • Custom JQL function code is updated

  • When “Refresh All” is clicked in the “Review JQL Executions” page

The refresh job is asynchronous and runs from a queue, so only one job is ever running at a time.

NOTE: Precomputations are only updated if their values have changed.

Stopping a Precomputation Refresh Job

You can stop a running precomputation job by clicking “Force Stop”:

image-20240614-190308.png

...