Intro to App Scripts

Overview

This article covers the various Event Types used to trigger App Scripts, the Order of Operations for actions performed by App Scripts, how to access the script editor to create scripts, and the limitations of App Script capabilities.

📜 What are App Scripts? 

App Scripts are self-contained blocks of code written in the Groovy scripting language.  App Scripts are triggered to run in response to user actions in TrackVia, and empower admins to customize application behavior by automating data changes, enforcing business rules, and creating seamless workflows.

✍️ Who Can Use App Scripts?

App Scripts are built at the Table level, so you must edit a Table in order to access that Table's Script Editor. This means that only Super Admin users or users assigned to an App Admin role can create and modify App Scripts. They can:

• Access the Script Editor 
• Create, view, edit, and delete App Scripts
• Enable or disable App Scripts
• Review App Script error logs
  
  

Why Use App Scripts?

App Scripts are best used when you need to:

• Automatically populate or update field values (e.g. auto-fill a "Status" field based on the user's selection in another field)
• Create or update records based on user input (e.g. create a new "Task" record every time a "Project" record is added)
• Enforce extra data validation beyond the options available in Form rules (e.g. prevent the deletion of a record if it has related Child Records - refer to the Using Runtime Exceptions section of the App Script Example Library article for more information.)
• Maintain consistency across related tables (e.g. auto-creating Child Records, or deleting all Child Records when their Parent Record has been deleted).
• Perform actions in response to specific events like Saving or Deleting a record.
  
  

When do App Scripts Run?

App Scripts are triggered to run based on the following record-level events: 

App Script  Order of Operations

The graphic below shows the order in which actions in TrackVia take place. Understanding the order of operations will help to inform which Event Type you should use to trigger your App Script to run.

As shown above, App Scripts require a user to save changes to a record in order for the script to be triggered to run. Some key points to keep in mind are:

• "Before Event" App Scripts (Before Insert, Before Update, Before Delete) are triggered once a user clicks "save" on a record. These scripts will run and perform their actions prior to the changes being saved to the database.
• Most App Scripts can use "Before Event" triggers, but there are two main instances when App Scripts need to use an "After Event" trigger: 
  1. When the script references a triggered field - We can see in the order of operations above that the "Before Event" scripts would run prior to any Triggered fields running their calculations, but "After Event" scripts don't run until AFTER Triggered fields have performed their calculations.
  2. If the script is creating Child Records upon the creation of a Parent Record. In this case, the Parent record needs to be created and saved to the database first before any Child Records can be created and linked to the Parent Record.
• When an "After Event" script makes changes, those changes must progress through the order of operations again until reaching the Save Event, which can re-trigger "Before Event" scripts. If not carefully scoped, this can lead to repeated execution and potential timeout errors. To avoid this, ensure "Before Event" scripts are narrowly targeted and efficient.

📝 How to Access the Script Editor and Create App Scripts

To manage App Scripts:

1. Edit a Table

2. Click on the "Application Scripts" tab near the top of the page

3. On the left side of the screen you will see any existing App Scripts on the Table, and to create a new one, click "Add A New Script"

4. (Optional) Under "AppScript Name", enter a title for the new script

5. Select the Trigger Event (e.g. Before Update) 

6. Begin coding your script using the Groovy language

🔎 Where to View a List of All App Scripts in Your Account

After you've created App Scripts, you can view the list of every App Script that exists in your account by clicking on the "App Overview" tab in the Navigation Bar at the top of the screen and select the "App Insights" option from the drop down menu which brings you to the App Scripts tab.

Here you'll find overview details for each App Script including:

• the App where the script exists
• the Table the script was built on
• the name of the script
• the script's Trigger Event
• the script's status (active or inactive)
• the last error that occurred in the script's error log

🚫 App Script Limitations

• App Scripts CANNOT be triggered to run based on a user opening a View, or a Form. They can only be triggered to run if a record is created, updated, or deleted. 
• App Scripts can only access data that is physically stored in the database – this means that any field that does not store its data in the database cannot be referenced in a script.
  The field types that cannot be referenced by App Scripts are: Calculated fields, Auto Counters, and Record ID fields as these fields generate their values on the fly instead of storing their values in the database.
• App Scripts have limited functionality with Image fields and Document fields. These field types can by referenced by App Scripts to check whether the field contains a file, but the file itself cannot be referenced (e.g. an App Scripts cannot open files attached to a record and access the data within the file).
• For Mobile device users, App Scripts do not run while the device is offline, and will only run once the device is connected to the Internet.

Related Articles: 

• Script Writing - Basic Concepts
• App Script Best Practices
• App Script Limitations
• App Script Troubleshooting Basics
• App Script Example Library