HPE GreenLake for Reporting developer guide

The examples in this guide help you start using the Reporting APIs to check the status of reports using this service.

Prerequisites

Endpoints

Endpoints are the host URLs that you submit your API request to. Reporting APIs use the following endpoint:

https://global.api.greenlake.hpe.com/

URIs

Unique Resource Identifiers (URIs) identify a server or resource used in the Reporting API. A URI is a full API path ending with a specific endpoint. For example:

/reporting/v1alpha1/report-exports-metadata
/reporting/v1alpha1/report-exports
/reporting/v1alpha1/async-operations/{id}
/reporting/v1alpha1/statuses/{id}
/reporting/v1alpha1/statuses

Access and permissions

You need the correct permissions to use the HPE GreenLake Reporting APIs.

View permission for an HPE GreenLake platform workspace (ccs.accounts.platform.customer.view) is sufficient to make the following API calls:

GET /reporting/v1alpha1/report-exports-metadata
GET /reporting/v1alpha1/async-operations/{id}
GET /reporting/v1alpha1/statuses/{id}
GET /reporting/v1alpha1/statuses

Edit permissions are required to make the following API call:

POST /reporting/v1alpha1/report-exports

Find out more about Roles & Permissions in the HPE GreenLake Edge-to-Cloud Platform User Guide.

Generating a token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access the HPE GreenLake platform Reporting API, proceed as follows:

Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
Go to Manage > API > Create Credentials .
Select  HPE GreenLake Platform  from the Select Service Manager  drop-down and enter a credential name in Credential Name to create the credentials and generate access tokens for HPE GreenLake platform service APIs. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.

Making it all work

A typical HPE GreenLake for Reporting API workflow:

To determine what data to report on, call the GET Report exports metadata .
Use the POST Report exports to generate your report, using the columns, filter criteria, and supported operators returned in step 1. Make a note of the report identifier returned in the API response.
Check the status of the asynchronous API call with the GET Get report status by ID endpoint.
View the report with the URI returned in GET asynchronous operation details .

info

If you configure recipient email address, the report is emailed when to the listed recipients.

GET report exports metadata

This API returns a list of all the data available for reporting, including:

The supported columns.
The data types that each column contains.
The filter criteria that can be used.
The supported filtering operators.

info

The data available to report on depends on the configuration of your HPE GreenLake workspace.

Calling this API helps you structure your call to the POST report exports endpoint.

Copy

Copied

GET /reporting/v1alpha1/report-exports-metadata

Example response.

Copy

Copied

            {
              "items": [
                  {
                      "id": "SUBSCRIPTION",
                      "kind": "REPORT.EXPORTS.METADATA",
                      "type": "subscription",
                      "columns": [
                          {
                              "displayName": "Subscription Key",
                              "name": "SUBSCRIPTION_KEY",
                              "dataType": "string"
                          },
                          {
                              "displayName": "Subscription Type",
                              "name": "SUBSCRIPTION_TYPE",
                              "dataType": "string"
                          },
                          {
                              "displayName": "Subscription Tier Description",
                              "name": "SUBSCRIPTION_TIER_DESCRIPTION",
                              "dataType": "string"
                          },
                          {
                              "displayName": "Available Quantity",
                              "name": "AVAILABLE_QUANTITY",
                              "dataType": "integer"
                          }
                      ],
                      "filterCriteria": [
                          {
                              "name": "product_type",
                              "dataType": "string",
                              "supportedOperators": ["EQ"]
                          },
                          {
                              "name": "sort_by",
                              "dataType": "string",
                              "supportedOperators": ["EQ"]
                          }
                      ]
                  },
                  {
                      "id": "UID_DEVICE_INVENTORY",
                      "kind": "REPORT.EXPORTS.METADATA",
                      "type": "device_inventory",
                      "columns": [
                          {
                              "displayName": "Serial Number",
                              "name": "SERIAL_NUMBER",
                              "dataType": "string"
                          },
                          {
                              "displayName": "Device Model",
                              "name": "DEVICE_MODEL",
                              "dataType": "string"
                          },
                          {
                              "displayName": "MAC Address",
                              "name": "MAC_ADDRESS",
                              "dataType": "string"
                          },
                          {
                              "displayName": "Part Number",
                              "name": "PART_NUMBER",
                              "dataType": "string"
                          }
                      ],
                      "filterCriteria": [
                          {
                              "name": "unassigned_only",
                              "dataType": "boolean",
                              "supportedOperators": ["EQ"]
                          },
                          {
                              "name": "archive_visibility",
                              "dataType": "string",
                              "supportedOperators": ["EQ"]
                          }
                      ]
                  }
              ],
              "count": 2,
              "total": 6,
              "offset": 0
          }

POST report exports

With the information returned by the GET report exports metadata endpoint, structure the reporting request. This is an asynchronous API call.

Copy

Copied

POST /reporting/v1alpha1/report-exports

In your payload:

Give the report a name, define the type, and provide a description of the report.
Define the query elements ( queryElements ), specifically, the columns of information you want to return in the report. The example payload shows the criteria of a report on workspace subscriptions.
Specify the filter criteria ( filterCriteria ). For example, to return a particular subscription you could filter on a unique subscription key. Separate multiple filterCriteria with a comma.
Define the format of the report ( CSV , PDF , EXCEl , TXT ), the email subject, and recipients email address (separate multiple recipients with a comma).

An example of filter criteria.

Copy

Copied

    {
        "key": "SUBSCRIPTION_KEY",
        "operator": "EQ",
        "value": "123PQR32AQ5BC"
    },
    {
        "key": "product_type",
        "operator": "EQ",
        "value": "DEVICE"
    }

Example request payload.

Copy

Copied

        {
          "name": "Name of the report",
          "description": "Description about the report",
          "kind": "REPORT.EXPORTS",
          "type": "subscriptions",
          "definition": {
              "queryElements": {
                  "columns": [
                      "SUBSCRIPTION_KEY",
                      "SUBSCRIPTION_TYPE",
                      "SUBSCRIPTION_TIER_DESCRIPTION",
                      "AVAILABLE_QUANTITY",
                      "QUANTITY",
                      "SUBSCRIPTION_START",
                      "SUBSCRIPTION_END",
                      "CONTRACT"
                  ],
                  "filterCriteria": [
                      {
                          "key": "product_type",
                          "operator": "EQ",
                          "value": "DEVICE"
                      },
                      {
                          "key": "SUBSCRIPTION_KEY",
                          "operator": "EQ",
                          "value": "123PQR32AQ5BC"
                      },
                      {
                          "key": "QUANTITY",
                          "operator": "GT",
                          "value": "5"
                      },
                      {
                          "key": "sort_by",
                          "operator": "EQ",
                          "value": "expiration"
                      },
                      {
                          "key": "direction",
                          "operator": "EQ",
                          "value": "asc"
                      }
                  ]
              },
              "enrollment": {
                  "delivery": {
                      "format": "CSV",
                      "email": {
                          "subject": "Subscription report sorted with expiration generated",
                          "recipients": [
                              "test@test.com"
                          ]
                      }
                  }
              }
          }
      }

A successful call to this API returns a 202 Accepted response if the request is processing. This response indicates that the call is being processed, but is not yet complete. A 202 Accept response includes:

A unique identifier for the request.
An indication of the status, for example, that the request is in process. It might return a more detailed message.

The location header of a successfully completed POST report exports includes a URL to retrieve the report.

GET report status by ID

Use this API to get an update on the progress of the asynchronous API call. Pass the status identifier (id) returned in the GET async operations into the API request.

Example request.

Copy

Copied

GET /reporting/v1alpha1/statuses/{id}

Example response.

Copy

Copied

{
    "id": "<Status-Id>",
    "resourceUri": "</reporting/v1alpha/statuses/{id}>",
    "type": "REPORT",
    "status": "<status of stage>",
    "stage":"<Report Submission/In queue>",
    "message": "<small brief of the message to customer",
    "isExpired": "<True/False based on the expiry of the report>",
    "reportType": "<Subscription Report or Device Inventory Report or Activate Report>",
    "reportDownloadUrl": "<Presigned URL after report generation is complete and report is not expired else empty>",
    "recipientEmailId": "<Recipient email Id>",
    "startTime": "<timestamp at which report request placed in RFC3339 format>",
    "statusTimestamp": "<Timestamp of last available status in RFC3339 format>",
    "createdAt": "<Timestamp of the creation date in RFC3339 format>"
}

GET asynchronous operation details

Use the GET asynchronous operation details API to retrieve a URL to view the report (and other information on the POST reports exports API call).

In the request, include the unique identifier (id) returned by the POST reports export API, and include it in your request. For example:

Copy

Copied

GET /reporting/v1alpha1/async-operations/**{id}**

The response body includes a results array that contains the URL (resourceUri) to the report when the report is generated.

Filtering

Filters limit the resources that take part in the action of a REST call. When a REST call includes a filter, the GET or PUT action is restricted to a response that meets the filter requirements. Specify filters using the query parameter filter.

Filtering example

In this example of filtering, the query limits resources to results with the attribute flag and the value true. Within the filter, the separator is...

Copy

Copied

GET <URI>?filter=example eq true

Filtering on a single property

Copy

Copied

filter = <propertyName> <comparison operation> <literal>

For example:

Copy

Copied

GET <URI>?filter=example eq example`

Property is the name of an attribute in the requested resource type, such as flag. The property name is always to the left of the operation. Specify nested property names with the / separator.

Operation evaluated. Operations compare properties against literals, for example, eq. All parameters except in require the property on the left and the literal on the right. The in parameter allows the property on either side.

Operation	Example	Description
`eq`	`type eq 'REPORT'`	Checks if the type is `REPORT`.
`ne`	`type ne 'REPORT'`	Returns all results when type is not equal to `REPORT`.
`gt`	`createdAt gt 2019-08-24T14:15:22Z`	Returns all resources created after the specified date.
`ge`	`createdAt ge 2019-08-24T14:15:22Z`	Returns all resources created on or after the specified date.
`lt`	`createdAt lt 2019-08-24T14:15:22Z`	Returns all resources before the specified date.

A literal, for example, true, is what an operation compares a property to. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals.

Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

The following are examples of literals.

String — Anything in 'single quotes'. Reserved characters in string literals must be URL encoded.
Integer — -100, -1, 0, 1, 100
Decimal — -3.14, -2.71, 2.71, 3.14
Timestamp — 2019-10-12T07:20:50.52934852Z. The timestamp format is [RFC3339]
Boolean — true, false
Null — Null is equal to itself and nothing else. Null is not greater or less than anything.

OData filtering reference

This filtering is a subset of OData 4.0 filtering.