Configuration

Tasks

A task is a collection of different actions, each with its own trigger, which can execute one or several scripts. While the scripts in each task are independent, they can share data within the same task by using $.taskLocal and between tasks by using $.global:

Task options

Each task can be individually enabled or disabled by configuring the “Enabled” option. If the task is disabled, none of the actions in the task will be triggered and the scripts will not be executed. Each task can have an unlimited number of actions.

Actions

An action is an object that can have several scripts, as well as a trigger, which will start the execution of these scripts. There are 6 different types of actions, each with their own configuration settings:

• Start-up: Executes scripts when the module starts.
• Shutdown: Executes scripts when the module shuts down.
• Periodic: Executes scripts after a configurable period.
• Change: Executes scripts when the specified tag changes.
• Condition: Executes scripts when the specified tag fulfills a condition.
• External: Never executes by itself. Will execute when called by external modules.

Start-up, shutdown, and external do not require any specialized configuration, whilst the others will require different configuration settings to be applied.

Periodic

Periodic actions offer the following configuration options:

Periodic options

• Period: Specifies the time period for this action, displayed in ms. The default value is 10 seconds.
• Period type: Selects how the period will be calculated. Valid values are:
  • Fixed delay: The scripts trigger after the specified period in ms has elapsed since the scripts have completely finished executing. For example, if the scripts take 250 ms to complete execution, the period is set to 10,000 ms, and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:250, and the third at 00:00:30.500 and so forth.
  • Fixed rate: The scripts trigger after the specified period in ms has elapsed since the last trigger, independently of when the script finished its execution. For example, if the scripts take 250 ms to complete execution, the period is set to 10,000 ms, and the current time is 00:00:02.463, the first execution will be at 00:00:12.463, the second execution at 00:00:22:463, and the third at 00:00:32.463 and so forth. If the scripts don't finish before the next period triggers, the script will start as soon as the previous execution finishes.
  • Fixed interval: The action starts at fixed intervals depending on the period, independently of when the script finished execution. If the specified period elapses before the script finishes, all missed intervals will be skipped. For example, if the period is 10,000 ms, the script will always execute at 00:10:00.000, 00:20:00.000, etc., independently of when the script ends. If execution of the script takes longer than the specified period, enough intervals are skipped to allow the script to execute at the next interval.
  • Cron: The action starts periodically based on a cron expression. If the script doesn't finish before the next scheduled time, this execution will be skipped.

Change

Tag change actions offer the following configuration options:

Tag change options

• Trigger type: Selects between the different trigger types for the tag change action. 
  Note:

  This feature is available from N3uron version 1.21.5.
  The available types are as follows:
  • Single tag: This trigger type will execute the script whenever the specified tag generates a tag event.

    Single tag trigger

    
    

  • Tag group: This trigger type will execute the script whenever any of the tags within the group generate a tag event.

    Tag group trigger

    Multiple tags (Filter): This trigger will execute the script whenever any of the tags that meet the filter conditions generate a tag event.Multiple tags trigger

• Trigger options:
  • Property: Selects which of the tag’s properties should be monitored for changes. The valid values are Any, Value, Quality, or Timestamp.
  • Initial change: If enabled, the initial event after a tag subscription can trigger the scripts. Otherwise, the initial event is discarded.
  • Maximum event buffer size: Specifies the maximum number of events that will be buffered in case the events are received faster than the script can execute. After the buffer fills up, the oldest events will be discarded. Otherwise, the script will be triggered once for each event in the buffer. The minimum value is 1, which means that the script will always execute using the last event received.

Condition

Condition actions offer the following configuration options:

Condition options

• Tag: Selects which tag will be monitored by this action. Each condition action can only monitor one tag.
• Property: Selects which tag property will be used to check the condition. The valid values are Value, Quality, and Timestamp.
• Initial change: If enabled, the initial event after a tag subscription can trigger the condition check. Otherwise, the initial event is discarded.
• Condition: Selects the condition that must be met for the scripts to trigger. The valid values are:
  • Null: Triggers if the tag property is null.
  • Not null: Triggers if the tag property is not null.
  • Equal to: Triggers if the tag property is equal to the specified value.
  • Not equal to: Triggers if the tag property is not equal to the specified value.
  • Greater than: Triggers if the tag property is greater than (but not equal to) the specified value.
  • Greater than or equal: Triggers if the tag property is greater than or equal to the specified value.
  • Less than: Triggers if the tag property is less than (but not equal to) the specified value.
  • Less than or equal: Triggers if the tag property is less than or equal to the specified value.
• Value: Specifies the value that will be used along with the condition to see if the script needs to trigger.
  
• Condition type: Selects how the condition applies. The valid values are: 
  • If true: The scripts will trigger when the condition becomes true. 
  • If false: The scripts will trigger when the condition becomes false.
  • While true: The scripts will trigger once when the condition becomes true and then trigger again periodically while the condition remains true.
  • While false: The scripts will trigger once when the condition becomes false and then trigger again periodically while the condition remains false.

If the condition type is either If true or If false, the following two additional configuration options are shown: 

• Trigger on update: If enabled, scripts will trigger every time a new tag event is received while the condition remains true. Otherwise, the scripts will not trigger again until after the condition is cleared.
• Maximum event buffer size: Specifies the maximum number of events that will be buffered in case the events are received faster than the script can execute. When the buffer becomes full, the oldest events will be discarded. Otherwise, the script will be triggered once for each event in the buffer. The minimum value is 1, which means that the script will always execute using the last event received.

If the condition type is While true or While false, the following two additional configuration options are shown: 

• Period: Specifies the period between script executions, displayed in ms. The default value is 10 seconds.
• Period type: Selects how the period will be calculated. The valid values are:
  • Fixed delay: The scripts trigger after the specified period in ms has passed since the scripts have completely finished executing. For example, if the scripts take 250 ms to complete execution, the period is set to 10,000 ms, and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:250, and the third at 00:00:30.500 and so on.
  • Fixed rate: The scripts trigger after the specified period in ms has passed since the last trigger, independently of the time when the script finished its execution. For example, if the scripts take 250 ms to complete execution, the period is set to 10,000 ms and the current time is 00:00:02.463, the first execution will be at 00:00:12.463, the second execution at 00:00:22:463, and the third at 00:00:32.463 and so on. If the scripts don't finish before the next period triggers, the script will start as soon as the previous execution finishes.
  • Fixed interval: The action starts at fixed intervals depending on the period, independently of when the script finished its execution. If this period elapses before the script finishes, all missed intervals will be skipped. For example, if the period is 10,000 ms, the script will always execute at 00:10:00.000, 00:20:00.000, etc., independently of when the script ends. If execution of the script takes longer than the specified period, enough intervals are skipped to allow the script to execute at the next interval.
  • Cron: The action starts periodically based on a cron expression. If the script doesn't finish before the next scheduled time, that execution will be skipped.

External

External actions are different from normal actions, they never invoke the script, instead they wait to be called from another N3uron module, such as via OpcUaServer methods. These methods receive the arguments passed from the module that calls them and return a value back to the module that called them.

When calling an external action, it takes a single object argument containing key-value pairs, where each key is the argument name and the value is the argument value:

//Object argument when calling external script
{
  arg1: "String",
  arg2: 123,
  boolArg: true
}

//Resulting $.event object in the script
$.event = {
  arg1: "String",
  arg2: 123.
  boolArg: true
}

The return value can be any anything and depends on what the calling module is expecting. For example, OpcUaServer expects the return value to be an object where each key is the output argument name and each value is the value of that output argument. More detail about the specific return values can be found in the documentation for all modules that allow calling external scripts.

Scripts

A script is user defined JavaScript code that will execute every time an action triggers. Each action can have one or more scripts. 

Each script has access to several objects and functions that are used to interface with N3uron and to share data between different scripts in the same task or between different tasks. All of these objects are detailed in the API section of this manual.

Scripts also have access to all Node.js native libraries (such as fs or net), as well as user defined libraries.

Each script has the following options:

Script options

• Enabled: Enables and disables execution of this script.
• Script: Contains the script that will be executed. By clicking the code button, a code editor will be displayed where the user code can be entered.
• Runtime configuration:
  • Inactivity timeout: Sets the inactivity timeout of the Javascript worker. The worker shuts down after this timeout has passed.
• Parameters: These parameters are passed to the script in the $.parameters object. They are usually used to define a configuration that is then used for the script. For example, a parameter can be used to set a basepath that will be used in the script, or the host + port combination used to open a socket in the script. These parameters are read-only. If they are written, they will throw up an exception. Parameters can be one of the following types:
  • String: Represents a JavaScript string.

    
    

  • Number: Represent a JavaScript number, which is defined as a 64 bits floating point number (except that only finite values are allowed, meaning that neither NaN nor ± Infinite are permitted).

    
    

  • Boolean: Represents a Javascript boolean data type, which can be either true or false.

    
    

  • Array: Represents a JavaScript array, which is an ordered collection of elements. By clicking on New ArrayElement, users can add elements to the array, each with a specific type (including nesting arrays and objects).

    
    

    

    
    

  • Object: Represents a JavaScript object, which is a key-value collection. Each object can have multiple properties that can be the same types as the parameters, including array and objects, meaning that it can be used to build nested data structures.

    
    

  • TagPath: Users can select a tag previously created in the Tags section by clicking on the blue button on the right-hand side of the Value field.

    
    

    

Libraries

This section allows users to declare shared libraries that can then be used by all the tasks in this Scripting instance. There are three types of libraries, as seen in the following screenshot:  

Internal library configuration

• Internal libraries: These libraries are bundled with N3uron and as such, can be loaded directly without installing anything more. The internal libraries available to Scripting are:
  • Cron: This library is used tovalidate a given cron expression, as well as retrieving the next time the expression has to be executed. More information can be found at cron.
  • JsPDF: This library is used to generate PDF documents using JavaScript. The included version is X. More information can be found at JsPDF.
  • JSZip: This library is used to read and write .zip files. The included version is 3.1.4. More information can be found at JSZip.  
  • LZ4: This library is used to compress data using the LZ4 algorithm. The included version is 0.5.3. More information can be found at LZ4.
  • Moment.js: This library is used to parse and format dates & times. This library version includes both moment (version 2.23.0) and moment-timezone (version 0.5.23). More information can be found at Moment and Moment Timezone.
  • MongoDB: This library is used to connect and execute queries to a MongoDB database. The included version is 2.2.36. More information can be found at MongodB.
  • MQTT.js: This library is used to communicate with a MQTT broker using the MQTT protocol. The included version is 2.2.1. More information can be found at MQTT.js.
  • MySQL: This library is used to connect to a MySQL database and execute queries. The included version is 2.17.1. More information can be found at MySQL.
  • PostgreSQL: This library is used to connect to a PostgreSQL database and execute queries. The included version is 6.4.2. More information can be found at PostgreSQL.
  • Protobuf.js: This library is used to serialize and parse messages using Google’s Protocol Buffers format. The included version is 6.8.0. More information can be found at Protobuf.js.
  • SQL Server: This library is used to connect to a SQL Server database and execute queries. The included version is 3.3.0. More information can be found at SQL Server.
  • WebSockets: This library is used to create a WebSocket client and server. The included version is 1.1.0. More information can be found at WebSockets.
  • XLSX Writer: This library is used to write data to XLSX files. 
  • Xml2Js: This library is used to serialize and parse XML. The included version is 0.4.16. More information can be found at Xml2Js.
• External libraries: These libraries are external to N3uron and must be installed by the user. They can be installed manually, but the recommended method is through the Node Package Manager (npm). More information about install libraries can be found here. When using external libraries, this is either the path of the library entry point (index.js and main.js being the typical entry points) or the path to the folder containing the package.json file (typically, node_modules/LIBRARY_NAME). 
  Note:

  External libraries must be compatible with Node 12.22.10. Additionally, native modules may or may not work, depending on whether they are declared as "Context-aware".
• Static libraries: These libraries contain user defined code directly in N3uron. A use case for these libraries is creating one or multiple classes that are shared across different scripts. These libraries have full access to the same API as the rest of Scripting and they are also saved to N3uron backups (unlike external libraries, which are not saved). In order to export data from a static library, the module.exports syntax is used.

Source

Scripting can also act as a data provider for tags. To do this, all new tags will need to be configured with Scripting as their source, as seen in the following screenshot:

Scripting source tag configuration

Scripting source tags accept a single optional parameter in the form of an alias that will be used to reference the tag when providing data for that tag. If provided, the tag can be updated using said alias. Otherwise, the full path will need to be used. The full path can be used regardless of whether a tag has an alias or not. In order to update a tag, the $.api.tag.update or $.api.tag.updateAlias functions must be called.