Groovy Basics

This section highlights some important aspects of Groovy to allow you to better understand the examples in the sections that follow.

Commenting Your Scripts

It is important that you document your scripts so that you and your colleagues who might view the code months from now will remember what the logic is doing. You can use either a double-slash combination // which makes the rest of the current line a comment, or you can use the open-comment and close-comment combination of /* followed later by */. The latter style can span multiple lines.

Here is an example of both styles in action:

// Loop over the names in the list
for (name in listOfNames) {
  /*
   * Update the location for the current name.
   * If the name passed in does not exist, will result in a no-op
   */
  updateLocationFor(name,      // name of contact
                    'Default', /* location style */
                   )
}

When using multi-line comments, it is illegal for a nested /* ... */ comment to appear inside of another one. So, for example, the following is not allowed:

// Nested, multi-line comment below is not legal
def interest = 0
/*
  18-MAY-2001 (smuench) Temporarily commented out calculation!
 
  /*
   * Interest Accrual Calculation Here
   */
   interest = complexInterestCalculation()
*/

Instead, you can comment out an existing multi-line block like this:

// Nested, multi-line comment below is legal
def interest = 0
//
// 18-MAY-2001 (smuench) Temporarily commented out calculation!
// 
//  /*
//   * Interest Accrual Calculation Here
//   */
//   interest = complexInterestCalculation()
//

Or, alternatively had your initial code used the // style of comments, the following is also legal:

// Nested, multi-line comment below is not legal
def interest = 0
/*
  18-MAY-2001 (smuench) Temporarily commented out calculation!
 
  //
  // Interest Accrual Calculation Here
  //
  interest = complexInterestCalculation()
*/

The most common style-guide for comments would suggest to use multi-line comments at the beginning of the script, and single-line comments on subsequent lines. This allows you to most easily comment out code for debugging purposes. Thus, you typical script would look like this:

/*
 * Object validation rule for BankAccount
 * 
 * Ensures that account is not overdrawn
 */
def balance = CurrentBalance
// Use an object function to calculate uncleared charges
def unclearedCharges = unclearedChargesAmountForAccount()
// Perform some other complicated processing
performComplicatedProcessing()
// return true if the account is not overdrawn
return balance > unclearedCharges

Defining Variables

Groovy is a dynamic language, so variables in your scripts can be typed dynamically using the def keyword as follows:

// Assign the number 10 to a variable named "counter"
def counter = 10

// Assign the string "Hello" to a variable named "salutation"
def salutation = 'Hello'

// Assign the current date and time to a variable named "currentTime"
def currentTime = now()

Using the def keyword you can define a local variable of the right type to store any kind of value, not only the three examples above. Alternatively you can declare a specific type for variables to make your intention more explicit in the code. For example, the above could be written like this instead:

// Assign the number 10 to a variable of type Integer named "counter"
Integer counter = 10

// Assign the string "Hello" to a variable named "salutation"
String salutation = 'Hello'

// Assign the current date and time to a variable named "currentTime"
Date currentTime = now()

Note: You can generally choose to use the def keyword or to use a specific type for your variables according to your own preference, however when your variable needs to hold a business object, you must to define the variable’s type using the def keyword. See the tip in Using Substitution Expressions in Strings below for more information.

Referencing the Value of a Field in the Current Object

When writing scripts that execute in the context of the current business object, you can reference the value of any field in the current object by simply using its API name. This includes all of the following contexts:

object validation rules
field-level validation rules
formula field expressions
object triggers
field triggers, and
object functions

To write a script that references the value of fields named contactPhoneNumber and contactTwitterName, you would use the following code:

// Assign value of field "contactPhoneNumber" to "phone" var
def phone = contactPhoneNumber

// Assign value of field "contactTwitterName" to "twitterName" var
def twitterName = contactTwitterName

// Assemble text fragment by concatenating static text and variables
def textFragment = 'We will try to call you at ' + phone +
                   ' or send you a tweet at ' + twitterName

Defining a local variable to hold the value of a field is a good practice if you will be referencing its value more than once in your code. If you only need to use it once, you can directly reference a field's name without defining a local variable for it, like this:

def textFragment = 'We will try to call you at ' + contactPhoneNumber +
                   ' or send you a tweet at ' + contactTwitterName

Note: When referencing a field value multiple times, you can generally choose to use or not to use a local variable according to your own preference, however when working with an RowIterator object, you must to use the def keyword to define a variable to hold it. See the tip in the Using Substitution Expressions in Strings for more information.

Working with Numbers, Dates, and Strings

Groovy makes it easy to work with numbers, dates and strings. The expression for a literal number is just the number itself:

// Default discount is 5%
def defaultDiscount = 0.05
// Assume 31 days in a month
def daysInMonth = 31

To create a literal date, use the date() or dateTime() function:

// Start by considering January 31st, 2019
def lastDayOfJan = date(2019,1,31)
// Tax forms are late after 15-APR-2019 23:59:59
def taxSubmissionDeadline = dateTime(2019,4,15,23,59,59)

Write a literal string using a matching pair of single quotes, as shown here.

// Direct users to the Acme support twitter account
def supportTwitterHandle = '@acmesupport'

It is fine if the string value contains double-quotes, as in:

// Default podcast signoff
def salutation = 'As we always say, "Animate from the heart."'

However, if your string value contains single quotes, then use a matching pair of double-quotes to surround the value like this:

// Find only gold customers with credit score over 750
customers.appendViewCriteria("status = 'Gold' and creditScore > 750")

You can use the normal + and - operators to do date, number, and string arithmetic like this:

// Assign a date three days after the CreatedDate
def targetDate = CreatedDate + 3

// Assign a date one week (seven days) before the value
// of the SubmittedDate field
def earliestAcceptedDate = SubmittedDate - 7

// Increase an employee's Salary field value by 100 dollars
Salary = Salary + 100

// Decrement an salesman's commission field value by 100 dollars
Commission = Commission - 100

// Subtract (i.e. remove) any "@"-sign that might be present
// in the contact's twitter name
def twitNameWithoutAtSign = ContactTwitterName - '@'

// Add the value of the twitter name to the message
def message = 'Follow this user on Twitter at @' + twitNameWithoutAtSign

Using Substitution Expressions in Strings

Groovy supports using two kinds of string literals, normal strings and strings with substitution expressions. To define a normal string literal, use single quotes to surround the contents like this:

// These are normal strings
def name = 'Steve'
def confirmation = '2 message(s) sent to ' + name

To define a string with substitution expressions, use double-quotes to surround the contents. The string value can contain any number of embedded expressions using the ${expression} syntax. For example, you could write:

// The confirmation variable is a string with substitution expressions
def name = 'Steve'
def numMessages = 2
def confirmation = "${numMessages} message(s) sent to ${name}"

Executing the code above will end up assigning the value 2 messages(s) sent to Steve to the variable named confirmation. It does no harm to use double-quotes all the time, however if your string literal contains no substitution expressions it is slightly more efficient to use the normal string with single-quotes.

Tip: As a rule of thumb, use normal (single-quoted) strings as your default kind of string, unless you require the substitution expressions in the string.

Using Conditional Expressions

When you need to perform the conditional logic, you use the familiar if/else construct. For example, in the text fragment example in the previous section, if the current object's ContactTwitterName returns null, then you won't want to include the static text related to a twitter name. You can accomplish this conditional text inclusion using if/else like this:

def textFragment = 'We will try to call you at ' + ContactPhoneNumber
if (ContactTwitterName != null) {
  textFragment += ', or send you a tweet at '+ContactTwitterName
}
else {
  textFragment += '. Give us your twitter name to get a tweet'
}
textFragment += '.'

While sometimes the traditional if/else block is more easy to read, in other cases it can be quite verbose. Consider an example where you want to define an emailToUse variable whose value depends on whether the EmailAddress field ends with a .gov suffix. If the primary email ends with .gov, then you want to use the AlternateEmailAddress instead. Using the traditional if/else block your script would look like this:

// Define emailToUse variable whose value is conditionally
// assigned. If the primary email address contains a '.gov'
// domain, then use the alternate email, otherwise use the
// primary email.
def emailToUse
if (endsWith(EmailAddress,'.gov') {
  emailToUse = AlternateEmailAddress 
}
else {
  emailToUse = EmailAddress
}

Using Groovy's handy inline if / then / else operator, you can write the same code in a lot fewer lines:

def emailToUse = endsWith(EmailAddress,'.gov') ? AlternateEmailAddress : EmailAddress

The inline if / then / else operator has the following general syntax:

BooleanExpression ? If_True_Use_This_Expression : If_False_Use_This_Expression

Since you can use whitespace to format your code to make it more readable, consider wrapping inline conditional expressions like this:

def emailToUse = endsWith(EmailAddress,'.gov') 
                 ? AlternateEmailAddress 
                 : EmailAddress

Using the Switch Statement

If the expression on which your conditional logic depends may take on many different values, and for each different value you'd like a different block of code to execute, use the switch statement to simplify the task. As shown in the example below, the expression passed as the single argument to the switch statement is compared with the value in each case block. The code inside the first matching case block will execute. Notice the use of the break statement inside of each case block. Failure to include this break statement results in the execution of code from subsequent case blocks, which will typically lead to bugs in your application.

Notice, further, that in addition to using a specific value like 'A' or 'B' you can also use a range of values like 'C'..'P' or a list of values like ['Q','X','Z']. The switch expression is not restricted to being a string as is used in this example; it can be any object type.

def logMsg
def maxDiscount = 0
// warehouse code is first letter of product SKU
// uppercase the letter before using it in switch
def warehouseCode = upperCase(left(SKU,1))
// Switch on warehouseCode to invoke appropriate
// object function to calculate max discount
switch (warehouseCode) {
  case 'A': 
    maxDiscount = Warehouse_A_Discount()
    logMsg = 'Used warehouse A calculation'
    break
  case 'B':
    maxDiscount = Warehouse_B_Discount()
    logMsg = 'Used warehouse B calculation'
  case 'C'..'P':
    maxDiscount = Warehouse_C_through__P_Discount()
    logMsg = 'Used warehouse C-through-P calculation'
    break    
  case ['Q','X','Z']: 
    maxDiscount = Warehouse_Q_X_Z_Discount()
    logMsg = 'Used warehouse Q-X-Z calculation'
    break
  default:
    maxDiscount = Default_Discount()
    logMsg = 'Used default max discount'
}
println(logMsg+' ['+maxDiscount+']')
// return expression that will be true when rule is valid
return Discount == null || Discount <= maxDiscount

Returning a Boolean Result

Two business object contexts expect your groovy script to return a boolean true or false result. These include:

object-level validation rules
field-level validation rules

Groovy makes this easy. One approach is to use the groovy true and false keywords to indicate your return as in the following example:

// Return true if value of the commission field is greater than 1000
if (commission > 1000) { 
  return true
}
else {
  return false
}

However, since the expression commission > 1000 being tested above in the if statement is itself a boolean-valued expression, you can write the above logic in a more concise way by simply returning the expression itself like this:

return commission > 1000

Furthermore, since Groovy will implicitly change the last statement in your code to be a return, you could even remove the return keyword and just say:

commission > 1000

This is especially convenient for simple comparisons that are the only statement in a validation rule.

Assigning a Value to a Field in the Current Object

To assign the value of a field, use the Groovy assignment operator = and to compare expressions for equality, use the double-equals operator == as follows:

// Compare the ContactTwitterName field's value to the constant string 'steve'
if (ContactTwitterName == 'steve') {
  // Assign a new value to the ContactTwitterName field
  ContactTwitterName = 'stefano'
}

Tip: See Avoiding Validation Threshold Errors By Conditionally Assigning Values for a tip about how to avoid your field assignments from causing an object to hit its validation threshold.

Writing Null-Aware Expressions

When writing your scripts, be aware that field values can be null. You can use the nvl() null value function to easily define a value to use instead of null as part of any script expressions you use. Consider the following examples:

// Assign a date three days after the PostedDate
// Use the current date instead of the PostedDate if the
// PostedDate is null
def targetDate = nvl(PostedDate,now()) + 3

// Increase an employee's custom Salary field value by 10 percent
// Use zero if current Salary is null
Salary = nvl(Salary,0) * 1.1

Tip: Both expressions you pass to the nvl() function must have the same datatype, or you will see type-checking warnings when saving your code. For example, if Salary is a number field, then it is incorrect to use an expression like nvl(Salary,’<No Salary>’) because the first expression is a number while the second expression is a string.

Understanding Null Versus the Empty String

In Groovy, there is a subtle difference between a variable whose value is null and a variable whose value is the empty string. The value null represents the absence of any object, while the empty string is an object of type String with zero characters. If you try to compare the two, they are not the same. For example, any code inside the following conditional block will not execute because the value of varA (null) does not equals the value of varB (the empty string).

def varA = null
def varB = '' /* The empty string */
if (varA == varB) {
  // Do something here when varA equals varB
}

Another common gotcha related to this subtle difference is that trying to compare a variable to the empty string does not test whether it is null. For example, the code inside the following conditional block will execute (and cause a NullPointerException at runtime) because the null value of varA is not equal to the empty string:

def varA = null
if (varA != '') {
  // set varB to the first character in varA
  def varB = varA.charAt(0)
}

To test whether a string variable is neither null nor empty, you could explicitly write out both conditions like this:

if (varA != null && varA != '') {
  // Do something when varA is neither null nor empty
}

However, Groovy provides an even simpler way. Since both null and the empty string evaluate to false when interpreted as a boolean, you can use the following instead:

if (varA) {
  // Do something when varA has a non-null and non-empty value
}

If varA is null, the condition block is skipped. The same will occur if varA is equal to the empty string because either condition will evaluate to boolean false. This more compact syntax is the recommended approach.

Understanding Secondary Fields Related to a Reference

A reference field represents a many-to-1 foreign key between one object and a another object of the same or different type. For example, a TroubleTicket object might have a reference field named reportedBy that represents a foreign key to the specific Contact object that reported the trouble ticket. When defining a reference field, you specify a default display field name from the reference object. For example, while defining the reportedBy lookup field referencing the Contact object, you might specify the Contact Name field (contactName).

When you define a reference field like reportedBy, you get one primary field and two secondary fields:

The Foreign Key Field
This primary field is named reportedBy and it holds the value of the primary key of the referenced contact.
The Related Object Accessor Field
This secondary field is named reportedByObject and it allows you to programmatically access the related contact object in script code. This is the default name, but be aware it can be edited in the relationship editor.
The Display Name Field
This secondary field name follows the pattern objectAccessorName_displayFieldName. It holds the value of the display field related to the referenced object. For this example, the field is reportedByObject_contactName and reflects the name of the related contact.

To access additional fields besides the default display name from the related object, you can use the related object accessor field like this:

// Assume script runs in context of TroubleTicket object
def contactEmail = reportedByObject?.emailAddress

If you reference multiple fields from the related object, you can save the related object in a variable and then reference multiple fields using this object variable:

// Assume script runs in context of TroubleTicket object
def contact = reportedByObject
def email = contact?.emailAddress
def linkedIn = contact?.linkedInUsername

To change which contact reported the TroubleTicket, you can set a new contact by using one of the following techniques. If you know the primary key value of the new contact, then use this approach:

// Assume script runs in context of TroubleTicket object
def newId = /* ... Get the Id of the New Contact Here */
contact = newId

If you know a unique value of some contact's default display field, then you can use this approach instead:

// Assume script runs in context of TroubleTicket object
reportedByObject_contactName = 'James Smith'

Tip: If the value your script assigns to a reference field’s secondary display name field (e.g. reportedByObject_contactName) uniquely identifies a referenced object, then the corresponding value of the reference field itself (e.g. reportedBy) will automatically update to reflect the primary key of the matching object.

Attention: If the value your script assigns to a reference field’s secondary display name field does not uniquely identify a referenced object, then the assignment is ignored.

Using Groovy's Safe Navigation Operator

If you are using "dot" notation to navigate to reference the value of a related object, you should use Groovy's safe-navigation operator ?. instead of just using the . operator. This will avoid a NullPointerException at runtime if the left-hand-side of the operator happens to evaluate to null. For example, consider a TroubleTicket object with a reference field named assignedTo representing the staff member assigned to work on the trouble ticket. Since the assignedTo field may be null before the ticket gets assigned, any code referencing fields from the related object should use the safe-navigation operator as shown here:

// access referenced object and access its last name
// Using the ?. operator, if related object is null,
// the expression evaluates to null instead of throwing
// NullPointerException
def assignedToName = assignedToObject?.lastName

Tip: For more information on why the code here accesses assignedToObject instead of a field named assignedTo, see Understanding Secondary Fields Related to a Reference

Assigning a Value to a Field in a Related Object

To assign a value to a field in a related object, use the assignment operator like this:

// Assume script runs in context of an Activity object (child of TroubleTicket)
// and that troubleTicket is the name of the parent accessor
troubleTicket.status = 'Open'

Since a child object must be owned by some parent row, you can assume that the troubleTicket accessor will always return a valid parent row instead of ever returning null. This is a direct consequence of the fact that the parent foreign key value in the Activity object’s troubleTicket field is mandatory. In this situation, it is not strictly necessary to use the Groovy safe-navigation operator, but in practice is it always best to use it:

troubleTicket?.status = 'Open'

By following this advice, you can be certain your code will never fail with a NullPointerException error when you happen to work with an accessor to a related object that is optional. For example, suppose you added a reference field named secondaryAssignee to the Activity object and that its value is optional. This means that referencing the related accessor field named secondaryAssigneeObject can return null if the foreign key field secondaryAssignee is null. In this case, it is imperative that you use the safe-navigation operator so that the attempted assignment is ignored when there is no secondary assignee for the current activity.

secondaryAssigneeObject?.openCases = caseTotal

Tip: For more information on accessing related objects see Using the Related Object Accessor Field to Work with a Parent Object and Using the Related Object Accessor Field to Work with a Referenced Object..

Printing and Viewing Diagnostic Messages

To assist with debugging, use the Logs window to view details on runtime exceptions as well as the runtime diagnostic messages your scripts have generated. Open the window by clicking on the Logs button at the bottom of the Visual Builder window, located next to the Audits button. Log messages related to your user account appear the first time the window is opened. Check the Enable Logging checkbox when you want messages logged by your own script code to be written to the diagnostic log. The messages are shown by default in chronological order. When a runtime exception occurs, additional details on the offending script and line number where the error occurred are visible in the tooltip by hovering your mouse over the exception message. The search field allows you to filter the log messages. To export the messages to a file, use the Export toolbar button. To close the Logs window again, click again on the Logs button in the window’s title bar.

If you keep the Logs window open while you work, consider the following approach. Before starting a new attempt to reproduce the problem, click the Clear toolbar button to remove any previous messages generated. After encountering the error you are diagnosing, click the Refresh toolbar button to see the latest log messages generated.

Viewing Diagnostic Messages for Debugging

Writing Diagnostic Log Messages from Your Scripts

To write messages to the diagnostic log, use the print or println function. The former writes its value without any newline character, while the latter writes it value along with a newline. For example:

// Write a diagnostic message to the log. Notice how
// convenient string substitution expressions are
println("Status = ${Status}")

In this release, the diagnostic messages in the log are not identified by context, so it can be helpful to include information in the printed diagnostic messages to identify what code was executing when the diagnostic message was written. For example:

// Write a diagnostic message to the log, including info about the context
println("[In: BeforeInsert] Status = ${Status}")

Working with Lists

A list is an ordered collection of objects. You can create list of objects using Groovy's square-bracket notation and a comma separating each list element like this:

// Define a list of numbers
def list = [101, 334, 1208, 20]

Of course, the list can be of strings as well:

// Define a list of strings
def names = ['Steve','Paul','Jane','Josie']

If needed, the list can contain objects of any type, including a heterogeneous set of object types, for example a mix of strings and numbers.

To refer to a specific element in the list, use the square brackets with an integer argument like this.

// Store the third name in the list in a variable
def thirdName = names[2] // zero based index!

Remember that the list is zero-based so list[0] is the first element of the list and list[5] is the six element. Of course you can also pass a variable as the value of the operand like this:

for (j in 2..3) {
  def curName = names[j]
  // do something with curName value here
}

To update a specific list item's value, you can use the combination of the subscript and the assignment operator:

names[2] = 'John'

To add an entry to the end of the list, use the add() method:

names.add('Ringo')

A list can contain duplicates, so if you write code like the following, then the string Ringo will be added twice to the list:

// This will add 'Ringo' twice to the list!
names.add('Ringo')
names.add('Ringo')

To test if an entry already exists in the list, use the contains() function. This way, you can ensure that you don't add the same item twice if duplicates are not desirable for your purposes:

// The exclamation point is the "not" operator, so this
// first checks if the 'names' list does NOT contain 'Ringo' before
// adding it to the list
if (!names.contains('Ringo')) {
  names.add('Ringo')
}

To remove an entry from the list, use the remove() method.

names.remove('Ringo')

Note that this only removes the first occurrence of the item in the list, returning a boolean result indicating true if the desired item was found and removed. Therefore, if your list allows duplicates and you need to remove them all, you'll need to write a loop to call remove() until it returns false.

You can iterate over the entries in a list using the for...in loop like this:

// Process each name in the list, returning
// false if any restricted name is encountered
for (name in names) {
  // call an object function for each name processed
  if (isNameRestricted(name)) {
    return false
  }
}
return true

You can define an empty list using the square-bracket notation with nothing inside like this:

def foundElements = [] // empty list!

Working with Maps

A map is an unordered collection of name/value pairs. The name in each name/value pair is called the map's key for that entry since it is the key to looking up the value in the map later. You can create a map using Groovy's square-bracket notation, using a colon to separate each key and value, and a comma between each key/value pair like this:

// Define a map of name/value pairs that associate
// a status value (e.g. "Open", "Closed", "Pending") with a
// maximum number of days
def maxDaysByStatus = [Open:30, Closed:90, Pending:45]

Notice that by default, the map key is assumed to be a string so you don't need to include the key values in quotes. However, if any key value contains spaces you will need to use quotes around it like this:

def maxDaysByStatus = [Open:30, Closed:90, Pending:45, 'On Backorder':10]

If you want to use another type as the map key, you need to surround the key with parentheses. Consider the following example without the parentheses:

def x = 1
def y = 2
def xvalue = 'One'
def yvalue = 'Two'
// this creates a map with entries ('x'->'One') and ('y'->'Two')
def m = [x:xvalue,y:yvalue]

The above example creates a map with key values of the strings x and y, rather than using the value of the variable x and the value of the variable y as map keys. To obtain this effect, surround the key expressions with parentheses like this:

def x = 1
def y = 2
def xvalue = 'One'
def yvalue = 'Two'
// this creates a map with entries (1->'One') and (2->'Two')
def m = [(x):xvalue,(y):yvalue]

This creates a map with key values of the numbers 1 and 2.

To reference the value of a map entry, use dot notation like this, using the may key value as if it were a field name on the map object:

def closedDayLimit = maxDaysByStatus.Closed

If the key value contains a literal dot character or contains spaces or special characters, you can also use the square-bracket notation, passing the key value as the operand:

def onBackorderDayLimit = maxDaysByStatus['On Backorder']

This square bracket notation is also handy if the key value is coming from the value of a variable instead of a literal string, for example:

// Loop over a list of statuses to process
for (curStatus in ['Open','On Backorder']) {
  def limitForCurStatus = maxDaysByStatus[curStatus]
  // do something here with the current status' limit
}

To add an new key/value pair to the map, use the put() method:

// Add an additional status to the map
maxDaysByStatus.put('Ringo')

A map cannot contain duplicate key entries, so if you use put() to put the value of an existing element, the existing value for that key is overwritten. You can use the containsKey() function to test whether or not a particular map entry already exists with a given key value, or you can use the containsValue() function to test if any map entry exists that has a given value — there might be zero, one, or multiple entries!

// Test whether a map key matching the value of the
// curKey variable exists or not
if (maxDaysByStatus.containsKey(curKey)) {
  def dayLimit = maxDaysByStatus[curKey]
  // do something with dayLimit here
}
else {
  println("Unexpected error: key ${curKey} not found in maxDaysByStatusMap!")
}

To remove an entry from the map, use the remove() method. It returns the value that was previously associated with the key passed in, otherwise it returns null if it did not find the given key value in the map to remove.

maxDaysByStatus.remove('On Backorder')

You can define an empty map using the square-bracket notation with only a colon inside like this:

def foundItemCounts = [:] // empty map!

Working with Ranges

Using ranges, you can conveniently creates lists of sequential values. If you need to work with a list of integers from 1 to 100, rather than creating a list with 100 literal numbers in it, you can use the .. operator to create a range like this:

def indexes = 1..100

The range is particularly useful in performing iterations over a list of items in combination with a for loop like this:

def indexes = 1..100
for (j in indexes) {
  // do something with j here
}

Of course, you need not assign the range to a variable to use it in a loop, you can use it inline like this:

for (j in 1..100) {
  // do something with j here
}