Creating functions

Introduction to functions

A function takes an instruction set designed to perform actions on your data. Think of it like a small application that takes data as input, processes it according to a set of rules, and then produces a desired output. For example, a function might combine the values from two fields, calculate the average value from a set of numbers, or simply check whether certain conditions are true.

Functions can also handle more complex data operations efficiently without requiring a deep understanding of the underlying technical complexities. In summary, even if you are new to data operations, functions allow you to manipulate and analyze data effectively, easing tasks that would otherwise require extensive technical knowledge.

Indexed vs non-indexed functions

When a function is indexed, it means that the field the function operates on is optimized for search queries. However, an indexed function cannot access the machine’s local time or other methods that are incompatible with optimised search. This tutorial includes examples of each type of function.

How this tutorial is organized

This tutorial shows how to create and publish functions 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 and leave out the fields highlighted in red as they are created in the tutorial prerequisite section:

The parts that make up this tutorial are:

1. Function prerequisites

2. Creating a function

3. Creating a non-indexed function

Function prerequisite: add functions to data model

Prior to writing a function in the EBX® Script IDE, you must first create a data model field and specify that it is a function. This field will display the output from your function. Therefore, the data type of this field must correspond to the expected return type of your function (e.g., date, string, integer, etc.).

To add a function type field to your data model:

1. Open your data model in the DMA, and create the following fields:

   • Field 1: The function written for this field will concatenate the first and last name fields and should return a string.

     • Name: full_name

     • Label and description: Full name

     • Kind of element: Field and tic the Function checkbox.

     • Data type: String

   • Field 2: The function written for this field will use a person's last login to determine whether they are considered an active user. Its return/data type will be Boolean.

     • Name: status

     • Label and description: Active user

     • Kind of element: Field and tic the Function checkbox.

     • Data type: Boolean

2. Save and optionally publish your data model. Note that once the field is saved, the script outline is automatically generated and available to work with. 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.

   What's next? Create an indexed or non-indexed function.

Creating a function

By default, when a function is created, it is set to be indexed. So no special consideration is required. However, you can check to see whether your function is indexed by selecting the Information tab and ensuring the Index property is checked.

Script tip: Familiarize yourself with built-in ESL functions and variables. See the API reference documentation for more information.

To create a function that can be indexed:

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, and select the Full name function created in the prerequisite section above. The icon indicates a function.

   As shown below, the function is automatically populated based on the field's data type (string) and returns a string value:

   export function getValue(): string
   begin
   	return 'A string value';
   end

3. In this example function, a value is computed as follows:

   • Retrieve the Person's first and last name using the _ebx.record.first_name and _ebx.record.last_name variables, respectively. In these variables, the _ebx.record is a built-in function that accesses the current record and the .<name> is the name of the field you want to retrieve in the data model. See Creating a non-indexed function for an example of how to use additional built-in functions.

   • Return a single value made of the combined first and last name with a space character separating the two values. All of this logic goes in a single return statement, which is terminated using a semi-colon (pipe characters add elements to the string):

     export function getValue(): string
     begin
     return _ebx.record.first_name | ' ' | _ebx.record.last_name;
     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 Full name field is populated:

   

Creating a non-indexed function

This function example demonstrates how to create a non-indexed function. It also shows how to use an import to add built-in functionality to a script. In ESL, related functions and procedures are organized into Units. To use a unit's functions, declare the unit in a script using the following syntax: uses core.<unit_name> as <alias>;.

Script tip: Write out the pseudocode for more complicated functions before you start coding. The pseudocode for this example reads: Get the number of days between the last login and today; if this number is greater than 30 return false, otherwise (else) return true indicating this is an active user.

To create an non-indexed function:

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, and select the Active function created in the prerequisite section above. Functions are indicated by this icon.

   As shown below, the function is automatically populated based on the field's boolean data type, which returns true or false:

   export function getValue(): boolean
   begin
   	return false;
   end
   

3. Disable indexing. As this script accesses the machine's local time, it cannot be indexed:

   1. Select the Information tab at the top of the script.

   2. Deselect the Compatible with optimized search checkbox.

   3. Return to the Script tab.

4. Write the logic that determines what the function will achieve. In this example, the function determines whether a user is considered active by getting the user's last login date, today's date, and calculating the difference. If the difference is less than 30 days, the user is active:

   • Add the following line to the top of the script as the core.date unit contains the days() function to calculate the number of days between two dates.

     uses core.date as date;
     
     
     

   • Use an if then else statement to check whether a condition is true. The if uses the days() function to get the number of days since a user's last login and the > operator checks whether the number of days is greater than 30.

     uses core.date as date;
     export function getValue(): boolean
     begin
     
     if date.days(_ebx.record.last_login, date.now()) > 30 then
     return false;
     else
     return true;
     
     end
     
     
     

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

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

   The following image shows the result of the script where the Active user field is populated to indicate whether a user is considered active: