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	Type	Required
`org_id`	Organization	path	Yes
`report_schedule_id`	UUID of the report schedule	String	Yes

Properties for Reporting Schedules

Parameter	Description	Type	Required
`href`	Report Schedule URI	String	Yes
`report_template`	Template for the report. Required: `href`	Object	Yes
`name`	Name of the report template	String	Yes
`report_generation_frequency`	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	Yes
`report_parameters`	Any specific parameters required for this report template to define one of the report types, using on of the listed schemas: `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object, required	Yes
`scheduled_at`	Timestamp in UTC for report generation	Sring	No
`send_by_email`	Flag for whether to send user report by email	Boolean	True/false
`report_time_range`	Define `start_date` and `end_date` for the report	String	No
`created_at`	Timestamp (rfc3339 timestamp) in UTC when this report schedule was created	String	No
`created_by`	The URI of the user who created this report schedule. Required: `href`	Object	No
`updated_at`	Timestamp (rfc3339 timestamp) when this report schedule was last updated.",	String	No
`updated_by`	The URI of the user who updated this report schedule	Object	No

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
```

```
ves_report_params.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`

Parameters for Reporting Templates

Parameter	Description	Type	Required
`org_id`	Report Template URI	String	Yes
`template_type`	Template type of the report	String	Yes

Properties for Reporting Templates

Parameter	Description	Type	Required
`href`	Report Template URI	String	Yes
`name`	Display name for this report template. maxLength: 255		Yes
`report_parameters`	Any specific parameters required for this report template to define one of the report types, using on of the listed schemas: `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object	Yes
`enabled`	Determines whether the report template is enabled for this org	Boolean	No
`show_in_ui`	Determines whether this report is to be shown in the PCE UI	Boolean, default: `true`	No

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`

Parameters for On-Demand Reports

Parameter	Description	Parameter Type	Required
`href`		Integer	Yes
`report_template`	Template for the report	Object	Yes
`send_by_email`	Flag for whether to send user report by email	Boolean	True/false
`progress_percentage`	Progress percentage for this report.	Integer	No
`generated_at`	Report generation timestamp in UTC	Sring, null	No
`status`	Current status of this report	String	Yes
`report_parameters`	Any specific parameters required for this report template	Object	Yes

Properties for On-Demand Reports

Parameter	Description	Parameter Type	Required
`href`	Report URI	String	Yes
`report_template`	Template for the report	Object	Yes
`report_parameters`	Any specific parameters required for this report template to define one of the report types, using on of the listed schemas: `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object	Yes
`status`	Current status of this report	String	No Yes for GET
`send_by_email`	Flag for whether to send user report by email	Boolean	True/false
`progress_percentage`	Progress percentage for this report.	Integer	`"minimum": 0, "maximum": 100`
`generated_at`	Report generation timestamp in UTC	Sring, null	No
`created_at`	Timestamp in UTC when this report was created	String	No
`created_by`	User who created this report	Object	No
`updated_at`	Timestamp in UTC when this report was last updated.	String	No
`updated_by`	User who last updated this report	Object	No

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.
```
ves_report_params.schema.json
```
Provides report parameters for the new ves (vulnerability-exposure score ) report type.

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": []
		}
	}
]

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
}

VEN Dashboard

The Dashboard uses the following API to aggregate various data from the system and help you focus on the data you are interested in:

POST api/v2/orgs/:xorg_id/vens/statistics

You can obtain summary statistics for VENs by specifying which statistics you are interested in from a set of options. The API also supports obtaining a count for a specific value of a property (such as a count of VENs from a specific product version).

Sample Request

{
	“property_counts”: [
	{  
		"property": "version",
		"values": ["19.3", "18.3"]
		"filters": [
		{  
			"filter_property": "status",
			"values": ["active", ""]
		},
		{  
			"filter_property": "containerized",
			"values": ["true"]
		}
		]
	},
	{
		"property": "version",
		"filters": [
		{
			"filter_property": "status",
			"values": ["active"]
		}
		]
	},
	{
		"property": "health"
		}
	]
}

Sample Response

{
	“property_counts”: [
	{  
		"property": "version",
		“counts”:[
		{
			"value": "19.1",
			"count": 1
		},
		{
			"value": "18.3",
			"count": 2
		}
		]
	},
	{
		"property": "version",
		“counts”:[
			{
			"value": "18.1",
			"count": 1
		},
		{
			"value": "18.2",
			"count": 1
		},
		{
			"value": "18.3",
			"count": 2
		},
		{
			"value": "19.1",
			"count": 2
		}
	]
},
{
		"property": "health",
		“counts”:[
		{
			"value": "healthy",
			"count": 3
		},
		{
			"value": "warning",
			"count": 3
		},
		{
			"value": "err",
			"count": 2
		}
	]
	}
]
}

REST API Developer Guide 22.5

Reporting APIs

Reporting API Types

Reporting Schedules

Parameters for Reporting Schedules

Properties for Reporting Schedules

Defining Report Schedule Query

Report Templates

Parameters for Reporting Templates

Properties for Reporting Templates

Defining Report Templates Query

On-Demand Reports

Parameters for On-Demand Reports

Properties for On-Demand Reports

Report Settings

Schemas to Define a Report

Examples

Report Templates

Report Schedules

On-demand Reports

Report Settings

VEN Dashboard

Search results