EZView Widget

<< Click to Display Table of Contents >>

EQuIS 7  >>  Enterprise > Widgets >

EZView Widget

The EZView widget queries and downloads EQuIS reports and creates EQuIS Information Agents (EIAs) to automatically send reports. A primary purpose of the widget is to run the selected report and then export the report output to third party programs, such as Excel (.xls) workbooks, ArcGIS shapefiles (.shp), tab delimited (.txt) files, and Google Earth (.kmz) files. Users can also drag and drop reports from the EZView widget to a map widget by dragging the report icon from the EZView widget onto the map.

 

Ent-EZView_Widget_Sample

 

The EZView widget displays the report icon on the left. The report icon will include an envelope if an EIA is defined for the widget. The right side of the widget includes the following:

Report Name – The name of the selected report.

Last Download – The date/time (end-user browser local time) that the report was last downloaded.

Run Time – The run time (i.e., elapsed time) indicates how long it took the report to run the last time it was downloaded (excludes download time).

File Size – The file size of the report output the last time it was downloaded.

Record(s) – If applicable, the number of records in the tabular output of the report the last time it was downloaded.

 

View Data

 

If the option to enable a link to the Report Parameter Editor is selected in the widget properties, the EIA_Edit_icon icon will appear on the EZView widget to the left of the Download button. Clicking this icon opens the Report Parameter Editor. Depending on the user's permission for the selected report, the user can view/edit the report parameters, run the report with the selected parameters, and save the report or create a new report.

 

Download Data

To export the report output, click on the Download button to open a drop-down menu with download options.

Ent-EZView_Widget_Download_Dropdown

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.

 

Note: The PDF output is produced by generating default Report Definition Language (RDL) to display the table of data and rendering that RDL as .pdf file. See the EQuIS Professional documentation for more information on customizing the default RDL used for displaying IGridReport data.

 

RDL Reports

 

A published RDL Report will show two download options. See the EQuIS Professional documentation for more information on designing and publishing RDL reports:

xlsx – The Microsoft Excel workbook produced by the published RDL as rendered by Microsoft's ReportViewer control.

pdf – The PDF output produced by the published RDL as rendered by Microsoft's ReportViewer control.

 

"Class" Reports

 

A non-tabular report will only display the download option for the file type that it generates. For example, the "Google Earth: Locations" Report only generates *.kmz files, so only the .kmz option will be available.

 

 

Widget Properties

 

The editor for this widget allows the user to select a report, configure the report, and create EIAs. To add a report or edit other widget properties, open the Widget Editor by selecting the More Options dashboard_chooser icon in the upper right corner of the widget to display the drop-down menu and then select the Edit menu option.

Widget Title – By default, the widget title is EZView. The title can be modified.

Widget Color – The color of the widget can be changed using the Change Widget Themecolor_iconicon to the left of the widget title.

Report Chooser This control is used to select the report to be used with this instance of the EZView widget. The name of the currently selected report (if applicable) is displayed by default. To select a different report, click the Choose a Report button or name of the report. The Report Chooser will open and display available reports. Select the desired report.

Report Parameters – The report parameters (e.g., analytes, sample date range, etc.) can be edited by clicking on the Edit button clip0016 to open the Report Parameter Editor for the selected report. A user with editor permission on the selected report may update the report.

Edit/Create EIAs – Select this button to create or edit an EIA. A detailed discussion of EIAs is provided in the next section.

View/edit parameters in the widget to run the report without saving Checking this option enables a link to the Report Parameter Editor. The EIA_Edit_icon icon will appear on the widget. Clicking this icon opens the Report Parameter Editor. Depending on the user's permission for the selected report, the user can view/edit the report parameters, run the report with the selected parameters, and save the report or create a new report.

Cancel – Select the Close without Saving Close_icon button to exit the Widget Editor without saving changes.

Save – Changes will be applied to the widget by clicking on the Save Widget_Save_icon button. The Widget Editor screen will close after the save operation is complete.

 

 

EQuIS Information Agents

Click the EZView_EIA_Edit_Iconbutton to edit or create EIAs. A window opens to create and set the properties for an EIA on the current widget. There are two tabs on the EIA window—the Data tab and the EQuIS Information Agent tab.

 

Data Tab

 

In case the user wishes to change the selected report while implementing an EIA, the Data tab provides a link to the Report Chooser and the Report Parameter Editor. To enable the EQuIS Information Agent tab, click the Create new EIA agent radio button.

 

EQuIS Information Agent Tab

 

The EIA will run the report and send the information according to the EIA settings. Some settings allow the report to run multiple times, depending on a set schedule or other factors. Note that if the report was supposed to have run at least one time during a period of time, but did not for some reason (such as report generation was disabled in the Workflow Widget properties for that day or time of day), the report will run one time for all the missed times.

 

Note: The hour portion of Start Time and End Time is a drop-down selection. The values are stored as UTC and converted to and from Local Time. For this reason the range of valid values extends from the previous day (before mid-night) through the following day (past mid-night) to accommodate a 24-hour clock in all time zones. The hour values, displayed in a 24-hour format, are relative to the relevant Date or Day parameter. For example, a report scheduled to run at midnight ( 00:00 ) UTC would appear to be scheduled for "Previous day at 17:00" when viewed from US Mountain Standard time UTC -7:00. The same entry when viewed from Sidney, Australia Eastern Standard Time UTC +10.00 would appear to be scheduled for "10:00".

 

To enable an EIA for the report, do the following:

1.Check the Enable Agent (EIA) for this report check box. (To remove an EIA, uncheck this check box.).

 

Note: EIAs are managed at the widget level. Removing the EZView Widget associated with the EIA will remove that EIA from the database ST_SCHEDULE table. This is why EZView Widgets setup as EIAs may not be closed unless the EIA is manually removed from the widget.

 

2.Choose which type of agent to use and configure the EIA settings:

a.New Data (EDD) – Sends a report when a new EDD arrives. There is a short delay of approximately 15 minute between when an EDD is loaded into the database and when an EIA may report on that event. At run time, the values for FACILITY_ID and EBATCH from the EDD are passed to the report, replacing the parameter values saved with the report.

EZView_EIA_Create_EIA

Once the New Data (EDD) option is selected, the agent can be configured to further limit what EDD information is applicable to the report by clicking on any of the following settings in the Event Info section:

EDDs facility must match Report's facility – If this setting is checked, then the agent will only run if the EDD was loaded to a facility that equals the facility identified in the report's FACILITY_ID parameter or is a member of the group identified by the report. If the report has no FACILITY_ID parameter, the value may be set in the ST_USER_REPORT.FACILITY_ID database field for the report.

Limit report to only data within the EDD (i.e. new data) – If this setting is checked, the generated report will be limited to the data from the submitted EDD. If it is unchecked, the report will be run according to the report parameter settings. This is performed by passing the EDD's ebatch number to the report's EBATCH parameter. If unchecked, the value -1 is passed to the report. The report must support this feature by interpreting -1 to mean that this parameter should be ignored. When this box is unchecked, the generated report will display all data in the EQuIS database and incoming EDD matching the previously defined criteria.

 

Note: The Limit report to only data within the EDD (i.e. new data) option MUST be selected for "by EDD" reports (e.g., Analytical Results by EDDs) to run as an EIA and return results ONLY from that submitted EDD.

 

Limit agent to EDDs from user – If this setting is checked, the agent will only run for EDDs submitted by the user selected from the drop-down list.

Limit agent to data trigger – Allows definition of a secondary "Trigger Report" to determine if the waiting report, identified on the Data tab, should be run. When an EDD is loaded, the "Trigger Report" is run and limited to only data within the EDD. If the "Trigger Report" returns any results, then a task is created to generate the waiting report. If the "Trigger Report" does NOT return any results, then the waiting report is not run. Since using an existing report as the "Trigger Report" runs the risk of parameters being changed elsewhere, you will need to create a new report to use for this purpose.

To define the "Trigger Report", perform the following steps:

1.Select the type of report from the Define Trigger drop-down list. One option is "Report triggers itself." If this selection is made, no other steps are needed.

2.Click the Add button clip0190 when it appears. This opens a Report Parameter Editor dialog for defining trigger reports.

3.From this dialog, set the report parameters for the "Trigger Report" as desired.

4.Click the Save As button to save the newly defined trigger report. Once a report has been defined and saved, the name of the report will appear in the read-only text box next to the "Limit agent to data trigger:" label.

 

b.Once – Send the report once (and no recurring event or schedule). This option is useful for generating long running reports that would cause the web browser to abort before completion. There is no auto-delete to remove these agents once the report is generated and delivered. Configure a One-Time Schedule agent as follows:

i.Begin schedule on – This is the date the schedule will begin to run. This will default to the current date. The date may be edited using the calendar tool or by entering the date manually in the text box. The calendar tool will open if the text box drop-down is clicked or if the calendar tool icon Calendar_Icon is clicked. Note that when entering the date manually in the text box, the date must be in the same format as the current default date. 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.

Month View

Report_Parameter_Editor_Calendar_example

Year View

Report_Parameter_Editor_Calendar_Year-example

ii.Start time – The time of day the schedule will begin relative to the "Begin Schedule On" date. The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. See the note above for valid hour selection. The minutes text box allows values from 0 to 59. If the minutes text box is left blank, zero minutes on the hour will be assumed.

c.Daily Schedule – Schedule reports on a daily recurrence. Daily recurrences can occur every day or every N days. Daily recurrences schedules may also include a time base recurrence to schedule the report to run multiple times during the day. Daily Schedules are configured as:

i.Repeat every ____ days – Entering a positive integer value will result in a schedule that starts at "Begin schedule on" and repeats every N days.

ii.Scheduled Start and End

Begin Schedule On – The date the schedule will begin. This is a required field.

Stop Schedule On – The date when the recurrence should end. This field must be enabled by check box. When null, the recurrence has no end.

Start Time – The time of day the recurring schedule will begin relative to the "Begin Schedule On" date. The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. See the note above for valid hour selection. If "Repeat during the day" is enabled, the time recurrence is relative to this time.

Repeat every ____ hours and ____ minutes – Schedule the agent to run more than once per day. These fields must be enabled by check box. When enabled, the valid range of values is 0 to 23 hours and 0 to 59 minutes.

End Time – The hour portion of the time field is corrected from UTC and may represent a time either on the previous day or the following day. The end time must be after "Start Time."

 

Note: If both the repeat after every hour and minutes text boxes are left blank, repeat after every one minute is assumed.

 

d.Weekly Schedule – Create a recurring schedule that repeats on a weekly basis. Weekly schedules are configured as:

i.Repeat after every ___ weeks – Define a schedule that runs every N weeks. If left blank, then the value one (1) is assumed.

ii.On the following days – Place a check box on the day(s) of the week for which the agent should run. At least one day must be selected.  The Start Time value is relative to this day. For example, with only Mon checked and a Start Time of "Previous Day at 23:00", the agent will run on Sunday night as 11:00 pm relative to the user's time zone.

iii.Scheduled Start and End – These settings are the same as for "Daily Schedule".

e.Monthly Schedule – Create a recurring schedule that repeats on a monthly basis that occurs every calendar month that is selected. The monthly schedule may also be used for yearly or quarterly recurrence. Monthly schedules are configured as:

i.Months – Select the months that the recurrence may be scheduled. At least one month must be selected.

ii.On Week of Month – Allows a schedule to be setup on a specific week of the month. Note that selecting the "5th" week of a month will not be applicable to every month and the schedule may not run these months.

iii.On the following days – This option is active when the "On Week of Month" option is selected. Place a check box on the day(s) of the week for which the agent should run. At least one day must be selected. The report will run on the days of the week for that week using the scheduled Start and End settings on that day.

iv.On Calendar Day – Schedule the agent to run on the specified date of the month. This option is mutually exclusive with the "On Week of month" option. Note that some calendar days are not applicable to every month (such as February 30 or 31) and the schedule will not run on these days. The option of "Last" is for the last day of the month to address this issue.

 

Scheduling Note: Agents are not guaranteed to run at the exact time they are scheduled. The "Workflow Heartbeat" agent runs every minute (by default) and queues Report Generate tasks when an agent should have run at least once since the last time the schedule was evaluated. The report is not actually run until the "Report Generate" agent processes that entry in the queue. Even under ideal conditions, it could be several minutes before the report is actually run. Also, If EQuIS Enterprise Workflow is down for several days then resumes operation, an agent that may have been scheduled to run several times during the outage will be queued to run only once when the operation resumes.

 

3.Enter the Notice Information that will be used when the EIA sends the notification email:

To – Enter a comma-separated list of email addresses. This field will be pre-populated with the email address of the current user. The email addresses may be other users, but are not required to be. If you enter an email address that does not exist as a user, that user will be created as a Limited User.

Subject – Enter the subject of the notice/email. See Replacement Tags below for additional information.

Attachment – Enter the file name for the attachment and select the desired file type. See Replacement Tags below for additional information.

Message – Enter the body of the notice/email. See Replacement Tags below for additional information.

 

Replacement Tags

Attachment, Subject, and Message may contain replacement tags that will be replaced with the run time values. The following tags are valid for EIA agents.

{Message} - Original message template

{Attachment} - Attachment name

 

{ReportInfo.AssemblyName} - Base Report Assembly Name

{ReportName} - Base Report Display Name

{ReportInfo.DisplayName} - Base Report Display Name

{ReportInfo.Id} - Base Report ID

{ReportInfo.Name} - Base report Name

{ReportInfo.ObjectName} - Base Report Object Name

{ReportInfo.ReportType} - Base Report Report Type

 

{PickReportName} - User Report Name

{UserReportInfo.FacilityId} - User Report Facility ID

{UserReportInfo.Name} - User Report Name

{UserReportInfo.ReportId} - User Report Report ID

{UserReportInfo.UserId} - User Report Owner's User ID

{UserReportInfo.UserReportId} - User Report User Report ID

 

{AgentName} - EQuIS Information Agent Name

{ReportEventInfo.Name} - EQuIS Information Agent Name

{ReportEventInfo.OutputType} - EQuIS Information Agent Output Type

{ReportEventInfo.EventType} - EQuIS Information Agent Event Type

{ReportEventInfo.EventTypeDesc} - EQuIS Information Agent Event Type Desc

{ReportEventInfo.FormatName} - EQuIS Information Agent Format Name

{ReportEventInfo.ReportEventId} - EQuIS Information Agent Report Event ID

{ReportEventInfo.UserId} - EQuIS Information Agent Owner's User ID

{ReportEventInfo.UserReportId} - EQuIS Information Agent User Report ID

{ReportEventInfo.WaitingReportId} - EQuIS Information Agent Waiting Report ID

 

For scheduled and EDD agents, the UserReportId is the ID of the user report run. For Trigger agents, it is the trigger report's UserReportId and WaitingReportId is the ID of the user report run.

 

{FacilityCode} - Facility Code

{FacilityName} - Facility Name

{FacilityCity} - Facility City

{FacilityClient} - Facility Client

{FacilityCountry} - Facility Country

{FacilityCounty} - Facility County

{FacilityPhoneNumber} - Facility Phone Number

{FacilityPostalCode} - Facility Postal Code

{FacilityProjectManager} - Facility Project Manager

{FacilityState} - Facility State

{FacilityAddress} - Facility Address

 

{Connection.Database} - Name of the EQuIS Database

{Connection.Edition} - Edition of the RDBMS Hosting the EQuIS Database

{Connection.Server} - Name of the Server Hosting the EQuIS Database

 

{Parameters} - A ';' delimited list of parameter name and value pairs for all report parameters. Alternatively, individual parameter values may be referenced by name. For example {Parameters.sys_loc_code} will be replaced with the value of the parameter @sys_loc_code. Any substitution tags of the form {Parameters.item} will be removed if that parameter is not found in the report.

 

{DateTime} - Date and time that the report was completed in server's local timezone

{DateTimeUTC} - Date and time that the report was completed in UTC timezone

 

For reports that produce tabular data (e.g., IGridReport), tags may be included that will be replaced with data from the report output table. Even though the report output itself is attached to the email, it may be useful to have the email subject or body include data from the report output. To include data from the report output, use a tag of {DataTable.colum_name}, where column_name (all uppercase or all lowercase, not mixed case) is the name of a column in the report output. If the column_name used in the tag is not a valid column name, the tag will not be replaced (the tag itself will remain in the notice). If the column_name is a valid column name, the tag will be replaced by a comma-separated list of all unique values found in that column. A null value will be represented in the list as "(null)". For example, the following tags may be used as indicated:

 

{DataTable.sys_loc_code} - A list of all unique sys_loc_code values in the report output table

{DataTable.sample_date} - A list of all unique sample_date values in the report output table

{DataTable.matrix_code} - A list of all unique matrix_code values in the report output table