Parameterized Reports

Parameters can be used select which tags to use for your custom report each time you run it. For example, if your application has several stations and you would like to produce the same report individually for each station, then you can use a parameter.

When running a parameterized report from the Reports Page, you will be prompted for the necessary values when the report runs. If running the report with a Report Tag, you can preset the parameter values as part of the Report Tag's configuration.

There are three main tasks:

1. Create one or more parameters.
2. Use those parameters as part of your tag query.
   (Optionally, you can also use those parameters as part of any text that you choose to add to the report.)
3. Provide values to the parameters, either when running the report or configured within a Report Tag.

 

Add and Manage Parameters

Use the tools in the Report Studio ribbon to add parameters:

The Manage Parameters button opens a dialog where you can create new parameters and modify existing ones. And example of adding a new parameter being created follows:

The example shows a new parameter being configured. Recommended practice is to ensure that the parameter name is unique, avoiding any conflict with tags or other named objects. The description field should guide developers or operators when selecting the tag or value for the parameter. If the parameter is of type tag, then you should guide the user by selecting which types can be used. You may use the Ctrl key to select several types.

The same dialog is used when editing existing parameters.

Parameterized pages, plain widgets, and the Report Studio use parameters in the same way and share configuration dialogs.

(For pages and widgets only.) Text parameters can be marked as non-translatable. Select this for text that should never be translated, such as I/O addresses.

Removing Parameters:

By design, there are no tools in the user interface to delete parameters. The easiest way to remove one is to use the Version ControlVersion Control system to find the change where the parameter was added to the page and reverse that. Otherwise, if you are certain that a parameter is not needed and that it cannot be edited to use for a new purpose, then experienced developers can remove parameters by editing source code, then importing the changed file.

Values for Parameters

Use the Values tool in the Report Studio to set display values for use while building the report. This allows you to preview the effect of a parameter while continuing development work.

These values are saved as part of the report definition and will be used as defaults if other values are not provided when running the report.

Use Parameters in Tag Queries

After creating a parameter, you can use it in your tag queries and parameterized text. Tag queries assume that the parameter will contain a parent tag and do not work otherwise.

The following is easier to do if you use the Values tool to select a tag whose child tags should be displayed while you continue configuration.

Working in a Tag Query, set the Context to a parameter that contains a tag as shown in the following example:

Open the Tag Selector. The available tags are limited to child tags of the one associated with your parameter.

Select the tags for your report or create a query as shown in the preceding example.
(|*running | * | * | * |, which is any tag whose name ends with "running".) In a query, "Field" will be "value" for every tag except certain custom-code tags and communication drivers (see Communication Driver Log-Enabled Variables)

Use Your Parameters in Report Text

After adding text to your report, look in the Text Properties panel to find and click the button to open the Make Parameterized Phrase dialog.

Your parameter will be available for inclusion in the phrase. For tag parameters, Name, ShortName, and Description will be included.

 

Supply Parameter Values when Running the Report

When running your parameterized report from the Reports Page, users will be prompted to provide values for the parameters.

If configuring a Report Tag to run your report, you can set values for your parameters in the tag as shown in the following image. To run the report for multiple stations, create multiple Report tags.

 

You now have a parameterized report, good for any station of type aStationType. If you return to the Reports page and run Station Flow Rates, you will be prompted for a station. Let's create a Report tag to automate that...

 

1. Open the Tag Browser and navigate to the top level.
2. Create a new Report tag at the top level of the tag hierarchy.
3. Name it Station 2 Flow Report and set the description to match.
4. On the Tags/Parms tab, select Station 2.
5. On the Period tab, set the Preset to Last 60 minutes before trigger time.
6. Set the Trigger to "Daily", with a time two minutes later than right now.
7. Set the output type to PDF File.
8. Set the Path to one you prefer (your desktop, documents folder, or other...).
9. Save the tag.

 

Within two minutes, your report should be created for Station 2. This is a new station so you can expect that most of the last hour will not have data. In a real application, you might make this tag part of the aStationType hierarchy and use a parameter so that every station automatically has this report.