Reporting APIs

Reporting APIs allow users to generate application reports. Instead of first exporting generated data, such as traffic flows, and then using other tools to create reports, users can now use built-in reports.

Users can request one-time or recurring reports, specify time ranges, as well as report types.

Reporting APIs belong to several groups based on their use:

Reporting API Types

Reporting Schedules

These APIs provide a way for the Global Organization Administrator (this_global_org_user) to manage report schedules.

Each report can be generated once or recurring, where the recurrence is specified at the time of report configuration.

The default time-range is 30 days, and other possible values are: 1 day, 7 days, 14 days, 30 days, 60 days, and 90 days.

Functionality	HTTP	URI
Returns a collection of report schedules.	`GET`	`[api_version][org_href]/report_schedule`
Returns a scheduled report for the provided UUID.	`GET`	`[api_version][org_href]/report_schedule/:report_schedule_id`
Updates a report schedule for the provided UUID.	`PUT`	`[api_version][org_href]/report_schedule/:report_schedule_id`
Create a new report schedule.	`POST`	`[api_version][org_href]/report_schedule`
Deletes a report schedule for the provided UUID.	`GET`	`[api_version][org_href]/report_schedule/:report_schedule_id`

Parameters for Reporting Schedules

Parameter	Description	Parameter Type	Format
`org_id`	Organization	path	Integer
`scheduled_at`	Timestamp in UTC for report generation	Sring	date/time
`send_by_email`	Flag for whether to send user report by email	Boolean	True/false
`report_generation_frequency`	(POST) How often to generate a report: in addition to daily, `weekly`, `monthly`, and `quarterly` reports, you can schedule to receive the report only `once`.	String
`report_time_range`	Define `start_date` and `end_date` for the report	String	date/time

Defining Report Schedule Query

To define the query for report schedules, reference the required schemas (explained in Schemas to Define a Report).

executive_summary_report_params.schema.json

```
traffic_flow_report_params.schema.json
```
```
report_app_groups.schema.json
```
```
custom_date_range.schema.json
```

Report Templates

These API's provide a way for the Global Organization Administrator (this_global_org_user) to manage report templates. In each report-template, they can specify type, time-range, recurrence and suitable parameters for the report type.

Functionality	HTTP	URI
Lists the collection of all available report templates for this user and organization.	`GET`	`[api_version][org_href]/report_templates`
This API is used to enable/disable a specific report type, which can be done only by the organization administrator.	`PUT`	`[api_version][org_href]/report_templates`

Defining Report Templates Query

To define the query for report templates, reference the required schemas (explained in Schemas to Define a Report).

On-Demand Reports

The user authorized as the Global Organization Administrator (this_global_org_user) can download various kinds of reports, as well as create them on-demand or add the property report_format to determine the format in which the report will be generated.

Functionality	HTTP	URI
Returns a collection of reports.	`GET`	`[api_version][org_href]/reports`
Returns a report for the provided UUID.	`GET`	`[api_version][org_href]/reports/:report_id`
Downloads a specific report.	`GET`	`[api_version][org_href]/reports/:report_id/download`
Creates a new on-demand report.	`POST`	`[api_version][org_href]/reports`
Cancels a report if it's not yet completed/failed	`PUT`	`[api_version][org_href]/reports/:report_id`
Added a new property `report_format` which determines the format in which the report should be generated	`POST`	`[api_version][org_href]/reports_schedules`
Added a new property `report_format` which determines the format in which the report should be generated	`PUT`	`[api_version][org_href]/reports_schedules`

Report Settings

Report Settings define for how many days a report will be stored or persisted.

The user authorized as the Global Organization Administrator (this_global_org_user) can manage the report settings, list them or update.

Functionality	HTTP	URI
Get the report settings for an organization	`GET`	`[api_version][org_href]/report_settings`
Updates the report settings for an org	`PUT`	`[api_version][org_href]/report_settings`

Schemas to Define a Report

These schemas are referenced and used to define the content of a report:

```
executive_summary_report_params.schema.json
```
Reports parameters for the executive summary report, such as report_time_range (Time range the report is built across) and references to report_time_range_definitions.schema.json#/definitions/custom_date_range or report_time_range_definitions.schema.json#/definitions/last_num_days.

```
traffic_flow_report_params.schema.json
```
Reports parameters for traffic flow query report.

```
report_app_groups.schema.json
```
This is the App Group Schema for reports.

```
custom_date_range.schema.json
```
Provides the time range the report is built across.

```
common legacy_workload_modes.schema.json
```
Provides the assigned labels summary with the label URI, as well as the key and value in the key-value pair.

```
report_time_range_definitions.schema.json
```
Provides the report parameters for the executive summary report, such as Start date for the range, End date for the range, and Last x number of days the report is built across.

```
labels_summary.schema.json
```
Provides the assigned labels summary with properties such as label URI, Key in key-value pair, and Value in key-value pair.

Examples

Report Templates

GET /orgs/:xorg_id/report_templates

List the report templates for this user and organization.

[
	{
		"href": "/orgs/1/report_templates/executive_summary_report",
		"name": "Executive Summary",
		"report_parameters": {}
	},
	{
		"href": "/orgs/1/report_templates/traffic_flow_report",
		"name": "Traffic Flow Query",
		"report_parameters": {
			"app_groups": []
		}
	}
]

This request references the following two schemas (see Schemas to Define a Report).

executive_summary_report_params.schema.json
traffic_flow_report_params.schema.json

Report Schedules

POST /api/v2/orgs/1/report_schedules

Request to create a new report schedule:

{
	"report_template": {
		"href": "/orgs/1/report_templates/traffic_flow_report"
	},
	"name": "John's Traffic Flow Report - Quarterly",
	"report_generation_frequency": "quarterly",
	"report_parameters": {
		"report_time_range": {
			"last_num_days": 90
		},
		"app_groups": [
     
		]
	}
}

Response (201 created)

{
	"href": "/orgs/1/report_schedules/8a08b381-c8fe-4837-b9c6-071c70861369",
	"report_template": {
		"href": "/orgs/1/report_templates/traffic_flow_report"
	},
	"name": "John's Traffic Flow Report - Quarterly",
	"report_generation_frequency": "quarterly",
	"report_parameters": {
		"app_groups": [],
		"report_time_range": {
			"last_num_days": 90
		}
	}
}

On-demand Reports

POST /api/v2/orgs/1/reports

Request to create an on-demand report in the PDF format (report_format):

{
	"report_template": {
		"href": "/orgs/1/report_templates/executive_summary_report"
	},
	"description": "John's Executive Summary Report",
	"report_parameters": {
		"report_time_range": {
		"last_num_days": 30
		}
	},
	"report_format": "pdf"
}

Response

{
	"href": "/orgs/1/reports/be9b68ec-c35a-49bb-9400-f78c9950e321",
	"report_template": {
		"href": "/orgs/1/report_templates/executive_summary_report",
		"name": "Executive Summary Report"
	},
	"description": "John's Executive Summary Report",
	"created_at": "2021-01-15T05:45:27.130Z",
	"updated_at": "2021-01-15T05:45:27.130Z",
	"progress_percentage": 0,
	"generated_at": null,
	"status": "queued",
	"report_parameters": {
		"report_time_range": {
			"last_num_days": 30
		}
	},
	"created_by": {
		"href": "/users/1"
	},
	updated_by": {
		"href": "/users/1"
	}
}

Report Settings

GET /orgs/:xorg_id/settings/reports

Request to list report settings:

{
	"href": "/orgs/1/report_settings",
	"report_retention_days": 1,
	"enabled": true,
	"max_queued_reports": 25
}

REST APIs for 22.2

Reporting APIs

Reporting API Types

Reporting Schedules

Parameters for Reporting Schedules

Defining Report Schedule Query

Report Templates

Defining Report Templates Query

On-Demand Reports

Report Settings

Schemas to Define a Report

Examples

Report Templates

Report Schedules

On-demand Reports

Report Settings

Search results