Configuration

Channel

The first step when configuring the REST API Client is to create a connection to a REST endpoint. This is represented by a channel. Channels have the following configuration:

• Enable data collection: Enables data collection for this channel. If set to false, no requests on this channel will be executed.
• Connection: This section contains options related to the HTTP/HTTPS connection.
  • Protocol: Select between unsecure HTTP protocol or secure HTTPS protocol.
  • Host: Hostname or IP address of the target REST server without http:// or https://.
  • Port: TCP port where the target REST server will be listening. By default, HTTP uses port 80 and HTTPS uses port 443. The 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 in order 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 this case, this option must be set to false.

• Timing: This section contains options related to timeouts and retries that affect all the requests in the channel.
  • Request timeout: Specifies how much time can pass after a request is sent to the server before it times out and is retried (in milliseconds). The default value it 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.

Request

A Request represents the REST request that is sent to the server. Requests have the following options:

• 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.
• Method: Selects between the different HTTP REST methods. Some methods (such as GET) do not have a body (and as such, the body section is hidden), while others such as POST or PUT require a body.
• 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.

  
  

  • Periodic: This type of trigger becomes active after a specified period has passed. It is configured as per the below example:  
    • Scan rate: Specifies the periodiod between each time the trigger is activated, displayed in milliseconds. The default and minimum value is 1000 milliseconds.
    • Type: Determines how this period is calculated. Valid values are: 
      • Fixed time: The trigger will activate as soon as the specified scan rate has passed since the previous execution ended. For example, if a trigger is set to execute every 30 seconds, and the first execution occurred at 12:30:17, the next execution will be at 12:30:47.
        • 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 executed at 11:31:25, rescheduling the timer to execute 60 seconds after the current execution.
            • Reschedule disabled: The periodic trigger will executed at 11:31:10, which is 60 seconds after the previous periodic execution.
      • Fixed interval: The trigger will execute at specific intervals based on the scan rate. As per the previous example, if the scan rate is 30 seconds, the trigger will execute at 12:30:00, 12:30:30, regardless of when the module started. 
        Note:

        Cron is available from N3uron version 1.21.7.
      • Cron: This field will require you to provide or select a cron expression to define the desired schedule. Readers can find further information at crontab.guru. For example, 0 3 * * * would schedule the task to run at 3 AM every day. It is also possible to select a predefined cron expression:
        • Every 15 minutes.
        • Hourly.
        • Daily.
        • Weekly.
        • Monthly.
  • TagCondition: This type of trigger activates whenever a tag-based condition is met. It is configured as per the below example: 
    • Tag: Path to the tag used in this tag condition trigger. 
    • Property: The property of the tag used to trigger the transaction (Value, Quality, or Timestamp). 
    • Initial change: If enabled, the transaction will be triggered by the initial subscription to the tag events as soon as the module is started (or whenever the tag model changes). Otherwise, the initial event won't be considered for the tag condition. 
    • Condition: The condition the tag must be in for the trigger to become active. If the tag is a string, it will be 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 will trigger when the condition becomes true. It can only be triggered once (or once per tag update) depending on the value of the "Trigger on update" option. 
      • If false: The action will trigger when the condition becomes false. As per the case above, it can only be triggered once (or once per tag update). 
      • While true: The action triggers once when the condition becomes true, and then repeats periodically, according to the specified period. 
      • While false: Same as above, except it triggers while the condition is false. 
    • Trigger on update: If true, the action will trigger whenever there is 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 tag acting as the trigger will be reset after the transaction is executed. If disabled, the trigger must be manually cleared. Only used for If True and If False conditions. 
    • Reset value: Specifies the value that will be used to reset the tag that is acting as the trigger. Only used when Reset trigger is set to true or for If true and If false conditions. 

      
      

• Parameters: List of parameters that will be available to all scripts in this request. More information about parameters can be found at $.parameter.

  
  

• Path: This section is used to obtain the path of the REST request. It can be one of two types:
  • Plain text: The path is created using a static string. This is the simplest way of creating the request path. However, paths that require dynamic values (such as a date, or values that depend on tags) cannot be created this way.
  • Custom script: Creates a path by executing a custom JavaScript script. This confers greater flexibility compared to plain text, since using this method means that the path can be created dynamically based on parameters. The path can be set by assigning the desired value to the $.output variable. More information can be found in the $.output section.
• Headers: This section is used to define which headers are sent with the request. More information about the headers can be found in the headers section.
• Body: This section only appears when the request needs a body (such as a POST, PUT, and PATCH requests) and is used to generate the body of the request. More information can be found in the body section.
• Response format: Establishes the expected response format.
  • Encoding: Determines the encoding of the response. Valid values are UTF8, Binary, Base64, and Hexadecimal.
  • Serialization: Determines the serialization of the incoming response. Valid values are Binary, Text, JSON and XML.
• Response parser: Determines how the response is parsed into a N3uron compatible format, which is then saved into tags.
  • Type: Selects the type of serializer used to parse the body. Currently, only Custom serializers are supported.
  • Script: User defined JavaScript code that will be used to parse the body of the response. The response received from the REST API server can be found in the $.input property (containing response body, response status code, and header). More information about scripts can be found in the user defined scripts section.

Headers

When executing a Request, headers are sent along with the request. Each request has a number of headers that are set automatically by the module and a variable number of custom headers created by the user. The below screenshot shows the configuration options for these headers & two custom headers.

• Fixed headers: These headers are set automatically by the module. However, a custom header with the same name as these headers can be created to override this value.
• Accept-Encoding: Configures the Accept-Encoding header for the request, which is used to indicate which encoding the client can support to the server. Valid values are Gzip, Deflate, and None.
• Authorization: Configures the Authorization header for the request, which some servers use to determine whether the client is authorized to execute the REST request. The authorization header can be one of three types:
  • None: The authorization header is not added automatically. However, it can still be added as a custom header if custom authorization is desired.
  • Basic: Employs HTTP basic authentication using a username and password.
  • Bearer: Uses a static bearer token to authenticate with the server
• Custom headers: These headers are created by users and can either be used to override a fixed header (for example, if the server uses a custom authorization method) or to add headers that the REST server requires for servicing a request. The above figure displays two custom headers of the Accept and Content-Type.
  • Type: Custom headers can be created in two ways, either by using a static text, or by executing code to dynamically create the header. These correspond respectively to the raw text and custom script options.
  • Value: Sets the value of the custom header to the specified string. This option is only available for raw text types.
  • Script: The Script that will be used to dynamically generate the custom header. The header is set by assigning it to the script’s $.output property. More information can be found in $.output and information surrounding custom scripts can be found in user defined scripts. This option is only available for custom script types.

Body

This section is used to create the body that is sent with the request. These options will only appear when the REST method is either POST, PUT, or PATCH. The configuration used to create a body is as follows:

• Body format: This section determines the format and encoding of the body.
  • Serialization: Determines how the body is serialized before being sent to the destination. Valid options are Binary, Text, JSON, and XML.
  • Encoding: Sets the encoding of the body after it is serialized. Valid options are UTF8, Binary, Base64, and Hexadecimal.
• Body serializer: Determines how the body of the request will be created.
  • Type: Selects the type of serializer used to create the body. Currently, only Custom serializers are supported.
  • Script: User defined JavaScript code that will be used to generate the body. The output of the script must be set in the $.output field. More information can be found in the $.output section and information about scripts can be found at user defined scripts.

Tag Configuration

REST API Client can be used as a source module and as such, can generate tag events from REST requests. In order for these tag events to be valid, tags with the REST API Client as their source must be created (Refer to this link for more detailed information on creating tags). See the below screenshot for an example configuration:

• 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.