Custom User-Defined Functions

While uPlan has many common built-in functions , it is also possible to create custom functions using either QLingo or JavaScript to further extend uPlan’s capabilities.

Note that it is not possible to create custom user-defined functions in uCreate Print. However, you can link uCreate Print to a plan file that contains custom functions.

Create Custom Functions with QLingo

This example will create a function called "fullname" that will take firstname and lastname parameters and concatenate (join) them with a space.

1. Create a new QLingo function and select the type of data that the function will return to uPlan.

   

2. Name the new function.

3. Right-click on the new function and add parameters for the values that you need to push into the function.

   

4. Select the appropriate data type for the incoming data and name the new parameters.

5. Repeat for any additional parameters needed by your function. In this example, create parameters for firstname (string) and lastname (string).

6. Double click the function name, or right-click and select Edit expression.

   

7. Write your QLingo expression using normal QLingo syntax. In this example, use the Trim() function to remove any white space from the firstname and lastname parameters, and use the & (ampersand) to concatenate the firstname, space and lastname.

Create Custom Functions with JavaScript

XMPie extends the standard JavaScript with additional capabilities. To read more, see XMPie's JavaScript Advanced Capabilities.

This example will create a function called "getFromList" that will receive three parameters: a list, a delimiter and an index number. And will return the value that is in the index position of the list.

1. Create a new JavaScript function and select the type of data that the function will return to uPlan.

   

2. Name the new function.

3. Right-click on the new function and add parameters for the values that you need to push into the function.

   

4. Select the appropriate data type for the incoming data and name the new parameters.

5. Repeat for any additional parameters needed by your function. In this example, create parameters for: list (string), delimiter (string) and index (number).

6. Double click the function name, or right-click and select Edit Expression.

   

7. Write your JavaScript expression using normal JavaScript syntax. In this example, use the JavaScript Split() function to convert the list to an array. You can then simply return the value from the correct index of the array. (Remember that JavaScript is zero-based, so the first element of the array will be index 0.)

   The JavaScript expression editor consists of two editable areas:

   

   The upper area is for your main function that you can see is defined automatically. The lower area allows you to define any additional functions that will be called from your main function.

Use the new Custom Function in an ADOR or Variable

Now that you have created a custom function, you can use it like any other uPlan function, by dragging and dropping the function (or typing the function name) into one or more ADORs or variables and setting the required parameter values.

1. Open your ADOR or variable’s Expression. In this case, I have created a new ADOR called "firstPreference". From the Functions list, drag the "getFromList" function into the editor.

   

2. Replace the parameter names with the values you want to pass to the function. In this case:

   • The list is coming from the Recipient Information schema "preferences" field,

   • The delimiter is "," (since the preferences list is comma delimited), and

   • The index is 0 (zero) to get the first item from the list.

   

3. Generate a proofset to confirm your function is working as expected.

   

Watch a video

Learn how to create Custom Functions in uPlan