Using Reporting
Reporting can be broken down into two types of reports: graphical and tabular. Graphical reports leverage dashboards 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 dashboard and export this information to a PDF, CSV, HTML, XLS, or XLSX document.
This document describes how to generate both types of graphical reports.
Dependencies
-
coreReport-ui and coreReport-app must be installed.
-
The presentation server must have fontconfig installed (Refer to the FAQ).
-
A dashboard 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 the Profiles UI.
Configuration -> Reports -> Profiles
After you click Add, 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 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: Indicates the file type of the report.
-
For a graphical report, select either PNG or PDF. Oracle strongly recommends enabling Autosize Report for these report formats.
-
For a tabular report, select Data Export.
-
Graphical Specific Fields
This section briefly describes the Report Profile fields specific to graphical reports.
Note:
When first setting up a report, Oracle recommends selecting the Autosize Report option rather than manually configuring the other parameters.
-
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 dashboard. For example, if a dashboard was created with the intention of being viewed on a monitor with dimensions 2048 x 1536, then this value should be set to 2048.
-
Height: The height (in pixels) of the virtual web browser used to render the dashboard. For example, if a dashboard was created with the intention of being viewed on a monitor with dimensions 2048 x 1536, then this value should be set to 1536.
-
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, that is, 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, that is, 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.
-
Dashboard: A list of all the dashboards available on the system, accessible in the navigation pane at: Configuration -> Dashboards -> Dashboards. 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 dashboard will serve as the foundation for the data presented in the report.
-
Dashboard Parameters: Some dashboards accepts additional parameters, which serve as a means to augment the data presented in the dashboard.
- For example, the Device Overview dashboard is provided by default and can be used to show information about devices in the device catalog. To view the information associated to a specific device, a URL parameter of DeviceName=XX.z# would need to be added to this field.
Note:
Dashboard parameters for the default, out-of-the-box dashboards can be seen when a dashboard is opened in a new browser tab as the portion of the URL that follows the '?'. It is unnecessary to specify parameter values DashboardID and DashboardTypeID since these are automatically determined based on the chosen value for the Dashboard 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: Dashboards may optionally contain a footer (basic or enhanced). The values for this field include: None, Basic, and Enhanced.
-
Render Timeout: Since dashboards are generated dynamically each time the browser accesses the dashboard page, it is necessary to wait for the browser to generate all the nodes (SVG and DOM elements) contained within the dashboard. This field represents the time (in seconds) that the virtual browser will wait before rendering the document as a report.
-
-
Status: Indicates whether 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.
-
User: Specifies the user login that should be used by the ReportRunner when accessing the selected dashboard. That is, the generated report will appear, for all intents and purposes, exactly as the chosen dashboard 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.
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 a 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 dashboards
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 dashboard 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):
dnf install fontconfig urw-fonts