Script Writing - Using Variables

Overview

This article details the different types of Variables, the data type they are used to interact with, and how they are declared. Click on a Variable below to jump to that section:

• String
• Int / Integer (Number)
• Date
• Boolean
• List
• Map
• List<String>
• List<Map>
• Double
• Float
• BigDecimal
• def

Variable Types and How to Use Them

1. String

Check out the Script Writing - Working with Strings article for more details and examples

Strings are used to interact with plain text such as values in Single Line, Paragraph, and Drop Down fields.

Common Use Cases

• Updating existing Text values or stamping a text value into a field
• Concatenating text values from multiple fields

Declaring String Variables

• Strings are declared using single quotes ( ' ) or double quotes ( " ).
• Multi-line Strings are declared using either triple single quotes ( ''' ) or triple double quotes ( """ ).

See the examples of each below:

//Single Quotes
String helloWorldSingle = 'Hello World' as String

//Double Quotes
String helloWorldDouble = "Hellow World" as String

//Multi-line Single Quotes
String helloWorldMLSingle = '''Hello
World''' as String

//Multi-line Double Quotes
String helloWorldMLDouble = """Hello
World""" as String

2. Int / Integer (Number)

• Integers are whole numbers (e.g. 42)
• Integers can be positive or negative numbers.
• Integers (int) are also used when declaring Constants in TrackVia.

👀 Note: We recommend using BigDecimal instead of Integer when performing any math with variables.

Declaring Integers

Integers are declared with int. For example: int ten = 10 as int

Math with Integers

Integers can be used to perform simple mathematical operations. See the examples below:

int ten = 10 as int
int five = 5 as int

//Addition Example
10 + five
//Output
//15

//Subtraction Example
ten - five
//Output
//5

//Multiplication Example
ten * five
//Output
//50

//Division Example
ten / five 
//Output
//2

3. BigDecimal

• BigDecimal is the preferred data type used for working with any non-integer numbers (e.g. non-whole numbers). 
• This allows a larger amount of decimal points after a number and can prevent errors due to rounding.

See the examples of arithmetic using BigDecimal below: 

BigDecimal num1 = 23.56 as BigDecimal
BigDecimal num2 = 136.182323 as BigDecimal

BigDecimal num3 = 13.5 /1.75 as BigDecimal
//num3 = 7.7142857143

BigDecimal num4 = num1 + num2 as BigDecimal
//num4 = 159.742323

BigDecimal num5 = num1 * num2 as BigDecimal
//num4 = 3208.45552988

4. Date

All Dates and Date/Time values in TrackVia are stored as UTC timestamps. When doing any manipulation of values in Date or Date/Time fields, the time zones must be accounted for.

The example below details the process of using a Date variable in conjunction with the Calendar class in order to manipulate the date value and set it equal to the first day of the next month.

// Create date variable
Date theDate = currentValues["Date Field"] as Date

// Create calendar variable for date manipulation
Calendar calendar = Calendar.getInstance()

// Set calendar date to date variable
calendar(theDate)

// Add one month to date
calendar.add(Calendar.MONTH, 1)

// Set calendar date to the first day of the month
calendar.set(Calendar.DAY_OF_MONTH, calendar.getActualMinimum(Calendar.DAY_OF_MONTH))

// Set date variable equal to the calendar variable
theDate = calendar.getTime()

// Set date field to the new date
currentValues["Date Field"] = theDate

5. List

Check out the Script Writing - Working with Lists article for more details and examples

Lists are ordered sequences of data. Lists can hold a variety of data and can have different data types intermingled within a single List. 

Declaring Lists

Lists are declared using List as List. See examples of various Lists below:

//A List of integers
[11, 12, 13, 14]

//A List of Strings
['I', 'Love', 'TrackVia']

//A nested List
[1, 2, [3, 4], 5]

//A List that includes different data types
['TrackVia', 21, 2.11]

//Empty List
[]

6. Map

• Maps are collections of key : value pairs (e.g. ["Field name 1" : "value in field 1" , "Field name 2" : "value in field 2"]
• Maps are declared with Map
• In TrackVia, think of a Map as a complete record that contains all values from every field on the record.

Accessing Attribute Values within a Map

• In this example, we have a "Person" record with the following fields and values: 
  Name = John Smith
  Age = 50
  Address = 123 Main Street

See the example below for how this example is declared as a Map with the key : value pairs: 

Map person = [name: "John Smith", age: 50, address: "123 Main Street"];

• Let's assume that this "Person" record is the current record that triggered our App Script to run. With this in mind, we can use currentValues to pull the value found in each field. See the example below:

currentValues["Name"]
//Returns "John Smith"

currentValues["Age"]
//Returns 50

currentValues["Address"]
//Returns "123 Main Street"

7. List<String>

List<String> is a List composed of Strings. 

List stringList = ["thingA", "thingB", "thingC"];

8. List<Map>

List<Map> is an array composed of the key : value pairs of multiple Maps.

List listOfMaps = [
[key: "value"],
[key: "value"], 
[key: "value"]
];

9. Boolean

• Boolean is a data type that holds only two possible values: true and false.
• Boolean is declared with as Boolean

In TrackVia, Booleans are often used for:

• Checkbox fields (checked = true, unchecked = false)
• Conditional logic (e.g. "If this is true, then do that")

The example below shows how to access a Checkbox field called "Manager Approved" using Boolean to check whether the Checkbox has been checked, and if so, change the "Status" Drop Down field to "Approved to Start", and if it is unchecked, change the "Status" field to "Awaiting Approval".

Boolean managerApproved = currentValues["Manager Approval"] as Boolean
if(managerApproved){
currentValues["Status"] = "Approved to Start"
}
else{
currentValues["Status"] = "Awaiting Approval"
}

10. Double

Double is used to store decimal numbers (i.e. a number with digits after the decimal point such as 3.14). 

Use Double when:

• Working with Currency fields, Percentage fields, or Number fields whose values may contain digits following the decimal point.
• You want to perform math with decimal numbers
• Integer division: Use Doubles if you want decimal results. Integer math will round down.

The example below shows how to use Double to retrieve a decimal number, and then multiply it by an Integer:

Double unitPrice = currentValues["Unit Price"] as Double
int quantity = currentValues["Quantity"] as int
Double total = unitPrice * quantity
currentValues["Total Price"] = total

11. Float

Very similar to Double, Float is a decimal number type, but with less precision and memory usage than Double. Because of this, Float should only be used in place of Double in rare instances such as specifically needing to reduce memory usage, or to integrate with APIs or external code that requires Float values.

• Float: 32-bit floating-point number with ~6-7 decimal digits
• Double: 64-bit floating point number with ~15-16 decimal digits (more common and precise)

Below are examples of Float Values. 👀 Note the f at appended to the last digit indicating that it is a Float, not a Double. 

• 3.14f
• 75.0f
• 0.123456f

See the example below for how to declare a Float:

Float unitPrice = currentValues["Unit Price"] as Float

12. def

In Groovy, def is a keyword used to declare a variable without explicitly specifying its type.

• Using def allows Groovy to dynamically assign the data type based on the value. 
• def is ideal for quick and flexible scripting where strict typing isn't required.

The example below shows how to use def to read a field's value without explicitly defining the field's data type (e.g. no need to append as String) - Groovy can infer the type based on the value. 

def status = currentValues["Status"]

• However, if you are declaring a Variable where the data type MUST be clear, such as passing to a method that requires a Map, you can use def to declare the variable, but you will need to explicitly define the type by appending as Map to it. 

The example below shows how to use def to explicitly define a Variable as a Map:

def record = loadRecord("tableId", "Field Name" , "Search Term") as Map

🥇 Best Practices for using def

• Use descriptive variable names to improve readability
• Use def when the data type is obvious from the context to keep your code clean and concise
• Use type casting when working with numbers or dates to help avoid errors in math or comparisons

Related Articles: 

• Script Writing - Using Constants
• Script Writing - Using Functions
• Script Writing - Syntax Rules
• App Script Example Library