Create Tag Queries

The Report Studio is still under development and has not officially been released. Be warned that code may change such that reports you create with this pre-release trial version might need to be updated in order to continue working after your next VTScada update.

Until the official release, documentation for the Report Studio will open in response to the F1 key but will not be shown in the menu system. To view a table of contents for the complete chapter, navigate to The Report Studio

All tables start with a single column. Click the [+] bar to the right to add more.
Note that a tag query that includes multiple tags or calculations will generate as many columns as needed to display the result of the query.

Tag queries are typically placed in column B of a table. Recommended practice is place a Time-type data set in Column A because summary titles (if summary lines are configured) are always placed in the first column, therefore any data that you intend to summarize should be placed in other columns. (Timestamps are not summarized.)

If your query involves more than one tag or more than one calculation, additional columns will be created as required when the report runs, to a limit of 30 columns. You do not need to create a separate column for every tag and every calculation.

Whether configuring a Time column or a query, start by clicking in the title row as shown to open the Data Cell Properties panel.

Select column B to define a tag query data set

To Create or Edit a Tag Query

In the Data Cell Properties panel, click the pencil icon to edit an existing query or click the [+] button to create a new one..

Configuration options for a Tag Query data cell.

A new Tag Query being created.

With the Data Cell Properties panel, you can do the following for Tag Query data sets:

Delete the column

Click the trash can icon in the header of the Data Cell Properties panel. Note that deleting the column removes it from the table but does not remove the data set definition.

There is currently no way to delete or rename a data set definition.

Create a Data Set

Every "time" column definition, every tag query, every recipe batches query and every alarm and event query is stored as a named "Data Set". You are advised to give each a descriptive name because it is likely that you will eventually have many.

No predefined data sets exist for tag queries. You must create one using the tags in your application.

  • Click the plus button [+] to create a new data set with a name of your choosing.
  • Click the pencil button to allow editing of the following properties.
  • Click the copy button to clone a data set.

Set the Type to Tag Query

The type property must be set to "Tag Query" for this column to include tag data from your application. This also applies to the Raw Timestamp column.

Set a Tag Hierarchy Context [Optional]

Context can be used in two ways:

  • As a filter, limiting tag selection to those below a parent tag such as a station.
  • As a parameter, allowing the same report to be run for multiple contexts or stations.

Setting a context for a tag query column.

To use Context as a filter, select a parent tag. The Tag Selector will show only child tags of that parent.

To use Context as a parameter, you must first create a parameter. Refer to Define Parameterized Reports. Note that a value must be assigned to the parameter for use in the Report Studio before you can continue with further steps. Proceed to tag selection as usual. When operators run the report, they will be prompted to select a station or other parent tag to use for that instance of the report. Use Report Tags to predefine a choice for the parameter.

Open the Tag Selector

Click on the Tag Selector button to open the Tag Selector Dialog, where you can choose the tags to include in the report. If a Context was set, only child tags of that parent will be shown. The order of the tags in the Tag Selector dialog will affect the order of the columns in the report.

Note that it is often helpful to define a query rather than select specific tags.

Add Data Columns

Data columns are the calculations applied to tag values. Examples include Average, Minimum, Run Time and also "Raw Value".

Add as many data columns as needed for each tag in the data set by clicking the <<Click to Add>> tool at the bottom of the list. There must always be at least one data column for every data set. Values in a report can be averages, snapshots, minimums, etc. A list is provided within this topic.

Data column properties

Select each column to adjust header and precision.

If the data column displays a numeric value (e.g. Average, Minimum, ...) you can specify the header text for the column and the precision with which the value is displayed. The default is to use the precision specified with the tag's display configuration. Otherwise, you may specify a precision between 0 and 9.

 

 

If the data column displays a time value (e.g. Time of Minimum, Raw Timestamp, ...) you can open the Parameterized Phrases dialog to display time and date in the format of your choice. This is usually required for Raw Timestamps, which are measured to the millisecond.

If reporting on Raw Timestamp and Raw Data values for more than one tag, note that the column for each tag is generated independently. Timestamps are unlikely to match across any row.

To remove the default function, add a second data column using the function you want, then delete the first. Arrows to the side of the Data Columns list allow you to change the order of the functions.

Group Data Columns By Tag

Given a Data Set with multiple tags and multiple data columns, the default is to group the output by tag. You could choose instead to group by the data column function. For example, a set of columns showing all of the averages, then a set of columns showing all of the minimums, etc.

For complex groupings, you might use multiple tag-query columns. ( C, D, etc...)

Define Header Text

Sets the title for each column. Because columns are generated automatically according to your tag query, it is typical to use parameters to define titles dynamically.

Select from the drop-down list of predefined titles or click the provided button to open the Make Parameterized Phrase dialog. Refer to Parameterized Phrases for examples.

Summary Suppression

Typically used when both of the following conditions are true:

  • You have created one or more summary rows
  • Your report includes two or more data sets.

If either of those conditions is not true, there is no need to suppress summary information.

An example of where you might use this is a pump report that includes a data column for flow characteristics, and a column for pump run time. The first data set might be summarized with a Range. The second might be summarized with a total. For each column you would suppress all summaries that do not apply.

Data Column Reference for Tag Queries

Except for the raw timestamp and raw data options, all calculations are performed for time span defined by the table's time per record value. Refer to Set the Time per Record.

  • Average - Average of all values within the set time per record (time span).
  • Minimum - Smallest of all values within the set time per record.
  • Maximum - Largest of all values within the set time per record.
  • Delta - Difference between the largest and smallest of all values within the set time per record.
  • Value at Start - Use for "snapshot" reports. The value at the beginning of each time per record interval.
  • Minimum Time - Time within the span when the smallest value was recorded.
  • Maximum Time - Time within the span when the largest value was recorded.
  • Starts - Number of zero to non-zero transitions.
  • Running Time - Length of time when the value was non-zero.
  • Totalize - Adds all the recorded values within each time per record.
  • Start and End Difference - The difference between the last value recorded and the first value recorded for a time per record.
  • Bitwise AND - Should be used only with digital tags (those having a value of 1 or 0) Compares the current row to the previous and returns 1 if both are 1.
  • Bitwise OR - Should be used only with digital tags (those having a value of 1 or 0) Compares the current row to the previous and returns 1 if either are 1.
  • Raw Timestamp - Use with Raw Data. The time when the value was recorded. A display format that includes milliseconds is recommended.
  • Raw Data - Returns all values stored rather than a calculation over the time per record interval. Should not be used in combination with other calculations.
  • Runtime Data - A constant value, calculated at runtime. Use this to display any of the following from a selected tag: ShortName, Relative name, Description, Area, Units. The value will be shown in every row.