Creating triggers

Introduction to triggers

In the EBX® Script Language (ESL), a trigger is a scripted procedure that automatically executes in response to specific events, such as changes to a record (creation, update, or deletion). You can use triggers to enforce business rules, validate data, or perform automated tasks aligned with these events. By ensuring that conditions are met, or actions are taken whenever an event occurs, it enhances data integrity and consistency.

How this tutorial is organized

This tutorial shows how to create and publish triggers in the EBX® Script IDE. It does not cover complex use cases, or all of the user interface options. To follow along, you can create the basic data model shown below (this model is a continuation of the model used in the function tutorial):

The parts that make up this tutorial are:

• Completing prerequisites

• Creating a triggered procedure

Trigger prerequisite: add trigger to data model table

Prior to writing the logic for a trigger in the EBX® Script IDE, you must first add a trigger to a data model element. This tutorial demonstrates adding a trigger to a table. Once you create the trigger in the data model, it is automatically available in the EBX® Script IDE.

To add a trigger to a data model table:

1. Open the docPerson data model and select the person table.

2. Select the Advanced properties tab and click the + icon next to Triggers.

3. Configure the trigger:

   • For the trigger's Component, select [Built-in] EBX Script .

   • For the trigger's Parameters:

     • Script name: Enter a name for the trigger. This name is used by the IDE to identify this trigger. For this example, enter: lastModificationDate.

     • The type of trigger: Use the menu to select the desired trigger type. For this tutorial, use: Trigger after modification.

4. Save and then optionally publish your data model. Note that once the table is saved after adding the trigger, the trigger's script outline is automatically created and available to work with in the IDE. However, you cannot publish the script until the data model publication is up to date. So it might be a good idea to publish the data model at this time.

   Whats next? create and publish a script for a triggered procedure.

Creating a triggered procedure

As procedures in ESL don't return a value, they are more suitable for triggers, which usually execute a set of instructions based on an event. The event used in this example that initiates the execution of the scripted procedure is modification of a record. The goal is to populate the Person table's Last modified field with the current date anytime a record is modified.

Script tip: use variables to hold values that can change over time, or are computed based on inputs or even other variables. This example uses variables to hold values that specify a data model, table, and PK. These values are required to update a record. Create variables using the following syntax: var <variable_name> := <assignment> where var declares the variable with a <variable_name>, the := assigns a value, and the value can be a direct value, expression, or result of a method call.

1. If the EBX® Script IDE perspective is not open, click the icon at the top right of the EBX® toolbar and select Script IDE.

2. In the Navigation pane on the left of the screen locate @trigger folder, and select the trigger created in the prerequisite steps.

   As shown below, the trigger is based on the type of trigger selected in the prerequisite steps and set to execute after modification:

   export procedure onAfterModify()
   begin 
   end

3. Write the instructions for the procedure:

   1. Import functionality from the following units: core.data, core.date, and core.complex. Additionally, add a reference to the data model containing the Person table, docPerson in this case:

      uses core.data as data;
      uses core.complex as complex;
      uses core.date as date;
      references model docPerson;

   2. Write the instructions for the procedure between the begin and end statements using variables to store the table, the table's primary key, and the record.

      • The table variable uses the findTable() function from the core.data unit to lookup a table. It requires the following input: <dataModel.tableName>(_ebx.dataset). This example uses the docPerson model and the person table. The predefined variable _ebx.dataset provides required information on the dataset where the event is triggered.

        var table := data.findTable<docPerson.person>(_ebx.dataset);

      • The core.complex unit facilitates operations with complex data types, such as a primary key. As shown below, use the built-in primaryKeyOf function (from core.complex) for the table's primary key field. As a parameter, pass in the: dataModel.tableName in this case: docPerson.person. This creates a PK with no assigned values. The next line of code assigns the PK's id field to the value of a selected record:

        var pk := complex.primaryKeyOf<primarykeyof docPerson.person>(); 
        pk.id := _ebx.record.id;

      • The lookupRecordForUpdate function from the core.data unit gets a modified record. Pass the current EBX® transaction as a parameter using the built-in variable: _ebx.transaction. Then, pass the table and pk variables that were defined above.

        var record := data.lookupRecordForUpdate(_ebx.transaction, table, pk);

   3. Add the modification date to the record and save it:

      • Specify which field to update using: record.fieldName. The field name in the example model is last_modification_date:

        record.last_modification_date := date.now();

      • Save the updated record. Use the built-in saveRecord() function and pass the modified record as the single parameter:

        data.saveRecord(record);

      • The complete procedure is:

        uses core.data as data;
        uses core.complex as complex;
        uses core.date as date;
        references model docPerson;
        
        export procedure onAfterModify()
        begin
            var table := data.findTable<docPerson.person>(_ebx.dataset);
            var pk := complex.primaryKeyOf<primarykeyof docPerson.person>(); 
            pk.id := _ebx.record.id;   
            var record := data.lookupRecordForUpdate(_ebx.transaction, table, pk);
            
            record.last_modification_date := date.now();
            data.saveRecord(record);
           
        end

4. Save the script. The IDE automatically checks for any compilation errors and will display them in the Messages section below the script.

5. If no errors are found, select Publish all to publish the script.

   The following image shows the result of the script where the Last modified field is updated each time a record is changed: