Page Comparison

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.

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 Added

Step

2: Click on Update Org Data and add org data

Click on the “Update Org Data” card

Then click on the “Add Org Data” button:

Image Modified

Copy your

spreadsheet data and paste into the

editor and click “Save”

Image Added

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:

assignee in orgOf("William MacLane")

Verify the expansion is correct.

Image Modified

Function, you can create custom JQL functions in Forthic.

https://youtu.be/o3aUDhD-bC8

The following functions can be customized:

• fx.users allows you to write custom Forthic code to return an array of users

• fx.issues allows you to write custom Forthic code to return an array of issues

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:

Image Modified

You can define new words using this pattern:

: 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:

Image Modified

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:

"Kai Bentley" FULL-ORG

Image Modified

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:

"William MacLane" FULL-ORG "LENGTH 12 >" SELECT

We could use this in JQL by defining a new word called MACLANE-LONG:

: 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:

Image Modified

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”:

: MACLANE-DIRECTS   "William MacLane" DIRECTS;

Image Modified

In the case of DIRECTS, we could actually just call it directly (since we can pass data to words through Forthic):

Image Modified

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:

["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:

"ENG" INCOMPLETE-EPICS

Image Modified

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":

"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":

Image Modified

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:

Image Modified

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:

"'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:

Image Modified

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:

Image Modified

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:

Image Modified

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.

Image Modified

Going Further

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.