The OrgJQL plugin adds organizational filters to your JQL queries. Here’s the table of contents for this page:
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Quick Start
This will get you up and running with OrgJQL in two minutes.
Prerequisites
You’ll need a spreadsheet with the following columns:
First column: Jira display names of users (you don’t need a complete org listing – just add the people that are relevant for your queries)
Second column: Manager display name for each user
Here’s an example:
Step 1: Go to the “Update Org Data” card
Click on add org data and give your data a name.
Then paste your user/manager spreadsheet into the form (see Prerequisites) and click “Save”.
Step 2: Test the org data by going to the “Test Org Data” tab
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.
Step 3: Try OrgJQL in the Issue Navigator
Copy your query from Step 2 and run it in Jira’s issue navigator. Verify the results, and you’re ready to go!
Step 4: Leave a review
Let us know if you run into any problems or if you’d like to request a feature by visiting the Forthix JSM Portal
Managing Org Data
In this section, we’ll show you how to add and update organizational data for OrgJQL
Update Org Data Tab
This tab lists what data you currently have set up. The default data is what’s used for the orgOf JQL function. Non-default data can be used when customizing the fx.users function. See “Customizing JQL Functions” below.
Viewing Org Data
You can view the data for an organization by clicking on its name. For instance, clicking on “Engineering” might show the following:
Updating Org Data
The format of the organizational data is an array of user/manager pairs. Note that the names are Jira Display names. Also note that, in OrgJQL, arrays use whitespace as separators instead of commas.
An alternative way to updating org data is to copy and paste it from a spreadsheet. In this case, the first column of the spreadsheet should be user names and the second, the corresponding manager:
When adding or updating org data, just add the relevant users and managers. While you can add your entire company, you can always start with a smaller, more relevant set of people.
Default Data
The default data set can be set by ensuring the “Default Data” slider is on for the dataset in question:
The default data is used for the orgOf word and for many of the customized JQL functions.
Testing Org Data
To check your default org data, go to the “Test Org Data” tab and enter a query using the orgOf JQL function:
You can check the query by clicking the “View in Jira” link.
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.
Background on JQL Executions
When a JQL function is executed, it expands into a JQL fragment that is substituted into the query.
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:
Refreshing expansions
You can click on the “Refresh” control for each clause to force update an expansion:
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”:
Customize JQL Functions
In addition to the orgOf JQL function, OrgJQL also provides to other functions you can customize:
fx.usersallows you to write custom Forthic code to return an array of usersfx.issuesallows you to write custom Forthic code to return an array of issues
We'll go through both of these functions in this video.
Background
OrgJQL was written in Forthic, a language developed at LinkedIn to build hundreds of internal Jira-based tools for program and engineering management. Forthic is also the language that allows fx.users and fx.issues to be customized on-the-fly, directly within your Jira instance without any external servers.
Forthic in Jira
The editor for customizing OrgJQL functions is actually a Forthic IDE. You can execute words directly within the IDE and see their effect in the developer pane at the bottom of the editor:
You can define new words using this pattern:
| Code Block |
|---|
: NEW-WORD WORDS TO BE EXECUTED; |
For instance, we can extract 3 + from the previous example and create a new ADD-3 definition and use it like this:
Example: Customize fx.users
Getting all the users that roll up into a manager
Let’s start by showing how to get all the users in a manager’s org. This is actually how the orgOf JQL function is implemented.
NOTE: This assumes you have some org data set up. See “Managing Org Data” for more info.
The FULL-ORG word returns all of the users that roll up into a manger (see the right sidebar for more info). For instance, executing the following line will return all of the users in Kai Bentley’s org:
| Code Block |
|---|
"Kai Bentley" FULL-ORG |
A silly example to get all users whose names are more than 12 characters
This is an example that does something that you can’t do directly in JQL. It’s a silly example, but it illustrates a useful pattern. We’ll use SELECT to filter a list of names given a predicate, in this case, all names greater than 12 characters:
| Code Block |
|---|
"William MacLane" FULL-ORG "LENGTH 12 >" SELECT |
We could use this in JQL by defining a new word called MACLANE-LONG:
| Code Block |
|---|
: MACLANE-LONG "William MacLane" FULL-ORG "LENGTH 12 >" SELECT; |
We can then save the code and then test the expansion in the “Test Custom JQL Functions” tab:
Get the direct reports for a manager
We can use the DIRECTS word to get the direct reports for a manager. For instance, we could use this definition to get the direct reports for “William MacLane”:
| Code Block |
|---|
: MACLANE-DIRECTS "William MacLane" DIRECTS; |
In the case of DIRECTS, we could actually just call it directly (since we can pass data to words through Forthic):
Customizing fx.issues
We’ll implement a classic JQL function that returns all Epics that have unresolved Stories. We can do this in 10 lines of Forthic:
| Code Block |
|---|
["project"] VARIABLES
: FIELDS ["Summary" "Parent"];
: project-EPIC-JQL ["project = " project @ " and resolved = NULL and issuetype='Epic'"] CONCAT;
: project-EPICS project-EPIC-JQL FIELDS jira.SEARCH;
: project-EPIC-KEYS-STR project-EPICS "'key' REC@" MAP UNIQUE "," JOIN;
: project-STORY-JQL ["Parent in (" project-EPIC-KEYS-STR ") and issuetype='Story' and resolved = null"] CONCAT;
: project-UNRESOLVED-STORIES project-STORY-JQL FIELDS jira.SEARCH;
: project-EPICS-w/UNRESOLVED project-UNRESOLVED-STORIES "'Parent' REC@" MAP UNIQUE SORT;
: INCOMPLETE-EPICS (project !) project-EPICS-w/UNRESOLVED; |
(Don’t worry about the syntax just yet – we’ll go over each line)
Giving it a try
The word that gives us the incomplete epics is called…INCOMPLETE-EPICS. We can run it like this:
| Code Block |
|---|
"ENG" INCOMPLETE-EPICS |
Passing a parameter to a definition
If we look at the INCOMPLETE-EPICS definition, we see that the first part of it looks like this: (project !). In Forthic, parentheses are whitespace, so you can ignore those. We use parentheses to indicate that we’re going to take the top of the stack and store it in a variable. The project variable is defined in Line 1.
The ! word sets the value of a variable to what’s just before it. So, this line sets the value of project to "ENG":
| Code Block |
|---|
"ENG" (project !) |
Naming convention: prefix definitions with variable names
When a definition uses the value of a variable, we prefix its name with the variable’s name. You can see that in Lines 4 through 9 above. Each of those words relies on the value of project being set. Once it is, any of those can be called at will. The project variable establishes a context that those words run in.
Line 3: FIELDS
The FIELDS word simply defines an array of Jira fields to pull for each issue.
NOTE: Forthic arrays start with [ and consist of all objects on the stack up until ]. Because we use the state of the stack rather than syntax to define arrays, commas are not needed to separate array elements.
Line 4: project-EPIC-JQL
The project-EPIC-JQL word constructs the JQL to pull all the epics for a project by concatenating strings together (the @ word retrieves the value of a variable).
This is what it looks like when project has the value of "ENG":
Line 5: project-EPICS
The project-EPICS word uses the jira.SEARCH word from the Forthic Jira module to pull issues. This word expects a JQL string and an array of Jira fields. Here are the results when it’s run:
Line 6: project-EPIC-KEYS-STR
The project-EPIC-KEYS-STR word extracts the issue keys for each of the epics. It uses the following to do this:
| Code Block |
|---|
"'key' REC@" MAP |
The MAP word maps a Forthic string over each of the epics, retrieving the result for each item into a new array. For this case, the string "'key' REC@" retrieves the key for each epic. The effect is to convert a list of epic records into a list of their associated issue keys. Here is the result of this word:
Line 7: project-STORY-JQL
The project-STORY-JQL word constructs JQL to pull all of the unresolved stories for the specified epics. It is similar to the project-EPIC-JQL word, but instead of a project, it concatenates the epic key string that we just computed into a JQL string:
This JQL string pulls all of the unresolved stories that are part of the epics of project
Line 8: project-UNRESOLVED-STORIES
The project-UNRESOLVED-STORIES word just pulls unresolved stories using the JQL from Line 7 and the fields from Line 3. Here’s the result from running this:
Line 9: project-EPICS-w/UNRESOLVED
The project-EPICS-w/UNRESOLVED word just gathers the Parent field (the Epics) from each of the unresolved stories. It uniques and sorts them. These are the incomplete epics for the project in question.
Closing Thoughts
Forthic brings new capabilities to Jira. You can essentially develop applications directly within a Jira instance instead of having to go through a long build and deploy cycle. We’ve only touched on what Forthic can do. To learn more, please sign up for Forthic Office Hours or ask us a question at the Forthix JSM portal.
References
Forthic github repo: https://github.com/linkedin/forthic
Forthix syntax: https://github.com/linkedin/forthic/blob/main/docs/SYNTAX.md
Forthic global words: https://github.com/linkedin/forthic/blob/main/docs/modules/global_module.md
Forthic Jira words: https://github.com/linkedin/forthic/blob/main/docs/modules/jira_module.md
Forthic Words
See the references above for more Forthic words. Ones that are useful for OrgJQL are listed in the table below
Word | Signature | Description |
|---|---|---|
|
| Given the Jira display name of a user, returns all the users that report into that user (including the user themselves) |
|
| Given the Jira display name of a user, returns all of their direct reports. |
|
| Given an array of items and a forthic predicate, returns a list of items for which the predicate is true |
|
| Sets the value of |
|
| Retrieves the value of a variable |
|
| Retrieves the value of a record’s field |
|
| Applies a Forthic string to each item, returning an array of the results |