Analytics Reports

Overview

Use the Analytics Reports API to schedule and publish analytics reports. You can use this API to schedule and publish a one-time or periodic analytics report, save filter information, or generate a report from saved information.

REST Endpoint: /mgmt/shared/file/data

Requests

POST /mgmt/shared/file/data

To schedule and publish an analytics report, you can send a POST request to the file/data endpoint.

Request Parameters

The JSON in the body of the POST request can contain the following parameters.

Name Type Required Description
details string Optional to schedule a report, generate a one-time report, or save filter data. Exclude to generate a report from saved data. This parameter can be updated using a PATCH. Description and details of the report.
id string Auto-generated by BIG-IQ when creating a schedule, only saving a data, or executing one-time report. Required to generate a report from saved data. UUID which identifies saved data.
fileStore object Required to schedule a report, to generate a one-time report, or save filter data. Exclude to generate a report from saved data. This parameter can be updated using a PATCH. This attribute stores all the file properties for report file generation.
     location string Same as for fileStore. Report file location. For example: “LOCAL”.
     expiry number Same as for fileStore. Number of expiryUnit units in this expiration period
     expiryUnits string Same as for fileStore. Time units used to measure the expiration period. For example “WEEK”.
     extension string Same as for fileStore. Report file extension. For example: “PDF”.
filters string A value for this parameter is required. Report filters required for report file information. This information only used for display in the report.
name string A value for this parameter is required. Name of the report.
reportName string A value for this parameter is required. Name of the report which displays as a report file header.
saveMetadata boolean Required to save filter data. Optional to schedule a report. Exclude to generate a report from saved data or to generate a one-time report. Set this to true to only save filter data.
scheduler object Required to schedule a report. Exclude to generate a report from saved data or generate a one-time report. This parameter can be updated using a PATCH. Adding values under this attribute can create a scheduler.
     deviceGroupName string Same as for scheduler. Name of device group
     interval number Same as for scheduler. Number of intervalUnit units of this report
     intervalUnit string Same as for scheduler. Time units used to measure the interval. For example “DAY”.
     scheduleType string Same as for scheduler. Type of report schedule
     timeToStartOn string Same as for scheduler. Time and date for the start of the report
sendMail object Optional to generate a one-time report, schedule a report, or to save filter data. Exclude to generate a report from saved data. This parameter can be updated using a PATCH. To send a mail with the generated report, use this attribute.
     subject string Same as for sendMail. Subject line for email
     toAddresses string Same as for sendMail. An array of email addresses for recipients.
services object Required to schedule a report or to generate a one-time report. Required to save filter data. Exclude to generate a report from saved data. This parameter can be updated using a PATCH. Information about services used for calling external service to get the content to be reported.
     details string Same as for services. Description and details of this object
     producer string Same as for services. Producer of service. For example: “ANALYTICS”.
     service object Same as for services. An array of service objects
          endpoint object Same as for service. Link of the service API.
                link string Same as for service. URL of service API
          payload object Same as for service. Body of the service API
          method string Same as for service. The HTTP method. For example: “POST”

Query Parameters

None

Response

The JSON in the response can contain the following parameters.

HTTP/1.1 200 OK

Name Type Description
details string This optional field can be used to add some details about this report. Description and details of the report
fileStore object This mandatory attribute will store all the file properties for report file generation.
     extension string Report file extension. For example: “PDF”.
     location string Report file extension. For example: “LOCAL”.
     expiry number Number of expiryUnit units in this expiration period
     expiryUnits string Time units used to measure the expiration period. For example “WEEK”.
filters string Report filters required for report file information. A value for this parameter is required. Information about filters used to create the report. This information is used only for display in the report.
id string The UUID that can be used to generate the report from saved data. This is auto-generated.
name string Name of the report. A value for this parameter is required.
reportName string Name of the report which also displays as a report file header. A value for this parameter is required.
sendMail object To send a mail with the generated report, use this attribute. This is optional.
     subject string Subject line for email
     toAddresses string An array of email addresses of a recipients for this email
     testConnectionOnly boolean Test connection only
services object Information about services used for calling external service to get the content to be reported. A value for this parameter is required.
     details string Description and details of this object
     producer string Producer of service. For example: “ANALYTICS”.
     service object An array of service objects
          endpoint object Link of the service API.
                link string URL of service API
          payload object Body of the service API
          method string The HTTP method. For example: “POST”
schedulerReference object Reference link to the scheduler
     link string URL for the scheduler
selfLink string The URL to access the scheduler

Permissions

Role Allow
admin Yes

GET /mgmt/shared/file/data/{id}

To retrieve schedule and publish information about a specific analytics report, you can send a GET request and include specified the identifier, id. Send the GET to the collection to retrieve all records.

Request Parameters

None

Query Parameters

None

Response

The JSON in the GET response can look similar to the response from the POST request.

Permissions

Role Allow
admin Yes

PATCH /mgmt/shared/file/data/{id}

To update schedule and publish information for an analytics report, you can send a PATCH request to the file/data/{id} endpoint.

Request Parameters

The JSON in the body of the PATCH request can contain the following parameters with the updated values. The following schedule and publish parameters can be changed using a PATCH: scheduler, services, fileStore, sendMail, or details.

Name Type Required Description
references object True The report’s publish and file storage references.
          publishReference object True Link to the report’s publish reference.
                link string True URL of the report’s reference.
          storageReference object True Link to the report’s file storage reference.
                link string True URL of the report’s file storage reference.

Query Parameters

None

Response

The JSON in the response to the PATCH can contain the updated values and look similar to the response to a POST.

HTTP/1.1 200 OK

Permissions

Role Allow
admin Yes

DELETE /mgmt/shared/file/data/{id}

To delete schedule and publish information for an analytics report, you can send a DELETE request to the file/data/{id} endpoint.

Request Parameters

None

Query Parameters

None

Response

The JSON in the response to the DELETE can contain the information of the deleted record.

HTTP/1.1 200 OK

Permissions

Role Allow
admin Yes

Examples

POST to schedule a report

The following example sends a POST request to schedule a report.

POST https://<BIG-IQ>/mgmt/shared/file/data

The JSON in the body of the POST can look similar to the following example.

{
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[Some details about this report]",
    "filters": "[Filters information to create the report. Only for display purpose in the report file]",
    "scheduler": {
            "deviceGroupName": "Test_DG",
            "scheduleType": "BASIC_WITH_INTERVAL",
            "interval": 1,
            "intervalUnit": "DAY",
            "timeToStartOn": "2020-11-11T01:00:00Z"
    },
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "subject": "Analytics scheduled report is ready",
            "toAddresses": [
                    "testmail@f5.com"
            ]
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    }
}

Response

The JSON in the body of the response to the POST can look similar to the following.
{
    "id": "e15f1840-102e-42be-ba69-73fec63adffa",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "schedulerReference": {
            "link": "https://localhost/mgmt/shared/task-scheduler/scheduler/e23b354a-499f-4a44-a926-94a01486714e"
    },
    "generation": 1,
    "lastUpdateMicros": 1600774118660523,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa"
}

POST to save filter data

The following example sends a POST request to save filter data.

POST https://<BIG-IQ>/mgmt/shared/file/data

The JSON in the body of the POST can look similar to the following example.

{
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[Some details about this report]",
    "filters": "[Filters information to create the report. Only for display purpose in the report file]",
    "saveMetadata": true,
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "subject": "Analytics scheduled report is ready",
            "toAddresses": [
                    "testmail@f5.com"
            ]
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    }
}

Response

The JSON in the body of the response to the POST can look similar to the following.
{
    "id": "61f02bc2-0ed0-4253-8484-929d9cbe2689",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "generation": 1,
    "lastUpdateMicros": 1600337232997575,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/61f02bc2-0ed0-4253-8484-929d9cbe2689"
}

POST to generate report from saved data

The following example sends a POST request to generate report from saved data.

POST https://<BIG-IQ>/mgmt/shared/file/data

The JSON in the body of the POST can look similar to the following example.

{
    "id": "61f02bc2-0ed0-4253-8484-929d9cbe2689"
}

Response

The JSON in the body of the response to the POST can look similar to the following.
{
    "id": "61f02bc2-0ed0-4253-8484-929d9cbe2689",
    "generation": 1,
    "lastUpdateMicros": 1600337232997575,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/61f02bc2-0ed0-4253-8484-929d9cbe2689"
}

POST to generate a one-time report

The following example sends a POST request to generate a one-time report.

POST https://<BIG-IQ>/mgmt/shared/file/data

The JSON in the body of the POST can look similar to the following example.

{
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[Some details about this report]",
    "filters": "[Filters information to create the report. Only for display purpose in the report file]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "subject": "Analytics scheduled report is ready",
            "toAddresses": [
                    "testmail@f5.com"
            ]
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    }
}

Response

The JSON in the body of the response to the POST can look similar to the following.
{
    "id": "24e2ebb6-aa94-4db2-b193-47448e30fbe0",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "generation": 1,
    "lastUpdateMicros": 1600432022871542,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/24e2ebb6-aa94-4db2-b193-47448e30fbe0"
}

GET to retrieve all records

The following example sends a GET request to retrieve all records.

GET https://<BIG-IQ>/mgmt/shared/file/data

Response

The JSON in the body of the response to the GET can look similar to the following.
{
    "items": [{
                    "id": "e15f1840-102e-42be-ba69-73fec63adffa",
                    "name": "Demo Scheduler Metadata",
                    "reportName": "Analytics Local Traffic Test Report",
                    "details": "[as given]",
                    "filters": "[as given]",
                    "services": {
                            "details": "Demo Service json",
                            "producer": "ANALYTICS",
                            "service": [{
                                            "endpoint": {
                                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                                            },
                                            "payload": "< body of above API >",
                                            "method": "POST"
                                    },
                                    {
                                            "endpoint": {
                                                    "link": "<Link of the Service API>"
                                            },
                                            "method": "GET"
                                    }
                            ]
                    },
                    "sendMail": {
                            "toAddresses": [
                                    "testmail@f5.com"
                            ],
                            "subject": "Analytics scheduled report is ready",
                            "testConnectionOnly": false
                    },
                    "fileStore": {
                            "extension": "PDF",
                            "location": "LOCAL",
                            "expiry": 1,
                            "expiryUnit": "WEEK"
                    },
                    "schedulerReference": {
                            "link": "https://localhost/mgmt/shared/task-scheduler/scheduler/e23b354a-499f-4a44-a926-94a01486714e"
                    },
                    "generation": 1,
                    "lastUpdateMicros": 1600774118660523,
                    "kind": "shared:file:data:filtermetadatastate",
                    "selfLink": "https://localhost/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa"
            },
            {
                    "id": "61f02bc2-0ed0-4253-8484-929d9cbe2689",
                    "name": "Demo Scheduler Metadata",
                    "reportName": "Analytics Local Traffic Test Report",
                    "details": "[as given]",
                    "filters": "[as given]",
                    "services": {
                            "details": "Demo Service json",
                            "producer": "ANALYTICS",
                            "service": [{
                                            "endpoint": {
                                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                                            },
                                            "payload": "< body of above API >",
                                            "method": "POST"
                                    },
                                    {
                                            "endpoint": {
                                                    "link": "<Link of the Service API>"
                                            },
                                            "method": "GET"
                                    }
                            ]
                    },
                    "sendMail": {
                            "toAddresses": [
                                    "testmail@f5.com"
                            ],
                            "subject": "Analytics scheduled report is ready",
                            "testConnectionOnly": false
                    },
                    "fileStore": {
                            "extension": "PDF",
                            "location": "LOCAL",
                            "expiry": 1,
                            "expiryUnit": "WEEK"
                    },
                    "generation": 1,
                    "lastUpdateMicros": 1600337232997575,
                    "kind": "shared:file:data:filtermetadatastate",
                    "selfLink": "https://localhost/mgmt/shared/file/data/61f02bc2-0ed0-4253-8484-929d9cbe2689"
            }
    ],
    "generation": 2,
    "kind": "shared:file:data:dataorchestratorcollectionstate",
    "lastUpdateMicros": 1600774118747059,
    "selfLink": "https://localhost/mgmt/shared/file/data"
}

GET to retrieve a single record

The following example sends a GET request to retrieve a single record.

GET https://<BIG-IQ>/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa

Response

The JSON in the body of the response to the GET can look similar to the following.
{
    "id": "e15f1840-102e-42be-ba69-73fec63adffa",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "schedulerReference": {
            "link": "https://localhost/mgmt/shared/task-scheduler/scheduler/e23b354a-499f-4a44-a926-94a01486714e"
    },
    "generation": 1,
    "lastUpdateMicros": 1600774118660523,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa"
}

PATCH to update a report

The following example sends a POST request to update a report. Patchable inputs: scheduler, services, fileStore, `sendMail, and details.

PATCH https://<BIG-IQ>/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa

The JSON in the body of the PATCH can look similar to the following example.

{
    "references": [{
            "publishReference": {
                    "link": "https://localhost/mgmt/shared/file/publish/25ea097f-6227-4ef7-a8d1-db96fced0684"
            },
            "storageReference": {
                    "link": "https://localhost/mgmt/shared/file/store/b3e58c28-66e9-4918-a24f-1e2c6871938f"
            }
    }]
}

Response

The JSON in the body of the response to the PATCH can look similar to the following.
{
    "id": "e15f1840-102e-42be-ba69-73fec63adffa",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "schedulerReference": {
            "link": "https://localhost/mgmt/shared/task-scheduler/scheduler/e23b354a-499f-4a44-a926-94a01486714e"
    },
    "generation": 2,
    "references": [{
            "validTill": "2020-11-18T06:44:26.171Z",
            "publishReference": {
                    "link": "https://localhost/mgmt/shared/file/publish/25ea097f-6227-4ef7-a8d1-db96fced0684"
            },
            "storageReference": {
                    "link": "https://localhost/mgmt/shared/file/store/b3e58c28-66e9-4918-a24f-1e2c6871938f"
            }
    }],
    "lastUpdateMicros": 1600774118660523,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa"
}

DELETE to delete a report

The following example sends a DELETE request to delete a report.

GET https://<BIG-IQ>/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa

Response

The JSON in the body of the response to the DELETE can look similar to the following.
{
    "id": "e15f1840-102e-42be-ba69-73fec63adffa",
    "name": "Demo Scheduler Metadata",
    "reportName": "Analytics Local Traffic Test Report",
    "details": "[as given]",
    "filters": "[as given]",
    "services": {
            "details": "Demo Service json",
            "producer": "ANALYTICS",
            "service": [{
                            "endpoint": {
                                    "link": "<Link of the Service API, like https://localhost/mgmt/ap/query/v1/tenants/default/products/local-traffic/reports>"
                            },
                            "payload": "< body of above API >",
                            "method": "POST"
                    },
                    {
                            "endpoint": {
                                    "link": "<Link of the Service API>"
                            },
                            "method": "GET"
                    }
            ]
    },
    "sendMail": {
            "toAddresses": [
                    "testmail@f5.com"
            ],
            "subject": "Analytics scheduled report is ready",
            "testConnectionOnly": false
    },
    "fileStore": {
            "extension": "PDF",
            "location": "LOCAL",
            "expiry": 1,
            "expiryUnit": "WEEK"
    },
    "schedulerReference": {
            "link": "https://localhost/mgmt/shared/task-scheduler/scheduler/e23b354a-499f-4a44-a926-94a01486714e"
    },
    "generation": 2,
    "references": [{
            "validTill": "2020-11-18T06:44:26.171Z",
            "publishReference": {
                    "link": "https://localhost/mgmt/shared/file/publish/25ea097f-6227-4ef7-a8d1-db96fced0684"
            },
            "storageReference": {
                    "link": "https://localhost/mgmt/shared/file/store/b3e58c28-66e9-4918-a24f-1e2c6871938f"
            }
    }],
    "lastUpdateMicros": 1600774118660523,
    "kind": "shared:file:data:filtermetadatastate",
    "selfLink": "https://localhost/mgmt/shared/file/data/e15f1840-102e-42be-ba69-73fec63adffa"
}