Configuring Action Triggers

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.

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.

How to Configure an Action Trigger

To configure an Action Trigger:

1. Navigate to Admin > Configuration > Objects > [Object] > Triggers.
2. Click Create under the Change Current Record - Before Save or Perform Other Actions - After Save section on the Create, Update, or Delete tab.
3. Enter a Label and Name for the Action Trigger.
4. 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.
5. Optional: Enter a Description.
6. 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.
7. Select a THEN action. Use the editor to build a formula around the action.
8. Optional: Select an ELSE action. This action applies if the IF condition returns false.
9. 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.
10. Optional: Click Edit Details () to change the Label, Name, or Description of the Action Block.
11. 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.
12. 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.
13. Optional: Click Delete () to remove the Action Block.
14. Click Save.
15. 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.

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.

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 the GetRecords and GetRelatedRecords 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 the GetRecords, GetRelatedRecords, and ThisRecord 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 the GetRecords, GetRelatedRecords, and ThisRecord 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 the GetRecords, GetRelatedRecords, and ThisRecord 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 as ALL, EXCEPTIONS, and ERROR.
• Message: Required, accepts a string or a formula that returns a string, such as Concat("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 the GetRecords 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 the GetRelatedRecords 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