Application Packaging Standard

Last updated 14-Nov-2018

Export Rated Data

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

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

This document illustrates a typical lifecycle of the rated 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 a cloud storage in accordance with the RDE service configuration. Every generated report is stored in a separate file.

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

  • "eventType":"ONETIME" - generate a single report for a specified period immediately.
  • "eventType":"PERIODIC" - generate reports periodically either once a day or once a month.
  • "eventType":"ON_INVOICE" - generate a report every time a new invoice on sold services appears.

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 a 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 Report APS Resource

The previous response contains a link to the collection of reports. For this type of the report generator, only one report is available in that collection. Get it by 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:

[
   {
      "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:

[
   {
      "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, 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 or once a month, 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 and thus have a couple of reports generated.

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