JavaScript Interpreter

Overview

JavaScript Interpreter is a processor that runs a custom JavaScript script that can process the block input to produce any output JSON.

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

Versions

There are two versions of the component available: the latest and 1.0.0.
Workflows containing blocks of the latest version can only be published in asynchronous mode, while v. 1.0.0 blocks are compatible with both synchronous and asynchronous mode publication.

The blocks of version 1.0.0 are identical to those of the Javascript operator in version 1.9 of NL Flow, however something has changed in the block properties:

• The name of the block, instead of editing the Block name field, can be modified by selecting Edit component name .
• The code validation tool.
• A smarter code editor with auto-completion.

As in NL Flow version 1.9, defining the input and output of a v. 1.0.0 block is still done via code and not as illustrated below.

Input

In general, a JavaScript Interpreter block accepts any JSON object as its input, but normally the code depends on the presence of specific contents.
It is possible to explicitly declare the structure of the input object, either in the code, in version 1.0.0, or defining input variables and mapping them to top-level keys of the output of upstream blocks or to keys of the workflow's input—if this has been described. This has two effects:

1. It is possible to have an input that is a collage of the output keys of different upstream sources and/or keys of the workflow input.

2. The explicit declaration helps:

   • Validate the code, because the validation panel inside the Functional tab of the properties pop-up provides a template of the input object.
   • Testing the workflow when it starts with a JavaScript Interpreter block because the test tool can provide a template of the input JSON to populate.

The input variables are managed in the Input tab of the block properties pop-up.

Block properties

The block properties are accessed by editing the block.
They are divided into these groups:

• Basic properties:

  • Block name
  • Component version (read only)
  • Block ID (read only)

• Functional

  The functional properties of the block coincide with the code of the script which is written with the code editor.

  • To copy the script to the clipboard select Copy code to clipboard .
  • To restore the default code select Clear .

  When writing the code, consider that the process function must be defined and:

  • It must have an argument corresponding to the block input.
  • It's return value will be the output of the block.

• Input

  The input properties are optional input variables mapped to upstream sources.

  • To declare a new input variable:

    1. Click the plus button: a new row is added below the list of existing properties.
    2. In the left field enter the name of the variable.

    3. Using the drop-down on the right, first select the type of the key choosing between number, string, boolean, object and array. After that, the list below will only show source keys of the same type.

       The list is divided in groups, one group for each possible source.
       Select the expand and collapse icons to the right of the source name or select the name of the source multiple times to show or hide the sub-list of output keys for that source.
       If the type of the variable is object, the first entry in the sub-list is the source name.

       

       By choosing it, you indicate that the variable must be set with the entire output JSON of that source.

       Note

       The drop-down list shows all the first-level output keys that can, potentially, be available, but the keys that are actually there when executing the workflow may be less. If you map a key that's not actually produced at runtime, the corresponding input variable will be set to null.

       You can filter the list by typing at the top of it: the list will show only keys with matching names.

       

       To cancel the mapping process, select No mapping from the list or, if you already chose a key, select Clear .

  • To modify an existing mapping:

    • Edit the left field to change the name of the input variable.
    • Use the drop-down as described above to choose a different source.

  • To remove an existing mapping, select Remove to the right of it.

• Output

  The Output tab of the properties pop-up is where you optionally declare the structure of the output object.

  • Basic

    In this tab you can declare the top-level keys of the output object.

    • To declare a new key:

      1. Click the plus button: a new row is added below the list of existing keys.
      2. In the left field enter the name of the key.
      3. Using the drop-down on the right, choose the type of the key.

    • To modify an existing key:

      • Edit the left field to change the name of the key.
      • Use the drop-down on the right to choose a different type.

    • To remove an existing key, select Remove to the right of it.

  • Advanced

    In this sub-tab of the Output tab you can declare the structure of the output object to the desired level of detail by writing a corresponding JSON template. To indicate the type of a property use these conventional values:

    Value	Type
    0	Number
    true or false	Boolean
    ""	String
    {}	Object
    []	Array

    To add a portion of JSON taken from a possible input source:

    1. Choose the source name from the first drop-down menu on the right, the one that shows the names of the blocks .
    2. Choose the top-level key from the second drop-down list, the one with the key icon .

    To reset the JSON select Clear text : the template is set to an empty object.

Output

A JavaScript interpreter block must produce a JSON object. You can optionally declare, at the desired level of detail, the structure of the output object using the Output group of the the block properties.
This declaration allows to use the JavaScript Interpreter block output as a source of input for any downstream block.

Inventory

To have a view of the possible data sources, expand the Inventory • JS Templates panel to the left of the Functional tab of the properties pop-up and select the Inventory tab.

To expand and collapse the panel select the expand and collapse icons.

The Inventory tab shows, grouped by type, all the possible sources, that is the upstream blocks plus, possibly, the input format of the workflow, labeled Input.
For each source, the structure of the output object in displayed as a navigable tree.

Templates

Some code snippets for various use cases are available as code templates.
To browse and use the templates, expand the Inventory • JS Templates panel to the left of the Functional tab of the properties pop-up and select the JS Templates tab.

To expand and collapse the panel:

• Select the expand and collapse icons.

Or:

• Select Toggle repository

The JS Templates tab shows the list of available templates with the indication of the author and a description for each of them.

• To view a template, select it from the list. The template code will be shown in the code editor, without replacing the current block's code.
• To return to the block's code, select JavaScript Interpreter at the top of the list.
• To replace the block's code with the template shown in the code editor, select Use this snippet .

Code validation

To validate the script, select Code validator . The Functional tab of the properties pop-up is selected and expanded.

• To specify the input JSON to test with:

  • Write the JSON inside the Test input pane.

  Or:

  • Select Upload to load an input JSON from file.

• To reset the input JSON select Clear .

• To start the test select Test code .

The Result panel shows the result, which is a JSON object in case of success or an error message. To copy the result JSON to the clipboard, select Copy code to clipboard .

Full screen mode

To extend the pop-up to the entire browser window or to restore its original size, select Toggle full screen .