Reporting and Data Export¶

To assist resellers in analyzing their commercial activities, there is a Reporting and Data Export (RDE) service that, once installed on the platform, allows resellers generate and download RDE reports about accounts and related resources changed during a specified period. An RDE report includes details about the following objects:

Reseller subscriptions
Customer accounts
Customer subscriptions
Service plans sold
Prices and discounts
Orders and invoices
Taxes

This document illustrates a typical lifecycle of the data export initiated by an external system using the OAuth authentication.

In this document:

Report Generators
One Time Report
Periodic Reports

Report Generators ¶

To generate reports, it is necessary to create one or more report generators that will create reports for specified periods and upload them to cloud storage in accordance with the RDE service configuration. Every generated report is stored in a separate file.

The RDEReportTemplate APS type enables a reseller to create report generators of the following types as specified by the eventType parameter:

"eventType":"ONETIME" generates a single report for a specified period immediately.
"eventType":"PERIODIC" generates reports periodically either once a day or once a month.
"eventType":"ON_INVOICE" generates a report every time a new invoice for sold services appears in the platform.

One Time Report ¶

Request Report Generation¶

From the RDEReportTemplate APS type, create an APS resource representing a report generation service (report generator) that will generate one or more reports for the specified period and store them in cloud storage.

POST /aps/2/resources

{
   "aps":{
      "type":"http://www.odin.com/rde/report-template/1.1"
   },
   "commonName":"NW Finance",
   "parameters":{
      "startDate":"2018-09-09T00:00:00Z",
      "endDate":"2018-10-05T23:59:59Z"
   },
   "format":"JSON",
   "notifyByEmail":false,
   "eventType":"ONETIME"
}

The response will look like this:

HTTP/1.1 202 Accepted

{
   "aps": {
      "type": "http://www.odin.com/rde/report-template/1.1",
      "id": "07cd68e6-eb96-47c4-9936-a89e27ee790d",
      "status": "aps:provisioning",
      "revision": 3,
      "modified": "2018-10-09T09:23:52Z",
      "package": {
         "id": "2a1f2c8e-02a6-48c1-874d-e7617bc247bf",
         "href": "/aps/2/packages/2a1f2c8e-02a6-48c1-874d-e7617bc247bf"
      }
   },
   "commonName": "NW Finance",
   "eventType": "ONETIME",
   "format": "JSON",
   "notifyByEmail": false,
   "parameters": {
      "endDate": "2018-10-10T23:59:59Z",
      "startDate": "2018-10-09T00:00:00Z"
   },
   "reportApsActorId": "2ebda147-e0c6-4649-ab8f-9c14bfb2262e",
   "reportApsIdentityId": "2fd41bc4-7e89-43cd-99bc-cdaa3283a4eb",
   "reportFiles": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/07cd68e6-eb96-47c4-9936-a89e27ee790d/reportFiles"
      }
   },
   "tenant": {
      "aps": {
         "link": "weak",
         "href": "/aps/2/resources/18b57549-da3e-4e16-bd10-254aec5c2118",
         "id": "18b57549-da3e-4e16-bd10-254aec5c2118"
      }
   }
}

Get a Report APS Resource¶

The previous response contains a link to the collection of reports. For this type of report generator, only one report is available in that collection. Get it using the following request:

GET /aps/2/resources/07cd68e6-eb96-47c4-9936-a89e27ee790d/reportFiles

If the report is not ready yet, the response can look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "modified": "2018-10-09T09:23:52Z",
         "id": "a7f79686-f6a6-4319-bb8b-4a40ed2ecbb3",
         "type": "http://www.odin.com/rde/report-file/1.1",
         "status": "aps:provisioning",
         "revision": 4
      },
      "generateDate": "2018-10-09T09:23:54Z",
      "format": "JSON",
      "name": "NW Finance",
      "eventType": "ONETIME",
      "parameters": {
         "endDate": "2018-10-10T23:59:59Z",
         "startDate": "2018-10-09T00:00:00Z"
      },
      "status": "IN_PROGRESS"
   }
]

When the report is ready, the response will be similar to the following:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "modified": "2018-10-09T09:24:22Z",
         "id": "a7f79686-f6a6-4319-bb8b-4a40ed2ecbb3",
         "type": "http://www.odin.com/rde/report-file/1.1",
         "status": "aps:ready",
         "revision": 6
      },
      "generateDate": "2018-10-09T09:23:54Z",
      "filePath": "https://rde4.blob.core.windows.net/rdecontainer/NW%20Finance.a7f79686-f6a6-4319-bb8b-4a40ed2ecbb3.2018-10-09.09-23-54.912+0000.json.gz?sig=%2BoSd89NgbR%2FOcwSDnhRaOVQ1cjw1yYLY85hqDRW7Y4s%3D&api-version=2016-05-31&st=2018-10-09T09%3A13%3A55Z&se=2019-01-07T09%3A13%3A55Z&sv=2016-05-31&sp=rwd&sr=b",
      "format": "JSON",
      "name": "NW Finance",
      "eventType": "ONETIME",
      "parameters": {
         "endDate": "2018-10-10T23:59:59Z",
         "startDate": "2018-10-09T00:00:00Z"
      },
      "status": "READY",
      "tmpPath": "https://rde4.blob.core.windows.net/rdecontainer/NW%20Finance.a7f79686-f6a6-4319-bb8b-4a40ed2ecbb3.2018-10-09.09-23-54.912+0000.json.gz?sig=r%2FIlLy34mb7CtQhbW49jDoP1hhwgczQQULBDsDXVA0I%3D&api-version=2016-05-31&st=2018-10-09T09%3A23%3A55Z&se=2018-10-11T09%3A23%3A55Z&sv=2016-05-31&sp=r&sr=b"
   }
]

Get Report Contents¶

Use any suitable tool to download the report file from the cloud storage medium, for example:

curl "https://rde4.blob.core.windows.net/rdecontainer/NW%20Finance.a7f79686-f6a6-4319-bb8b-4a40ed2ecbb3.2018-10-09.09-23-54.912+0000.json.gz?sig=r%2FIlLy34mb7CtQhbW49jDoP1hhwgczQQULBDsDXVA0I%3D&api-version=2016-05-31&st=2018-10-09T09%3A23%3A55Z&se=2018-10-11T09%3A23%3A55Z&sv=2016-05-31&sp=r&sr=b" --output /temp/rde-report2.json.gz

Periodic Reports ¶

Request Report Generation¶

To start generating RDE reports periodically, either once a day ("period":"P1D") or once a month ("period":"P1M"), send a request similar to the following:

POST /aps/2/resources

{
   "aps":{
      "type":"http://www.odin.com/rde/report-template/1.1"
   },
   "commonName":"NW Finance",
   "parameters":{
      "period":"P1D"
   },
   "format":"JSON",
   "notifyByEmail":false,
   "eventType":"PERIODIC"
}

A typical response:

HTTP/1.1 202 Accepted

{
   "aps": {
      "type": "http://www.odin.com/rde/report-template/1.1",
      "id": "42b1d0b8-7b1d-4153-9fed-280dc4b09e2f",
      "status": "aps:provisioning",
      "revision": 3,
      "modified": "2018-10-09T10:08:11Z",
      "package": {
         "id": "2a1f2c8e-02a6-48c1-874d-e7617bc247bf",
         "href": "/aps/2/packages/2a1f2c8e-02a6-48c1-874d-e7617bc247bf"
      }
   },
   "commonName": "NW Finance",
   "eventType": "PERIODIC",
   "format": "JSON",
   "nextReportDate": "2018-10-10T00:00:00Z",
   "notifyByEmail": false,
   "parameters": {
      "period": "P1D"
   },
   "reportApsActorId": "2ebda147-e0c6-4649-ab8f-9c14bfb2262e",
   "reportApsIdentityId": "2fd41bc4-7e89-43cd-99bc-cdaa3283a4eb",
   "reportFiles": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/42b1d0b8-7b1d-4153-9fed-280dc4b09e2f/reportFiles"
      }
   },
   "tenant": {
      "aps": {
         "link": "weak",
         "href": "/aps/2/resources/18b57549-da3e-4e16-bd10-254aec5c2118",
         "id": "18b57549-da3e-4e16-bd10-254aec5c2118"
      }
   }
}

A periodic task will be scheduled in the platform. To find it out in the provider panel, navigate to Operations > Tasks and then switch to the Periodic > Scheduled Tasks tab:

For testing purposes, it makes sense to run the task manually to generate a couple of reports.

Get Report APS Resources¶

Similar to the on-time case, to get a collection of APS resources representing the RDE reports, send a request on all reports generated by a report generator:

GET /aps/2/resources/42b1d0b8-7b1d-4153-9fed-280dc4b09e2f/reportFiles

If there are reports generated the response will look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "modified": "2018-10-09T10:21:53Z",
         "id": "b4deef9d-8dd2-4350-9150-2bdd644bb8cd",
         "type": "http://www.odin.com/rde/report-file/1.1",
         "status": "aps:ready",
         "revision": 6
      },
      "generateDate": "2018-10-09T10:21:25Z",
      "filePath": "https://rde4.blob.core.windows.net/rdecontainer/NW%20Finance.b4deef9d-8dd2-4350-9150-2bdd644bb8cd.2018-10-09.10-21-25.627+0000.json.gz?sig=MxNAcInZrIGMkaxSM23V3pJNJjT99JaVCWJSAhHpoPU%3D&api-version=2016-05-31&st=2018-10-09T10%3A11%3A26Z&se=2019-01-07T10%3A11%3A26Z&sv=2016-05-31&sp=rwd&sr=b",
      "format": "JSON",
      "name": "NW Finance",
      "eventType": "PERIODIC",
      "parameters": {
         "period": "P1D",
         "endDate": "2018-10-08T23:59:59Z",
         "startDate": "2018-10-08T00:00:00Z"
      },
      "status": "READY",
      "tmpPath": "https://rde4.blob.core.windows.net/rdecontainer/NW%20Finance.b4deef9d-8dd2-4350-9150-2bdd644bb8cd.2018-10-09.10-21-25.627+0000.json.gz?sig=%2FZoh8UdrBJnUzZHKv2oXa6D0M%2Fxkb78XJAdjVs3TMQg%3D&api-version=2016-05-31&st=2018-10-09T10%3A21%3A26Z&se=2018-10-11T10%3A21%3A26Z&sv=2016-05-31&sp=r&sr=b"
   },
   {
      "aps": {
         "modified": "2018-10-09T10:22:38Z",
         "id": "d57a5c81-043a-40fc-a360-94f8cf409a19",
         "type": "http://www.odin.com/rde/report-file/1.1",
         "status": "aps:provisioning",
         "revision": 4
      },
      "generateDate": "2018-10-09T10:22:40Z",
      "format": "JSON",
      "name": "NW Finance",
      "eventType": "PERIODIC",
      "parameters": {
         "period": "P1D",
         "endDate": "2018-10-08T23:59:59Z",
         "startDate": "2018-10-08T00:00:00Z"
      },
      "status": "IN_PROGRESS"
   }
]

← Subscription Management

Integrating Cloud Services →

CloudBlue Commerce API

Previous topic

Next topic

Reporting and Data Export¶

Report Generators ¶

One Time Report ¶

Request Report Generation¶

Get a Report APS Resource¶

Get Report Contents¶

Periodic Reports ¶

Request Report Generation¶

Get Report APS Resources¶

CloudBlue Commerce API

Previous topic

Next topic

Reporting and Data Export¶

Report Generators¶

One Time Report¶

Request Report Generation¶

Get a Report APS Resource¶

Get Report Contents¶

Periodic Reports¶

Request Report Generation¶

Get Report APS Resources¶

Report Generators ¶

One Time Report ¶

Periodic Reports ¶