Table Of Contents

RatedDataSupport

Unlike the typical behavior considered in the Resource Counters integration procedure, some cloud applications expose API that on a resource usage request returns a set of charges for the resources used on the application side for the specified period. In this document, such data is called “vendor rated data”.

In this case, the APS type of the application that is responsible for the resource usage counting must implement the RatedDataSupport APS type considered in this document. Typically, it must be the same APS type that also implements the SubscriptionService APS type. The APS resources instantiated from that APS type in the platform are usually called either “tenant”, or “management context”, or “subscription service” and the corresponding resources on the cloud application side are typically called “tenants”.

The implementation of RatedDataSupport by an APS type of an APS application makes the platform periodically poll the APS resources instantiated from that APS type. In those polls, the platform will call the exportRatedData custom operation on those resources instead of calling the retrieve operation.

In this document:

Schema

The considered APS type (download) looks as follows:

{
  "apsVersion": "2.0",
  "name": "RatedDataSupport",
  "id": "http://aps-standard.org/types/core/rated-data-support/1.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "properties": {
    "terminationDate": {
      "type": "string",
      "format": "date-time",
      "required": false
    }
  },
  "operations": {
    "exportRatedData": {
      "verb": "GET",
      "path": "/exportRatedData",
      "parameters": {
        "lastInvoiceDate": {
          "kind": "query",
          "type": "string",
          "required": true
        },
      },
      "response": {
        "type": "object",
        "properties": {
          "lastInvoiceDate": {
            "type": "string",
            "format": "date",
            "required": true,
            "kind": "query"
          },
          "charges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "accountId": {
                  "type": "string",
                  "required": true
                },
                "chargeType": {
                  "type": "string",
                  "enum": [
                    "COS",
                    "CHARGE",
                    "MSRP"
                  ],
                  "required": true
                },
                "chargeId": {
                  "type": "string",
                  "required": false
                },
                "invoiceId": {
                  "type": "string",
                  "required": false
                },
                "amount": {
                  "type": "number",
                  "required": true
                },
                "poNumber": {
                  "type": "string",
                  "required": false
                },
                "totalCost": {
                  "type": "number",
                  "required": true
                },
                "currencyCode": {
                  "type": "string",
                  "required": true
                },
                "unitOfMeasure": {
                  "type": "string",
                  "required": false,
                  "default": "unit"
                },
                "unitPrice": {
                  "type": "number",
                  "required": false
                },
                "skuId": {
                  "type": "string",
                  "required": false
                },
                "description": {
                  "type": "string",
                  "required": false
                },
                "chargeStartDate": {
                  "type": "string",
                  "format": "date",
                  "required": false
                },
                "chargeEndDate": {
                  "type": "string",
                  "format": "date",
                  "required": false
                },
                "hash": {
                  "type": "string",
                  "required": false
                }
              }
            }
          }
        }
      }
    }
  }
}

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

exportRatedData

GET

/exportRatedData

Object

Return rated data generated on the application side for a period starting from the specified date.

exportRatedData

HTTP Request

GET /aps/2/resources/{aps-id}/exportRatedData?lastInvoiceDate=<start-date>

"APS-Account-Hierarchy" : "List of APS ID of every account in the hierarchical chain starting from the provider"
  • lastInvoiceDate - start date of the requested period in the format of YYYY-MM-DD, for example, 2018-09-30

  • APS-Account-Hierarchy HTTP header - a string containing comma-separated APS IDs of the provider and all subsidiary resellers in the chain that leads to the customer, for example:

    “d257f87a-4bff-43ab-9ff7-11e217f3b93e, b3325a5f-3644-4d47-a936-0ec77c8e1e15, a3cab1f8-04b2-4ce6-a696-a956dd8f9071”

    In the example, the first APS ID belongs to the provider, then goes the customer’s parent reseller, and finally the customer itself.

Description

The operation is called by the platform VRD collector service to get a set of charges from an application.

Returns

An object with the following structure:

{
  "lastInvoiceDate": "<end-date>",
  "charges": [
      {<charge-1>},
      {<charge-2>},
      ...
  ]
}

A charge is a structure containing the following properties:

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

accountId

String

Required

Not applicable

APS ID of an account consuming the application service or a reseller.

chargeType

String enum: “COS” | “CHARGE” | “MSRP”

Required

Not applicable

Type of the rated data entity:
* “COS” - cost of service (how much it costs for the provider).
* “CHARGE” - charge for the used service (the final price for the specified account).
* “MSRP” - manufacturer’s suggested retail price.

chargeId

String

Not required

“”

Vendor specific charge ID, unique in scope of all charges reported by the application.

invoiceId

String

Not required

“”

Vendor specific invoice ID. It can be the same for several charges.

amount

Number

Required

Not applicable

The used amount of the resource.

PoNumber

String

Not required

“”

Customer purchase order number is a reseller specific number assigned to a subscription through the sales order when creating the subscription.

totalCost

Number

Required

Not applicable

Total sum for the resource usage in this charge.

currencyCode

Enum string

Required

Not applicable

Currency code in accordance with ISO 4217, for example, “USD”.

unitOfMeasure

String

Not required

“”

Vendor specified unit of resource measure.

unitPrice

Number

Not required

0

Price per resource unitOfMeasure.

skuId

String

Not required

“”

Vendor specific SKU assigned to the charged service component.

description

String

Not required

“”

Charge description given by the vendor.

chargeStartDate

String in the form of date-time.

Not required

“”

Start date of the period charged by the vendor.

chargeEndDate

String in the form of date-time.

Not required

“”

End date of the period charged by the vendor.

hash

String no longer than 255 symbols

Not required

“”

If used, the application must guarantee the uniqueness of the value in scope of all generated charges. For example, it can be the MD5 hash of the charge JSON structure.