Webtags

This page is the new Webtags page. This page and subpages hold a complete rewrite of the Webtags page.

The information that was on this old Webtags page has been moved to Webtags (preserving history). You are advised to use that page until this page is ready and this message has been removed. If any questions or remarks please send a PM to HansR on the forum. Do not use the discussion tab unless accompanied by a PM: there is no automated signal to HansR if you use that page.

This page and its subpages will document the Webtags from the point of view of the CumulusMX software and not the Cumulus 1 legacy software. Cumulus 1 is no longer maintained and will eventually disappear. If you are still using it, please refer to the original Webtags (preserving history) page where @sfws has tried to give both packages equal value. That effort is no longer maintained in this Webtags page. We hope you will understand this approach.

Please do not edit this page while it is being worked on i.e. while this message is still here.

---

Introduction

Data gathered by CMX is stored locally in the database (see e.g. dayfile and standard logfiles and a range of ini files, Extra Sensor files, Airlink logfiles etc...). To make these data - and calculated derivatives - available to the user CumulusMX (CMX) uses a system of Webtags. In short, a Webtag is a symbolic name which is translated into a value when asked by CMX. So e.g.:

 temp  -> (process) -> 17.1

The webtags can have modifiers to change the output or the input e.g. you can change the decimal point to a comma (output modifier). All these will be described below.

How to use Webtags, see below.

List of all tags

This chapter is about the full list of Webtags. The names of the webtags are basically functional i.e. you can guess what the value says. The order of the tags in the local list is unknown, most likely it is a mix of time of origin, functionality and alphabetical ordering. The order of the tags in the full list is functional i.e. they are grouped by an arbitrary functional partition. Within such group no effort has been made to order according to another ordinal.

The naming of the webtags can sometimes be confusing

At the time of this writing (25 september 2022) there are 870 distinct Webtags by name in the local list. The reader must be aware the full list may have flaws at any moment in time caused by the shear amount of tags and the speed of change in the software.

Inconsistency of tag names

The naming of the tags can sometime be confusing. The long history of development of Cumulus(MX) has left its traces and although technically corrections can be made, the effort to do that is such that I won't bet on it happening. So a short guide to what can be expected follows here.

For a shor history of inconsistency you may read here.

1. Inconsistency in use of "Y": The character "Y" has been selected to denote yesterday in tag names. The inconsistency is where it appears. e.g. rfallY, YSunshineHours, Ybeaufort, windAvgY
2. Inconsistency in Month and Year for this month and this year: #YearLongestDryPeriod, #SunshineHoursYear both as prefix and postfix they mean the same.
3. Inconsistency in use of "T": Where the "T" is added as indicating the time of the event (High or Low) e.g. leading to T<tag name>TH, this method is not consistently followed and may lead to some confusion. E.g. tempTH (the value for the temperature at its maximum) and TtempTH (for the time of that corresponding value). But also YearDewPointH (years highest dewpoint) and YearDewPointHT for the time of the event i.s.o. TYearDewPointH (which does not exist but which might have been more consistent).

Whatever you find and use, make sure you understand what you are looking at (you may need tests to verify). If the lists below are not correct, again you are invited to share or correct your discoveries.

The local List

From version 3.12.0 the complete list of Webtags can be generated from your running CumulusMX instance.

Goto the interface. In the menu go to Program settings=>General options, tick List web tags. The next time that MX is restarted, it will create a file called WebTags.txt in the same folder as where the executable is found. Unticking that parameter will have the inverse effect.

The WebTags.txt file will list all the tags your build of Cumulus can currently handle. This list only contains the bare tag names. Parameters and modifiers will need to be looked up and added to make use of these. This list can be of use if you are using the tags to create your own program or website while interfacing with CumulusMX. It is useful to save it now and then with the CMX version nr in its name. This will make it possible to find the new tags easily through making a difference.

The full List

The full list of Webtags carries a lot of additional information so it has its own Webtag page. It is grouped by functionality without additional ordering. Some description is given where available.

Using Webtags

There are the following methods to ask CMX to do this translation both of which will be discussed below (or in a sub-page). The two methods are:

1. Processing files through the running instance of CumulusMX
2. Getting the value by using the local interface GET method.
3. Getting the values through the local interface POST method

The first method is used in files used as input for the Extra Web Files in CMX which are then processed by CMX if you tick process The output file then contains the value.
The second and third method's principal use is to be used programmatically from anywhere you can reach the CumulusMX machine.

NOTE: it is not possible to give Webtag modifiers by using the get method but it is in the POST method. Check out the differences in the above links.

There are three bonus methods for getting values out of the CMX database:

1. Getting predetermined data (not really with Webtags)
2. Using MySQL through the Custom Upload feature
3. Using the Custom Logs feature of CMX (from 3.22 and up) through which you get a timeseries of one or more Webtag(s)

The predetermined methods and the SQL methods are really for programmers.

The local API methods are described on their own page.

How CumulusMX handles unknown Webtags

When CumulusMX is processing through tag names and finds one it cannot understand, a "*** web tag error - see MXdiags file ***" message will appear in the engine console (if running interactively, when running as a service it will be in the ServiceConsoleLog file), and the diagnostic file will include something like this:

Web tag error
Exception: i=8998 len=106297
inputText.Length=106297
token=<#daylightlength format=H>

This particular error is that when you use a single output format character it does not have same meaning as when there are multiple characters, correct this particular web tag to:

<#daylightlength format=%H>

If you are sure the Webtag does exist (Check the Local List) and you think you are correctly using parameters, it is time to bring the problem to the forum.

General Format for Web Tags

Before using the Webtags, the user must be aware of the formatting.

In the position, in any file to be processed, SQL, or HTTP POST call, where Cumulus is to insert the relevant data, place a web tag in the general format specified here:

 <#tag_name [optional input selection parameters] [optional output modification parameters]>

Only the GET method has another format and does not accept modifiers.

The terminology "optional" is used because some tag names do not accept any parameters, but there are some tag names where a parameter is mandatory. Therefore, check the web tag parameters page to learn whether a webtag name requires a mandatory parameter, or to find out which parameters are optionally available.

Processing files

The oldest, most common and possibly the easiest method for using webtags is processing a file (e.g. a HTML web page or a PHP script) which contains a webtag description like <#temp rc=y>. After processing the output file then contains the value (e.g. 17.1) for that webtag and the complete description, including the brackets have then disappeared.

The configuration should look like the screenshot below:

MySQL

In the MySQL settings of the Interface there exists the possibility to create Custom Upload queries. This is n ot the place to treat the use of MySQL extensively, but CumulusMX offers the possibility to use Webtags in such a Custom Upload query definition. The example below should clarify:

 INSERT IGNORE INTO `test_daily_summary` (`MaxRainRate`, `LogDate`, `RollOver`)
   VALUES ('<#rrateTM>', '<#metdateyesterday format=yyyy-MM-dd>',  '(1 * SUBSTRING(<#rollovertime>,0,2))');

Again, the modifiers are discussed below.