Custom Function

A Custom Function can be used to manipulate the values of agent variables and retrieve or update agent variable data in arbitrary external repositories.

Once defined, a Custom Function can be utilised in multiple Stages (on-entry or on-exit) or Transitions.

Defining a Custom Function

To fully define a Custom Function, you must specify:

• A Function Interface - define each input, output and secret parameter required.

• A Function Implementation - define the Javascript code that uses the parameters and implements the logic of the function.

Terminology

The discussion that follows uses specific terms to specifically differentiate:

• Agent Variables - the variables defined in the agent
• Parameters - the input and output parameters of the function.

At runtime, agent variables are mapped to and from input and output parameters according to the mappings specified where the custom function definition is used in Stages and/or Transitions.

Input Parameters

• For each input parameter, specify a Javascript parameter name that will be used by the function logic to access that parameter.

• In addition, to aid in the identification of each input parameter when the function actually gets used in Stages or Transition, specify a description for each.

Output Parameters

• For each input parameter, specify a Javascript parameter name that will be used by the function logic to populate that parameter.

• In addition, to aid in the identification of each output parameter when the function actually gets used in Stages or Transition, specify a description for each.

Secrets

• For each secret used in the function, specify a Javascript parameter name that will be used by the function logic to access that secret.

• In addition, select the secret that will be mapped to that parameter.

Implementing a Function

Execution Environment

• The function execution environment is a V8 Javascript environment supporting ECMAScript 2022.
• NB: All input parameters are passed by value - any modifcations to the input parameters in the function will not result in the mapped variable being updated. To change the value of a variable, you must return an updated value in an output parameter that will then be mapped at runtime to a variable.

fetch() and GraphQL Support

The environment has embedded support for fetch() and GraphQL for interacting with external endpoints. For more information, refer to the documentation.

Function Definition

The function definition must take the following specific form:

async function main({ inputParams, secrets }) {
    return {
        outputParams: {},
    };
}

Note:

• The function must be async.
• The function must be named main.
• The function must take a single argument object containing an inputParams object and a secrets object.
• The function must return a single object containing an outputParams element.

Example

To illustrate, assume we have defined a function interface for a function that takes:

• a single userChoice input parameter
• a single secret named myAPIKey
• a single availability output parameter

The following function is an outline of an implementation that conforms to the interface:

async function main({inputParams, secrets}) {
 
    const apiKey = secrets.myAPIKey;
    const userChoice = inputParams.userChoice;
 
    // Retrieve data using the API key and the user choice
    var result = ...
 
    return {
        outputParams: {
            availability: result.availability
        }
    };
 
}

Passing data in to the function

All input data is passed to the Javascript Function as a single argument object.

The argument object contains 2 specific items:

The inputParams object

The inputParams object is a Javascript object holding a set of key value pairs specified in the Function Definition as described above. For each, the key is the variable name you specified and the value is the value of the variable that gets bound to that input parameter at runtime.

You can use the input parameter in the function as follows:

async function main({inputParams, secrets}) {
    const userChoice = inputParams.userChoice;
    ...

The secrets object

Similarly, the secrets object is a Javascript object holding a set of key value pairs specified in Function Definition.

You can use the secrets parameter in the function as follows:

async function main({inputParams, secrets}) {
    const apiKey = secrets.myAPIKey;
    ...

Returning data from the function

All output data is returned from the Javascript Function as a single return object with a single outputParams member.

Each element of the outputParams object is mapped and used to update an agent variable.

    // Retrieve the result
    ...
 
    return {
        outputParams: {
            availability: result.availability,
        },
    };
};