Reporting
Reporting can be broken down into two types of reports: graphical and tabular. Graphical reports leverage portals and export the visualizations and data to either a PDF document or a PNG image. Tabular reports extract the data from the first grid within the selected portal and export this information to a PDF, CSV, HTML, XLS, or XLSX document.
This section of the product guide will walk you through how to generate both types of graphical reports as well as an example of a tabular report.
Dependencies
-
coreReport-ui and coreReport-app must be installed.
-
The presentation server must have fontconfig installed (Refer to the FAQ).
-
A portal with the desired data must be setup.
-
For automated report generation the Report Runner scheduled job must be enabled.
Setting Up Reports
If the dependencies are satisfied, then setting up a new report consists of the following two steps:
-
Create a new Report Profile.
-
Create a new Report.
Creating a Report Profile
Before generating either a graphical or tabular report, a Report Profile must be created. Navigate to Profiles.
Configuration -> Reports -> Profiles
After you click the Add button, the following fields will be presented to you.
Common Fields
This section describes the Report Profile fields common to both graphical and tabular reports.
-
Name - The profile name. This is used as a reference when selecting a Report Profile for a Report.
-
Notification Profile - This field contains a list of the notification profiles, as defined in the Profiles UI. For most purposes, the Generic Email or [NONE] options will suffice.
-
Notification Template - This field contains a list of the notification templates, as defined in the Templates UI. For most purposes, the Unified Assurance Report - Attachment, Unified Assurance Report - Inline, Unified Assurance - Link, or [NONE] options will suffice. As the template names suggest, these templates will format a notification which includes the report as an attachment, inline image, and download link (respectively).
-
Archive - Indicates whether or not the report should be retained in Unified Assurance's file repository. If checked, archived files will be saved with a file type of Report.
-
Days to Retain - This field is only activated if Archive is checked. If left empty or set to 0, the file is archived indefinitely. Otherwise, the File Reaper scheduled job (if enabled) will remove the file from the repository after the indicated number of days to retain it have expired.
Report Format - Report Format indicates the file type of the report. A graphical report may be generated by selecting either PNG or PDF. Additional details are provided within the PNG and PDF sections of this guide.
Graphical Specific Fields
This section briefly describes the Report Profile fields specific to graphical reports.
-
Autosize Report - Graphical reports are generated by means of a virtual web browser which leverages the WebKit browser engine. As a result of this design choice, Unified Assurance reports allow for customization of the browser's window size. Although, in general, it is preferable to allow the ReportRunner application to choose the window size. Leave this box checked to defer the size of the report to the ReportRunner.
-
Width - The width (in pixels) of the virtual web browser used to render the portal. For example, if a portal was created with the intention of being viewed on a monitor with dimensions 2048 x 1536, then this value should be set to 2048.
- Note: it is recommended when first setting up a report to select the autosize option, rather than manual configuration.
-
Height - The height (in pixels) of the virtual web browser used to render the portal. For example, if a portal was created with the intention of being viewed on a monitor with dimensions 2048 x 1536, then this value should be set to 1536.
- Note: it is recommended when first setting up a report to select the autosize option, rather than manual configuration.
-
Zoom - The scaling factor for the page prior to rendering the graphical report. This field accepts positive decimal values. The conventions are similar to the zooming behavior of a PDF document.
-
A value between 0 and 1 indicates that the virtual browser should zoom out, i.e., decrease the resolution. For example, 0.5 indicates that the browser should generate the report with a resolution 50% of the original view.
-
A value greater than 1 indicates that the virtual browser should zoom in, i.e., increase the resolution. For example, 2.0 indicates that the browser should generate the report with a resolution 200% of the original view.
-
Setting this value to 1 indicates that the virtual browser should render this image without alteration to the resolution.
-
-
Orientation - When rendering a graphical report as a PDF document, an orientation must be selected. The choices are Landscape or Portrait.
-
Page Size - When rendering a graphical report as a PDF document, a page size must be selected. The choices are Letter, A4, or Manual.
-
Manual Page Size - If the Manual option is selected for a graphical PDF report, then a manual page size must be specified. For example, to create a PDF with page size dimensions of 11 inches by 8.5 inches, enter 11in*8.5in. As another example, to create a PDF with page size dimensions of 10 centimeters by 20 centimeters, enter 10cm*20cm.
Tabular Specific Fields
This section briefly describes the Report Profile fields specific to tabular reports.
-
Data Format - Indicates the desired file type for a generated report. The options are: Excel 2007+ (*.xlsx), Excel 97-2003 (*.xls), CSV, Hypertext (*.html), PDF.
-
Orientation - When rendering a tabular report as a PDF document, an orientation must be selected. The choices are Landscape or Portrait.
Creating a Report
After creating a Report Profile, we may create a Report. Navigate to the Reports UI.
Configuration -> Reports -> Reports
After you click Add, the following form will be presented to you.
-
Report Fields - This section briefly describes the Report fields common to both graphical and tabular reports.
-
Name - The report name. This will be used as the basis for the file name of the report, with suffixes for a date and time (optional) and the file extension.
-
Append Date Time - If checked and the selected Report Profile is configured to archive reports, then a new report will be saved to the Unified Assurance file repository each time one is generated from this template. The file name of the report will include a date and time suffix of the form "YYYY-MM-DD_HH-mm-ss" (YYYY = 4 digit year, MM = 2 digit month, DD = 2 digit day, HH = 2 digit hour [0-23], mm = 2 digit minute, ss = 2 digit second).
- Note: if left unchecked, new reports will overwrite previously generated instances of the report (with the same name) in the file repository.
-
Profile - The list of Report Profiles, accessible in the navigation pane in the Profiles UI.
-
Portal - A list of all of the portals available on the system, accessible in the navigation pane at: Configuration -> Portals -> Portals. This field, for all intents and purposes, is the report. Regardless of whether a graphical or tabular report is desired, the data presented in the selected portal will serve as the foundation for the data presented in the report.
-
Portal Parameters - Some portals accepts additional parameters, which serve as a means to augment the data presented in the portal.
-
For example, the Device Portal by default will list all discovered/manually added devices. However, to view statistics associated to a specific device with ID of XX, a URL parameter of DeviceID=XX may be added to this field.
-
Note: portal parameters are easily visible while viewing a portal as the portion of the URL that follows the '?'. However, it is unnecessary to specify parameter values PortalID and PortalTypeID, since these are automatically determined based on the chosen value for the Portal field.
-
-
Email Recipients - A comma separated list of emails to which the ReportRunner should send notifications upon generation of a report.
-
Note: the content of the email will be determined by the Notification Template selected for the chosen Report Profile.
-
Footer - Portals may optionally contain a footer (basic or enhanced). The values for this field include: None, Basic, and Enhanced.
-
Render Timeout - Since portals are generated dynamically each time the browser accesses the portal page, it is necessary to wait for the browser to generate all of the nodes (SVG and DOM elements) contained within the portal. This field represents the time (in seconds) that the virtual browser will wait before rendering the document as a report.
-
-
Status - Indicates whether or not the report should be generated at its scheduled time by the Report Runner job.
-
User Group - This field is intended to help filter the list of users in the User field (described next).
-
User - Specifies the user login that should be used by the ReportRunner when accessing the selected portal. That is, the generated report will appear, for all intents and purposes, exactly as the chosen portal appears when the given user views it.
-
User Owner - Archived reports are stored in the Unified Assurance file repository, accessible in the navigation pane in the Files UI. The selected value for User Owner will be the value entered for the archived report in the File User Owner field.
Configuration -> Files -> Files
- Note: selecting a value other than [Public to All Users In Group] will hide the Group Owner field and make the generated report viewable to the selected user only.
-
Group Owner - Archived reports are stored in the Unified Assurance file repository, accessible in the navigation pane in the Files UI. The selected value for Group Owner will be the value entered for the archived report in the File Group Owner field.
Configuration -> Files -> Files
- Note: the selected value for this field is considered only if the User Owner field has [Public to All Users In Group] selected.
-
Viewers - Archived reports are stored in the Unified Assurance file repository, accessible in the navigation pane in the Files UI. The selected values for Viewers will be the values entered for the archived report in the Viewers field (under Files).
-
Presets - By default, the Report Runner scheduled job will wake up every minute and process all reports which are scheduled to run at that time. The Schedule field set indicates exactly what times a given report should be generated. This is a helper field to populate the cron style report scheduling. Predefined values include:
-
Every day at midnight
-
Weekdays at noon
-
Friday at 5 p.m.
-
Sunday at 2 a.m.
-
End of each month
-
-
Minutes - The cron style minute schedule. Indicates the minutes of the specified Hour, Day, and Month at which this report should be generated.
-
Hours - The cron style hour schedule. Indicates the hours of the specified Day and Month at which this report should be generated.
-
Days - The cron style day schedule. Indicates the days of the specified Month at which this report should be generated.
-
Months - The cron style month schedule. Indicates the months at which this report should be generated.
-
WeekDays - The cron style day of week schedule. Indicates the days of the week (Sunday to Saturday) at which this report should be generated.
Creating a Report Directly from Portals
For added convenience, reports may be created directly from the portal configuration UI, provided a Report Profile has already been created. To access via the navigation pane, go to Configuration -> Portals -> Portals.
Now, select a portal for which a report should be generated. Once the portal has loaded, go to the wrench icon located to the right side of the browser window and select the Save Report option, as indicated in the first image below.
Next, a form identical to the one detailed in the previous section will be presented. Fill out the form, shown in the second image below, and submit it. Descriptions of the fields are provided in the previous section.
Examples
This section provides a handful of examples to elucidate how to generate a report in the most common scenarios.
Graphical
Graphical reports leverage the versatility of Unified Assurance portals by capturing the images and data of the portal and storing the information in either a PNG or PDF file. Reports may optionally be archived and/or emailed to a list of recipients.
-
PNG - Here is an example of a fully populated Report Profile form for a graphical PNG report:
-
NOTE: We strongly recommend using the autosize feature in almost all graphical reporting scenarios.
-
Here is an example of a fully populated Report form for a graphical PNG report, utilizing the above profile:
-
NOTE: the scheduled time indicates that the report will run Saturday mornings at 00:05 (12:05am).
-
-
PDF - Here is an example of a fully populated Report Profile form for a graphical PDF report:
-
NOTE: We strongly recommend using the autosize feature in almost all graphical reporting scenarios.
-
Here is an example of a fully populated Report form for a graphical PDF report, utilizing the above profile:
-
NOTE: the scheduled time indicates that the report will run Saturday mornings at 00:05 (12:05am).
-
Tabular
Tabular reports export the data held in the first grid of a portal to CSV, PDF, HTML, or Excel (xls or xlsx).
-
XLS - Here is an example of a fully populated Report Profile form for a tabular XLS report:
-
Here is an example of a fully populated Report form for a tabular XLS report, utilizing the above profile:
-
NOTE: the scheduled time indicates that the report will run Saturday mornings at 00:05 (12:05am).
-
-
PDF - Here is an example of a fully populated Report Profile form for a tabular PDF report:
-
Here is an example of a fully populated Report form for a tabular PDF report, utilizing the above profile:
-
NOTE: the scheduled time indicates that the report will run Saturday mornings at 00:05 (12:05am).
-
FAQs
This section answers the most commonly asked questions regarding reporting.
How do I manually generate a report?
-
In the navigation pane, go to the Reports UI.
-
Select the report you wish to run. Notice that the Start button above the grid has become enabled.
-
Click Start. A progress bar will monitor the state of the report and indicate once it has completed.
-
If archiving is enabled, then the report will be available for download via the Unified Assurance file repository in the Files UI. Additionally, the report will be sent out as configured in the Notification Template (specified via Report Profiles).
My report has an grid with multiple pages of rows. How do I get my report to paginate through them?
A report can only display a single grid of results, so in order to display all rows in the grid, the number of rows displayed must be customized to display everything in one page. The report will automatically add additional pages based on the result set.
I want my report to have X number of rows. How do I change the rows displayed in a page?
Add or modify the report user's MaxPageSize (requires logout and login). The value can now be selected when creating report portals
Why does my report have Loading instead of data?
The reporting engine RenderTimeout was reached before it finished rendering. Modify the report profile RenderTimeout field to allow the virtual browser additional time to render the data. In some cases, a render timeout of 60 seconds (or higher) may be necessary to properly generate the report depending on the data set.
My report portal loads fine, but my report shows an error instead of data.
The API request timed out before it finished retrieving data, this is especially common if the report contains a large data set or large pagesize configured. Modify the report user's or report user group's UILoadTimeout preference (requires logout and login) to allow the API time to retrieve the data. In some cases, a render timeout of 60 seconds (or higher) may be necessary to properly generate the report depending on the data set size.
Why do I see blocks instead of text in my report?
This is due to a missing library. See FAQ "How do I install fontconfig and urw-fonts?".
How do I install fontconfig and urw-fonts?
-
Log into the presentation server(s) via a command line utility (PuTTY, SSH, etc.).
-
Run the following command (as root):
yum install fontconfig urw-fonts