Skip to main content

Table Triggers

Admin guide to Table Triggers in Encompass: run Cloud Function code before or after records are added, edited, deleted or merged. Needs Cloud Function access and trigger permissions; v22.01+.

B
Written by Bailey Naas-Thornton

Minimum Version Required: 22.01

Pre-Conditions

  • You must have access to create and edit Cloud Functions in Encompass
    ​
    ​

  • Your user account must have appropriate permissions to add table triggers
    ​
    ​

  • You need to understand the table structure, field names, and data types for the tables you want to trigger against
    ​
    ​

  • For triggers that modify data, appropriate update permissions are required on the target tables

Steps

Understanding Table Edit Triggers

Table Edit Triggers provide a way to execute custom code when specific operations occur on database tables within the Encompass system. The triggers can run before or after records are added, edited, or deleted, allowing you to implement business rules, validation, data synchronization, and automated workflows.

Trigger Types

Encompass supports seven types of triggers:

  • BeforeAdd (ID: 5) - Executes before a new record is added to a table
    ​
    ​

  • AfterAdd (ID: 1) - Executes after a new record has been added to a table
    ​
    ​

  • BeforeEdit (ID: 7) - Executes before changes to an existing record are saved
    ​
    ​

  • AfterEdit (ID: 2) - Executes after changes to an existing record have been saved
    ​
    ​

  • BeforeDelete (ID: 6) - Executes before a record is deleted
    ​
    ​

  • AfterDelete (ID: 3) - Executes after a record has been deleted
    ​
    ​

  • Merge (ID: 4) - Executes when records are merged

Creating a Table Trigger

1. Create a new Cloud Function in Encompass
​
2. Define the trigger logic in your code
​
3. Register your trigger with the system, specifying the table, trigger type, and field dependencies
​
- This is done on the Table Triggers table, attaching it to the table you want to trigger on.
​
4. Test your trigger to ensure it functions correctly

Trigger Execution Flow

1. When a table operation occurs (add, edit, delete), the Encompass system checks for registered triggers
​
2. For matching triggers, the system creates a TriggerParameter object with context information
​
3. Before triggers run immediately and can prevent the operation if validation fails
​
4. After triggers run once the database operation is completed
​
5. Asynchronous triggers run in the background without blocking the user's workflow
​
6. Triggers may be and are commonly batch executed, meaning that more than one record modification is added up, then the triggers are run all at once. This only applies to 'after' type triggers.

Fields And Definitions

Trigger Configuration Fields

  • TableName: The name of the table to watch for changes
    ​
    ​

  • TriggerTypeID: Numeric ID indicating when the trigger should fire (see Trigger Types above)
    ​
    ​

  • FieldList: Comma-separated list of fields that will activate the trigger when changed
    ​
    ​

  • APICommand: The name of the API command or function to execute
    ​
    ​

  • RunAsync: Boolean (0/1) indicating if the trigger should run asynchronously
    ​
    ​

  • Active: Boolean (0/1) indicating if the trigger is currently enabled

BC_TableTrigger.Trigger Structure

  • TableTriggerID: Unique identifier for the trigger
    ​
    ​

  • APICommand: The command to execute when the trigger fires
    ​
    ​

  • TriggerTypeID: The type of trigger (Before/After Add/Edit/Delete/Merge)
    ​
    ​

  • FieldArr: Array of field names that will activate the trigger
    ​
    ​

  • RunAsync: Whether the trigger should run in the background
    ​
    ​

  • Active: Whether the trigger is currently enabled

Best Practices

Performance Considerations

  • Minimize trigger chains: Avoid creating triggers that modify data which would trigger other triggers, as this can lead to performance issues and potential infinite loops.
    ​
    ​

  • Use field dependencies: Specify only the fields that should activate your trigger. This prevents unnecessary executions when unrelated fields are modified.
    ​
    ​

  • Use batch processing: Design triggers to handle multiple records efficiently rather than processing each record individually. Triggers are always executed in batch where they can in the Encompass code base for performance improvements, such as all Table Imports.

Error Handling

  • Validate input data: Always check for null values and validate data before use to prevent runtime errors.
    ​
    ​

  • Return clear error messages: When validation fails, provide specific error messages to help users understand the issue.
    ​
    ​

  • Avoid throwing exceptions in After triggers: Before triggers can validate and prevent operations, but After triggers should handle errors gracefully since the database operation has already completed.

Data Integrity

  • Be cautious with cascading updates: When implementing triggers that modify related records, ensure that your logic handles all edge cases.
    ​
    ​

  • Test thoroughly: Test your triggers with various scenarios, including edge cases and potential error conditions.

Security

  • Check permissions: Unless overriding permissions is necessary, ensure your trigger respects the user's permission level.
    ​
    ​

  • Limit trigger scope: Design triggers to execute only when necessary and with the minimum required permissions.

Maintenance

  • Document your triggers: Maintain documentation about what each trigger does, when it runs, and its dependencies.
    ​
    ​

  • Use meaningful names: Choose descriptive names for your triggers and related functions.
    ​
    ​

  • Keep triggers simple: Complex trigger logic is difficult to maintain. Consider breaking complex operations into smaller, more manageable pieces.
    ​
    ​

  • Test after upgrades: Re-test your triggers after system upgrades to ensure compatibility.

Did this answer your question?