Functions

The Functions on Objects widget allows you to use a TypeScript function to compute values which will be inserted when the document is generated from the template.

You can connect the function with input parameters which are passed at generation time. Functions on Objects sections can also be nested in generator sections like the Section generator or Table row generator; this enables you to compute separate values for each object in an object set. We recommend configuring batched functions inside generators.

Batched functions

Batched functions are functions that accept an object set as an argument and return results for each object in the object set. Users can configure batched functions for Functions on Objects sections that are nested inside generator sections.

Here is an example of a Functions on Objects section configured with a batched function:

Using batched functions significantly reduces the time taken to generate a document from a template. This is because of the overhead cost for executing functions: unbatched functions must execute once for each object in an object set, whereas a batched function executes only once for the entire object set.

When configuring a Functions on Objects section with a batched function, object sets taken as input can be an Object set from generator. An Object set from generator refers to the object set that is generated over by the surrounding generator section. Note that batched functions can have more than one input. In the case that a batch function is contained in a nested generator, the object set taken as input can be generated by at most one generator; the nested generator, or the top-level generator, but not both. If a batch function has multiple object set function inputs, all object sets that are configured to an Object set from generator should be from the same surrounding generator section.

Writing batched functions

A batched function takes an object set as an argument and returns a FunctionsMap that maps each object in the object set to the corresponding result. For more details, see the section on accepted function inputs and outputs.

For example, consider an unbatched function that takes in a Flight Alert object and calculates the urgency of the alert based on its delay:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
@Function()
public getAlertUrgency(flightAlert: FlightAlertWorkshopTutorial): string {
    const hoursDelayed = flightAlert.timeOfDelayHours
    if (hoursDelayed! > 4) {
        return "High";
    }
    else if (hoursDelayed! > 2) {
        return "Medium";
    }
    else {
        return "Low";
    }
}

A batched version of this function takes in an object set of FlightAlertWorkshopTutorial objects and returns a FunctionsMap<FlightAlertWorkshopTutorial, string>. The returned FunctionsMap contains a mapping of FlightAlertWorkshopTutorial objects to their urgency.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Function()
public flightAlertCalculateUrgency(flightAlerts: ObjectSet<FlightAlertWorkshopTutorial>):
    FunctionsMap<FlightAlertWorkshopTutorial, string> {
    const map = new FunctionsMap<FlightAlertWorkshopTutorial, string>();
    flightAlerts.all().forEach(flightAlert => {
        const hoursDelayed = flightAlert.timeOfDelayHours
        if (hoursDelayed! > 4) {
            map.set(flightAlert, "High")
        }
        else if (hoursDelayed! > 2) {
            map.set(flightAlert, "Medium")
        }
        else {
            map.set(flightAlert, "Low")
        }
    });
    return map;
}

Batch function generator object set limits

Section generator and table row generator object sets are capped during template generation. During template generation, batch functions are executed using intermediate object sets that are the result of limiting the size of the provided input object sets.

Accepted function inputs and outputs

Required outputs for unbatched functions

Unbatched functions must return one of the following types in order to be used in Notepad templates:

• Boolean
• Date
• Double
• Float
• Integer
• Long
• String

Required inputs and outputs for batched functions

Valid batched functions must have at least one argument of type ObjectSet<K>, and must have a return value of type FunctionsMap<K, V>. The type V must be one of the accepted types listed below:

• Boolean
• Date
• Double
• Float
• Integer
• Long
• String

Widget properties

• Batched/Unbatched: Allows the user to select whether they would like to configure a batched or unbatched function. Only displayed if the function widget is nested inside a generator section.
• Function: The function to run. If the batched option is selected above, only batched functions will be available.
• Function version: The version of the function to run.
• Function inputs: Values to pass into the function. The available parameters are defined by the selected function.
• Function result: The output generated by the function after execution. The results can be parsed in various formats such as plain text or Markdown. Markdown parsing is currently only supported for unbatched functions.

Template configuration

• Function inputs: Depending on the selected function, the different expected input values can be templatized via parameters.

An embedded Functions on Objects section can also be connected to a generator section in this way.