Handling Usage Event Data

Article
08/24/2015

Applies To: Windows Azure Pack

In a Windows Azure Pack for Windows Server billing system, usage event data about tenant management of subscriptions, plans and so on is expected to be used to calculate tenant billing information. To do this, the billing system’s billing adapter uses the Usage REST API to collect usage event data and build a database of usage data applicable to billing needs.

Getting Usage Events

The Usage Service endpoint exposes REST API to return billing data for plans, plan add-ons, plan service, add-ons, and subscriptions. For example, to retrieve the plan events the Retrieve Plan Events REST API call is made:

https://<Computer>:30022/billing/plans?startId=0&batchSize=1 HTTP/1.1
Accept: application/json
Authorization: basic <Token>
Host: <Computer>:30022
Connection: Keep-Alive

The response body returns a list of UsageEvent (Usage Metering Object) objects containing the recent plan events. For example:

[
  {
    "EventId": 1,
    "State": 0,
    "Method": "0",
    "Entity": {
      "Id": "Idjt711xf",
      "DisplayName": "TheDisplayName",
      "State": 0,
      "ConfigState": 0,
      "QuotaSyncState": 2,
      "LastErrorMessage": null,
      "Advertisements": [
        {
          "LanguageCode": "en-us",
          "DisplayName": "TheDisplayName",
          "Description": null
        }
      ],
      "ServiceQuotas": [
        {
          "ServiceName": "webspaces",
          "ServiceInstanceId": "4576E3B4-881D-4B9F-87F4-E72206FB11D6",
          "ServiceDisplayName": "Web Site Cloud",
          "ServiceInstanceDisplayName": null,
          "ConfigState": 0,
          "QuotaSyncState": 2,
          "Settings": [

          ]
        },
        {
          "ServiceName": "sqlservers",
          "ServiceInstanceId": "2FBED6DE-5195-4F95-98DC-B67829621025",
          "ServiceDisplayName": "SQL Servers",
          "ServiceInstanceDisplayName": null,
          "ConfigState": 0,
          "QuotaSyncState": 2,
          "Settings": [

          ]
        },
        {
          "ServiceName": "mysqlservers",
          "ServiceInstanceId": "0C18772C-3596-4E2A-BD60-21230C186D17",
          "ServiceDisplayName": "MySQL Servers",
          "ServiceInstanceDisplayName": null,
          "ConfigState": 0,
          "QuotaSyncState": 2,
          "Settings": [

          ]
        },
        {
          "ServiceName": "servicebus",
          "ServiceInstanceId": "B40CC649-1ACE-4134-ADC9-1E610B64F400",
          "ServiceDisplayName": "Service Bus",
          "ServiceInstanceDisplayName": null,
          "ConfigState": 0,
          "QuotaSyncState": 2,
          "Settings": [

          ]
        }
      ],
      "SubscriptionCount": 0,
      "MaxSubscriptionsPerAccount": 1,
      "AddOnReferences": [

      ],
      "AddOns": [

      ],
      "InvitationCode": null,
      "Price": null
    },
    "EntityParentId": null,
    "NotificationEventTimeCreated": "2013-07-31T23:56:20.05"
  }
]

For more information about the available Usage REST API, see Windows Azure Pack Usage Service Usage REST API Reference.

Processing Usage Events

To access usage event data, use the UsageEvent (Usage Metering Object) object returned by the Usage Service REST API. Event notifications sent to the billing adapter adhere to type - UsageEvent (Usage Metering Object)<T> type where T is be replaced by one of the following objects.

Plan
PlanAddon
AdminSubscription
ResourceProviderReference
PlanAddonReference

The UsageEvent object contains information about the event entity such as Plan and Subscription, the type of operation such as creation or deletion, and the current state of the operation. The following table describes what actions to take in a billing adapter for the each combination state:

Event/Operation	Create (POST)	Update (PUT)	Delete
Plans	Process all events	Ignore	Ignore (manual)
Plan Add-ons	Process all events	Ignore	Ignore (manual)
Plan Services	Process all events	Ignore	Ignore (manual)
Add-ons	Process all events	Ignore	Ignore (manual)
Add-on Services	Process all events	Ignore	Ignore (manual)
Subscriptions	process "Acknowledged" events	Process "Pending Approval" and "Acknowledged" events	Process "Acknowledged" events
Subscription Add-ons	process "Acknowledged" events, including "duplicate" events*	Ignore	Process "Acknowledged" events

The significant UsageEvent properties for processing the table above being:

Entity

Contains the object being operated on. For example, AdminSubscription (Administrator object) for a subscription.

Method

The type of operation such as POST, PUT, or DELETE.

State

The current state of the operation.

Value	Description
0	Acknowledged
1	Rejected
2	Pending Approval
3	Approved

Duplicate events can occur for some of the above operations. For example, a “delete a plan” event can occur twice in a row with the same data, because the operation can fail. For the event “create subscription addon,” a tenant has the ability to purchase the same addon multiple times (if it is configured that way) so each create event should be processed such that it results in a new entity creation in the Billing System. For all other create operations, duplicate creations should not be created in the Billing System (i.e. if the entity already exists, do not create another) and they can be safely ignored.

Entity Mapping Between Windows Azure Pack and a Billing System

The billing adapter should create entities in the Billing System with names that match the identifier sent from Windows Azure Pack. In this way, an administrator can correlate which entities in Windows Azure Pack correspond to which entities in the Billing System. If the Billing System does not support this, then the billing adapter will need to maintain mapping information to translate the identifiers used by Windows Azure Pack into the identifiers used by the billing system. For this reason, a billing adapter should have some mechanism which exposes this mapping information to an administrator in a secure manner, so that any discrepancies or uncertainties can be resolved.

Handling Subscriptions

Subscription events are created in the following circumstances:

When a subscription is activated or suspended.
When migrating a subscription.

Subscription Suspension

Important

Subscription Suspension as described here will not be available until the next update release of Windows Azure Pack. In the current RTM build, subscription suspension and activation are not detectable via this interface. There will be subscription update events that are not actionable from the perspective of the billing system and should be ignored.

If a subscription becomes suspended in Windows Azure Pack thus disallowing a tenant to provision new resources or access existing ones using the suspended subscription, this change will propagate into the Billing System via a subscription update event. The subscription object, AdminSubscription (Administrator object), has a state property which indicates if the subscription is Active or Suspended. If an administrator suspends a user’s subscription, they should make the appropriate arrangements in their Billing System to prevent inappropriate charges to the user. Note that the existing resources of a user such as databases, websites, and VMs, are not deleted; only the tenant’s access to them is removed. Also, because users may have multiple subscriptions, it is possible that one of a user’s subscriptions may be suspended while the rest remain active. A user-level suspension should not occur in the Billing System unless all subscriptions in Windows Azure Pack associated with that user have been suspended.

Subscription Migration

When a subscription migration is initiated in Windows Azure Pack, an event will be exposed in the Usage Service REST API as a subscription update event which contains the plan identifier of the new plan the subscription references. In order to detect this, a billing adapter will need to keep track of the WAP plan Identifier of each subscription so it can detect this change, and take the appropriate action in the Billing System. Additionally, any subscription addons that were previously associated with the migrated subscription need to be deleted in the Billing System; these add-ons are removed in Windows Azure Pack and their quota increases are integrated into the quotas of the new plan.

Share via