Submit Usage

In order to submit a Usage Document, use the insert method, described in the API documentation with the URL of the Usage Event Collector. You can see the structure of the data which is to be sent through a Usage Document here.

The collector is usually accessed via https://abacus-usage-collector.<cf-domain>. Contact your Abacus Integrator to obtain the exact URL.

You can also submit your usage by selecting the Create and send usage document to Abacus tile in the service dashboard.

With respect to the start and end timestamp, there are several points to note:

• The start timestamp should have a value numerically smaller or even the end timestamp.
• The end timestamp should be no greater than the current day, otherwise it will not be processed.
• Slack Window – specifies the amount of time by which a usage document can be submitted late.

There is no UPDATE or DELETE API available. Data is maintained with the principles of bookkeeping.

The service needs to provide their organization_id, space_id, consumer_id, plan_id, resource_id and resource_instance_id information, specific to each cloud resource.

• organization_id / space_id refers to the organization and space IDs under which the consumer service/app is running.
• consumer_id represents the ID of the app that is consuming the resource.
• resource_id refers to the identifier of the service.
• plan_id refers to the ID of the plan that Abacus is going to use.
• resource_instance_id can be either service instance guid (for Service Brokers) or guid identifying the tenant using the resource.

Further, the resource_id, plan_id, and resource_instance_id provide the services with a further level of aggregation that can be incorporated. Any distinct values in these fields will allow Abacus to aggregate usage records in a hierarchical method in the following order:
account -> organization -> space -> consumer -> resource -> resource_instance

Two Usage Documents are duplicate if they have same values for start^* , end, organization_id, consumer_id, resource_id, plan_id and resource_instance_id fields. Duplicate usage is ignored from Abacus. Duplicate Usage Document is not processed and the usage data would not be included in the usage report.

The service may also provide an optional field.

• dedup_id it is used if the Resource provider needs to submit multiple usages with the same values for start, end, organization_id, consumer_id, resource_id, plan_id, and resource_instance_id fields, without that leading to duplicate usage.
  Note: Have in mind that if you send two usage documents with the same dedup_id, but different organization_id, consumer_id, plan_id, resource_id, or resource_instance_id values, they will be treated as separate documents. (i.e. the dedup_id field, when specified, is just one additional field on which we differentiate documents)

The HTTP POST call should address the end point /v1/metering/collected/usage on your respective landscapes.

^* Currently having usages that differ only by their start time will be processed but only the first usage will be accessible through the location header link.

Usage payload

The payload of the POST call described above is documented here.

Examples

Abacus provides several examples on how to submit usage:

• Post usage

  Submits usage to non-secured Abacus. To run it, execute:

  cd ~/workspace/cf-abacus
  npm restart
  cd node_modules/abacus-demo-client && node src/test/report.js

• Demo client

  Simulates a Service Provider and Usage Consumer. Submits usage and verifies the submission by retrieving a usage report. Works with secured Abacus.

To run demo client:

cd ~/workspace/cf-abacus
npm restart
npm run demo

• The broker test app is a Java applications that:
  • uses Broker credentials
  • can submit usage document
  • can get report and visualize it

Possible Response Codes When Submitting Usage:

Code	Description
202	Usage document is successfully accepted for processing. No response body is returned
400	A field in the usage document is missing, i.e the organization field is missing. The response body will have a JSON object mentioning the missing field
403	Insufficient scope error, encountered when the resource_id value is invalid
404	A value in one of the ID fields is invalid or is missing
429	Too many requests sent by resource provider. Try again later
451	Organization license type not supported
500	Server Error
503	Server Overloaded. The server is overloaded by too many requests. Try again later.

Some responses have JSON body that includes at least an error field:

{
  "error": "license"
} 

Location Header

If the usage document is successfully submitted, a Location header is returned in the response. When a get request with the location header is performed, there are three possible responses :

• 404 not found: the usage document has not been processed yet;
• 200 with body original usage document: the usage has been successfully processed and it will be included in the report;
• 200 with body original usage document and an error field. The error could be:
  • a problem with metering plan.
  • the usage is out of slack and the usage document will not be processed successfully even with retry.

{
    "consumer_id" : "consumer-id",
    "space_id" : "space-guid",
    "organization_id" : "org-guid",
    "resource_id" : "resource-id",
    "resource_instance_id" : "resource-instance-id",
    "plan_id" : "standard",
    "start" : 1529409600000.0,
    "end" : 1530360000000.0,
    "measured_usage" : [ 
        {
            "measure" : "Sample-Unit",
            "quantity" : 200
        }
    ]
    "error" : {
        "isPlanBusinessError" : true
    }
}

If multiple duplicate usage documents have been submitted, the response contains the first usage document that has been submitted and successfully processed by Abacus.

<< Upload Plan	Generate Usage Reports >>

Related Links:

• Roles
• Secure Abacus
• Create a Resource Provider
• Resource Usage Document