Event Triggers

Your scripts can be executed based on events that happen within the application, such as when something is created, updated, or deleted. Additionally, you can choose to define whether the script should execute before or after a save. The UI will wait for scripts that are triggered by an event to finish, giving the script an opportunity to perform custom validation checks or update data.

To create an event trigger for your script, you can use the “Add an Event Trigger…” link on the right-side action panel or you can navigate to the Event Triggers tab on the left and click on the “New Trigger” button.

When creating  a new event trigger, you will be presented with the following modal window:

1.  Script: The name of the script that the event trigger is being attached to (read-only).

2.  Object: Select the object that you would like the event trigger to observe. For example, if you would like your script to be executed whenever a new matter is created, you would select "Matter" as the object here.

3. Action: Select the action that you would like the event trigger to observe. For example, if you would like your script to be executed whenever a new matter is created, you would select the "On Create" action. The available actions are context-dependent based on the selected object, however, most objects allow you to select between "On Create", "On Update", or "On Delete".

4. Action State: Select the state of the action that you would like the even trigger to observe. The action state determines the state of the object instance the script can use: either before the object is saved or after.  For example, if your script needs to determine that matters follow a strict 6-digit validation rule, you would set the action state to "Before Save" so your script can reject the incoming matter instance before saving it if your custom validation logic fails.

5.  Order: If you have multiple scripts that have the same trigger flow, you can apply a number here to determine the order that they are executed in. The lower the number, the higher the priority. 

6.  Save: Saves the trigger and closes the modal window.

Action State Behavior

Before Save Action State

When writing scripts that utilize the Before Save action state, the system expects that the same type of object that was provided to the script is the same object the script returns in order to execute successfully.

For example, if you create a before-save trigger on the matter object, the Get-InboundObjectInstance cmdlet will provide an instance of the matter that is about to be saved, giving you an opportunity to issue validation checks and/or alter field values prior to saving the matter. The script either needs to error out (preventing the save), or return the matter back to the system so it can be saved.

Script Example:

# This script has a "Before Save" event trigger on the "Matter" object

$incomingMatter = Get-InboundObjectInstance

if (([string]IsNullOrWhiteSpace($incomingMatter.Reference)) -or ($incomingMatter.Reference.Length -lt 6)) {
    throw "The reference field must be at least 4 characters long"
}

return $incomingMatter 

In this example, we are retrieving the incoming matter using the Get-InboundObjectInstance cmdlet and checking if the reference field has at least 4 characters. Because the script is attached to a matter trigger event, a matter object is provided through this cmdlet. This cmdlet will provide the object instance based on the trigger. In this script, if the reference field is not at least 4 characters long, it will throw an error preventing the matter from being saved. If the reference field is at least 4 characters, the script returns the matter back to the system so it can be saved.

After Save Action State

Scripts that utilize the After Save action state do not need to return anything because the object they have reference to has already been saved. If an object that has already been saved needs to be modified, you would need to use an appropriate cmdlet that can update the object directly.

Script Example:

# This script has an "After Save" event trigger on the "Matter" object

$savedMatter = Get-InboundObjectInstance

if (([string]IsNullOrWhiteSpace($savedMatter.Reference)) -or ($savedMatter.Reference.Length -lt 6)) {
    Write-Output "The reference field is missing. Applying a generic one."
    $savedMatter.Reference = "0001"

    # Save the matter back to the system
    Set-Matter -Entry $savedMatter | Out-Null
}

In this example, the Get-InboundObjectInstance will provide us with the matter that was saved. It uses the Set-Matter cmdlet to update the reference if it’s missing. Note that there is no return value required in this case.

Trigger Chains

Trigger chains occur when there are two or more scripts that have the same trigger conditions applied to them. This is allowed so that scripts can separate their specific concerns to promote modularity and facilitate easier maintenance. For example, you may have an on-update before-save matter script that checks that your matter fields have specific validation requirements prior to allowing a matter to be saved, and then another on-update before-save matter script that updates a custom field based on the calculation of some other fields. Because these two scripts are both attached to the Matter object and they both have On Update actions with Before Save action states, they will be executed at the same time, causing a trigger chain. Trigger chains behave differently depending on the action state.

Before Save Trigger Chain Action State

• The return object of a script will be the inbound object instance of the next script within a trigger chain. Any modifications made to the returned object will be present in the next script.

• The object that is returned from a script must be in the the expected inbound object type. Passing different object types within a trigger chain will not work and will result in unexpected behavior and cause errors.

• Returning a null value is allowed and will not place the script in an error state. This causes the input of the next script to be null, giving the script an opportunity to do something if desired. If you anticipate your scripts to pass null values within the trigger chain, be sure that your code has null checks in place to accommodate this situation.

• If an error occurs at any point within in a trigger chain (a non-zero exit code), the trigger chain will not execute the remaining scripts in the chain. Causing uncaught exceptions by using the Write-Error cmdlet or by using the throw command is the preferred way to "short circuit" execution of a trigger chain.

After Save Trigger Chain Action State

• Scripts are not chained together like before-save scripts so the input object of an after-save event will always be the object that was passed in as the result of the object that was saved. This makes scripts of this variety independent of one-another.

• Return functions have no effect on after-save scripts.

• If an error occurs in a trigger chain (a non-zero exit code), the trigger chain will continue to execute the remaining scripts in the order they were defined.

Event Trigger Use Cases

Below are some use cases on how to apply event triggers in a variety of scenarios.

Matter reference field must be 6-digits

Scenario: You're interested in designing a script that checks matters to ensure that the "Reference" field contains 6 digits. You would like to run this custom validation any time a new matter is created or updated, and you would like to ensure that the matter does not get saved if the rule is not met.

Trigger Solution: You would create 2 event triggers: An "On Create" trigger and an "On Update" trigger. Both triggers would use "Matter" as the object and "Before Save" as the action state.

Automatically create a QC task

Scenario: You would like to design a script that automatically creates a processing QC task when the task that describes the processing work is completed. You believe that this creates less work for your end users from having to manually create the QC tasks when they are finished with the work and also helps them stay on track with the business requirement of providing quality deliverables.

Trigger Solution: You would create a single event trigger that uses "Task" as the object, "On Update" as the action, and "After Save" as the action state.

Add a "On Behalf Of" user reference to billing entries

Scenario: You have a custom field on the billing entry object named "On Behalf Of" that you require your users to fill out whenever they create or update a billing entry. You would like to streamline this process and design a script to make it easier for them (and less error prone to missing entries) to not have to require them to enter anything into the field if they, as the creator, are also the "On Behalf Of" user.

Trigger Solution: You would create 2 event triggers: An "On Create" trigger and an "On Update" trigger. Both triggers would use "Billing Entry" as the object and "Before Save" as the action state.

Close a task based on the contents of an email reply

Scenario: You're interested in closing tasks when someone replies to a task email notification that contains the text "#close-task". You believe that this helps cut time for your users by not requiring them to go into the application just to close a task. It would also allow tasks to close faster opening the queue for the next task.

Trigger Solution: You would create a single event trigger that uses "Task Comment" as the object, "On Create" as the action, and "After Save" as the action state.

Performance Considerations

Because the UI will wait for scripts to execute before moving on, you need to keep performance considerations in mind. Scripts that take too long to execute or executing too many scripts at a time for the same events will lead to degregated performance which ultimately leads to poor user perception. Event triggers are a double-edged sword where attached scripts can help you fine-tune many custom and unique workflows, but be sure to measure and monitor your scripts performance, make optimizations where you can, and survey your users where appropriate so that your event triggers aren’t leading to poor user experience.