Custom functions in Documotor are pieces of JMESPath code with defined input parameters. They help simplify complex transformations that need to be used repeatedly in transformations within a unit.

Custom functions are defined just like transformations in the Transformation Editor, but can be reused anywhere within the unit they're defined in by invoking the function name preceded by a hashtag, e.g., #exampleFunction(). This page will guide you through configuration of a custom function.

How to create a custom function

From the Navigation Pane, select Custom functions.
Select New function.
Enter the new function name.
Select Create.
Open the created custom function.

From there on, the view is split into two panes, the Function Pane and the Testing Pane. The Function Pane, on the left, contains all functionality for the custom function itself. That is, you can define the number and names of the parameters and the function transformation. The right pane, the Testing Pane, contains three text editors for testing the custom function.

The Function Pane

The Function Pane contains the name of the function, the Parameters Menu and the Function Transformation Editor.

Parameters

To pass the parameters to the custom function, define them in the top of the function pane. To create a parameter, select the + button to the right of the Parameters label. Each parameter needs a name that's used when writing the function’s transformation in the text editor below.

By value vs By expression

A parameter can either be passed as by value or by expression. When a parameter is passed by value, it is evaluated when the function is called and the result is passed to the function. When a parameter is passed by expression it is not immediately evaluated on function call and instead evaluated in the scope where it is read in the function body. If a parameter is passed by value, the ByValue will be highlighted purple. To pass a parameter by expression, toggle the ByValue label, and it will turn grey, turning it off. ByValue on by default.

Function Transformation Editor

Below the parameters is a text editor where the JMES transformation that the custom function applies is configured. This transformation should refer to the parameters defined above the text editor, if there are any. To refer to parameters, put a hashtag # in front of the parameter name.

The Testing Pane

The Testing Pane contains Sample Data, Sample Transformation and Sample Result subpanes, just like in the Data tab of the Recipe Editor.

Sample Data

The Sample Data text editor should contain an example of some sample data to test how to use data variables when calling the custom function.

Sample Transformation

The Sample Transformation text editor is used to test calling the custom function. It is both possible to use hardcoded parameters or parameters from the Sample Data text editor. Below is an example of how to test call the function with both hardcoded parameters and parameters from the Sample Data.

Sample Result

The Sample Result shows the output from the Function Transformation in relation to how the Sample Transformation calls the function with hardcoded data or the Sample Data.

Example function

Here's an example function incorporating all of the above elements:

Function for joining the first and last name of a person to yield a full name.