Report Parameter Editor
Copyright © 2019 EarthSoft, Inc • Modified: 04 Mar 2019
For widgets that use data reports, the Report Parameter Editor is a tool to modify the parameter values for a selected report. On the Widget Editor screen, clicking the Edit button will open the Report Parameter Editor for the selected report.
Depending on which permissions the user has for the selected report, the Report Parameter Editor will allow the following actions: Download, View, Save, and Save As. If the user has at least view permission for the report, they will be able to run or download the report output. A user that does not have any permissions will not be able to see anything about the report.
•Download – To export the report output, click on the Download button to open a drop-down menu with download options. The following file types are available for download:
•.txt – Tab-separated text file containing the tabular data.
•.csv – Comma-separated, double-quote delimited text file containing the tabular data.
•.xlsx – Microsoft Excel workbook containing the tabular data.
•.kmz – Google Earth kmz file containing Placemarks for each location and a balloon pop-up with the tabular data for that location.
•.shp – A .zip file containing the Esri Shapefile (locations as features) and other related files (*.dbf, *.prj, etc).
•.pdf – A Portable Document Format (PDF) file displaying the tabular data.
•View – A user with view permission, but not edit or create report permission, will not be able to save changes made to the report parameters. Save buttons will not be available.
•Save – A user with edit permission for the opened report will see the Save button, and clicking on it will overwrite the current report with changes to the report name or any of the report parameters.
•Save As – A user with create report permission will see the Save As button, and clicking on it will open up the Save As dialog box. A report name field will be populated with a suggested, unique name for the new report, which can be changed by the user. When clicking the Save As button in the Save As dialog box, the new report name will be checked and if it is not unique, the user will need to edit the report name to be able to save the report. Using the Save As option will create a new report of the same type as the original report, and will use the selected parameter values.
Note: If a user has both edit and create report permissions, both the "Save" and "Save As" buttons will display.
Note: Download links are available in the Report Parameter Editor and will allow the user to download a report based on the selected parameters. If the report has a facility parameter, the download links will not be shown until after a facility is selected, to prevent empty report output. These download links do not require the report to be saved.
The parameters are grouped in tabs and each tab can be expanded to show all parameters by clicking on the name of the tab. The images below provide an example of the Report Parameter Editor for an Analytical Results II report and selection of the Location tab.
Many reports include facility as an input parameter. Use the Facility Chooser to select a facility.
Parameter values are listed next to the parameter name. If no value is shown, then no value has been set. To edit the parameter value, click on the drop-down next to the parameter and select the values by using the check boxes. Selected values will be highlighted.
Note: Some report parameter values may be a macro value. These values will have a message indicating that they are based on other data, and may change at any time. For these values, the actual value that is saved is a query. Usually they are the default value for the type of report. Changing this value to any other value and changing back to the initial display value, will not restore the query as the saved value. The parameter will still indicate that it is a changed value.
There are six different types of parameter values.
•Text – When editing this type of parameter, a text box is displayed with the current parameter value, if set. Changing the text in the text box updates the parameter value.
•List – When a list parameter is being edited, a list of possible values from which to choose will be displayed. The current value(s) will be highlighted in gray in the list and accompanied by a check box to the left of the value. Clicking on the check box in the list will select the value. The value can be cleared by un-checking the check box next to the value name in the drop-down list. Selected values will be displayed in the text box for the parameter.
•Single-Select – This type of list parameter only allows a single value to be selected at a time. Clicking on a new value in the list will replace the current value.
•Multi-Select – This type of list parameter allows the selection of multiple values. The values are displayed in the text box as a pipe ("|") delimited list. Clicking on a value in the list that is not currently selected will add that value to the selection. Clicking on a selected (highlighted) value will de-select it.
•Yes/No – This type of parameter can only have a Yes or No value. To change the value, click on the drop-down and click on the check box next to either the Yes or No values.
•Date – The default date value may be: (1) a static date that never changes, (2) a macro value based on other data and can change at any time, or (3) a relative dynamic date, such as "Today" or "First day of the Year", which will evaluate to the current representation of this relative date and may be a different date than the last time the report was run. If the value is other than a static date, a message will be displayed next to the value, indicating it is one of these types of values. When editing a date parameter, a text box and a calendar tool are displayed.
To select a static date, use the calendar tool or manually enter the date into the text box. Please note that the date format is specific and is based on the current culture as set in the browser. If a manually entered date is not understood, the parameter will be highlighted in red and a message will indicate the correct format to use. Changing the value in the text box will also update the calendar tool. The calendar shows the selected date highlighted with a solid circle and today's date highlighted with a circle outline. If Today's date is selected in the calendar tool, it will remain highlighted with a solid circle. To select a different month or year using the calendar control, click on the name of the month or the arrow pointing forward at the top of the control. This changes the calendar tool from the month view to the year view. Once in the year view, scroll through the available years as desired. The current selected month will be highlighted with a solid circle. Select the desired month/year combo to return to the month view to pick a specific date.
To set a relative dynamic date, select the drop-down menu at the bottom of the calendar tool. Scroll through the relative date options and select the desired option. The calendar tool will automatically update to reflect the selected relative dynamic date.
If a report parameter is required, the Report Parameter Editor screen will not allow the report to be run to view or download the report output, unless all required parameters have a value.
Required report parameters will be indicated in bold text. If a user clicks the Save button and a report parameter does not have a value, a validation message will appear after the report parameter to help indicate which parameters still need a value.
If a user has the create report permission, they can click the Save As button to create a new user report. The currently selected parameter values will be saved with the new user report. Clicking on the Save As button will open the Save As dialog box. In this dialog box, the user can save the report for the selected facility or for "all my facilities". When saving for all my facilities, the report will save without the facility parameter being set. This is useful for using the report with dashboards that filter the user's facility selection in the dashboard header. If there is an overlap between the original report's saved facility and the user's facility, another option for the report's original saved facility will also be included.
In the Save As dialog box, the report name field will be populated with a suggested, unique name for the new report, which can be changed by the user. The new report name must be unique; if it is not, clicking the Save As button will result in a message indicating that a report with that name already exists. The user will need to edit the report name to be able to save the report. Clicking on the Save As button in the Save As dialog box will create the new user report, and the Report Parameter Editor will close.
If a report is opened and there is an overlap between the report's saved value and the user's current facility, the facility parameter label will be highlighted in yellow with the text crossed out. The user's current facility will be shown as the facility parameter value. Running the report to view or download the report output will use the current facility as the facility value. A message also highlighted in yellow will indicate that the current facility ('<facility name>') overrides the report's facility ('<facility name>'). In this case, the Save button is disabled if present, but the Save As button will not be disabled.
If there are dashboard filters that overlap any of the report's other parameters, the parameter's name label will be highlighted in yellow with the name of the parameter crossed out. A banner at the top of the parameters will have a message indicating that there is an overlap. Running the report to view or download the report output will use the dashboard filter values for these parameters. The banner message includes a Clear button. Clicking this Clear button will clear the dashboard filters. While there is an overlap with dashboard filters, both the Save and Save As buttons will be disabled.
With at least viewer permission for the report, a user can use the View and Download links at the bottom of the dialog window. Like the other report parameters, these links are hidden if a facility parameter exists and a facility has not been selected in the facility chooser. Clicking on the View link will display a table of the report output. Clicking one of the download links will trigger a download of the report output. If the download link is labeled ".***", this means that the file format of the report output is not known.