Introduction

This quick guide discusses the HTTP POST functionality available on the Irisys Vector units, and how to configure it. This document should be used in conjunction with the document; HTTP POST Programming Guide which describes the output file format.

HTTP POST is just one of the many different methods of retrieving count data from a Vector device. It works by pushing out selected data fields at a fixed interval over HTTP. The data is in JSON format.

NOTE: This document refers to Vector firmware 2.0.123 and above. See the Firmware download section for Vector firmware updates.

In order to access these settings, you must first make an initial connection to the Vector unit; see separate guide: Making a Setup Connection.
If connected to a Vector via an Estate Manager connection, make sure you select the ‘Live View’ option to make changes

 

Count Logging Period

The HTTP POST function sends out data immediately after the data is logged to the device – as such, the count logging period defines the interval over which the data is sent. In this example, count logging is every minute:

 

HTTP POST Configuration

Once you are connected to your Vector, the HTTP POST settings are accessed via the ‘Settings’ tab, then ‘HTTP POST’:

If you are connected to your Vector via an Estate Manager connection, make sure you change from the ‘DB’ to ‘Live’ view in order to make changes:

 

There can be up to three separate HTTP POST entries configured, each either pointing to a different address and/or sending different data types, as required.

The Field meanings are as follows (Note also the short help descriptions for each field displayed on the right of the HTTP Post tab):

  • URL: This is the destination URL to POST the data to. If using a hostname, ensure that the Vector’s ‘IP Settings’ tab is configured with valid and accessible DNS server(s).
  • Timeout (seconds): This specifies a limit for the number of seconds from the POST beginning and the receipt of a ‘success’ message from the receiving server. If no such message is received before the timeout, then the transmission attempt is deemed to have failed.
  • Max Attempts: When the next log period is reached, the device will try to POST a message containing count data, the content of which is determined by the last successfully transmitted index, the max history and the max log POST settings. Max attempts dictates the number of times that the device will attempt to POST that message this time around. If this limit is reached without success, then the last sent index remains as it was and, when the next log period comes around, the log message will be constructed the same way as before, so will be the same as the previous message unless the max history (see below) has been exceeded, or the log is full and some older entries (that would have been present) have been culled to make space for new entries. This must be in the range [1 - 2147483647].
  • Max History: This limits the number of entries that the device will search back through when constructing a POST message. Max history must be in the range [1 - 2147483647]. When a device has a very large log history and you may only care about data that is up to a week old then you could set your max history to 4 x 24 x 7 = 672 to achieve this (assuming the default 15min logging interval is used). Setting the maximum value would provide the full history of your device, and with the shortest logging period allowed of once per minute the max history would effectively be over 4085 years, so is not required, nor recommended.
  • Max Logs POST: This limits the number of log entries that can be in a single POST message when constructing it. If this were 10, for example, and there were 100 items in the log and your max history was set as a value greater than or equal to 100, then the first POST would send indices 1 – 10, then the next would send 11 – 20, etc. This must be in the range [1 - 2147483647].
  • Authentication Token: This is an optional field and when set, the text is delivered in all HTTP POST message headers for the intention of rejecting messages if this token is not included.
  • Authorization Token: This is an optional field and when set, the text is delivered in all HTTP POST message headers for the intention of rejecting messages if this token is not included.
  • Data Fields: The various tick boxes allow configuration of what each POST message contains, and most are self-explanatory. All of these options are either directly relating to on device details (some configurable, some not), such as the ‘Sitename’, ‘MAC Address’, ‘Time zone’, etc. or they are calculated from device data such as the ‘Histograms’ data, ‘Local Time’ zone and of course the register count values. The only two which require more clarification are the ‘Value’ and ‘Log Period Value’. These both originate from the logged count register values; ‘Value’ is the actual logged value, but Log Period Value is the incremental value between logging periods. Note: If HTTP Post is enabled but no data fields are selected, the cumulative count data, mac address and timestamp fields will be posted by default.
Care should be taken when configuring the above HTTP POST settings. It is possible to configure POST messages containing large amounts of data, which is sent infrequently, or small amounts of data, which is sent more often. But, sending large amounts of data very often is not recommended, nor should it be required.

Remember that if a POST fails to send for any reason, the settings should allow for catch up of data in the next few POSTs. Settings should also allow for longer periods of network outage during which data cannot be sent but will be accumulating. When the network is restored the data sending will need to catch up again. Also remember that when a POST fails, subsequent POSTs could be larger and hence more prone to fail again. Therefore, settings that balance the speed of catchup, and amount of data being sent each time, should be sought.

Authentication and Authorization Token Notes: The purpose of these options is to allow partners to restrict what is allowed to post to their HTTP server. They enforce this restriction with a secret token that the device is configured to put in the HTTP Post header. Posts without the secret token can therefore be rejected by the server, whilst posts from Vectors will be received correctly. Both options are available dependent on partner requirements but the intended use is to enable one or the other (not both). For details of the HTTP post headers see the corresponding HTTP Post programming guide section.

 

Copyright © 2022 InfraRed Integrated Systems Limited

No part of this publication may be reproduced without prior permission in writing from InfraRed Integrated Systems Limited.  This document gives only a general description of the products and except where expressly provided otherwise shall form no part of any contract. From time to time changes may be made in the products.