User-Defined Functions

(Available from version 7.0 onwards.)

You can define any number of user-defined functions (UDFs) that can then be used anywhere in the project in the same way as the built-in functions are used. User-defined functions improve development efficiency and ease of maintenance through the reuse of code.

A user-defined function performs tasks and implements logic by combining:

A user-defined function can be called by workflows, event handlers, callout control event handlers, and other user-defined functions.

A user-defined function can optionally return an output value, and can optionally have input parameters. Input and return values can be of simple types, complex types, or of screen element types. Lists of all these types are also supported for both input and return types.

Manage User-Defined Functions

Instructions for managing user-defined functions is the same as for managing all solution components.

Specifically, you can:

Add Actions to a User-Defined Function

  1. Open the user-defined function if it is not already open.

  2. Define the function by dragging built-in functions and methods of complex variables, screen elements, workflows, and callouts into the Builder. Fill in parameter values as needed. In the example below, the user-defined function performs two functions from the File built-in services.

The full process is demonstrated in the video below.

Copy and Paste Actions

You can copy and paste actions within, and between the following assets:

  • Steps
  • Worklfows
  • User-Defined Functions
  • Transitions
  • Triggers
  • Callout control actions
  • If statements

To copy an action, right-click the action > Copy.

To paste an action, right-click the action Builder > Paste.

Set the User-Defined Function's Return Value Type

A user-defined function can return an output value that can be used as an input to another function or method. The type of value returned must be configured.

The return type cannot be changed if:

  • The user-defined function has been used within the solution, for example, if the user-defined function is called from a workflow.
  • A Return function has already been added to the user-defined function's Builder area.

In the example below, the user-defined function Calculate_BMI calculates a person's Body Mass Index (BMI), which is a measure of one's health based on one's mass and height. It returns a decimal value.

To set a user-defined function's return value type:

  1. Open the function's tab.

  2. Click Settings in the top-right corner of the canvas.

  3. Under Options, from the Return Value drop-down, select the type of value that the function returns.

    To select a screen element type, select List > Screen Element, and then select the specific screen element type.

    The Screen Element option will only be displayed if at least one screen element has been captured in the project, or in an imported package. (The Screen Element option will continue to be available even if all captured screen elements are deleted.)

    Also, the Screen Element Type list will only include types relevant to connectors that have been used to capture screen elements in the project.

  4. Click Save.

Set and Use User-Defined Function's Input Parameters

You can specify any number of input parameters that must be set when calling a user-defined function. A user-defined function does not have to have input parameters.

The input parameters are specified in the user-defined function's Settings window.

Those input parameters can then be used to populate the parameters of functions used in the user-defined function.

After setting a user-defined function's input parameters in the Settings window, they can be modified at any time, even if the function or its assets are in use in the project. See here.

The example below defines the input parameters for the user-defined function Calculate_BMI described above. Input parameters must be defined for mass and height.

To set and use a user-defined function's input parameters:

  1. Open the function's tab.

  2. Click Settings in the top-right corner of the canvas.

  3. Specify the input parameters. For each, set the Name and Type.

    The Screen Element option will only be displayed if at least one screen element has been captured in the project, or in an imported package. (The Screen Element option will continue to be available even if all captured screen elements are deleted.)

    Also, the Screen Element Type list will only include types relevant to connectors that have been used to capture screen elements in the project.

  4. Click Save.

    The input parameters are listed under the user-defined function in the Assets Panel.

    The input parameters are available for selection in the Selector window under User-Defined Functions. You can use these parameters to populate parameters of functions and methods in the user-defined function.

    If an input parameter is of a complex or list type, its properties and methods (where available) are also listed in the Selector window. For example, you can Assign a value to a timer variable's Interval property.

Set a User-Defined Function's Return Value

Use the Return function to set the user-defined function's return value.

If a Return Type has been set for the user-defined function, the user-defined function must include a Return function. An error will be displayed if a return value has not been set.

A Return function must be included for all conditions. For example, if the user-defined function includes an If control in which a Return function is present in the Then block, another Return function must be added to the Else block or an error will occur.

Note that when a Return function is performed, execution of the user-defined function ends even if there are other actions below the Return function.

After setting a user-defined function's return type in the Function Settings screen, it can be modified at any time, even if the function or its assets are in use in the project. See here.

The example below defines the input parameters for the user-defined function Calculate_BMI described above. The result of the BMI calculation must be returned to the workflow, event handler, or callout that called the user-defined function.

To set a user-defined function's return value:

  1. Open the user-defined function if it is not already open.

  2. Drag the Return function into the Builder. Because this user-defined function has a return type of decimal, the Return function includes an input parameter of type decimal.

  3. Specify the parameter value. In this example, the value returned is calculated as (mass)/(height)^2.

    To use the user-defined function's input parameters to populate the parameters of actions, select them from the User-Defined Functions section in the Selector window.

The full process is demonstrated in the video below.

Duplicate a User-Defined Function

Duplicating a user-defined function allows you to easily reuse the logic of an existing user-defined function. The duplicate includes all the functionality of the original.

From the Assets Panel, on the user-defined function, click Options > Duplicate.

Call a User-Defined Function

All user-defined functions in your project are listed in the Assets Panel in the User-Defined Functions section. You can drag a user-defined function into the Builder area as if it was a function under Built-In Services. User-defined functions can be called from workflows, event handlers, callout control event handlers, and other user-defined functions.

The workflow step shown below calls the user-defined function UDFunction - 1. This user-defined function does not have input parameters.

If the user-defined function requires that input parameters be specified, input parameter placeholders are displayed automatically when you drag the user-defined function into the Builder.

The example below shows how a workflow calls the user-defined function Calculate_BMI described above. Note that:

  • The user-defined function's input parameters are listed and must be populated. (In the example shown, actual values are entered, but in reality, the parameters would be populated with variables whose values differ per patient.)

  • The Assign function is used to assign the value returned by the user-defined function to a decimal variable called BMI.

Best Practices

Note the following best practices:

  • The recommended naming convention for a user-defined function is lower camelCase, for example, readCustomerData and writeToFile.

  • The recommended naming convention for input and output parameters of a user-defined function is lower camelCase, for example, customerNameand zipCode.