JQL Functions

Discover Golive advanced JQL functions to filter Jira Issues based on their linked environments:

deployedVersions()

Return the versions that are deployed on existing environments.

Basic examples

CODE

fixVersion in deployedVersions()

→ will return all issues having a fixVersion deployed to an existing environment. Useful to know the list of bugs that can be verified on a live environment.

CODE

affectedVersion in deployedVersions()

→ will return all issues having an “Affects Version/s:” deployed to an existing environment. Useful to know the list of bugs than can be reproduced on a live environment.

Advanced examples

CODE

fixVersion in deployedVersions(Staging,PreProd)

→ will return all issues having a fixVersion deployed to a Staging or PreProd environment. Useful to know the list of bugs for a customer acceptance testing campaign ?

CODE

fixVersion in deployedVersions(eCommerce,ERP)

→ will return all issues having a fixVersion deployed to an eCommerce or ERP environment.

CODE

fixVersion in deployedVersions(Staging,"Pre Production") 
and fixVersion in deployedVersions(eCommerce)

→ will return all issues having a fixVersion deployed to an eCommerce Staging or eCommerce Pre Production environment.

Examples using “status=…” expression

CODE

fixVersion in deployedVersions(Staging,PreProd,"status=Available")

→ will return all issues having a fixVersion deployed to a Staging or PreProd environment that have an “Available” status. Useful to know the list of bugs that can be tested on an “working” environment !

CODE

fixVersion in deployedVersions(Staging,PreProd,"status=Unavailable,EMPTY")

→ will return all issues having a fixVersion deployed to a Staging or PreProd environment that have an “Unavailable” or unknown status. Useful to get a list of bugs that cannot be tested because of non working or unstable environments.

deployedAndPreviousVersions()

Same as deployedVersions() but returns also the versions with a lower version number comparing to the deployed ones.

Imagine that you have the version 3.3 deployed on Staging, deployedAndPreviousVersions() will also return the versions 3.2, 2.0, 3.0.2, 1.0, 0.3,… (if they exist). It enables you to easily get the list of issues that can be tested, reproduced,… on your various environments.

Version Naming Convention

Since version 3.10 you can use almost any kind of naming conventions to order your versions. You can also mix numeric with alphanumerics to number your versions.

Version naming conventions examples:

1.2.3
1.2.3.b454
eCommerce 1.2.3
eCommerce_1.2.3
eCommerce-1.2.3
eCommerce 1.2.3.b343

Ordering rules examples:

1.2 > 1.1
1.20 > 1.2
1.001 == 1.1
1.2.3.b454 > 1.2.3.a999
1.2.3.b454 > 1.2.3.b452
1.2.3.b454 > 1.2.3
APP_A_MOBILE 1.2 > APP_B_ERP 1.3 (example of “apples with bananas” comparison, result may look wrong but it is correct. Read about the comparison algorithm below to know why)

N.B. You can use exactly the same syntax and sub functions as the deployedVersions() function.

Version comparison and ordering algorithm

The algorithm:

1.Normalize name of each version to compare:
1. 1.search for each numbers present in the version name
2. 2.add implicit leading zeros to found numbers in the version name
3. 3.put the version name to lower case to get the normalized version name. For example: “ECom 1.20.345Beta2” will become “ecom 00001.00020.00345beta00002” after normalization
2.Sort all “normalized” version names using a basic String comparator

This algorithm is very flexible and does not depends on usage of specific separators between chunk of numbers.

For java readers, you will find below example of comparisons with different format of version names below:

JAVA

public class VersionNameComparatorTest {

    private int compare(String versionName, String versionName2) {
         VersionNameComparator comparator = new VersionNameComparator(versionName);
        return comparator.compareTo(versionName2);
    }

    private void assertVersionEquals(String versionName, String versionName2) {
        assertEquals(0, compare(versionName, versionName2));
    }

    private void assertAscOrder(String beforeVersionName, String afterVersionName) {
        assertTrue(compare(beforeVersionName, afterVersionName) &lt; 0);
    }

    @Test
    public void testEquals() {
         assertVersionEquals("1.0", "1.0");
         assertVersionEquals("1.0.0", "001.000.0000");
        assertVersionEquals("1.0.0b.0", "1.000.000b.0");
         assertVersionEquals("test 1", "tEsT 001");
         assertVersionEquals("test 10", "test 0010");
    }

    @Test
    public void testOrder() {
         assertAscOrder("1.0", "1.1");
         assertAscOrder("rrr1.0kjhkjh1", "test 1.1");

         assertVersionEquals("1.0", "1.0");
         assertAscOrder("kjhkjh", "sadfsadf1 2.2");

         assertAscOrder("2.30.2", "2.31");
        assertAscOrder("2.30.2", "3.0");
         assertAscOrder("2.3.2", "2.30");

         assertVersionEquals("2.3", "2.03");
         assertVersionEquals("2.3", "2.003");
         assertVersionEquals("2.3", "2.0003");

         assertVersionEquals("2.30", "2.030");
         assertVersionEquals("2.30", "2.0030");

         assertAscOrder("2.30.b2", "2.30.c2");
         assertAscOrder("test 2.30.b2", "test 2.31");
         assertAscOrder("2.b3.2", "20.0");

         assertAscOrder("blabla 2.30.b2", "clabla 2.31");

         assertAscOrder("20170814CBT-T24-WP1200","20170816CBT-T24-WP1199");
         assertAscOrder("20170814CBT-T24-WP1205","20170816CBT-T24-WP1199");
         assertAscOrder("20170814CBT-T24-WP1200","20170814CBT-T24-WP1205");

         assertAscOrder("20170814","20170814CBT-T24-WP1200");
         assertAscOrder("20170814","20170814 1");

         // !the prefix take precedence over following numbers!
         assertAscOrder("BarCode 4.1245.0","Core 4.1177.0");
    }

}

Examples

CODE

fixVersion in deployedAndPreviousVersions(Staging)

→ will return all issues having a fixVersion with a version number equal or lower to the version currently deployed to Staging environments.

unarchivedVersions()

Returns all unarchived versions. Nothing to do with environments or deployments but very useful to exclude archived versions from the deployedAndPreviousVersions() function.

Examples

CODE

fixVersion in deployedAndPreviousVersions(Staging) and fixVersion in unarchivedVersions()

→ will return all issues having a fixVersion with a version number equal or lower to the version currently deployed to Staging environments, but EXCLUDING the archived versions.affectedVersion in deployedVersions()

environments()

Returns environments filtered by criteria. Search Environments API made available directly from a JQL function. This way, you can filter issues using your Environment Custom Fields.

Syntax

All of the pre-defined types, attributes and free text criterion can be used.

Multiple criterion are separated by AND operator.

Value comparison is done using:

= (equal) operator supported on the 3 types of criterion.
in operator is supported on pre-defined types (applicationName, categoryName...)

Consult the Rest API to see the full list of criterion.

Examples

CODE

environmentsField in environments("applicationName = eCommerce")

→ will return all environments related to the eCommerce application.

CODE

environmentsField in environments("applicationName in (eCommerce, Payment Service)")

→ will return all environments related to the eCommerce or Payment Service applications.

CODE

environmentsField in environments("applicationName in 
(eCommerce, Payment Service) AND categoryName in (Staging, PreProd)")

→ will return all Staging or Preprod environments related to the eCommerce or Payment Service applications.

CODE

environmentsField in environments("Team = Environment Support Team")

→ will return all environments owned by Environment Support Team. (here, Team is an environment attribute that can be replaced by your own attributes)