An Action Trigger allows you to create and execute custom business logic when a Create, Update, or Delete record operation occurs on an object record. This capability is similar to Vault Java SDK Record Triggers, however, Action Triggers rely upon Vault formula expressions rather than Java code. Action Triggers are made up of blocks of IF/THEN/ELSE
conditional logic to perform actions when a record operation occurs. These blocks of conditional logic are referred to as Action Blocks.
You can configure conditional logic to execute before or after a record is saved, referred to as Before Save and After Save events respectively. For example, you can configure an Action Trigger to send a notification to a user when a field is updated. Or, you can configure an Action Trigger to start a workflow when a record is created.
In addition, Action Triggers provide an editor that allows you to select functions and fields and actions, rather than manually type them in, as you build your conditional logic.
Note: Record changes that occur from an Action Trigger are audited as System on behalf of [User].
Before Save Events
Before Save events occur before a record is saved on the current object. Action Triggers configured in these events are best used with Update Current Record actions, which includes operations such as defaulting field values and validating data entry. Updating fields on the current record is more efficient before it’s saved than to update the same record again after it is saved.
After Save Events
After Save events occur after a record is saved on the object. For example, you could configure an After Save Action Trigger to update related records when a user saves a record after a specific update occurs. Or you could change the state of a record after a user saves the record if certain fields are populated with specific values. In addition, you could initiate a workflow after a record is created or updated. Each of these actions are best executed after a record is saved rather than before.
Accessing Action Trigger Configuration
You can configure Action Triggers in your Vault from Admin > Configuration > Objects > [Object] > Triggers. The Triggers tab displays Create, Update, and Delete tabs which represent record operations.
Each record operation tab displays a Change Current Record - Before Save and a Perform Other Actions - After Save section which allow you to configure Before Save and After Save Action Triggers. For example, if you configure a Before Save Action Trigger on the Create tab, you can create business logic that states whenever a record is created on this object, certain fields on the record must contain a specific value before the record is saved.
Note: Up to ten (10) Action Triggers are allowed per Before Save and After Save event.
How to Configure an Action Trigger
To configure an Action Trigger:
- Navigate to Admin > Configuration > Objects > [Object] > Triggers.
- Click Create under the Change Current Record - Before Save or Perform Other Actions - After Save section on the Create, Update, or Delete tab.
- Enter a Label and Name for the Action Trigger.
- Optional: Change the Order the Action Trigger executes in the Before Save or After Save event. Vault automatically orders Action Triggers in Before Save and After Save events from the lowest number to the highest number.
- Optional: Enter a Description.
- Create an IF condition. You can use the Action Trigger editor to create the condition. If the THEN action should always execute when the record operation occurs, click Set condition to always perform action in the editor. This option is available only when the IF condition line is blank. You cannot use Lookup, Formula, or Roll-up fields in Action Triggers.
- Select a THEN action. Use the editor to build a formula around the action.
- Optional: Select an ELSE action. This action applies if the IF condition returns false.
- Optional: Hover your cursor before or after an Action Block to display the Add Action Block button. Click this button to add an Action Block. You can also click the Add Action Block icon () to add an Action Block right after the current one selected.
- Optional: Click Edit Details () to change the Label, Name, or Description of the Action Block.
- Optional: Click Validate () to validate the formulas in your Action Block. If an error occurs, Vault highlights the line where the error is located. Hover your cursor over this highlighted area for more information on the error. You can also click Validate All () to validate all formulas in all Action Blocks for this Action Trigger.
- Optional: Click Copy Actions () to copy the conditional formulas in the Action Block to your clipboard, replace the conditional formulas in the Action Block with formulas from your clipboard, or duplicate the conditional formulas in a new Action Block.
- Optional: Click Delete () to remove the Action Block.
- Click Save.
- Optional: Click Save + Exit to leave editing the Action Trigger.
How to Turn an Action Trigger On & Off
When you save the Action Trigger, Vault saves it as a draft and does not execute your changes in production. To activate the Action Trigger, click the Turn ON Trigger icon (). This action changes the Operating Status to On. Click the Turn OFF Trigger icon () to turn the Action Trigger off and make it inactive. This icon is only available when the Action Trigger is saved after initial creation.
How to Activate an Action Trigger
If you made changes to an existing active Action Trigger, Vault saves those changes as a draft. The Version field contains a View Active button that allows you to view the active version of the Action Trigger. Click the Make Configuration Active icon () to apply your changes to the active version. You can also click Revert to Last Active Configuration () to use the previous active version. These options are also available in the Action Trigger’s Actions menu.
Best Practices for Update Record Operations
When configuring an Action Trigger in an Update record operation, ensure the Action Trigger executes only when the record is updated to meet a specific criteria. This process helps optimize performance and reduces redundant actions. You can accomplish this by using functions such as PriorValue($field)
to compare new field values with their previous value.
For example:
IF
PriorValue($impact__c) != impact__c && impact__c = "high__c"
Compares the previous value of the Impact field with the new value High.
Component Reference Formula Attribute
Some functions within Action Triggers require the use of components as attributes rather than the API name value. To reference a component, such as an object, object type, or workflow, use the API name preceded by a $
sign. For example, $vern_bio__v
is valid while vern_bio__v
is invalid.
Using the Action Trigger Editor
When you click or begin typing below an IF, THEN, or ELSE line, Vault displays the Action Trigger editor. This editor allows you to select functions and fields to build formula expressions, removing the need to manually enter formulas. You can also search for available fields and functions within the editor.
The Action Trigger editor uses an auto-complete functionality that displays menus based on your selected field or function. For example, if you select Country, the editor displays a list of operators you can select. Once you select an operator, you can select another field or function, or manually enter the next value. If you select a function or action, the editor adds the function without parameters to the Action Block. Click the function or action to display a link to Vault Help with more information. Click the Edit icon () to open the editor again.
When you add a THEN or ELSE action, the editor displays all actions available in the Before Save or After Save event. When you click an action’s edit icon (), Vault opens the Action Configuration dialog. This dialog allows you to select options related to building the action’s formula. For example, if you select Create Records, you can select the relevant object and field from the Action Configuration dialog. If you select a picklist field, click Set Value in the dialog to select fields from the picklist.
Once you click Continue in the dialog, Vault adds the action with functions and parameters related to your selection. For example, selecting related records returns the GetRelatedRecords
function in the action.
Order of Operations for Action Triggers
When a Create, Update, or Delete operation occurs, Vault performs the following sequence of steps:
- Before Save Action Triggers
- Execute Before Save Action Triggers
- Execute BEFORE Custom Vault Java SDK Record Triggers
- Save record changes to database
- After Save Action Triggers
- Execute After Save Action Triggers
- Execute AFTER Custom Vault Java SDK Record Triggers
- Commit saved record changes to database
Data available in Before Save and After Save events is dependent on the Create, Update, and Delete record operations. For example, in a Create record operation, you cannot retrieve old or existing values because a new record is being created. Likewise, it is not efficient to set a field value after it has been persisted in a Delete record operation.
Action Triggers can overwrite field values on records. For example, if a Before Save Action Trigger is configured in a Create operation to populate the optional Region Text field with value United States of America, Vault overwrites any other value the user enters in the field after they save the record.
Note: After Save Action Triggers in Create record operations always execute before Create Record event actions.
Excluded Action Triggers
Action Triggers are excluded from execution in the following scenarios:
- If Record Migration Mode and No Triggers are selected in Vault Loader.
- If the
X-VaultAPI-NoTriggers
header is set to true - If a Roll-up field calculation occurs
- If operations on a parent record cascade down to the child record
- If a user sync occurs on domain-level attributes
Configurable Actions
Vault allows you to perform the actions listed below on records through Action Triggers. This section describes creating these actions using the Action Trigger editor.
Actions that use related records accept three (3) levels of outbound object relationships from the originating object. Actions that use fields{}
must use a valid, active field on the specified object.
Note: You cannot use system-managed or read-only fields in any of the actions or functions.
Update Current Record
The Update Current Record (UpdateCurrentRecord(fields{})
) action updates fields on the current record the user is modifying or creating. You can enter multiple fields with their values. You cannot set a value on a parent object reference field if this action is used in a Before Save Action Trigger within a Create operation.
Parameters
fields{}
: Required, a comma delimited list of fields and values to set on the current record.
Example
UpdateCurrentRecord(
-
{$description__c:"New contract",
-
$contract_date__c:Today(),
-
$contract_code__c:code__c})
-
Sets a value for the Description, Contract Date, and Contract Code fields on the current record.
Create Record
The Create Record (CreateRecord(object/objectType, fields{})
) action creates a single record on a specified object or object type with specified field values.
You must select an object where the record will be created, an active field on the object, and enter a field value. You must select an object type if one exists on the selected object. You can enter multiple fields with their values.
Parameters
-
object/objectType
: required, indicates the object or object type to create the new record, such as$product__v
for object and$product__v.device__v
for object type. The$
component reference format is required on the object name. -
fields{}
: Required, a comma delimited list of fields and values to set on the record.
Example
CreateRecord($contract__c,
-
{$description__c:"New contract",
-
$contract_date__c:Today(),
-
$contract_code__c:code__c})
-
Creates a record on the Contract object and sets a value for the Description, Contract Date, and Contract Code fields on the created record.
Update Records
The Update Records (UpdateRecords(records, fields{})
) action updates fields on a related record or queried record on an object. If you query an unrelated object, you must provide VQL criteria to select the records to update. This action can update up to 5,000 records.
Parameters
records
: Required, accepts theGetRecords
andGetRelatedRecords
functions.fields{}
: Required, a comma delimited list of fields and values to set on the record.
Example
UpdateRecords(GetRecords($accounts__v, "reviewed=true"),{done__c=true})
-
Updates records in the Accounts object where Reviewed=true and sets the Done field value to true
Delete Records
The Delete Records (DeleteRecords(records)
) action deletes records on a related or queried object. If you select an unrelated object, Vault requires you to use VQL criteria to select the records to delete. This action can delete up to 5,000 records.
Parameters
records
: Required, accepts a GetRecords
or GetRelatedRecords
function.
Example
DeleteRecords(GetRelatedRecords($accounts__cr, "reviewed=true")
-
Deletes records where Reviewed=true in the related Accounts related object
Cancel Workflow
The Cancel Workflow (CancelWorkflow(records, workflowName)
) action cancels an active single-record workflow. The action skips any records without an associated workflow. This action can cancel an active workflow on up to 100 records.
Parameters
-
records
: Required, accepts theGetRecords
,GetRelatedRecords
, andThisRecord
functions. -
workflowName
: Required, accepts the Name value of an active, single record workflow in the specified object’s lifecycle. The Name value must be appended with$
reference format.
Example
CancelWorkflow(GetRecords($accounts__v, "reviewed=true"),$review__c)
-
Cancels the Review workflow on records in the Accounts object where Reviewed=true
Change State
The Change State (ChangeState(records, state)
) action changes the lifecycle state on the current record, a related record, or a queried record. This action can change the lifecycle state on up to 100 records.
Change State can cause a loop if it is used on the current record in an Update event. The loop can also occur if a Change State action is initiated by another process within the same execution path, such as a workflow started with a Change State Action step.
Parameters
records
: Required, accepts theGetRecords
,GetRelatedRecords
, andThisRecord
functions.state
: Required, name of a state in the specified object’s lifecycle. The Name value must use the$
component reference format.
Example
ChangeState(GetRelatedRecords($Object_Relationship.contracts__cr),$approved__c)
-
Changes the state of related Contracts records to Approved
Start Workflow
The Start Workflow (StartWorkflow(records, workflowName)
) action initiates a workflow on the current record, related records, or queried records. You can only start a single record workflow with Auto-start from entry action and event action enabled. Limit of 100 records.
Parameters
records
: **Required, accepts theGetRecords
,GetRelatedRecords
, andThisRecord
functions.workflowName
: Required, accepts the Name value of an active, single record workflow in the specified object’s lifecycle. Auto-start from entry action and event action must be enabled on the workflow.
Example
StartWorkflow(ThisRecord()), $review__c)
- Starts the Review workflow on the current record the user is modifying or updating
StartWorkflow(GetRelatedRecords($accounts__cr, "reviewed=true"), $review__c)
- Starts the Review workflow on related Accounts records where Reviewed=true
Cancel Operation
The Cancel Operation (CancelOperation((optional) errorMessage)
) cancels the record operation initiated by the user. This action rolls back any Action Triggers already performed in a Before Save or After Save event.
You can display a default, custom, or catalog error message to the end user when this action occurs. This message also displays in the API error response. CancelOperation()
with no parameters uses the default error message.
Parameters
errorMessage
: Optional, accepts a custom error message, such as "This operation is canceled"
, an expression that returns a string value, such as Concat("ABC-", name__v)
, or a reference to a message in the Message Catalog, such as $my_group__c.my_message__c
. The $
reference format is required on the catalog message name value.
Example
CancelOperation("Record update canceled")
- Displays the custom error message “Record update canceled” when this action occurs.
CancelOperation($custom_message_group__c.message_name__c)
- Displays the message defined in the Custom Message Group component in the Message Catalog when this action occurs
Print Log
The Print Log (PrintLog(messageType, message)
) action writes a log item to the Debug Log if Include Action Triggers is enabled. This action does not provide contextual help in the Action Trigger editor.
Parameters
messageType
: Required, accepts a Log Level filter, such asALL
,EXCEPTIONS
, andERROR
.Message
: Required, accepts a string or a formula that returns a string, such asConcat("name__v=", name__v)
. If a string is provided, Vault logs the message once, regardless of the number of records in the batch. If a string is not provided, Vault evaluates it once for each record in the batch, and outputs an array of results to the Debug Log.
Example
PrintLog("WARN", "Entered else condition unexpectedly for recordIds")
- Captures WARN logs in the Debug Log with the custom warning message: “Entered else condition unexpectedly for recordIds”
Send Notification
The Send Notification (SendNotification(notificationTemplate, recipients)
) action sends a Vault notification to a specified user. You must select a notification template available to the current object and a recipient.
You can select recipients from user names, User and Person object reference fields, active user groups, users assigned to a lifecycle role on the object, or an email address. You can enter up to 100 email addresses.
Inactive users, Persons, groups, and lifecycle roles will not receive a Vault notification. You can send 5,000 notifications per Send Notification action.
Parameters
notificationTemplate
: Required, accepts the Name value of a notification template using the$
component reference format, such as$trigger_notification__c
.recipients
: Required, accepts a user’s email address, User reference field, Person reference field, active user group, or an active lifecycle role. See examples below.
Example
SendNotification($trigger_notification__c, UserNames("john.smith@biorad.com","jane.doe@biorad.com"))
- Sends a Vault notification to John Smith and Jane Doe.
SendNotification($trigger_notification__c, UserFields($account_owner__c, $application__cr.reviewer__c))
- Sends a Vault notification to the user specific in the Account Owner field and the Reviewer field on the Application record related to the current object
SendNotification($trigger_notification__c, Persons($account_owner__c, $application__cr.reviewer__c))
- Sends a Vault notification to the Person specified in the Account owner field and the Reviewer field on the related Application record
SendNotification($trigger_notification__c, Groups($reviewers__c ))
- Sends a Vault notification to all users in the Reviewer group
SendNotification($trigger_notification__c, Roles($reviewers__c))
- Sends a Vault notification to all users assigned to the Reviewer lifecycle role
SendNotification($trigger_notification__c, Emails("john.smith@biorad.com", "jane.doe@abc.com"))
- Sends a Vault notification to users associated with the specified email addresses: “john.smith\@biorad.com”, “jane.doe\@abc.com”
GetRecords
The GetRecords
(GetRecords(object, criteria_vql)
) function retrieves records from a specified object. This function can be used within a records
parameter.
Parameters
object
: Required, accepts the object’s Name value, such as,$vern_bio__v
.criteria_vql
: Required, allows you to filter records to be used in theGetRecords
function. Outbound relationships only retrieve one (1) record. If the criteria VQL filters out this record, no update occurs. Inbound relationships can retrieve multiple records. If the criteria VQL filters out all related records, no update occurs. Otherwise, a filtered subset of records are updated.{{this.fieldName}}
is supported as a field value from the current record. For example,sub_account__c={{this.name__v}}
returns the current record Name value.{{IN_LAST()}}
and{{IN_NEXT()}}
are supported as in the last number of days from today and in the next number of days from today, respectively.
Example
UpdateRecords(GetRecords($accounts__v, "reviewed=true"),{done__c=true})
- Updates Reviewed records in the Accounts object and sets the Done field to true.
ChangeState(GetRecords($accounts__v, "reviewed=true"),$approved__c)
- Changes the state of Reviewed records to Approved on the Accounts object.
GetRelatedRecords
The GetRelatedRecords
(GetRelatedRecords(relationship_name, (optional) criteria_vql)
) function retrieves records related to the current record. This function can be used within a records
parameter.
Parameters
relationship_name
: Required, accepts the related objects Name value, such as$vern_bio__v
. The$
reference component is required. This parameter accepts three (3) levels of outbound relationships.criteria_vql
: Optional, allows you to filter records to be used in theGetRelatedRecords
function. Outbound relationships only retrieve one (1) record. If the criteria VQL filters out this record, no update occurs. Inbound relationships can retrieve multiple records. If the criteria VQL filters out all related records, no update occurs. Otherwise, a filtered subset of records are updated.{{this.fieldName}}
is supported as a field value from the current record. For example,sub_account__c={{this.name__v}}
returns the current record Name value.{{IN_LAST()}}
and{{IN_NEXT()}}
are supported as in the last number of days from today and in the next number of days from today, respectively.
Example
StartWorkflow(GetRelatedRecords($accounts__cr, "reviewed=true"), $review__c)
- Starts the Review workflow on related Accounts records in the Reviewed state.
ChangeState(GetRelatedRecords($accounts__cr), $active_state__c);
- Changes the state on related Accounts records to Active.
ThisRecord
The ThisRecord
(ThisRecord()
) function returns the current record. This function can be used within a records
parameter.
Parameters
ThisRecord
accepts a value related to the action the Action Trigger is performing. For example, if you are cancelling a workflow, the Name value of the workflow is accepted.
Example
CancelWorkflow(ThisRecord()), $review__c)
- Cancels the Review workflow on the current record.
PriorValue
The PriorValue
(PriorValue($field)
) function returns a field’s previous value.
Parameters
$field
: Accepts a field Name value using the $
component reference format.
Example
PriorValue($name__v)
Returns the previous value of the Name field.
Action Availability
The table below details which actions are allowed in Before Save and After Save events according to the record operation.
Action | Before Save Create | Before Save Update | Before Save Delete | After Save Create | After Save Update | After Save Delete |
---|---|---|---|---|---|---|
Create Record | X | X | X | |||
Update Current Record | X | X | ||||
Update Records | X | X | X | |||
Delete Records | X | X | X | |||
Cancel Workflow | X | X | X | |||
Change State | X | X | ||||
Start Workflow | X | X | X | |||
Cancel Operation | X | X | X | X | X | X |
Print Log | X | X | X | X | X | X |
Send Notification | X | X | X |
Performance Considerations
For optimal performance, each Action Trigger processes a batch of 500 records at a time. Action Triggers that process over 500 records create a separate batch until all records are processed. For example, if an Action Trigger processes 600 records, the first batch contains 500 while the second batch contains 100.
Action Triggers execute once and once only, even if a loop occurs on the same Action Trigger, such as a Change State action used on the current record. In this situation, Vault skips executing each subsequent iteration in the loop. However, it’s important to avoid creating Action Triggers that loop on themselves.
Action Triggers execute synchronously, similar to Vault Java SDK Record Triggers. This functionality means the longer an Action Trigger executes, the longer a user must wait for the UI to respond.
Action Trigger Errors
Action Triggers can run into errors during execution and when you are building the conditional logic. When Action Triggers encounter an error and are terminated, Vault reports them in the Debug and Runtime log. If the Action Trigger is performed on multiple records, the first error encountered is logged with a detailed error message.
Errors can occur due to system actions, such as time and nested depth limits exceeded, or due to an error in the Action Trigger formula, such as missing required fields, invalid validation rules, or entry criteria not met.
If an Action Trigger exceeds the limit of records it can update, Vault cancels it with an error message and rolls back any changes the trigger prompts.
Known Issues
-
Entering multiple lines of text in an Action Trigger formula may prevent the Action Configuration dialog from populating values after the Action Trigger is saved. For example, if a user enters a custom message in a Cancel Operation action on multiple lines in the Action Block, the message may disappear in the Action Trigger editor after the trigger is saved even if it is populated in the Action Block.
-
You cannot compare an id with an object reference field if id is on the left-hand side of an equals operator. For example,
UpdateRecords(GetRecords($my_object__c, "id = "), {$my_text__c: "hello world"});
is invalid.
Limits
The following limits apply to configuring action triggers:
- Up to ten (10) Action Triggers per Before Save and After Save event.
- Up to 50 Action Blocks per Action Trigger
- Action Triggers process up to 500 records at a time
- You cannot use system-managed fields or Formula fields in Action Triggers.
- Action Triggers and Java SDK Record Triggers timeout if all triggers in the transaction are not executed within 100 seconds. If a timeout occurs, all record operations in the transaction are rolled back. You can find information about your trigger execution times in the Debug Log.
- You cannot use Lookup, Formula, or Roll-up fields in Action Triggers.
- You cannot use Action Triggers on objects where the object component definition has
triggers_disallowed(true)
.
Related Permissions
Type | Permission Label | Controls |
---|---|---|
Security Profile | Admin: Action Triggers: Read | Ability to view Triggers tab on an object |
Security Profile | Admin: Action Triggers: Create | Ability to create Action Triggers |
Security Profile | Admin: Action Triggers: Edit | Ability to edit Action Triggers, including reordering, activating configurations, reverting active configurations, and turning Action Triggers on and off. |
Security Profile | Admin: Action Triggers: Delete | Ability to delete Action Triggers. |
Security Profile | Admin:Objects:Read | Ability to configure Action Triggers |