Message-ID: <272745192.11184.1711626744852.JavaMail.appbox@confluence> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_11183_1132122718.1711626744852" ------=_Part_11183_1132122718.1711626744852 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Expr Language

Expr Language

Expr Language (pronounced like "expert" without= the "t") is a simple language that lets you specify an "expression", or a = formula, which is calculated for an issue or another item.

Expr can be used in:

Expr fundamentals are easy to learn, and yet the language is powerful en= ough to address complex needs. The following guide will cover the basic req= uirements of the Expr language.

=20 =20

For a more in-depth study, see our Expr Language Reference and Formula Reference Documenta= tion.

You can view examples of Expr formulas in Sample Formulas or by adding bundled formulas to your structure. To see the f= ormula, simply open the = column options panel.

Language Components

An expression may contain one or more of the following:

There are also more advanced constructs:

Value Types

With Expr you can build formulas that operate on:

Normally, you don't need to worry about the value types when writing a f= ormula. The language engine will try to make sense of the formula and conve= rt the values as needed. For more complex formulas, or if something doesn't= work as expected, see Expr Function Reference for the expected types for each function.

Basic Constructs 

Variables

Variables are user-defined names, which represent attributes, such as:

Naming Variables

Variables can contain letters (English only), numbers or underscore ("_"= ) characters. Variables cannot contain spaces, and the first character must= be a letter or an underscore.

Examples:

As you write your formula, Structure attempts to map your variables to w= ell-known attributes. For example, the "remaining_estimate" variable above = will automatically be mapped to the Remaining Estimate field. See Mapping Variables for more= information.

Variable names are case-insensitive. Priority, priori= ty and pRiOrItY will all refer to the same variable.

Function Calls

A function calculates a value based on its arguments and, sometimes, som= e external aspect. A function call is written as the function name, followe= d by parentheses, which may or may not contain arguments.

Examples:

Function names are case-insensitive. You can write TO= DAY() or Today().

There are 100+ standard functions available with Structure =E2=80=93 see=  Expr Function = Reference for a complete list.

Function arguments may be separated by comma (,) or semicolon (;). But i= n every function call within a formula, you need to use either all commas o= r all semicolons.

Chained Function Calls

The chained notation allows you to easily apply a sequence of func= tions to a value, simply by listing each function one after the other, sepa= rated by a ( . ) dot.

When you use the chain notation, the value that comes before the dot bec= omes the first argument for the function. If the function takes multiple ar= guments, the rest of the arguments must be written in parentheses.

For example:

=20
created=
.FORMAT_DATETIME("yyyy").CONCAT(" year issue")
=20

In this example, FORMAT_DATETIME takes the date value in "created" = and formats it based on the argument in parenthesis ("yyyy"). CONCAT takes = the result from FORMAT_DATETIME and joins it with " year issue".

Numbers and Text Strings

Numbers

Formulas support whole numbers, decimals, or fractions. Commas, spa= ces, locale-specific, percentage, currency or scientific formats are not su= pported.

=20 =20 =20
Recognized as a number Not recognized as a number
0 0,0
1000 1,000

1234567890123456

1 100 025
11.25 1.234e+04
.111 ($100)


You can write a number that is written with a locale-specific decimal an= d thousands separator as a text value, and it will be automatically convert= ed to a number if needed. For example:

  • "1 122,25" * 2 =E2=86=92 2244.5

Text Strings

Text strings are a sequence of characters enclosed either in single (') = or double quotes ("). Examples:

Everything within a text string is retained exactly when the expression = is evaluated or displayed, except for the following:

Text Snippets

Text Snippets allow you to generate strings using variables and expressi= ons. This is particularly helpful in formulas that utilize wiki markup.

When using text snippets:

=20
""" $va=
r1 + $var2 =3D ${var1 + var2} """
=20
""" this $glass is half-${IF optimist: 'full' ELSE: 'empty'} """
=20

Operations

Expr provides basic arithmetic operations, comparisons, text operations = and logical operations.

=20 =20 =20
Operations Comments
+ - * / Basic operators. When used, the value is convert= ed to a number. Follows the general precedence rules for arithmetic, so&nbs= p;(2 + 3 * 4 =3D 14).
=3D !=3D

Equality and non-equality: if e= ither part of the comparison is a number, the other part is also converted = into a number. If both values are texts, then text comparison is used.

<= p>Text comparison ignores leading and trailing whitespace and is case-insen= sitive (according to Jira's system locale).

< <=3D > >=3D Numerical comparisons. When used, = both values are converted to numbers.
AND, OR,= NOT Logical operations.
CONCAT An operation that joins together t= wo text strings. Works similar to the function of the same name: a CONCAT b is the same as CONCAT(a, b).
( ) Parentheses can be used to group t= he results of operations prior to passing them to other operations. 

Order of Operations

When several types of operations are used, they are done in the followin= g order:

  1. Arithmetic operations
  2. Text operations (CONCAT)
  3. Comparison operations
  4. Logical operations. 

For detailed specification, see Expr Language Reference.

Property Access

Formulas can get the value of an item's property using the following not= ation: object.property

=20
fixVers=
ion.releaseDate  //returns the release date for the fixVersion
=20

You can also string multiple property calls together:

=20
project=
.lead.emailAddress  //returns the email address of the lead for the project=
=20

For a complete list of supported properties= , see Item Prop= erty Reference.

Conditional Expression

Simple "IF" expressions can be declared using the IF() function, but for more elaborate = IF cases, with multiple conditions and/or requiring an ELSE option, a condi= tional expression can be used.

=20
WITH to=
tal =3D x + y:
  IF total > 0:
     x / total
  ELSE : error
=20

Note: the ":" after "ELSE" is optional =E2=80=93 in the example abov= e, we've included it for readability.

Advanced Constructs

Local Variables

Local variables are helpful when an expression needs to be used in the s= ame formula several times. For example:

=20
IF time=
_spent + remaining_estimate > 0 :
   time_spent / (time_spent + remaining_estimate)
=20

You can see that in this formula we are using "time_spent + remaining_estimate" twice =E2=80=93 = once when we check that it's not zero (so we don't divide by zero) and agai= n when we divide by it.

Instead of repeating the expression every time, we can rewrite this form= ula using the WITH construct:

=20
WITH to=
tal_time =3D time_spent + remaining_estimate :
  IF total_time > 0 :
     time_spent / total_time
=20

You can define multiple local variables in = succession. You can also use previously defined local variables when defini= ng additional local variables. For example:

=20
WITH to=
tal_time =3D time_spent + remaining_estimate :
WITH progress =3D (IF total_time > 0 : time_spent / total_time) :
  IF(progress > 0.5, "Great Progress!", progress > 0.2, "Good Progres=
s", "Needs Progress!")
=20


Note the position of the colon (":") =E2=80=93 it must be p= resent where each local variable definition ends.

Aggregate Functions

An aggregate function calculates some aggregate value (like sum or minim= um) based on the values in a number of rows, typically for all sub-issues. = Aggregate functions are written very similar to standard functions, e= xcept they use curly braces: SUM{x}.

Examples:

  • SUM { remaining_estimate + time_spent } =E2=80=93 cal= culates the total effort (estimated and actual) for the issue and all its s= ub-issues.
  • MAX { resolved_date - created_date } =E2=80=93 calcul= ates the maximum time it took to resolve an issue, among the issue and its = sub-issues.

They can also contain modifiers, which influence h= ow the aggregation works:

  • SUM#all { business_value } =E2=80=93 this will force = the function to include values from all duplicate items in the total. (By d= efault, duplicates are ignored.)

See Aggregat= e Function Reference for a complete list of available aggregate functio= ns and modifiers.

Any local variables used inside an aggregate function must = also be declared inside the function - within the { } . 

User Functions

A User Function allows you to define a locally-used function within a fo= rmula. User functions can be defined in a similar manner as local variables= :

=20
WITH sq=
uare(x) =3D x * x :=20
  square(impactField) / square(storyPoints)
=20

In this example, the user function is given a name ("square") and then u= sed to perform the same calculation on multiple fields. To learn more, see&= nbsp;the language reference

User Functions for Arrays - using the "$" = character

When you need to perform an operatio= n on each element in an array, you can use a user function such as the one = above, or simplify it using =E2=80=9C$=E2=80=9D to indicate each element in= the array.

=20
worklog=
s.FILTER($.author =3D ME())
=20

In this example, the "$" tells Structure to apply "author =3D ME()" to e= ach element in worklogs - if the author is the current user, it returns tru= e and that worklog will be included in the FILTER results.

This method becomes very powerful when you combine multiple user functio= ns together. To learn more, see the = language reference.

Embedded Queries (JQL = and S-JQL)

You can embed JQL and Structured JQL queries inside an Expr formula, using a construct simil= ar to Aggregate Functions. The resu= lt will be a boolean value:

For example:

=20
// Coll=
ect total story points from all sub-issues assigned to members of Team2 gro=
up, unless the stories are under folder "Special"
SUM {=20
    IF JQL { assignee in membersOf("Team2") } :
    IF NOT SJQL { descendant of folder("Special") } :=20
      storyPoints
}
=20


Since JQL is a Jira-based query, it will work only on issues; the result= will be 0 on other types of items. S-JQL can be use= d for more complex queries applicable to the whole structure.

Comments

Comments are helpful when you have a large formula or when a reader migh= t need explanations of what is being calculated. It's a good idea to add co= mments wherever the formula is not trivial.

Example:

=20
// This=
 is a single-line comment.

/* This is a multi-line comment.
   It can be useful for longer explanations. */
=20

Additional Resources

------=_Part_11183_1132122718.1711626744852--