Not counted towards your tag license limit.
VTScada's JSON/XML Driver tag supports HTTP GET and HTTP POST requests to remote systems.
IO tags that are linked to a configured JSON/XML driver tag will gain Address Select. Click the [...] button next to the read/history/write field to open the Address Select dialog. This address book will be populated from the JSON/XML content of the HTTP response.
VTScada's JSON/XML Driver tag supports HTTP GET and HTTP POST requests.
- GET - requests information only. Parameters can be sent in the URL.
- POST - typically provides info to a remote system to be processed or stored. Data sent with the request should be included in the Message Body.
VTScada allows a message body with both GET and POST requests, although using a message body with GET is uncommon.
VTScada supports responses compressed via deflate or gzip methods.
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 ID tab
The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.
Name:
Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.
You may right-click on the tag's name to add or remove a conditional start expression.
Area
The area field is used to group similar tags together. By defining an area, you make it possible to:
- Filter for particular tag groups when searching in the tag browser.
- Link dial-out alarm rosters to Alarm tags having a particular area.
- Limit the number of tags loaded upon startup.
- Filter the alarm display to show only certain areas.
- Filter tag selection by area when building reports.
When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors).
To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.
You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).
To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.
There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).
Description
Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.
Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.
The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.
This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.
Help Search Key
Used only by those who have created their own CHM-format context sensitive help files to accompany their application.
JSON/XML Driver properties Communication tab
Configure the Request:
Method
Select the data format for HTTP requests. Use GET to retrieve data.
URL
This is the address of the file containing either JSON or XML-formatted data to be read by the driver.
If the URL does not specify a port number, then it will default to 80 for unsecured connections and 443 for secured connections.
Message Content Type
Set the format that the optional Message Body is written in. The options available are None, JSON, XML, Plain Text and Other. The default is None which is the most common configuration for a GET request. When a Type is selected, the address suffix will be displayed in the read-only field next to the droplist. If "Other" is selected, this field becomes editable and will accept an alternative suffix.
Message Body
Contains the data sent with the request when using the POST method. The maximum number of characters to be accepted is 65535.
Set the expected formatting of the Response:
Data Type
The data format you expect to receive in response. JSON or XML.
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
JSON/XML Driver properties Authentication tab
Username and Password
If required by the remote system, provide the Username and Password to access the file. Note that the password will displayed as "***" characters and will be stored in an encrypted form.
JSON/XML Driver properties 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.
JSON/XML Driver properties Connection tab
Polling Interval
Set the frequency in seconds for fresh reads of the URL. This defaults to 60 seconds.
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 tag Widgets
The following widgets are available to display information about your application’s JSON/XML Driver tags:
