Table Of Contents

Previous topic

Subscription Management

Next topic

Integrating Cloud Services

Reporting and Data Export

To assist resellers in analyzing their commercial activities, there is a Reporting Data Export (RDE, former Rated Data Export) 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.

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 rated data 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:

../../../_images/rde-periodic-task.png

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