Skip to content

Javascript operator

Introduction

A Javascript operator block takes any input JSON and can produce any output JSON using JavaScript code.
For this reason, it is typically used to post-process the output of the last block of the workflow to get output that meets the needs of the final workflow user, but it can also be used in intermediate steps to alter the JSON that gets passed from one block to the next.

Block properties can be set by editing the block.
The Javascript block properties window is composed of the following main areas:

  • General properties window
  • Code editor
  • Left panel, collapsed by default

General block properties

The general properties of a Javascript block are:

  • The block name.
  • The unique block ID and the service version, displayed in the title bar (read only, displayed also in the block tooltip in the canvas).

It is possible to edit only the block name.

Change properties window size

To enlarge the properties window to full screen view, select Toggle full screen .
To restore the default size of the window, select Toggle full screen .

Code editor

The Code editor area displays the JavaScript code of the block.

This is the default code:

let input = {};

let output = {};

function process(input){
  //here your code
  return input; 
}

With the default script, the block simply outputs whatever input it receives.

The scripting language conforms to the ECMAScript 5.1 Language Specification.
The export of values and the import of bindings are not supported.

The main function has to be named process. Its only parameter, input, corresponds to the JSON input of the block, while its return value becomes the JSON output of the block.

The input global variable can be used to provide an optional definition of the structure of the input JSON or only of the part of it that is considered relevant.
For example:

let input = { document: { categories: [] } };

indicates that the relevant part of the input JSON should contain a document object with a property named categories which is an array.

This optional definition affects code validation.
Also, when testing the workflow, is the workflow starts with—or contains only—a Javascript block, the definition is provided to the user as a template for the input of the block.

Note

The optional definition of the input structure is not related with the actual input to the block, which can be any JSON: the definition is not meant to validate the runtime input. So, when the workflow is executed, the function's input parameter assumes the value of the input JSON and the input object structure does not have to match that optionally defined in the input global variable.

The output global variable contains an optional definition of the structure of the function's return value. It is used during code validation to assess the structure of the return value and also to provide a formal definition of the block output which can be referred to when performing the input mapping of downstream blocks in the workflow.

Tip

If the structure of the return value is the same of the described portion of the input JSON, a succinct declaration is sufficient, like:

let input = { document: { categories: [] } };

let output = input;

Global variables other than input and output can be defined and used. Global variables are reset at each execution of the workflow.

This sample code transforms the categorization output of a model into a simpler array of labels:

let input = { document: { categories: [] } };

let output = { categories: [] };

function process(input) {
    let ret = [];
    if (input.document && input.document.categories) { 
        for (let cat of input.document.categories)
            ret.push(cat.label);
    }

    return { categories: ret };
}

In the code above, global variable input is defined to describe the relevant part of the input object, namely the categories array of the document object.
The process function iterates through the input categories and for each of them it considers only the label property, which it pushes to the ret array.
Global variable output describes the function's return value as an object containing a categories array: with the return statement the function sets and returns an object with the same structure.

Info

Beside each code line check for possible warnings:

or errors:

Code validation

To validate the code select the play button . During validation, the function is executed by setting the input parameter to the value of the input global variable.

A message is displayed depending on the result: or .

In case of error, you can select Show details to display the error type.

Select Show details to hide it.

Validation may fail if the script code references properties of the input parameter that have not been defined in the input global variable.
For example, validation fails for this script:

let input = { };

let output = { };

function process(input) {
    let ret = [];
    var doc = input.document;
    for (let cat of doc.categories)
        ret.push(cat.label);

    return { categories: ret };
}

because the doc variable is undefined since it refers to a part of the input that has not been described in the input global variable.

Note

When validation fails because code references parts of the input parameter that are not described in the input global variable, the script may still run without errors when the workflow is executed, provided that the actual JSON input to the block has all the elements the script code refers to.

This change to the definition of the input global variable:

let input = { document: { categories: [] } };

fixes this problem.
Another way to avoid this type of validation issues is testing the presence of parts of the input before using them, like in this script:

let input = { };

let output = { };

function process(input) {
    let ret = [];
    var doc = input.document;
    if(doc)
        for (let cat of doc.categories)
            ret.push(cat.label);

    return { categories: ret };
}

or this, which doesn't use variables:

let input = { };

let output = { };

function process(input) {
    let ret = [];
    if (input.document && input.document.categories) { 
        for (let cat of input.document.categories)
            ret.push(cat.label);
    }

    return { categories: ret };
}

Tip

A good programming practice is to combine the definition of the relevant parts of the input JSON in the input global variable with boolean tests of the actual presence of input elements.

In the samples above, validation still gives a warning because the return value has a structure that differs from that of the output global variable. This change to the definition of the output variable fixes the issue:

let output = { categories: [] };

This validation issue can also be ignored because it doesn't affect how the script works at runtime.

Code reset

To reset the script to the default code, select Clear .

Copy the script in the clipboard

To copy the entire code, select Copy to clipboard

Note

To copy a portion of the code, select it, then choose the Copy command in the browser context menu or press Ctrl+C.

Left panel

The panel positioned to the left of the properties window can take on two different names: JS Templates or Inventory • JS Templatesif the Javascript block is linked—directly or indirectly—to previous blocks of the workflow.

By default, this panel is collapsed.

Display or hide the left panel

To display the left panel select Expand or Toggle repository .

Once the panel is expanded, it may consist of the JS Templates or Inventory and JS Templates tabs .

To hide the left panel select Collapse or Toggle repository .

Select a tab to display it.

JS Templates tab

The JS Templates tab displays the actual JavaScript you are working on and the available built-in JavaScript templates.

Search a template

To search a template enter the search criteria in the Search bar (minimum three characters) then Enter.

Display a template in the Code editor

Select a JavaScript template in the list to display it in the Code editor.

The indicator on the left panel shows the selected template.

Note that you can't modify it or validate it because the template is read-only.

Use a template or a portion of it

The templates are read-only, but is possible to use the entire code or just a portion in the Code editor.

To use a template code in order to modify it in the Code editor, select Use this snippet , then the indicator in the left panel changes to JavaScript .

You can also use a portion of code. In this case use the usual Copy and Paste commands.

Inventory tab

The Inventory tab is displayed if the Javascript block is linked—directly or indirectly—to previous blocks of the workflow.

It shows the hierarchical structure of the JSON objects returned by those blocks.

It it useful as a guide to understand which input elements are available, so to use them to produce the block's output.

To expand and collapse items inside the panel, use the arrow buttons to the left of each items.

Save the changes

To save the changes, select Save.

The saving procedure also validate the code.

Note

If the code contains errors, the save procedure is completed but a message is displayed in the Editor tab right upper corner: