Defining a function

How functions work

The purpose of a connector function is to take some inputs provided by your integration in Lucy and transform that into a payload that can be sent to your connector agent.

Optionally, the function can receive a reply from the connector agent and decode that reply into a set of outputs.

Defining inputs and outputs

Each function has inputs and outputs and you need to define those.

You also need to define the logic for how the inputs and outputs are encoded and decoded when sent to the connector agent.

Our Query function will take one input - the sql query, and return one output - the result of the query.

You can see that the editing screen has 2 sections - one for defining the inputs and one for defining the outputs.

These inputs and outputs are defined as a JSON structure.

The JSON structure for inputs looks like this:

[
  {"id":"query","label":"Sql Query"}
]

You can see we have defined a single input. The id of the input is query. The label is what we show in the block when you use the model designer. It is a user-friendly name to use to identify that input.

Output parameters are also structured in the same way:

[
 {"id":"result","label":"Result Set"},
 {"id":"count","label":"Total Count"}
]

This function will take a query as input and return the result and the total count as separate outputs.

Lets fill this in:

And then save it.

Defining the transformation logic

Now that you have defined your inputs and outputs, the next step is to specify the logic for transforming those inputs into a string payload to send to the connector and the logic to decode a string payload received from the connector and parsing it into outputs.

This logic must be written in ES6-compliant javascript.

The logic for taking inputs and transforming it into a string payload to send to the connector is called the Pre-Processing Script

The logic for taking the output string the connector returns and parsing it into outputs is called the Post-Processing Script

Usually the string payload that is sent to and received from the agent is just a JSON object encoded a a string

Here's how it might work for a function that takes 2 inputs and returns 3 outputs:

Input Processing Logic

Lets write the Pre-Processing script for our connector.

We will just take the 'query' parameter and encode it into a JSON Object.

The javascript code we write has access to the input parameters through a global variable called inputs.

The inputs variable is a dictionary of key/value pairs with a key for each of the inputs you defined (The id of the input is used). The value is the actual value passed by whomever is calling this function in the agent.

There is a global runtime.setPayload() function that you can use to set the final payload that is sent to the agent. You can write any javascript code you need to perform your transformation before setting the final payload.

In this case, it's simple - we just want to encode the query as a parameter.

By convention - its good to include the function name in the payload as well, if you want your agent to support multiple functions

Here's what our script looks like:

var a = {"query":inputs.query,"function":"sqlquery"};
runtime.setPayload(JSON.stringify(a));

Go to your function definition screen and in the pre-processing tab, add this code.

Output Processing Logic

Similarly we can write a script for our output processing.

The post-processing script has access to a global variable called outputPayload

This contains the response from the agent.

You can then process it in any way you need and then call runtime.setOutput(dictionary)

The setOutput function takes a dictionary and assigns each key/value pair to the corresponding output parameter.

So if you defined 2 outputs with ids as result and count your dictionary should have 2 keys corresponding to the ids of the outputs.

Lets use the following - simplified and expanded for clarity:

var obj = JSON.parse(outputPayload);
var result = obj.result;
var count = obj.count;
runtime.setOutput({result,count});

It should look like this:

Hit the 'Save' button to save it.