¶ Expressions
¶ Introduction
Expressions are a powerful addition to Maven Documents. You've probably already noticed this term when going through elements reference. As you can find there, some of the attributes of those elements have the option to also use Expressions as the attribute value.
Maven Documents Expressions using Javascript Expression Language - powerful context-based expression parser and evaluator.
You will find that examples from the Jexl Documentation are fully compatible with Maven Documents.
There is also a free Jexl Playground that you can explore and play around in.
¶ Can Jexl Examples Simply be Copy-Pasted?
They almost can.
You only need to keep in mind two things when trying to copy-paste such examples.
- Expressions need to have a certain form for Maven Documents to recognize them successfully.
You are already familiar with {!QueryName.FieldName} notation that you can use to add fields in your Template Document.
Now, when you write Expressions, you would need to input a slightly different notation: {!$Expression}. - If {!$Expression} receives any arguments, you would need to make sure that those arguments exist (are valid).
Arguments on Jexl Documentation most certainly will never be. But, you always have the information about arrays or fields that can be used as arguments in your Expressions in - either Template Builder or even Query Builder in Salesforce.
¶ What is the Best Way To Start Using Expressions?
Instead of going through Jexl Examples, we prepared some of the examples that are ready to be copy-pasted and tested out easily.
We suggest you use Sales Quote from our Document Solution Gallery which is fully compatible with every example we are using further in the document. These examples are sorted out by the input (argument) they ingest and you can find them below.
We also built custom Expressions based on the feedback of our current clients who are using the Maven Documents app and integrated them as well. These custom Expressions proved to be quite helpful in building a complex Document Template and serve as enrichment to standard Jexl ones.
You can recognize them by the marked "custom" checkbox in the tables below.
¶ Where Can I Use Expressions?
-
As mentioned in the introduction, you can use Expressions in any attribute of the element that supports it. That information can be found in the elements reference.
-
They can also be used in the variable elements themselves - which is the reason the variable element exists in the first place. Once placed inside the variable, it will hold the computed value of the Expression, and you can then place that variable in multiple places in the Template Document, instead of writing the same Expression every time over and over again.
-
In Query Builder as an Expression Field. We call them Expression fields because they are used the same way as Salesforce fields are used in Query Builder.
These Expressions will be executed for every record on the Object that they are defined on.
They only have visibility of the exact record that they are located on and every Global Variable.
So inside of that Expression, you can use any Salesforce field that you selected with Query Builder and any Global Variable you created. -
Expressions can also be placed directly in the Template Document. Same as you would place fields, but again with a slightly modified notation that is used for Expressions only - {!$Expression}.
¶ Value wrapping in Expressions
Every field value used inside of an expression is considered a String at first, regardless of its data type in Salesforce. That means that it's important to wrap the field value when performing data type-specific operations. For example, one might think that the result of the following expression: '{!$Opportunity[0].Amount + 10}' will be the addition of the first opportunity amount and number 10. That is incorrect. Remember, once we import the field value of the opportunity amount into the expression it is considered a String. So the expression parser will validate this as a concatenation of two string values. To perform addition we would have to wrap the opportunity amount field value using the toDecimal function.
¶ Array
| Expression | Expected | Actual |
|---|---|---|
{!$count( |
1 | 1 |
{!$isEmpty( |
No records in the Account object | false |
{!$isNotEmpty( |
Account Object contains records | true |
{!$max(Account[0] |
The largest Account Opportunity Amount | 435000 |
{!$min(Account[0] |
The smallest Account Opportunity Amount | 435000 |
{!$sum(Account[0] |
The Sum of Account Opportunities Amounts | 435000 |
{!$join(Account[0] |
Connects all values of a field in an array of objects with a separator between them | 1,2,1,1 |
¶ String
| Expression | Expected | Actual |
|---|---|---|
{!$isBlank(Account[0] |
Checks if the Account record's Name field is empty | false |
{!$contains(Account[0] |
Checks if the Account record's Name field contains the letter "a" | true |
{!$charAt(Account[0].Name, 0)} |
Returns the first letter of the Account Name | E |
{!$charCodeAt(Account[0].Name, 2)} |
Returns an integer between 0 and 65535 representing the UTF-16 code unit of the defined letter from the corresponding Account Name | 83 |
{!$concat('The ', 'name ', |
Concatenates the provided string arguments and returns a new string | The name of the Opportunity is Edge SLA |
{!$endsWith(Opportunity[0].Name, 'SLA', |
Determines whether the Opportunity record's name ends with the characters of the defined string, returning true or false as appropriate. The end Position value at which the string is expected to be found is optional | true |
{!$indexOf(Account[0].Name, 'a', |
The position of the first occurrence of the "a" letter in the name of the defined Account record. The end Position value at which the letter is expected to be found is optional | 12 |
{!$lastIndexOf(Account[0] |
The position of the last occurrence of the "a" letter in the name of the defined Account record | 34 |
{!$repeat(Opportunity[0].Name, 2)} |
Builds and returns a new string which contains the 2 copies of the defined Opportunity record's name, concatenated together | Edge SLAEdge SLA |
{!$slice(Opportunity[0].Name, 3, 7)} |
Extracts a part of the defined Opportunity record's name and returns it as a new string | e SL |
{!$split(Account[0].Name, 'i', 3)} |
Takes the defined Account record's name and divides it into an ordered list of substrings by searching for the pattern, puts these substrings into an array, and returns the array. The limit parameter stands for the number of substrings and is optional | "Edge Commun", "cat", "ons" |
{!$startsWith(Opportunity[0].Name, 'E', |
Determines whether the defined Opportunity record's name begins with E. The end Position value at which the letter is expected to be found is optional | true |
{!$substring(Account[0] |
The Part of Account Name between the 0th and 4th Indexes | Edge |
{!$toLowerCase(Opportunity[0].Name)} |
Returns the defined Opportunity record's name converted to lower case | edge sla |
{!$toUpperCase(Opportunity[0].Name)} |
Returns the defined Opportunity record's name converted to upper case | EDGE SLA |
{!$trim( Account[0].Name )} |
Removes whitespaces from both ends of the defined Account record's name | Edge Communications |
{!$replace(Account[0].Name, 'i', 'EE', 'flags')} |
Returns a new string with the first found "i" letter replaced by "EE" in the defined Account record's name. If you use the flags parameter, the second argument will be interpreted as the regex. The flags parameter is optional | Edge CommunEEcations |
{!$replaceAll(Field, 'pattern', 'replacement', 'flags')} |
Returns a new string with all "i" letters replaced by "EE" in the defined Account record's name. If you use the flags parameter, the second argument will be interpreted as the regex. The flags parameter is optional | Edge CommunEEcatEEons |
¶ Number
| Expression | Expected | Actual |
|---|---|---|
{!$toDecimal(Account[0] |
Opportunity's Amount | 435000 |
{!$toDecimal(Account[0] |
Opportunity's Amount + 10 | 435010 |
{!$toPercent(0.123, |
Show the number as the percentage with 2 digits after the comma | 12.30% |
{!$round(10.234, |
Round the number to 2 digits after the comma | 10.23 |
{!$setScale(10.23, |
Show the number with 4 digits after the comma | 10.2300 |
{!$row()} |
Returns the row (number) of the Cell from Repeater in Google Sheets or XLSX file | 12 |
{!$column()} |
Returns the column (number) of the Cell from Repeater in Google Sheets or XLSX file | E |
{!$index()} |
Returns the index (ordinal number) of the repeating value in Repeater and Table | 1, 2, 3 |
¶ DateTime
| Expression | Expected | Actual |
|---|---|---|
{!$date(Account[0] |
Full Opportunity's closure date and time | Sat Jun 05 2021 00:00:00 GMT-0400 (Eastern Daylight Time) |
{!$time(Account[0] |
Full Opportunity's closure time | 00:00:00 GMT-0400 (Eastern Daylight Time) |
{!$dateTime( |
Full Account's creation date and time | Wed Aug 04 2021 04:37:00 GMT-0400 (Eastern Daylight Time) |
{!$now()} |
Full current date and time | Tue Aug 24 2021 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addDays(now(), |
Full Current date and time + 10 days | Fri Sep 03 2021 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addMonths(now(), |
Full Current date and time + 10 months | Fri Jun 24 2022 03:10:24 GMT-0400 (Eastern Daylight Time) |
{!$addYears(now(), |
Full Current date and time + 10 years | Sun Aug 24 2031 03:10:24 GMT-0400 (Eastern Daylight Time) |
¶ Format
| Expression | Expected | Actual |
|---|---|---|
{!$format( |
Opportunity Amount with two decimal 00 | 435,000.00 |
{!$format(now(), |
The current date in the short format | 8/24/2021 |
{!$format(now(), |
The current time in the short format | 12:10 AM |
{!$format(now(), |
The current date and time in the short format | 8/24/2021, 12:10 AM |
{!$format(dateTime |
Opportunity Last Modified Date in the short format | 8/24/2021 |
{!$format(date(Account[0]. |
The current date in a custom format | 2021-08-03 |
{!$format(dateTime |
The current date and time in a custom format | 2021-08-24/17:21:00 |
Be careful with year formats: yyyy represents the calendar year of the date, while YYYY represents the calendar year of the week.
For example, the calendar year of 30/12/2024 is 2024. But technically, the 30th of December falls in the first week of 2025. The calendar year of the week is 2025.
Hence, yyyy and YYYY represent different years for the same date or timestamp.
¶ Comparison
Lets say that {!$toDecimal(Account[0].Opportunities[0].Amount)} gives value of 150.
| Expression | Expected | Actual |
|---|---|---|
{!$toDecimal( |
The Account opportunity's amount is less than 100 | false |
{!$toDecimal( |
The Account opportunity's amount is greater than 100 | true |
{!$toDecimal( |
The Account opportunity's amount is lesser than or equal to 100 | false |
{!$toDecimal( |
The Account opportunity's amount is greater than or equal to 100 | true |
¶ Logical
| Expression | Expected | Actual |
|---|---|---|
{!$toBoolean( |
If the Account opportunity's amount is less than 100, it is true. Otherwise, it is false | false |
¶ GroupBy
We can use the groupBy function to group records by the desired field. Consider the following scenario.
Let's say that the example above generates a table like this one.
However, if we want to create separate tables for records with a different Quantity value we can use a variable that groups OpportunityLineItems records using Quantity field.
The example above will result in the following three tables.
