Application Scripts

Application Scripts are business logic scripts that enable developers and administrators to customize the behavior within the TrackVia platform. Based on the Groovy language, developers can easily tailor the application to meet the unique needs of the business. Application scripts are created and managed via the integrated Groovy code editor. They are stored at the table and can be invoked for any of the following record level events:

  • Before Insert
  • After Insert
  • Before Update
  • After Update
  • Before Delete
  • After Delete

In most cases, the Before event should be used. A notable exception is with creating a new record and using a script to add children. In this case, use After Insert because the children need the parent to exist before they can link to it.

Application scripts work at the table level and thus are not associated to any views or forms.

Application scripts are transactional. If any portion of the application script incurs an error or a timeout is exceeded, all changes that have been made within the script will be reverted.

Transactionality is an important concept. Application scripts will not leave you with incomplete information but your users will see an error if a script fails.

Restrictions

To ensure performance and security, the application script is executed in a private container. Access to any system resources are disallowed. Each application script is allotted a quota of time and CPU. Applications scripts are not executed on update or delete for batch operations on all records.

Groovy

TrackVia Application Scripts are built using the Groovy programming language. The Groovy language gives developers the ability to work in an industry standard language and take advantage of unique TrackVia capabilities with full transactionality. There’s extensive documentation on the language on the Groovy website.

Bind Variables

Bind Variables are special variables that are automatically available in all application scripts. They are the baseline for accessing and working with data within the script.

currentValues is a “Map” containing the values of the record that has triggered the application script. These values can be accessed or modified using the field or relationship name.

previousValues is a “Map” containing the values of the record prior to the update of the record. The previousValues variable is only populated for before or after update scripts. These values can be accessed or modified using the field or relationship name.

childTables is a “Map” of “Lists” into which new child records can be added. After the execution of the Applogic script, new records that have been added to these lists are created and linked to the parent record.

childRecords is a “Map” of Lists containing existing child records organized by table and relationship name

Functions

Special functions are provided and accessible in all application scripts for finding and working with the data.

Function: addChild
Description: adds a child record
Arguments:
Name of the child table
Name of the relationship
Map of the record values
Returns:
void
Example:

addChild "Child Table", "Link to Parent", ['Child Name':'David', 'Child Number':42]

Function: getChildren
Description: Get the associated child records.
Arguments:
Name of the child table
Name of the relationship
Returns:
List of found child records
Example:

List childRecords = getChildren "Child Table", "Link to Parent"

Function: loadRecord
Description: Find a record by a single value
Arguments:
Name of the table
Name of the field
Value of the field
Returns:
Map of the found record
Example:

Map record = loadRecord "Table Name", "Field Name", "Field Value"

Function: loadRecord is a function to find a record by the values in the map
Arguments:
Name of the table
Map of fields and values
Returns:
Map of the found record
Example:

Map childRecord = loadRecord "Child Table", [‘Field One’ : ‘Value’, ‘Field Two’ : ‘Value’]

Function: find
Description: find a list of records by a single value
Arguments:
Name of the table
Name of the field
Value of the field
Returns:
List containing 0 or more matching records Example:

List records = find “Table Name”, “Field One”, “Value”

Function: find
Description: find a list of records by a map of key and value pairs
Arguments:
Name of the table
Map of the fields and values
Returns: List containing 0 or more matching records
Example:

List records = find “Table Name”, [‘Field One’: ‘Value’, ‘Field Two’: ‘Value’]

Function: delete
Description: delete the record
Arguments:
Map of the fields and values
Returns:
void
Example:

Map record = loadRecord "Table Name", "Field Name", "Field Value"
delete record

Function: update
Description: update the record
Arguments:
Map of the fields and values
Returns:
void
Example:

Map record = loadRecord "Table Name", "Field Name", "Field Value"
update record

Function: save
Description: adds a record to the table
Arguments:
Name of the table
Map of the record
Returns:
Map representing the saved record
Example:
save “Table Name”, [ ‘Field One’ : ‘Value’, ‘Field Two’ : ‘Value’]

Examples

How do I change a value in the current record ?

currentValues["Status"] = “Active” currentValues[“Age”] = 20;

How do I change a value in the parent record ? currentValues[“Link to Parent”][“Status”] = “Active”

How do I change a value in the grandparent record?

currentValues[“Link to Parent”][“Link to Grandparent”][“Status”] = “Active”

How do I fetch a value in the parent record?

String status = currentValues[“Link to Parent”][“Status”]

How do I add a child record?

addChild "Child Table", "Link to Parent", ['Name':'Hitchhikers Guide to the Galaxy’, 'Meaning of Life':42]

How do I change a value in the child record ?

List<Map> childRecordsList = getChildren ‘Child Table’, ‘Link to Parent’
Map childRecord = childRecordsList.find { Map record ->
record.'Name'.toString().contains(‘Hitchhikers Guide to the Galaxy’) }

if (childRecord) {
childRecord['Meaning of Life’] = 42
}

How do I print a value in all child records ?

List childRecords = childRecords["Child Table"]["Link to Parent"] as List
if (childRecordsList) {
childRecordsList.each {logger.info("${it['Child Name’]}”)}
}

How do I update values in child records ?

List childRecords = getChildren("Table", "Link to Parent") as List

childRecords.each {it["Name"] = currentValues["Name"]}
childRecords.each {it["Meaning of Life"] = 42}

How do I create child records ?

// Create 5 child records
(1..5).each {
addChild “Child Table”, “Link to Parent”, [‘Status’ : ‘Active’, ‘Index’ : ${it}]
}