JSON/XML Driver

Not counted towards your tag license limit.

Given a fixed URLClosed Uniform Resource Locator. The address of a web page., the driver will read the JSONClosed JavaScript Object Notation or XML data at that address and turn it into a nested VTScada dictionary with arrays.

Data may be read by attached I/O tags such as Analog Status, Digital Status or String I/O as appropriate. The address will depend on the structure of the JSON or XML file, therefore an Address Assist dialog is provided. All I/O tags linked to this driver will gain an address assist button automatically. The contents of the resulting dialog will be populated from the file. If the file cannot be read for any reason, then no addresses will be available.

Supports responses compressed via deflate or gzip methods.

The JSON/XML driver works in one direction only: it reads data into VTScada. It does not write data out to external URLs.

Multiple JSON/XML drivers connecting to the same domain will do so sequentially by default. This may cause unnecessary wait times. Configure your application so that your JSON/XML drivers connect to a specific domain in parallel for more efficient simultaneous data transfer. See Connect JSON/XML Drivers in Parallel for more information.

Error codes

JSON/XML drivers connect to web servers. Therefore, most errors that you might see will be a standard HTTP code. 401 (unauthorized access attempt) and 404 (page not found), are common. Other possible error codes include:

  • -1: Connection timed out
  • -2: Response timed out
  • -3: Invalid (non-HTTP) response
  • -4: Incomplete response
  • -5: Unsupported transfer-encoding
  • -6: Missing parameters

JSON/XML Driver properties Settings tab

JSON/XML Driver properties Settings tab

The Settings tab includes the following properties:

URL

This is the address of the file containing either JSON or XML-formatted data to be read by the driver.

Use the selector below the address to specify which of the two supported data types will be found at this URL. If the URL does not specify a port number, then it will default to 80 for unsecured connections and 443 for secured connections.

Username and Password

If required by the remote system, provide the Username and Password required to access the file. Note that the password will displayed as "***" characters and will be stored in an encrypted form.

Polling Interval

Set the frequency in seconds for fresh reads of the URL. This defaults to 60 seconds.

Processor

The name of a JSON/XML processor. Standard (the default processor) supports live values being read from the site, but does not provide support for timestamped historical data, forecast data, or dynamic data where the payload structure can change. For these cases, you can write your own processor that will handle complex data structures. See: Write a JSON/XML Processor

Connection Time Limit (s)

Sets the time in seconds that the driver will wait for a response before it gives up and retries or sets an error if all retries have been attempted.

Retries

The number of times to retry a message before declaring an error.

Use only if the driver is connected to a device that uses a serial port or a UDP/IP port that is configured to be polled. When connected directly to a device using TCP/IP, this value should normally be set to 0 since TCP/IP is a guaranteed message delivery protocol.
For unreliable communications, such as radio, set to 3 or 4.

Max Request Rate (per second)

The maximum number of requests to send per second to the host. The default is an unlimited rate.

A limited rate is necessary for situations where a host may reject a client if it has received more than X requests per second from that client.

Typically, all driver instances that use the same host would be configured with the same Max Request Rate, but this is not required. Each driver will enforce only its own specified rate limit.

Hold

Select this to have I/O tags attached to the driver hold their last value in the event of a communication failure. If not selected, tags will have their value set to invalid on a communication failure.

External Trigger

Optionally, specify a tag or expression that will cause a fresh read of the URL to be performed.

JSON/XML Driver properties Extra HTTP Headers tab

Some APIs may require extra information such as tokens, form data, etc. Use this tab to specify name=value pairs to be added to the header. Values may be specified here, or supplied from expressions or tags.