Version:

Version:

Version:

Version:

Version:


Table of Contents

User Guide

Reports in FortiSOAR

You should use FortiSOAR Reports for your reporting purposes since you can easily create rich reports and dashboards in FortiSOAR. You can also schedule reports, view historical reports and also search for text in the report PDF, which is in the text PDF format.

You can design your report to include a date or date range as an input parameter to a report; i.e. define a date range, date, or filter criterion in the template for reports. Similarly, users of the report can also specify a date range and filter data in the report whose template have the date or filter parameter defined. For information on how you can define and use dates or date ranges to filter data in the reports, see the Dashboards, Templates, and Widgets chapter. You can also specify the timezone in which you want to export your reports.

Dashboards and reports have good performance since only the required content is loaded and lazy loading of the content is enabled.

Click Reports in the FortiSOAR left navigation to display the Reporting page, which the following tabs:

  • Library: Centralized repository of all reports. The Library page displays a list of reports and its associated schedules. To see the details of schedules associated with a report, you can click the down arrow in the reports row. You can also view the generated reports from this page and also see the roles that have been assigned to a particular report. You can create new reports, edit and manage reports, and search for reports on this page. You can also import a valid JSON report template on this page.
  • Schedules: Lists all the created schedules on this page. You can click View Details in a schedule row to view the detail schedule record page. Using the schedule detail record page, you can view the logs of the playbooks (by clicking the View Executed Playbooks) that were executed using this schedule, and also perform actions such as stopping, updating, or starting the schedule using this page. You can also search for schedules by schedule name, and filter schedules by status and report on this page.
  • History: Lists all created (historical) reports on this page. You can search for report using its historical name and filter reports and schedules by various criteria. You can also download a pdf version of the historical report from this page.

Reports page

Pagination is enabled on all pages within Reporting, i.e., on the Library, Schedules, and History pages for better navigation and also on the item rows within the report rows, for example, the schedule entries within a report row.

Permissions required for working with reports

Note

Only when an administrator modifies reports, those modifications are applicable across the system and applicable to users, based on their roles.

  • To view reports, you must be assigned a role that has Read permissions on the Application and Reporting modules, and the report must be assigned to your role.

  • To create and edit reports, you must be assigned a role that has Read, Create, and Update permissions on the Reporting module and Read permission on the Application module. Additionally, if you also want to delete reports and configurations, you must be assigned a role that has Read, Create, Update, and Delete permissions on the Reporting module and Read permissions on the Application module.

  • To customize only your own reports, i.e., the changes made in the reports would not be visible to any other user, a role with Read, Update and Create permission on the Reporting module and Read permission on the Application module is sufficient. If such a user (a non-admin user) changes the dashboard, then a copy of the original dashboard is created and those changes are visible to only that particular user and not to other users.

  • To customize reports, i.e., the changes made in the reports would be visible to all users who have access to that report, a role that has Read and Update permissions on the Reporting module and Read permissions on the Application and Security modules must be assigned. If you have these permissions, then the changes are made in the original dashboard and these changes are visible to all the users who have access to the dashboard.

  • To create a schedule, you must be assigned a role that has Read, Create, and Update permissions on the Schedules and Read and Create permissions on the Playbooks module. To delete schedules, you must be assigned a role with Delete permissions on the Schedules module.

  • To view saved reports, you must be assigned a role that has Read, Create, and Update permissions on the Saved Reports module. To delete saved reports, you must be assigned a role with Delete permissions on the Saved Reports module.

  • To export your reports as a PDF file, you must be assigned a role that has Read permissions on the Application and Reporting modules, Create, Read, and Update permissions on the Saved Reports modules, Read and Execute permissions on the Playbooks module, and Create and Read permissions on the Files module.

In addition to the appropriate permissions mentioned above, users also require to have appropriate rights on the module for which they want to create or edit reports. Since if users do not have Module Read permissions on the module that they want to consume in the report, then they will not be able to view the details of that module in the report. For example, if you have Module Read permissions on the Alerts module but not on the Incidents module, then you can update reports that consume Alerts as their data source. However, if you try to update a report that consumes Incidents as the data source, FortiSOAR displays a message such as You do not have necessary permissions for Incidents.

Working with reports

To create a new report, click Reports in the FortiSOAR left navigation, which displays the Library tab on the Reporting page, and click the + Create New Report button.

The Library tab contains a list of reports that have been created. You can search for reports by report name using the Search box and refresh the Library page using the Refresh icon. You can also edit existing reports and perform other operations from this page.

To view the details of the schedules associated with a report, click the down arrow in the report row whose associated schedules you want to view or modify, and then click on the schedule row. This will display the Schedule Details dialog, using which you can view or modify the schedule. One report can have multiple schedules, but one schedule can only be associated with a single report.

Importing a report template:

Use the export and import template feature to share reports across users. If you see a report that a colleague has created that you feel would be useful to you as well, then instead of you having to recreate the report, your colleague can export the report, and you can import it and start using the same.

Note

You can only import a valid JSON template. The template that you import is only applicable to your report. Administrators must import, update, and assign reports for the changes to apply to all users.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click Import Report.
  3. In the Import Report Template dialog box, drag-and-drop the JSON template file, or click to browse to the JSON template file.
  4. Click Import.
    If the file is in the appropriate JSON format, FortiSOAR displays Template Imported successfully!

Based on the permissions that are set for you, you can perform the following operations on the Library page:

Adding or Editing Reports on the Library page

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. To create a new report, click the + Create New Report button on the Library page. To edit an existing report, click the Actions (Action icon on Reports Page)icon, in the row of the report that you want to edit, and click Edit Template.
    Templates are JSON definitions of the interface structure composed of widgets. Widgets are configurable interface elements that are used to represent data, such as charts or lists visually. For more information on Templates and Widgets, see the Dashboards, Templates, and Widgets chapter.
    From version 6.4.4 onward, reports are enhanced to support page breaks, by providing a Page Break option on the Edit Template page. To insert page breaks for reports (rows in report), you can choose from the following options:
    • Not Specified: In this case, page breaks are not added, i.e., this option allows page breaks within rows.
    • Avoid Page Breaks: In this case, page breaks are avoided, i.e., if a page break occurs within a row in a report, then the row automatically gets printed on a new page.
    • Print On New Page: In this case, page breaks are added between rows, i.e., each row of a report is printed on a new page.
    Editing the Report Template - Page Break option
    Note: If you have changed a report that an administrator has assigned to you, then you will not be able to view the administrator changes to that report. To reset the administrator changes to the report, click Actions > Reset to Original State, i.e., the changes that the administrator made will be visible and your changes will be lost.
  3. In the Template Title field, enter the template title.
  4. Click Add Row and structure the row by defining the number and layout of columns from the options displayed in Define a new structure.
  5. Click Add Widget and from the Choose Widget dialog box, select the appropriate widget.
    For more information on Templates and Widgets, see the Dashboards, Templates, and Widgets chapter.
  6. Click Edit Widget to configure or reconfigure the widget properties and click Save.
    Note: The Only Me | All filter is not applicable to Reports, i.e., on the Reports page, you cannot toggle the view based on this filter, instead, you must change this in the report template itself when you are adding or editing a widget. For more information on Widgets, see the Dashboards, Templates, and Widgets chapter.
  7. Click Apply Changes.
    To revert the changes, you have made to the template, click Revert Changes.
Tooltip

To add a report heading, you can use the Richtext Content widget. You can also add fields (choose fields) from modules that you want to display in the Richtext Content widget making it simpler and efficient for you to add fields in the Richtext format. For more information on the Richtext Content widget, see the Dashboards, Templates, and Widgets chapter.

To clone a report template:

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to edit, and click Clone Template.
  3. Update the template title.
    By default, the template title appears as cloned: name of the original template.
  4. Update the template and widgets as required.
  5. Click Apply Changes.

To export a report template:

Note

Report templates get exported as a JSON template.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to edit, and click Export Template.
    FortiSOAR downloads the template on your machine in the JSON format.

To remove a report template:

Note

You can only remove reports that you have added. You cannot remove reports created by an administrator or by any other user.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to remove, and click Remove Template.
  3. On the Confirm dialog, select Confirm.

To assign roles to reports

Note

You must have a minimum of Read permission on the "Security" module, apart from other appropriate privileges to perform this task.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report to which you want to assign a role, and click Assign to Role.
    This displays the Assign to Role (s) dialog in which you can select the role(s) to which you want to assign the report.
  3. In the Assign to Role(s) dialog box, select the role to which you want to assign the report.
    Assign to Role dialog
  4. Click OK.
    Users having the role specified will be able to see the report(s) associated with that role the next time they log on to FortiSOAR.

Performing operations on the Report Page

To view the generated report

To view the generated report, on the Library page, click View in the row of the report that you want to view. This displays the Report Page. You can also perform the Assign to Role (if you have administrative privileges), Edit Report, New Report, Clone Report, Export Report, in the JSON format, and Remove Report operations by clicking the Actions (Actions Icon) icon on the Report Page. In addition to these operations, you can export a report as a pdf.

To go back to the Library page, click Back to Library.

To export a report as a PDF

On the Report Page, you can download the report in a .pdf format by clicking the Export As PDF button. The report is exported in text PDF format, which enables you to search text in the report PDF and also reduces the file size of your report as compared to an image PDF.

Note

The PDF report that you export might not exactly match with the report view that you see on the FortiSOAR UI. This happens if the data that is used to create the report gets updated from the time you have viewed the report till the time the report is exported.

By default, reports are exported in the light theme. This report gets downloaded on your machine. This report also gets saved and is available in the History page (Reports > History).

Tooltip

You can export a FortiSOAR report that contains more than one page in the PDF format, i.e., the exported report PDF can consist of multiple pages. However, note that report pages are split into multiple pages based on the height of the report. Therefore, you must arrange your widgets, especially widgets in the Chart category, in the report in such a way that widgets are not placed between two pages, else the data of that widget will get split into two parts.

If you have manually exported the report, i.e, by clicking the Export As PDF button on the Reports page, then the report is generated by default in the timezone that is set by your administrator. If the administrator has not set any timezone, then the report is generated in the timezone of the user's browser. Administrators can define a timezone that will be used by default for exporting reports. This timezone will be applied by default to all reports that you export from the Reports page. For more information, see the System Configuration chapter in the "Administration Guide."

If your administrator has set the default timezone in which to export reports, then that timezone is displayed when you click the Export As PDF option. The default timezone set will be displayed in the Timezones dialog:

Timezones Dialog

Either retain the default timezone or change the timezone using the Timezone drop-down list, and then click the Export Report By Selected Timezone button in the Timezones dialog. For our example we have retained the default timezone. Therefore, the report will be exported in the default timezone (America/Los_Angeles), which is visible on the exported report as shown in the following image, if you have added timezone as part of the report. For more information see Displaying of timezone within exported reports.

Exported report displaying default Timezone

If you want to export the report in the timezone other than the default timezone, then in the Timezones dialog that appears when you click the Export As PDF option, choose the required timezone. In the Timezones dialog, you can search and select the timezone in which you want to export the report. For our example the default timezone is set as America/Los_Angeles and if for example, you want to export the report in the Asia/Kolkata timezone, then type kol in the search box below the Timezone field to find the correct timezone, as shown in the following image:

Timezones dialog for exporting reports

Now, click the Export Report By Selected Timezone button. This will export the report and you will be able to see this timezone (Asia/Calcutta) on the exported report as shown in the following image, if you have added timezone as part of the report. For more information see Displaying of timezone within exported reports.

Exported report displaying selected Timezone

Input Variables in Dashboards and Reports

You can define variables that you can use in widgets as filters to consume inputs and create a dashboard or a report dynamically. Using input variables, you can filter data in a dashboard or report to display a particular set of data without having to define the same criteria in each widget in the dashboard or report. Once you configure the variable as a filter in widgets, the dashboard or report is displayed according to the filter value you have specified. You can also specify inputs for dashboards or reports, based on which dashboard or reports are updated dynamically to display the dashboard or report according to the updated input values.

For more information and examples of input variables, see the Dashboards, Templates, and Widgets chapter.

From version 6.4.0 onwards, the user experience of working with reports that need input to load has been improved. If a report, for example, Incident Summary Report was configured such that no default incident ID was specified and required the user to provide the incident ID before the report could be displayed, then earlier FortiSOAR would display messages such Widget not configured properly. Now, FortiSOAR displays a message such as Please provide required input to load the report and prompts you to enter the Incident ID in the Configure Reports Inputs dialog, as shown in the following image:

Reporting page that requires inputs from users

Displaying of timezone within exported reports

If you want to display the timezone in which the report (.pdf) has been exported, do the following steps in the template of the report in which you want to display the timezone:

  1. On the Reports page, in the report row in which you want to display the timezone, click the Actions icon, and then select Edit Template.
    Generally, you will find that the heading of the report is displayed using the Richtext Content widget.
  2. In the Richtext Content widget row, click the Edit icon.
  3. In the Richtext Content widget, click the Add Dynamic Fields link.
    For more information on templates and widgets, see the Dashboards, Templates, and Widgets chapter.
  4. From the Field Type drop-down list, select Utility Fields.
  5. From the Field drop-down list, select Timezone, and click Add Field.
    This will paste the jinja value of the Timezone field, i.e., {{timezone}} in the Richtext Content widget on the location where your cursor is placed as shown in the following image:
    Richtext Content widget: Adding Timezone
  6. Click Save to save the updates to the reports template.

If your report has been scheduled using the timezone as Asia/Kolkata, then you will be able to see this timezone (Asia/Calcutta) on the exported report as shown in the following image:

Exported report displaying the timezone

Scheduling Reports

You can schedule reports to run automatically at specific times and also automatically send reports to the relevant users. For example, you can schedule a report that contains Critical Open Alerts to be sent out to, for example, managers in a SOC team, at 8 am in the morning on Mondays.

Tooltip

You can create multiple schedules for a single report.

When you click Reports in the left navigation, the Reporting page with the Library tab selected is displayed.

On the Library page, you can see the list of reports and its associated schedules. You can also add new schedules to a report or modify existing schedules on this page.

Note

To schedule a report you must be assigned with the appropriate role associated with that report, and also appropriate permissions on the Schedules and Saved Reports modules.

To add a new schedule, do the following:

  1. On the Library page, in the report row for which you want to add a new schedule, click the Actions icon, and then select Schedule Report.
  2. In the Schedule Details dialog, configure the following parameters
    1. In case of a report that takes input variables, you must specify the required inputs in the Report Inputs section.
      For example, if a report requires the incident id as an input parameter, then you must enter the Incident ID in the Report Inputs section.
      Schedule Dialog
    2. In the Schedule Name field, enter the name of the schedule.
    3. If you want to start the schedule immediately after creating the schedule, click the Start Schedule checkbox.
    4. In the Cron Expression section, add a valid cron expression to schedule the report.
      Cron expression is a string consisting of up to five subexpressions (fields) that describe individual details of the schedule.
      In the Cron Expression section, you can click the Hourly, Daily, Weekly, Monthly or Yearly links in the By row to schedule your report and define the schedule for your report. For example, to schedule a report to run weekly at 9:00 am in the morning every Monday, click the Weekly link and in the hour box type 9, in the minute box type 0, and in the day of the week type 1 (0-Sunday, 1-Monday, 2-Tuesday...6-Saturday) as shown in the above image. A short description of the schedule also appears below the cron expression box, in our example, it appears as At 9:00 AM, only on Monday, which means the report will run every Monday at 9 am as shown in the above image.
      Note: The schedule runs as per the timezone selected in the Timezone drop-down list.
    5. From the Timezone drop-down list, search for and select the timezone in which you want to export the report. For example, if you want to search for the timezone of London, you can type lon in the search box below the Timezone field to find the correct timezone.
      Reports: Schedule Details dialog - Search Timezone
      The time that is displayed in the generated reports, i.e., reports that are present in the History tab, will be based on the timezone you have selected.
      If you do not select any timezone, then by default, the timezone is set as UTC.
    6. If you want to ensure that you do not rerun the workflow, if previous scheduled instance of the report is yet running, then click Limit execution to one active instance at a time.
    7. (Optional) In the Start Time field, you can specify the date and time from when the schedule will start running.
    8. (Optional) In the End Time field, you can specify the date and time after which the schedule will not run, i.e., the date and time to stop the schedule.
      Note: Once a schedule reaches the specified end time, then the schedule displays Yes in the Expired column on the schedules listing page. It is recommended that you should make the expired schedules "Inactive".
    9. In the Email Address field, enter a semicolon-separated list of email IDs to whom you want to send this scheduled report.
      Note: Ensure you provide valid email addresses.
    10. Click Save to save this schedule.
      You can also choose to immediately run and display the report, i.e., run the report schedule immediately (outside of its scheduled time) by clicking the Run Schedule Now button.
      The schedule is saved in the Inactive state if you have not selected the Start Schedule checkbox. In our example we have not selected this checkbox.
      Schedule  in the Inactive state

To start your newly created schedule, click the Start Schedule button in the schedule row:
Start Schedule

To perform other actions, on the Library page, do the following:

  • To view schedules associated with reports and the details of the schedule, click the down arrow in the report row whose associated schedules you want to view as shown in the following image:
    Schedules associated with reports
    The schedule details include information such as, the name of the schedule, the schedule timezone, the timing of the schedule, the last run of the schedule, and the total run count of the schedule. You can also stop a running schedule using the Stop Schedule button; similarly, you can also start a stopped schedule using the Start Schedule button. If you want to immediately view a report (outside of its scheduled time), click the Trigger Schedule Now icon, which immediately triggers the schedule associated with the report.
    Note: When you stop a schedule the value, i.e., datetime of the Last Run At field becomes blank.
  • To modify a schedule, click the down arrow in the report row whose associated schedules you want to modify, and then click on the schedules row. This will display the Schedule Details dialog, using which you modify an existing schedule.

Click the Schedules tab, to do the following:

  • View a list of all the schedules associated with reports, i.e., all schedules that have been created for reports are visible on this tab.
  • Search for schedules by schedule name.
  • Filter schedules by Status and Report name. Filtering by Report name will display the schedule associated with the report. One report can have multiple schedules, but one schedule can only be associated with a single report.
  • Refresh the Schedules page using the Refresh icon.
  • Perform the following actions in a particular schedule row: Stop a running schedule using the Stop button in the schedule row; similarly, you can also start a stopped schedule using the Start button. Update a schedule, by clicking the Edit icon. Clicking the Edit button, displays the Schedule Details dialog, using which you can update the schedule. Delete a schedule by clicking the Delete icon. To run a schedule immediately (outside of its scheduled time), click the Trigger Schedule Now button.
    Reporting - Scheduling Tab
  • View brief details of the reports associated with the schedule by clicking the down arrow in the row of the schedule whose report details you want to view.
    The report details include information such as, name of the playbook that ran for the schedule, a link to the PDF version of the report, the name of the report, the date on which the schedule was created, and the name of the user who created the schedule. Clicking the report link in the File column downloads the PDF version of the historical report associated with the schedule.

Historical Reports

Click the History tab to view a list and details of all created (historical) reports on this page, as shown in the following image:

Historical Reports

The historical report details include the name of the playbook that ran for the schedule, a link to the PDF version of the report, the report name, a link to the Schedule Details dialog using which you can update the schedule of the report, the datetime when the historical report was created, and the name of the user who created the report. Clicking the report link in the File column downloads the PDF version of the historical report.

You can refresh the History page using the Refresh icon. To delete a historical report click the Delete icon in the row of the historical report you want to delete.

You can search for historical reports by the report's historical name and also filter reports and schedules on this page based on the following criterion:

  • By Report Name: Enter the name of the saved report that you want search.
  • By Report: Select the name of the report from this drop-down list to filter reports.
  • By Schedule: Select the name of the schedule from this drop-down list to filter reports.
  • Created On: Select the relative date range within which you want to search for created reports, for example, all reports created in the Last 30 Mins.
  • Created By: Select the user from this drop-down list to filter reports based on the user who has created the reports.

Reports in FortiSOAR

You should use FortiSOAR Reports for your reporting purposes since you can easily create rich reports and dashboards in FortiSOAR. You can also schedule reports, view historical reports and also search for text in the report PDF, which is in the text PDF format.

You can design your report to include a date or date range as an input parameter to a report; i.e. define a date range, date, or filter criterion in the template for reports. Similarly, users of the report can also specify a date range and filter data in the report whose template have the date or filter parameter defined. For information on how you can define and use dates or date ranges to filter data in the reports, see the Dashboards, Templates, and Widgets chapter. You can also specify the timezone in which you want to export your reports.

Dashboards and reports have good performance since only the required content is loaded and lazy loading of the content is enabled.

Click Reports in the FortiSOAR left navigation to display the Reporting page, which the following tabs:

  • Library: Centralized repository of all reports. The Library page displays a list of reports and its associated schedules. To see the details of schedules associated with a report, you can click the down arrow in the reports row. You can also view the generated reports from this page and also see the roles that have been assigned to a particular report. You can create new reports, edit and manage reports, and search for reports on this page. You can also import a valid JSON report template on this page.
  • Schedules: Lists all the created schedules on this page. You can click View Details in a schedule row to view the detail schedule record page. Using the schedule detail record page, you can view the logs of the playbooks (by clicking the View Executed Playbooks) that were executed using this schedule, and also perform actions such as stopping, updating, or starting the schedule using this page. You can also search for schedules by schedule name, and filter schedules by status and report on this page.
  • History: Lists all created (historical) reports on this page. You can search for report using its historical name and filter reports and schedules by various criteria. You can also download a pdf version of the historical report from this page.

Reports page

Pagination is enabled on all pages within Reporting, i.e., on the Library, Schedules, and History pages for better navigation and also on the item rows within the report rows, for example, the schedule entries within a report row.

Permissions required for working with reports

Note

Only when an administrator modifies reports, those modifications are applicable across the system and applicable to users, based on their roles.

  • To view reports, you must be assigned a role that has Read permissions on the Application and Reporting modules, and the report must be assigned to your role.

  • To create and edit reports, you must be assigned a role that has Read, Create, and Update permissions on the Reporting module and Read permission on the Application module. Additionally, if you also want to delete reports and configurations, you must be assigned a role that has Read, Create, Update, and Delete permissions on the Reporting module and Read permissions on the Application module.

  • To customize only your own reports, i.e., the changes made in the reports would not be visible to any other user, a role with Read, Update and Create permission on the Reporting module and Read permission on the Application module is sufficient. If such a user (a non-admin user) changes the dashboard, then a copy of the original dashboard is created and those changes are visible to only that particular user and not to other users.

  • To customize reports, i.e., the changes made in the reports would be visible to all users who have access to that report, a role that has Read and Update permissions on the Reporting module and Read permissions on the Application and Security modules must be assigned. If you have these permissions, then the changes are made in the original dashboard and these changes are visible to all the users who have access to the dashboard.

  • To create a schedule, you must be assigned a role that has Read, Create, and Update permissions on the Schedules and Read and Create permissions on the Playbooks module. To delete schedules, you must be assigned a role with Delete permissions on the Schedules module.

  • To view saved reports, you must be assigned a role that has Read, Create, and Update permissions on the Saved Reports module. To delete saved reports, you must be assigned a role with Delete permissions on the Saved Reports module.

  • To export your reports as a PDF file, you must be assigned a role that has Read permissions on the Application and Reporting modules, Create, Read, and Update permissions on the Saved Reports modules, Read and Execute permissions on the Playbooks module, and Create and Read permissions on the Files module.

In addition to the appropriate permissions mentioned above, users also require to have appropriate rights on the module for which they want to create or edit reports. Since if users do not have Module Read permissions on the module that they want to consume in the report, then they will not be able to view the details of that module in the report. For example, if you have Module Read permissions on the Alerts module but not on the Incidents module, then you can update reports that consume Alerts as their data source. However, if you try to update a report that consumes Incidents as the data source, FortiSOAR displays a message such as You do not have necessary permissions for Incidents.

Working with reports

To create a new report, click Reports in the FortiSOAR left navigation, which displays the Library tab on the Reporting page, and click the + Create New Report button.

The Library tab contains a list of reports that have been created. You can search for reports by report name using the Search box and refresh the Library page using the Refresh icon. You can also edit existing reports and perform other operations from this page.

To view the details of the schedules associated with a report, click the down arrow in the report row whose associated schedules you want to view or modify, and then click on the schedule row. This will display the Schedule Details dialog, using which you can view or modify the schedule. One report can have multiple schedules, but one schedule can only be associated with a single report.

Importing a report template:

Use the export and import template feature to share reports across users. If you see a report that a colleague has created that you feel would be useful to you as well, then instead of you having to recreate the report, your colleague can export the report, and you can import it and start using the same.

Note

You can only import a valid JSON template. The template that you import is only applicable to your report. Administrators must import, update, and assign reports for the changes to apply to all users.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click Import Report.
  3. In the Import Report Template dialog box, drag-and-drop the JSON template file, or click to browse to the JSON template file.
  4. Click Import.
    If the file is in the appropriate JSON format, FortiSOAR displays Template Imported successfully!

Based on the permissions that are set for you, you can perform the following operations on the Library page:

Adding or Editing Reports on the Library page

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. To create a new report, click the + Create New Report button on the Library page. To edit an existing report, click the Actions (Action icon on Reports Page)icon, in the row of the report that you want to edit, and click Edit Template.
    Templates are JSON definitions of the interface structure composed of widgets. Widgets are configurable interface elements that are used to represent data, such as charts or lists visually. For more information on Templates and Widgets, see the Dashboards, Templates, and Widgets chapter.
    From version 6.4.4 onward, reports are enhanced to support page breaks, by providing a Page Break option on the Edit Template page. To insert page breaks for reports (rows in report), you can choose from the following options:
    • Not Specified: In this case, page breaks are not added, i.e., this option allows page breaks within rows.
    • Avoid Page Breaks: In this case, page breaks are avoided, i.e., if a page break occurs within a row in a report, then the row automatically gets printed on a new page.
    • Print On New Page: In this case, page breaks are added between rows, i.e., each row of a report is printed on a new page.
    Editing the Report Template - Page Break option
    Note: If you have changed a report that an administrator has assigned to you, then you will not be able to view the administrator changes to that report. To reset the administrator changes to the report, click Actions > Reset to Original State, i.e., the changes that the administrator made will be visible and your changes will be lost.
  3. In the Template Title field, enter the template title.
  4. Click Add Row and structure the row by defining the number and layout of columns from the options displayed in Define a new structure.
  5. Click Add Widget and from the Choose Widget dialog box, select the appropriate widget.
    For more information on Templates and Widgets, see the Dashboards, Templates, and Widgets chapter.
  6. Click Edit Widget to configure or reconfigure the widget properties and click Save.
    Note: The Only Me | All filter is not applicable to Reports, i.e., on the Reports page, you cannot toggle the view based on this filter, instead, you must change this in the report template itself when you are adding or editing a widget. For more information on Widgets, see the Dashboards, Templates, and Widgets chapter.
  7. Click Apply Changes.
    To revert the changes, you have made to the template, click Revert Changes.
Tooltip

To add a report heading, you can use the Richtext Content widget. You can also add fields (choose fields) from modules that you want to display in the Richtext Content widget making it simpler and efficient for you to add fields in the Richtext format. For more information on the Richtext Content widget, see the Dashboards, Templates, and Widgets chapter.

To clone a report template:

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to edit, and click Clone Template.
  3. Update the template title.
    By default, the template title appears as cloned: name of the original template.
  4. Update the template and widgets as required.
  5. Click Apply Changes.

To export a report template:

Note

Report templates get exported as a JSON template.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to edit, and click Export Template.
    FortiSOAR downloads the template on your machine in the JSON format.

To remove a report template:

Note

You can only remove reports that you have added. You cannot remove reports created by an administrator or by any other user.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report that you want to remove, and click Remove Template.
  3. On the Confirm dialog, select Confirm.

To assign roles to reports

Note

You must have a minimum of Read permission on the "Security" module, apart from other appropriate privileges to perform this task.

  1. Log on to FortiSOAR and click Reports in the left navigation.
  2. On the Library page, click the Actions icon, in the row of the report to which you want to assign a role, and click Assign to Role.
    This displays the Assign to Role (s) dialog in which you can select the role(s) to which you want to assign the report.
  3. In the Assign to Role(s) dialog box, select the role to which you want to assign the report.
    Assign to Role dialog
  4. Click OK.
    Users having the role specified will be able to see the report(s) associated with that role the next time they log on to FortiSOAR.

Performing operations on the Report Page

To view the generated report

To view the generated report, on the Library page, click View in the row of the report that you want to view. This displays the Report Page. You can also perform the Assign to Role (if you have administrative privileges), Edit Report, New Report, Clone Report, Export Report, in the JSON format, and Remove Report operations by clicking the Actions (Actions Icon) icon on the Report Page. In addition to these operations, you can export a report as a pdf.

To go back to the Library page, click Back to Library.

To export a report as a PDF

On the Report Page, you can download the report in a .pdf format by clicking the Export As PDF button. The report is exported in text PDF format, which enables you to search text in the report PDF and also reduces the file size of your report as compared to an image PDF.

Note

The PDF report that you export might not exactly match with the report view that you see on the FortiSOAR UI. This happens if the data that is used to create the report gets updated from the time you have viewed the report till the time the report is exported.

By default, reports are exported in the light theme. This report gets downloaded on your machine. This report also gets saved and is available in the History page (Reports > History).

Tooltip

You can export a FortiSOAR report that contains more than one page in the PDF format, i.e., the exported report PDF can consist of multiple pages. However, note that report pages are split into multiple pages based on the height of the report. Therefore, you must arrange your widgets, especially widgets in the Chart category, in the report in such a way that widgets are not placed between two pages, else the data of that widget will get split into two parts.

If you have manually exported the report, i.e, by clicking the Export As PDF button on the Reports page, then the report is generated by default in the timezone that is set by your administrator. If the administrator has not set any timezone, then the report is generated in the timezone of the user's browser. Administrators can define a timezone that will be used by default for exporting reports. This timezone will be applied by default to all reports that you export from the Reports page. For more information, see the System Configuration chapter in the "Administration Guide."

If your administrator has set the default timezone in which to export reports, then that timezone is displayed when you click the Export As PDF option. The default timezone set will be displayed in the Timezones dialog:

Timezones Dialog

Either retain the default timezone or change the timezone using the Timezone drop-down list, and then click the Export Report By Selected Timezone button in the Timezones dialog. For our example we have retained the default timezone. Therefore, the report will be exported in the default timezone (America/Los_Angeles), which is visible on the exported report as shown in the following image, if you have added timezone as part of the report. For more information see Displaying of timezone within exported reports.

Exported report displaying default Timezone

If you want to export the report in the timezone other than the default timezone, then in the Timezones dialog that appears when you click the Export As PDF option, choose the required timezone. In the Timezones dialog, you can search and select the timezone in which you want to export the report. For our example the default timezone is set as America/Los_Angeles and if for example, you want to export the report in the Asia/Kolkata timezone, then type kol in the search box below the Timezone field to find the correct timezone, as shown in the following image:

Timezones dialog for exporting reports

Now, click the Export Report By Selected Timezone button. This will export the report and you will be able to see this timezone (Asia/Calcutta) on the exported report as shown in the following image, if you have added timezone as part of the report. For more information see Displaying of timezone within exported reports.

Exported report displaying selected Timezone

Input Variables in Dashboards and Reports

You can define variables that you can use in widgets as filters to consume inputs and create a dashboard or a report dynamically. Using input variables, you can filter data in a dashboard or report to display a particular set of data without having to define the same criteria in each widget in the dashboard or report. Once you configure the variable as a filter in widgets, the dashboard or report is displayed according to the filter value you have specified. You can also specify inputs for dashboards or reports, based on which dashboard or reports are updated dynamically to display the dashboard or report according to the updated input values.

For more information and examples of input variables, see the Dashboards, Templates, and Widgets chapter.

From version 6.4.0 onwards, the user experience of working with reports that need input to load has been improved. If a report, for example, Incident Summary Report was configured such that no default incident ID was specified and required the user to provide the incident ID before the report could be displayed, then earlier FortiSOAR would display messages such Widget not configured properly. Now, FortiSOAR displays a message such as Please provide required input to load the report and prompts you to enter the Incident ID in the Configure Reports Inputs dialog, as shown in the following image:

Reporting page that requires inputs from users

Displaying of timezone within exported reports

If you want to display the timezone in which the report (.pdf) has been exported, do the following steps in the template of the report in which you want to display the timezone:

  1. On the Reports page, in the report row in which you want to display the timezone, click the Actions icon, and then select Edit Template.
    Generally, you will find that the heading of the report is displayed using the Richtext Content widget.
  2. In the Richtext Content widget row, click the Edit icon.
  3. In the Richtext Content widget, click the Add Dynamic Fields link.
    For more information on templates and widgets, see the Dashboards, Templates, and Widgets chapter.
  4. From the Field Type drop-down list, select Utility Fields.
  5. From the Field drop-down list, select Timezone, and click Add Field.
    This will paste the jinja value of the Timezone field, i.e., {{timezone}} in the Richtext Content widget on the location where your cursor is placed as shown in the following image:
    Richtext Content widget: Adding Timezone
  6. Click Save to save the updates to the reports template.

If your report has been scheduled using the timezone as Asia/Kolkata, then you will be able to see this timezone (Asia/Calcutta) on the exported report as shown in the following image:

Exported report displaying the timezone

Scheduling Reports

You can schedule reports to run automatically at specific times and also automatically send reports to the relevant users. For example, you can schedule a report that contains Critical Open Alerts to be sent out to, for example, managers in a SOC team, at 8 am in the morning on Mondays.

Tooltip

You can create multiple schedules for a single report.

When you click Reports in the left navigation, the Reporting page with the Library tab selected is displayed.

On the Library page, you can see the list of reports and its associated schedules. You can also add new schedules to a report or modify existing schedules on this page.

Note

To schedule a report you must be assigned with the appropriate role associated with that report, and also appropriate permissions on the Schedules and Saved Reports modules.

To add a new schedule, do the following:

  1. On the Library page, in the report row for which you want to add a new schedule, click the Actions icon, and then select Schedule Report.
  2. In the Schedule Details dialog, configure the following parameters
    1. In case of a report that takes input variables, you must specify the required inputs in the Report Inputs section.
      For example, if a report requires the incident id as an input parameter, then you must enter the Incident ID in the Report Inputs section.
      Schedule Dialog
    2. In the Schedule Name field, enter the name of the schedule.
    3. If you want to start the schedule immediately after creating the schedule, click the Start Schedule checkbox.
    4. In the Cron Expression section, add a valid cron expression to schedule the report.
      Cron expression is a string consisting of up to five subexpressions (fields) that describe individual details of the schedule.
      In the Cron Expression section, you can click the Hourly, Daily, Weekly, Monthly or Yearly links in the By row to schedule your report and define the schedule for your report. For example, to schedule a report to run weekly at 9:00 am in the morning every Monday, click the Weekly link and in the hour box type 9, in the minute box type 0, and in the day of the week type 1 (0-Sunday, 1-Monday, 2-Tuesday...6-Saturday) as shown in the above image. A short description of the schedule also appears below the cron expression box, in our example, it appears as At 9:00 AM, only on Monday, which means the report will run every Monday at 9 am as shown in the above image.
      Note: The schedule runs as per the timezone selected in the Timezone drop-down list.
    5. From the Timezone drop-down list, search for and select the timezone in which you want to export the report. For example, if you want to search for the timezone of London, you can type lon in the search box below the Timezone field to find the correct timezone.
      Reports: Schedule Details dialog - Search Timezone
      The time that is displayed in the generated reports, i.e., reports that are present in the History tab, will be based on the timezone you have selected.
      If you do not select any timezone, then by default, the timezone is set as UTC.
    6. If you want to ensure that you do not rerun the workflow, if previous scheduled instance of the report is yet running, then click Limit execution to one active instance at a time.
    7. (Optional) In the Start Time field, you can specify the date and time from when the schedule will start running.
    8. (Optional) In the End Time field, you can specify the date and time after which the schedule will not run, i.e., the date and time to stop the schedule.
      Note: Once a schedule reaches the specified end time, then the schedule displays Yes in the Expired column on the schedules listing page. It is recommended that you should make the expired schedules "Inactive".
    9. In the Email Address field, enter a semicolon-separated list of email IDs to whom you want to send this scheduled report.
      Note: Ensure you provide valid email addresses.
    10. Click Save to save this schedule.
      You can also choose to immediately run and display the report, i.e., run the report schedule immediately (outside of its scheduled time) by clicking the Run Schedule Now button.
      The schedule is saved in the Inactive state if you have not selected the Start Schedule checkbox. In our example we have not selected this checkbox.
      Schedule  in the Inactive state

To start your newly created schedule, click the Start Schedule button in the schedule row:
Start Schedule

To perform other actions, on the Library page, do the following:

  • To view schedules associated with reports and the details of the schedule, click the down arrow in the report row whose associated schedules you want to view as shown in the following image:
    Schedules associated with reports
    The schedule details include information such as, the name of the schedule, the schedule timezone, the timing of the schedule, the last run of the schedule, and the total run count of the schedule. You can also stop a running schedule using the Stop Schedule button; similarly, you can also start a stopped schedule using the Start Schedule button. If you want to immediately view a report (outside of its scheduled time), click the Trigger Schedule Now icon, which immediately triggers the schedule associated with the report.
    Note: When you stop a schedule the value, i.e., datetime of the Last Run At field becomes blank.
  • To modify a schedule, click the down arrow in the report row whose associated schedules you want to modify, and then click on the schedules row. This will display the Schedule Details dialog, using which you modify an existing schedule.

Click the Schedules tab, to do the following:

  • View a list of all the schedules associated with reports, i.e., all schedules that have been created for reports are visible on this tab.
  • Search for schedules by schedule name.
  • Filter schedules by Status and Report name. Filtering by Report name will display the schedule associated with the report. One report can have multiple schedules, but one schedule can only be associated with a single report.
  • Refresh the Schedules page using the Refresh icon.
  • Perform the following actions in a particular schedule row: Stop a running schedule using the Stop button in the schedule row; similarly, you can also start a stopped schedule using the Start button. Update a schedule, by clicking the Edit icon. Clicking the Edit button, displays the Schedule Details dialog, using which you can update the schedule. Delete a schedule by clicking the Delete icon. To run a schedule immediately (outside of its scheduled time), click the Trigger Schedule Now button.
    Reporting - Scheduling Tab
  • View brief details of the reports associated with the schedule by clicking the down arrow in the row of the schedule whose report details you want to view.
    The report details include information such as, name of the playbook that ran for the schedule, a link to the PDF version of the report, the name of the report, the date on which the schedule was created, and the name of the user who created the schedule. Clicking the report link in the File column downloads the PDF version of the historical report associated with the schedule.

Historical Reports

Click the History tab to view a list and details of all created (historical) reports on this page, as shown in the following image:

Historical Reports

The historical report details include the name of the playbook that ran for the schedule, a link to the PDF version of the report, the report name, a link to the Schedule Details dialog using which you can update the schedule of the report, the datetime when the historical report was created, and the name of the user who created the report. Clicking the report link in the File column downloads the PDF version of the historical report.

You can refresh the History page using the Refresh icon. To delete a historical report click the Delete icon in the row of the historical report you want to delete.

You can search for historical reports by the report's historical name and also filter reports and schedules on this page based on the following criterion:

  • By Report Name: Enter the name of the saved report that you want search.
  • By Report: Select the name of the report from this drop-down list to filter reports.
  • By Schedule: Select the name of the schedule from this drop-down list to filter reports.
  • Created On: Select the relative date range within which you want to search for created reports, for example, all reports created in the Last 30 Mins.
  • Created By: Select the user from this drop-down list to filter reports based on the user who has created the reports.