Configuration

Enable data collection

Enables data collection for this channel. If set to false, no requests on this channel will be executed. The default value is true.

Connection

This section contains options related to the HTTP/HTTPS connection to the target REST server.

• Protocol: Select between the HTTP protocol and the secure HTTPS protocol. When HTTPS is selected, additional security options become available.

• Host: Hostname or IP address of the target REST server without http:// or https:// prefixes. Example: api.example.com or 192.168.1.100.

• Port: TCP port where the target REST server will be listening. By default, HTTP uses port 80, and HTTPS uses port 443. Valid range is 1 to 65536.

• Options: This section contains additional options that are used when the protocol is HTTPS.

  • CA: Allows using a custom certificate as a trusted Certificate Authority to validate the certificates returned by the server. This can be useful when the server is using certificates signed with a non-trusted CA or when using self-signed certificates.

  • Reject untrusted certificates: When set to true, connections to the target HTTPS server will be silently dropped if the server supplies a certificate that is not signed by a trusted certificate authority. This can occur when using self-signed certificates. In such cases, this option must be set to false. The default value is true.

Timing

This section contains options related to timeouts and retries that affect all the requests in the channel.

• Request Timeout: Specifies the maximum time that can pass after a request is sent to the server before it times out and is retried (in milliseconds). The default value is 10000 milliseconds.

• Retries: Selects how many times a request will be retried before being aborted. The default value is 3 retries, which means that the request will be sent 4 times to the server (initial request plus 3 retries).

• Transmission delay: Specifies the delay between one request and the next one on this channel (in milliseconds). The minimum value is 0, which means that the next request will be sent out as soon as possible after the current one finishes.

Enable data collection

Enables or disables this request. If disabled, the request will never be sent to the server, and any tags with this request as their source will remain with a BAD-UNINITIALIZED quality. The default value is true.

Method

Selects between the different HTTP REST methods. When a method that does not support a request body (such as GET) is selected, the body configuration field is hidden. Conversely, selecting methods like POST or PUT will display the body field. The supported methods are:

• GET: Executes a REST GET request.

• DELETE: Executes a REST DELETE request.

• POST: Executes a REST POST request.

• PUT: Executes a REST PUT request.

• PATCH: Executes a REST PATCH request.

Triggers

Each request can have one or more triggers that dictate when it will be executed. Each trigger is checked continuously, and whenever one becomes active, the request will be executed. Available triggers are:

1. Periodic: This type of trigger becomes active after a specified period has passed. Configuration options:

   • Type: Selects how the period is calculated. The options are:

     • Fixed time: The period starts counting when the module starts, and it will be increased by the specified amount whenever the trigger is active. For example, if the period is 30000 ms and the module starts at 12:32:12, the transaction will execute on start, and every 30 seconds afterwards, for example, at 12:32:42.

     • Fixed interval: The trigger becomes active at fixed points in time, depending on the given period. For example, if the period is 5 minutes, the trigger will activate at xx:00, xx:05, xx:10, etc., regardless of when the module started.

     • Cron: The actions start periodically based on a cron expression. If the script doesn't finish before the next scheduled time, that execution will be skipped. This field will require you to provide or select a cron expression to define the desired schedule.

   • Scan rate: Specifies the period between each time the trigger is activated, displayed in milliseconds. The default and minimum value is 1000 milliseconds.

   • Reschedule timer: If enabled, the transaction activation time will be rescheduled whenever another trigger is activated.
     Example: If a transaction with several triggers (including a 60-second periodic trigger, which executed at 11:30:10) is executed at 11:30:25:

     • Reschedule enabled: The periodic trigger will be executed at 11:31:25, rescheduling the timer to execute 60 seconds after the current execution.

     • Reschedule disabled: The periodic trigger will be executed at 11:31:10, which is 60 seconds after the previous periodic execution.

   • Run on start: Determines whether the trigger should execute immediately when the module starts. Default is Yes

2. TagCondition: This type of trigger activates whenever a tag-based condition is met. Configuration options:

   • Tag: Path to the tag used in this tag condition trigger. The tag path must exist in the N3uron tag namespace.

   • Property: The property of the tag used to trigger the transaction. Options include Value, Quality, and Timestamp.

   • Initial change: Specifies if the script should trigger on the initial subscription or not.

   • Condition: Specifies the comparison applied to evaluate the condition. If the tag is a string, it is compared alphabetically (for example, aa > ba returns true, while aa > ab returns false).

   • Value: Specifies the value used in the condition. It can be a Number, a String, or a Boolean.

   • Condition type: Determines how the condition will be evaluated:

     • If true: The action triggers when the condition becomes true. It can only trigger once (or once per tag update), depending on the value of Trigger on update.

     • If false: The action triggers when the condition becomes false. Just like the case above, it can trigger only once or once per tag update.

     • While true: The action triggers once when the condition becomes true, and then repeats periodically, according to the period specified.

     • While false: Same as above, except it triggers while the condition is false.

   • Trigger on update: If true, the action will trigger whenever there's a new tag update that still satisfies the condition. Otherwise, it will only trigger the first time the condition becomes true. This option is only used when the condition type is set to If true or If false.

   • Reset trigger: If enabled, the trigger will be reset to the given value after each completed transaction.

   • Reset value: Selects the reset value of the trigger when it resets after a transaction.

3. TagChange: This type of trigger activates when there is any change to the specified tag. Configuration options:

   • Tag: Path to the tag to monitor for changes.

   • Property: The property of the tag to monitor (Value, Quality, or Timestamp).

   • Initial change: Specifies if the script should trigger on the initial subscription or not.

Parameters

Tag values that can be referenced throughout the request configuration. They allow dynamic request construction based on the last value of the specified tags. Parameters can be accessed in scripts using $.parameter['paramName'] or $.parameter.paramName, where paramName is the instance name of the parameter. Each parameter object contains the properties tag, value, quality, and ts (timestamp).

• Parameter type: Selects between the different parameter types. The different types are:

  • Single tag: This parameter will contain a single tag specified with a tag path.

    • Tag: Selects the tag used for this parameter. The last value of this tag can then be accessed in scripts either by using $.parameter['paramName'] or $.parameter.paramName, where paramName is the instance name of this parameter. The tag must exist in the N3uron tag namespace.

  • Tag group: This parameter will contain a group of tags that are included in the specified path.

    • Group: The group that is monitored for changes. Specify the complete path to the tag group to include all tags within that group.

  • Multiple tags (Filter): This parameter will contain any of the tags that match the given filters.

    • Tag filters: Define filter criteria to select multiple tags. Each filter (TagFilterPath) includes:

      • Mode: Determines whether to include or exclude tags matching the filter criteria.

      • Path: Starting path for the filter. Use / for root or specify a specific path like /PLANT01/.

      • Regex pattern: Regular expression pattern to match tag paths. Use .* to match all tags under the specified path.

Path

Specifies the path of this request. For example, if the complete URL of the request is https://www.example.com:443/Data.json, the protocol selected should be HTTPS, the host and port should be set to www.example.com and 443, respectively, and the path must be /Data.json.

• Type: Selects how the request path is generated:

  • Plain text: The path is set to a static text value.

    • Text: Static path string. Example: /storage or /api/v1/data.

  • Custom script: The path is generated by running a user-defined script before each request.

    • Script: Script that will be used to generate the path of the request. The script has access to the following functions and objects:

      • Buffer: Class used to manipulate a byte buffer directly. More information can be found at NodeJS API Reference.

      • querystring: Object used to simplify the creation of query strings. More information can be found at NodeJS API Reference.

      • moment: Class used to parse, format, and manipulate dates. This has access to both normal moment and moment-timezone. More information can be found at moment and moment-timezone.

      • sprintf: Function used to simplify formatting a string using placeholders and a list of arguments, using the same format as the C sprintf function. More information can be found at C++ reference - sprintf.

      • $.logger: Object containing logging functions that can be used to log custom messages during script execution. Valid log levels are error, warn, info, debug, and trace. Each of these functions can be used as $.logger.info(message, args...). The logger accepts a format string in the sprintf format.

      • $.local: This object can be used to keep user-defined data between multiple executions of the same request. By default, it's an empty object. For example, a property named scanCount can be defined by using if(!$.local.scanCount) $.local.scanCount = 0. These properties can be accessed from any scripts executed by a request

      • $.parameter: Object containing all declared parameters for this request. Each parameter can be accessed by using its instance name. For example, if a parameter is named startTime, it can be accessed using $.parameter.startTime. Each parameter has a value, quality, and timestamp (in UNIX epoch format, with milliseconds). Using the previous example, in order to access the value $.parameter.startTime.value is used; the quality requires using $.parameter.startTime.quality, and the timestamp uses $.parameter.startTime.ts.

      • $.output: This property must be set by the script to the desired path. It has to be a string, otherwise an error will be raised, and the request won't be executed. For example, to create a path that depends on a parameter named startTime, the following script can be used: $.output = "/Data.json?startTime="+$.parameter.startTime.

Headers

HTTP headers provide additional metadata about the request. The REST API Client manages fixed headers automatically and allows custom headers for API-specific requirements.

• Fixed Headers: Headers automatically managed by the module. Configuration options:

  • Accept-Encoding: Sets the Accept-Encoding header of the request. The valid values are:

    • GZip: Sets the Accept-Encoding header to GZip, which indicates to the server that the client can accept GZip-compressed payloads. This is the recommended value.

    • Deflate: Sets the Accept-Encoding header to Deflate, which indicates to the server that the client can accept Deflate-compressed payloads.

    • None: Sets the Accept-Encoding header to *, which indicates to the server that the client can only accept uncompressed payloads.

  • Authorization: Selects the type of authentication used with this request. The supported types are:

    • None: No Authorization header will be set for the request.

    • Basic: Uses basic HTTP authentication to authenticate with the server.

      • Username: Username used for authentication with the server.

      • Password: Password used for authentication with the server.

    • Bearer: Uses a bearer token to authenticate with the server.

      • Token: Token used for bearer authentication with the server.

• Custom headers: User-defined headers for API-specific requirements or to override fixed headers.

  • Type: Selects how the header value is generated:

    • Raw text: Sets the header to a static text value.

      • Value: Static string value for this header.

    • Custom script: Generates the header value dynamically using JavaScript.

      • Script: Script that will be used to generate the value of this header. The script has access to the following functions and objects:

        • Buffer: Class used to manipulate a byte buffer directly. More information can be found at NodeJS API Reference.

        • moment: Class used to parse, format, and manipulate dates. This has access to both normal moment and moment-timezone. More information can be found at moment and moment-timezone.

        • sprintf: Function used to simplify formatting a string using placeholders and a list of arguments, using the same format as the C sprintf function. More information can be found at C++ reference - sprintf.

        • $.logger: Object containing logging functions that can be used to log custom messages during script execution. Valid log levels are error, warn, info, debug, and trace. Each of these functions can be used as $.logger.info(message, args...). The logger accepts a format string in the sprintf format.

        • $.local: This object can be used to keep user-defined data between multiple executions of the same request. By default, it's an empty object. For example, a property named scanCount can be defined by using if(!$.local.scanCount) $.local.scanCount = 0. These properties can be accessed from any scripts executed by a request.

        • $.parameter: Object containing all declared parameters for this request. Each parameter can be accessed by using its instance name. For example, if a parameter is named startTime, it can be accessed using $.parameter.startTime. Each parameter has a value, quality, and timestamp (in UNIX epoch format, with milliseconds). Using the previous example, in order to access the value $.parameter.startTime.value is used; the quality requires using $.parameter.startTime.quality, and the timestamp uses $.parameter.startTime.ts.

        • $.output: This property must be set by the script to the value desired for this header. It has to be a string, otherwise an error will be raised, and the request won't be executed. For example, to create a header that depends on a parameter named cookie, the following script can be used: $.output = "$.parameter.cookie".

Body

Defines the request body sent to the server for HTTP methods that support it (POST, PUT, PATCH). The body is constructed using serialization and encoding settings, then generated by a custom script.

• Body format: Configures how the body data is processed before being sent:

  • Serialization: Selects the serialization of the body of the request data. For the serialization to work properly, the data must previously be prepared in a specific format using the body data serializer:

    • Binary: The body data must be a binary Buffer, and no further modifications are done; the Buffer will be sent as is.

    • Text: The body data must be a string, and then this string will be sent as the body of the request.

    • JSON: The body data must be a JavaScript object, which will then be converted to a JSON string.

    • XML: The body data must be a JavaScript object, which is then converted into an XML string.

  • Encoding: Selects which format is used to encode the body.

    • UTF8: Encodes the body as a UTF8 string.

    • Binary: Encodes the body as a binary buffer.

    • Base64: Encodes the body as a Base64 encoded string.

    • Hex: Encodes the body as a hexadecimal string.

• Body serializer: Defines how the body data is generated:

  • Type: Selects the method used to generate the body data:

    • Custom: Utilizes a user-defined script to generate the body data. This can be used to create nearly any body format, at the cost of increased complexity by requiring JavaScript knowledge.

  • Script: Script that will be used to generate the body of the request. The result of this script will then be serialized using the specified serializer, and then it will be encoded before being sent. The parsing script has access to the following functions and objects:

    • Buffer: Class used to manipulate a byte buffer directly. More information can be found at NodeJS API Reference.

    • moment: Class used to parse, format, and manipulate dates. This has access to both normal moment and moment-timezone. More information can be found at moment and moment-timezone.

    • sprintf: Function used to simplify formatting a string using placeholders and a list of arguments, using the same format as the C sprintf function. More information can be found at C++ reference - sprintf.

    • $.logger: Object containing logging functions that can be used to log custom messages during script execution. Valid log levels are error, warn, info, debug, and trace. Each of these functions can be used as $.logger.info(message, args...). The logger accepts a format string in the sprintf format.

    • $.local: This object can be used to keep user-defined data between multiple executions of the same request. By default, it's an empty object. For example, a property named scanCount can be defined by using if(!$.local.scanCount) $.local.scanCount = 0. These properties can be accessed from any scripts executed by a request.

    • $.parameter: Object containing all declared parameters for this request. Each parameter can be accessed by using its instance name. For example, if a parameter is named startTime, it can be accessed using $.parameter.startTime. Each parameter has a value, quality, and timestamp (in UNIX epoch format, with milliseconds). Using the previous example, in order to access the value $.parameter.startTime.value is used; the quality requires using $.parameter.startTime.quality, and the timestamp uses $.parameter.startTime.ts.

    • $.output: The script must set this value to the desired output. The type of the output depends on the selected serializer; if the serializer is JSON or XML, the output must be an object, if it's text, it must be a string, and if the serializer is binary, then the output must be a Buffer.

Response format

Defines how the response body from the server is decoded and deserialized before being passed to the Response parser.

• Encoding: Selects which format is used to decode the message. Available formats:

  • UTF8: Decodes the message as a UTF8 string.

  • Binary: Decodes the message as a binary buffer.

  • Base64: Decodes the message as a Base64 encoded string.

  • Hex: Decodes the message as a hexadecimal string.

• Serialization: Selects the serialization of the incoming data. This data will be deserialized using the selected serializer:

  • Binary: The data will not be deserialized, instead it will be forwarded to the parser as a binary Buffer.

  • Text: The data will be converted to a string, and then this string will be forwarded to the parser.

  • JSON: The message will be deserialized from a JSON string into a JavaScript object, which is then forwarded to the data parser.

  • XML: The message will be deserialized from XML into a JavaScript object, and then forwarded to the data parser.

Response parser

Defines how the deserialized response data is parsed and mapped to tags.

• Type: Selects the method used to parse the data obtained after deserializing the message:

  • Custom: Utilizes a user-defined script to parse the data. This can be used to parse nearly any message, at the cost of increased complexity by requiring JavaScript knowledge. This can also be used to deserialize custom formats if the deserializer is set to binary.

• Script: Script that will be used to convert the incoming message into a specific format that is used to provide data to tags. The parsing script has access to the following functions and objects:

  • Buffer: Class used to manipulate a byte buffer directly. More information can be found at NodeJS API Reference.

  • moment: Class used to parse, format, and manipulate dates. This has access to both normal moment and moment-timezone. More information can be found at moment and moment-timezone.

  • sprintf: Function used to simplify formatting a string using placeholders and a list of arguments, using the same format as the C sprintf function. More information can be found at C++ reference - sprintf.

  • $.logger: Object containing logging functions that can be used to log custom messages during script execution. Valid log levels are error, warn, info, debug, and trace. Each of these functions can be used as $.logger.info(message, args...). The logger accepts a format string in the sprintf format.

  • $.local: This object can be used to keep user-defined data between multiple executions of the same request. By default, it's an empty object. For example, a property named scanCount can be defined by using if(!$.local.scanCount) $.local.scanCount = 0. These properties can be accessed from any scripts executed by a request.

  • $.parameter: Object containing all declared parameters for this request. Each parameter can be accessed by using its instance name. For example, if a parameter is named startTime, it can be accessed using $.parameter.startTime. Each parameter has a value, quality, and timestamp (in UNIX epoch format, with milliseconds). Using the previous example, in order to access the value $.parameter.startTime.value is used; the quality requires using $.parameter.startTime.quality, and the timestamp uses $.parameter.startTime.ts.

  • $.input: This contains the headers, the body, and the status code of the response.

    • $.input.statusCode: This contains the status code of the request, as an integer. More information can be found at HTTP response status codes.

    • $.input.headers: This is an object containing the headers of the response. The name of the headers is in lower-case.

    • $.input.body: This contains the body of the response. The type and format of the body depends on the deserializer that is used; it can either be a Buffer (if binary deserialization is used), a string (when using text deserialization), or a JavaScript object (if the deserialization is either JSON or XML).

  • $.output: This is the output of the parsing function. By default, it's an empty array where objects containing the tag updates have to be placed. The format of each element of the array must be {tag: TAG_ADDRESS, value: TAG_VALUE, quality: TAG_QUALITY, ts: EPOCH_TIMESTAMP}.

    • TAG_ADDRESS: This value is used to choose which tag will be updated. It can either be the tag address of the tag (defined in the tag configuration), or the path of the tag if the tag address is empty.

    • TAG_VALUE: This is the value used to update the tag. It can be any value.

    • TAG_QUALITY: This is the quality of the tag for this event. It has to be a number from 0 (Bad) to 192 (Good). If the quality is not present, it will be automatically set to 192.

    • EPOCH_TIMESTAMP: This value is the timestamp of the event. It has to be a number in epoch format with milliseconds. If the timestamp is not present, it will be automatically set to the current time.

Enabled

When disabled, tags won’t be updated with the values received from the device. Instead, they will essentially act as memory tags. When set to enabled, the tag value will be continuously updated with the values received from the field device, or in this case, the REST server. The default value is set to disabled.

Module type

Defines the driver type used to retrieve values from the field. In this example, RestApiClient must be selected from the drop-down menu. If RestApiClient does not appear in the drop-down menu, this means that this driver has not been installed on this machine yet and must be installed.

Module name

Selects which instance of the REST API Client module will provide the data for this tag.

Config

• Enabled: Enables data collection for this tag. If disabled, no events can occur in this tag.

• Request: Selects which request will provide data to this tag. The request must already exist in the selected REST API Client instance. The format for this property is Channel/Request.

• Alias: The alias can be used to associate this N3uron tag with the data retrieved from the REST server. This property can be left blank, which means that the full tag path must be used to assign the values received from the REST server. If a tag alias is used, tags can be referred to in the request parser using this alias, instead of the full tag path.