====== Reports ======

{{indexmenu_n>8}}

<wrap #ks1 />

===== Reports =====

The information to be presented within a report is organized into **report elements**. There are different types of elements that perform calculations and display information in very different ways.

**Although they generally have a very similar configuration form, each type of element will be configured separately.** You may have as many type and style items as you need.

<WRAP center round info 90%>

  * **Pandora FMS simplifies monitoring management through user permissions**. There are several permission systems that restrict what users can see or manage. The most important one is the [[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration|groups concept]] (either groups predefined by Pandora FMS and/or custom groups) //combined with the profile of each user//. Pay special attention to the notes about the ''ALL''  group throughout the documentation.
  * In version 771 and later, the "[[#ks7|Enterprise ACL System]]" has specific options enabled for administration and report management with custom user profiles to suit any need.

</WRAP>

<wrap #ks2 />

===== Creating a report =====

Menu <wrap :en>**Operation → Reporting → Custom reports → Create report**</wrap>. A form will be presented, where the name of the report must be indicated, (<wrap :en>**Name**</wrap>) and select the group (<wrap :en>**Group**</wrap>) //the report will belong to,//  and also whether the report is private or not (<wrap :en>**Write access**</wrap>) with its description (optional).

In the <wrap :en>**Write access**</wrap> field you will be able to choose the report editing rights:

  * <wrap :en>**Only the group can edit the report**</wrap>: Only the group the report belongs to will be able to edit it.
  * <wrap :en>**Only the user and the admin user can edit the report**</wrap>: Only the author and an administrator user can edit the report.
  * <wrap :en>**The next group can edit the report**</wrap>: If you choose this option, a list will appear where you may choose another group that can **also**  edit the report.

By default the report will be interactive (checked as **No**  in <wrap :in>**Non-interactive Report**</wrap>). By checking a report as **non-interactive**, the report can only be sent by email. The options to create a cover page (<wrap :en>**Generate cover page in PDF render**</wrap>) and an index (<wrap :en>**Generate index in PDF render**</wrap>) when generating a PDF from the report are also enabled.

Click <wrap :en>**Save**</wrap> to save. Once done you will have an empty report ready to add elements to it [[#ks3_2|by means of the icons arranged]] on the edit form.

//Version 770 or later://  In the <wrap :en>**List of reports**</wrap>, by clicking on the corresponding icon in the HTML column (except if the report is not interactive), you will be able to see the filters and the report itself on the screen. The report can be added (or removed) to your list of favorite reports by clicking on the star icon next to the report name.

{{  :wiki:pfms-menu-operation-favorite-reporting.png  }}

<wrap #ks3 />

===== Report management =====

Menu <wrap :en>**Operation → Reporting → Custom reports → Reports**</wrap>.

{{  :wiki:pfms-operation-reporting-custom_reports-list_of_reports-op.png  }}

In the list of registered reports, for each item, in the **Op.**  column you have the options of:

  * Editing.
  * Copying.
  * Deleting.
  * Selecting for mass deletion with the button <wrap :en>**Delete**</wrap>.

<wrap #ks3_1 />

==== Main data tab ====

It is the only one available when creating a new report, since the basic data of the report is defined here. Once saved properly, you will have access to the rest of the tabs. These fields are the same for both report [[#ks2|creation]] and [[#ks3|editing]].

When finished creating or editing, click <wrap :en>**Update**</wrap> to save the field data.

<wrap #ks3_2 />

==== List Items tab ====

An overview of all items that make up a report is displayed. Use the <wrap :en>**Filters**</wrap> subsection to search among the items recorded in the report; for example displaying the <wrap :en>**Agents**</wrap> list will display //the agents recorded in that selected report//.

<WRAP center round info 90%>

The <wrap :en>**Agent**</wrap> and <wrap :en>**Module**</wrap> columns appear blank //for some item types//  (e.g. <wrap :en>**S.L.A**</wrap> or <wrap :en>**Text**</wrap>): that is completely normal.

</WRAP>

The items in the list will appear following the order in which they will be displayed in the report, this order can be modified in the <wrap :en>**Sort items**</wrap> subsection (or deleted in the <wrap :en>**Delete items**</wrap> subsection, see <wrap :en>**Op.**</wrap> column).

  * <wrap :en>**P.**</wrap>: Position of the elements in the report, //this number is also used to operate the sub-sections//:
      * <wrap :en>**Sort items**</wrap>: An item must be checked first in order to be sorted.
      * <wrap :en>**Delete items**</wrap>: It deletes without the need to check any item, just indicate the position number and whether to delete up or down.
  * Columns <wrap :en>**Type**</wrap>, <wrap :en>**Agent**</wrap> and <wrap :en>**Module**</wrap>: Show each value of each item and clicking on the column header allows sorting (<wrap :en>**Ascendant**</wrap> or <wrap :en>**Descendent**</wrap>) according to it, see <wrap :en>**Sort items**</wrap>.
  * <wrap :en>**Op.**</wrap>: It displays buttons to [[#ks3_3|edit]] or delete each item and, in addition, a checkbox for selecting each item. Clicking the checkbox in the <wrap :in>**Op.**</wrap> header allows you to check or uncheck all items.

<wrap #ks3_3 />

==== Item editor tab ====

Clicking <wrap :en>**Item editor**</wrap> will allow you to create a new item for the selected report.

//The form is dynamic according to the type of item//  (<wrap :en>**Type**</wrap>) //to create//. If you are editing you may modify all fields **except for type**.

<WRAP center round tip 90%>

If you need to change the type, the way to do it is to delete the current one and create it again with the same settings.

</WRAP>

The fields common to all types are:

  * <wrap :en>**Name**</wrap>: Report name. The following macros can be used:
      * ''_agent_'': Name of the Agent you selected in the report item.
      * ''_agentdescription_'': Description of the Agent you selected in the report item.
      * ''_agentgroup_'': Group of the Agent you selected in the report item.
      * ''_address_'': Address of the Agent you selected in the report item.
      * ''_module_'': Name of the Agent Module you selected in the report item.
      * ''_moduledescription_'': Description of the Agent Module you selected in the report element.
  * <wrap :en>**Show item in landscape format (only PDF)**</wrap>: Display the article in landscape format (PDF only).
  * <wrap :en>**Page break at the end of the item (only PDF)**</wrap>: Page break at the end of the article (PDF only).

The fields are filled in according to the type of item selected and to save click <wrap :en>**Create item**</wrap>.

<WRAP center round important 60%>

Saving an item adds a new item //but if the just created item has more configurable options, then the button//  <wrap :en>**Update item**</wrap> will appear.

</WRAP>

<wrap #ks3_3_1 />

=== Types of items ===

There are different [[:en:documentation:pandorafms:technical_annexes:22_pfms_report_types|report types]]:

  * <wrap :en>**Graphs**</wrap>: Reports with multiple types of graphs.
  * <wrap :en>**IPAM**</wrap>: Reports with data taken from the [[:en:documentation:pandorafms:monitoring:11_ipam|IPAM PFMS IPAM feature]].
  * <wrap :en>**SLA**</wrap>: Reports of [[:en:documentation:pandorafms:introduction:03_glossary|Service Level Agreement]].
  * <wrap :en>**Forecasting**</wrap>: Reports with data prediction.
  * <wrap :en>**Modules**</wrap>: They are focused and oriented to present information from modules directly.
  * <wrap :en>**Grouped**</wrap>: It allows to consolidate different sources of information to be presented.
  * <wrap :en>**Text / HTML**</wrap>: To be able to insert headers, subtitles or report footers.
  * <wrap :en>**Alerts**</wrap>: Everything related to [[:en:documentation:pandorafms:management_and_operation:01_alerts|alerts]].
  * <wrap :en>**Events**</wrap>: Everything related to [[:en:documentation:pandorafms:management_and_operation:02_events|events]].
  * <wrap :en>**Inventory**</wrap>: Everything related to [[:en:documentation:pandorafms:management_and_operation:04_inventory|inventory]].
  * <wrap :en>**Configuration**</wrap>: Report with the operating parameters of agents or groups.
  * <wrap :en>**NetFlow**</wrap>: Reports on [[:en:documentation:pandorafms:monitoring:18_netflow|NetFlow and sFlow]].
  * <wrap :en>**Log**</wrap>: It will show the //log//  entries in the selected period.
  * <wrap :en>**Permissions report**</wrap>: It allows you to select users or groups of users and list their names, groups and permissions.
  * <wrap :en>**NCM**</wrap>: It allows to display network changes in the [[:en:documentation:pandorafms:monitoring:16_ncm|NCM PFMS feature]].
  * <wrap :en>**Security hardening**</wrap>: Information aimed at increasing the security of the monitored devices.
  * <wrap :en>**Vulnerabilities**</wrap>: Known security threats of varying degrees of importance.

In addition, in the <wrap :en>**Global**</wrap> tab you may add several [[#ks3_6|additional report types]].

<wrap #ks3_4 />

==== Wizard tab ====

This tab allows you to create a full report automatically and with a few clicks. By applying common configurations, it is possible to generate elements applied to multiple agents and/or modules.

Again this form is dynamic according to the [[#ks3_3_1|report type]] chosen in the **Type**  list:

  * <wrap :en>**Graphs**</wrap>.
  * <wrap :en>**Forecasting**</wrap>.
  * <wrap :en>**Modules**</wrap>.
  * <wrap :en>**Grouped**</wrap>.
  * <wrap :en>**Alerts**</wrap>.
  * <wrap :en>**Events**</wrap>.

<WRAP center round info 60%>

Once the type of report, the period, the agents and, if necessary, the modules have been selected, by clicking on the <wrap :en>**Add**</wrap> button //as many items will be generated in the report as agents and/or modules have been selected//.

</WRAP>

<wrap #ks3_5 />

==== SLA-Wizard tab ====

This wizard allows you to specifically create SLA report items automatically.

  * <wrap :en>**SLA**</wrap>: It will display a standard SLA report item, indicating the percentage of compliance for the selected period. Additional options are also available for monthly, weekly and hourly periods.
  * <wrap :en>**Availability graph**</wrap>: A graph will be generated with the availability data of the selected modules.
  * <wrap :en>**SLA services**</wrap>: A new report element representing the SLA calculation of the selected services will be created.

You will be able to choose the value //validity//  ranges of the modules to be selected. This feature will allow you to check the time percentage a module maintained values within specific ranges.

If no thresholds are defined, they will be dynamically adjusted to the criticality thresholds of each module.

<WRAP center round info 60%>

**Even if the person creating the report item does not explicitly**  belong to the group ([[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration#ks1_2_2|ALL]]), you may still assign the <wrap :en>**ALL**</wrap> group as a filter of Agents from which to choose Modules.

</WRAP>

<wrap #ks3_6 />

==== Global Tab ====

In this report section you may create type elements:

  * <wrap :en>**Exception**</wrap>: It displays values from several modules that satisfy a logical operation (field <wrap :en>**Condition**</wrap>).
  * <wrap :en>**General**</wrap>: It displays values from mutiple modules sorted (ascending or descending, by agent name) and/or grouped by name.
  * <wrap :en>**Top N**</wrap>: It displays N values discriminated by maximum, minimum or average over the total number of modules added, sorted in ascending or descending order or by agent name.

That way you may add different modules from different agents, in addition to being able to choose the operation to be performed in each module: summation, average, minimum, maximum.

<WRAP center round info 60%>

**Even if the person creating the report item does not explicitly**  belong to the group ([[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration#ks1_2_2|ALL]]), you may still assign the **ALL**  group as a filter of Agents from which to choose Modules.

</WRAP>

Once the parameters have been chosen and the <wrap :en>**Add**</wrap> button is clicked, a report item containing the selected agents and modules will be created.

<wrap #ks3_7 />

==== Advanced options Tab ====

<wrap #ks3_7_1 />

=== Custom logo ===

By default ''pandora_log.jpg''  will be used. You may select from the drop-down list any of the possible logos to decorate the header of each PDF page. This list is built from the image files contained in the directory:
<file>

/var/www/html/pandora_console/images/custom_logo/

</file>

You may add the image files to this directory. They must have the correct permissions so that the user with which the web service is provided has access to these files, by default ''apache:apache''.

<wrap #ks3_7_2 />

=== Macros ===

To reuse editing templates, you may use the following macros in rich text fields:

  * **(_DATETIME_)**: It will be replaced by the date of the moment the report is generated, in the date format configured in Pandora FMS Console general options.
  * **(_REPORT_NAME_)**: It will be replaced by the name of the report.
<wrap #ks3_8 />

==== View report tab ====

This tab displays the report in HTML format, and it is the same as the **HTML view**  option included in the [[#ks3|list of registered reports]].

<wrap #ks4 />

===== Viewing a report =====

Menu <wrap :en>**Operation → Reporting → Custom reports**</wrap> → icon <wrap :en>**List of reports**</wrap>.

Reports can be displayed in HTML, XML, PDF, JSON or CSV format by clicking on the corresponding icons for each column and report item.

To send them by e-mail, click on the corresponding icon in the **E-mail**  column and a pop-up form will open where the recipient(s) and optionally a subject field and a message field will be displayed.

<WRAP center round tip 60%>

If you need to send the same report to several recipients, separate the addresses by commas.

</WRAP>

<wrap #ks4_1 />

==== Exporting and importing reports ====

See section for [[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration#resources_exportimport|importing and exporting in PRD format]].

<wrap #ks5 />

===== Automatic report scheduling =====

To //**create**//  scheduled reports use the <wrap :en>**Operation → Reporting → Custom reports → Custom reports → Schedule**</wrap> menu with the <wrap :en>**Send custom report by e-mail**</wrap> option from the drop-down list in <wrap :en>**Task**</wrap>. The interface is the same for creating or editing a scheduled report (except for the <wrap :en>**Create report**</wrap> or <wrap :en>**Update schedule**</wrap> button to save an edit).

Automatic report scheduling is also included in the [[:en:documentation:pandorafms:monitoring:17_discovery_2#console_tasks|Console tasks]].

<WRAP center round info>

To find out if scheduled report forwarding is enabled, check their status by means of the <wrap :en>**Console tasks**</wrap>.

</WRAP>

Some common fields:

  - <wrap :en>**Scheduled**</wrap>: Periodicity of the task: daily, monthly, etc. or once only (<wrap :en>**Not scheduled**</wrap>, see next item).
  - <wrap :en>**Next execution**</wrap>: Next execution of the task, select date in the first field and time in the second field (pop-up menu when clicking on each).
  - <wrap :en>**Report pending to be created**</wrap>: From the registered reports, select the one to be sent.
  - <wrap :en>**Report Type**</wrap>: Type of report to be sent (XML, etc.). If you select <wrap :en>**Send custom report (from template) by email**</wrap> in the <wrap :en>**Task**</wrap> list, additionally configure:

  * <wrap :en>**Template pending to be created**</wrap>: [[#k6|Custom template]] for report creation.
  * <wrap :en>**Agents**</wrap>: Agents to include in the report, use <wrap :en>**Regex agent filter**</wrap> to select agents by means of regular expressions.
  * <wrap :en>**Report per agent**</wrap>: Information of the Agents selected in <wrap :en>**Agents**</wrap> for the report, if you wish to generate separate reports for each report.

<WRAP center round important 60%>

For e-mail forwarding to work, the following must be done [[:en:documentation:pandorafms:management_and_operation:12_console_setup#ks1_1_3|previously configured in Pandora FMS forwarding options]].

</WRAP>

If <wrap :en>**Save to disk in path**</wrap> is selected, the path to be saved in the report and, optionally, a prefix for the file names must be specified.

<wrap #ks6 />

===== Report templates =====

Report templates are components that allow **parameterizing**  the creation of reports that can later be applied on a set of agents.

<WRAP center round box 90%>

Each element of the templates will search for a match with an agent and/or module by means of a regular expression or a substring, making this system very flexible.

</WRAP>

When creating a **report template**, a number of elements are defined. These defined elements are the same //report items//  that are defined for a report.

<WRAP center round info 90%>

The difference is that each of these **template items**  will generate one or more **report items**, // provided that when **applying**  the template//  there is a match with any of the chosen agents and/or modules.

</WRAP>

<wrap #ks6_1 />

==== Create template ====

Menu <wrap :en>**Operation → Reporting → Custom Reports**</wrap> and click on the icon <wrap :en>**List of templates**</wrap> in the upper right corner, right next to the <wrap :en>**List of reports**</wrap> icon. Then click <wrap :en>**Create template**</wrap>:

  * <wrap :en>**Group**</wrap>: Group the new staff will belong to.
  * <wrap :en>**Agents to apply**</wrap>: A regular expression, case insensitive, to filter the agents to which the new template will be applied. For example, if you use ''Network*'', the agents named ''network_agent1''  or ''NetworK CHECK''  will match when the template is applied.
  * <wrap :en>**Generate cover page in PDF render**</wrap>: To generate a PDF cover page.
  * <wrap :en>**Generate index in PDF render**</wrap>: To generate an index in the //rendering//  or PDF generation.

To save the template when you finish filling in the fields, click <wrap :en>**Save**</wrap>.

<wrap #ks6_1_1 />

=== Item editor ===

By clicking the icon <wrap :en>**item editor**</wrap> new items may be created within the screen.

The item types are the same ones as those of reports, except that when applyed to an agent or module, this one will be chosen as a regular expression. For example, ''oracle_agent.*'' it may correspond the agents: ''oracle_agent_1'', ''oracle_agent_2'', ''oracle_agent_producción'', etc.

In case of leaving the field empty, the template item may be applied on all agents when [[#ks6_3|applying the report template]].

When a module is specified, this one may be literally interpreted by enabling the verification checkbox <wrap :en>**Module exact match**</wrap>. If not activated, it will use the matching standard method by regular expression.

<wrap #ks6_1_2 />

=== List of items ===

Menu <wrap :en>**Operation → Reporting → Custom reports**</wrap> → icon <wrap :en>**List of templates**</wrap> → button <wrap :en>**Edit**</wrap> template → icon <wrap :en>**List items**</wrap>.

{{  :wiki:pfms-operation-reporting-custom_reports-list_of_templates-edit-list_items.png  }}

In the item list section you may see and edit the items created within the template and modify their order as well as delete them.

<wrap #ks6_1_3 />

=== Advanced template options ===

Menu <wrap :en>**Operation → Reporting → Custom reports**</wrap> → icon <wrap :en>**List of templates**</wrap> → button <wrap :en>**Edit**</wrap> template → icon <wrap :en>**Advanced options**</wrap>.

In this section you may configure visual aspects of the resulting report such as font, logo, header, first page or report footer, [[#ks3_7|as you would do with a standard report]].

Once you have finished editing the visual aspects, click <wrap :in>**Update**</wrap> to save the changes.

<wrap #ks6_2 />

==== Template management ====

Menu <wrap :en>**Operation → Reporting → Custom Reports**</wrap> and click on the <wrap :en>**List of templates**</wrap> icon.

  * From there you will be able to delete a report template through its corresponding trash can icon in the <wrap :en>**Operations**</wrap> column. You may also select multiple templates and then click the <wrap :en>**Delete**</wrap> button.
  * Similarly by clicking on the <wrap :en>**Duplicate**</wrap> button of each template you may copy with prefix <wrap :en>**copy of**</wrap> plus the template name to a new template.
  * By clicking on the pencil icon corresponding to each item you may edit the selected template.

<wrap #ks6_3 />

==== Direct application of a report template ====

Menu <wrap :en>**Operation → Reporting → Custom reports**</wrap> → icon <wrap :en>**List of templates**</wrap>. Then in each template there are buttons for each display: HTML, JSON, and so on. Clicking on one of them will open the form <wrap :en>**Generate a dynamic report**</wrap> which will only bring the consultation written in <wrap :en>**Agents to apply**</wrap> [[#ks6_1|when the template was created]].

  * In <wrap :en>**Filter group**</wrap> and <wrap :en>**Filter agent**</wrap>, dynamically, it will be possible to filter from the list initially presented in <wrap :en>**Agents available**</wrap>.
  * Click on one or more of the available agents (or select all in <wrap :en>**Select all**</wrap>) and click the right arrow button to add to the <wrap :en>**Agents to apply**</wrap> list.
  * Conversely you may uncheck agents, use all the fields and buttons until you get the required list of agents.
  * Click <wrap :en>**Generate**</wrap>.

<wrap #ks6_4 />

==== Template Wizard ====

You may make use of the template wizard (<wrap :en>**Template Wizard**</wrap>) if you need to //instantiate//  a report template in a real report to have it available in Pandora FMS report list:

The <wrap :en>**Create report per agent**</wrap> check box can be activated to generate a report for each selected agent. If it is not checked, a general report with all information will be generated.

  * In case a report is generated per agent, the title of the report will follow this format:
      * [title of the template] - [agent name] ([agent name])
  * In case a total report is generated, the title will follow this format:
      * [report title] - agents ([number of agents]) - [date].

<wrap #ks6_5 />

==== Report cleaning ====

The [[#ks6_4|Report template wizard]] is used to delete reports created in previous applications from a template.

There select a template from the <wrap :en>**Templates**</wrap> drop-down list and then click on the delete button (broom icon).

{{  :wiki:template_wizard_cleanup.png  }}

This action will delete all reports created based on this template, automatically.

<wrap #ks7 />

===== Enterprise ACL system focused on reporting =====

<WRAP center round info 90%>

Version 771 or later.

</WRAP>

By means of the "[[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration#ks1_5|Enterprise ACL System]]" it is possible to create custom profiles with which you may assign viewing, modification, creation and deletion permissions for reports.

To do this, go to the ACL Enterprise System settings (<wrap :en>**Management → Profiles → Enterprise ACL setup**</wrap>), select the profile the permissions are to be assigned to from the drop-down list at <wrap :en>**User profile**</wrap>.

Select <wrap :en>**Reporting**</wrap> in <wrap :en>**Section**</wrap> and then add in <wrap :en>**Section 2**</wrap> the necessary permissions:

  * <wrap :en>**New custom reports**</wrap>: It allows you to create reports to the selected user profile.
  * <wrap :en>**Edit custom reports**</wrap>: It allows you to edit reports to the selected user profile.
  * <wrap :en>**Remove custom reports**</wrap>: It allows you to delete reports to the selected user profile.

{{  :wiki:pfms-acl_enterprise-reports_and_profiles-01.png  }}

[[:en:documentation:start|Go back to Pandora FMS documentation index]]