Sample Billing Adapter Code for Windows Azure Pack

Recently we are seeing many customers (including service providers) building external systems (specifically Billing) to integrate with Windows Azure Pack (WAP) for collecting usage and notification data. The Usage and Notification data in WAP is collected and stored in a Usage DB for a limited period of time (40 days by default) which is exposed through a Usage endpoint for accessing that data through the Usage REST API.

The sample covered in this post is an ASP.Net, MVC 4, web application which interacts with WAP’s Usage REST API endpoint in reading the usage and notification data at a regular interval which is configurable. This sample is targeted at developers who need to implement a web service that continuously monitors the WAP’s Usage endpoint and reads the updated or incremental data for processing. It contains examples on how to interface with Usage REST API and endpoint, as well as a sample method of extracting and interpreting that data, and transforming into a form (JSON) for storing it in files.

Note:

The application scope is to simulate a billing adapter scenario and showcase all the Usage APIs available in WAP for a typical billing system to consume. Here in the sample the transformation of WAP usage data and loading into external billing system is not in scope as it varies from customer to customer and so we recommend to use the sample as a reference material in building the end-to-end billing adapter solution.

The Purpose of Sample Billing Adapter Code:

While most customers are able to develop their custom billing adapter for WAP using the published WAP Developer Kit (Windows Azure Pack Usage Service) document, we still see many customers asking for sample code that implements specific use cases which can be used as an example to refer and extend to real world use case scenarios. Also, there are requirements where customers want to know more details behind implementing the WAP Usage and Notification APIs for the external systems (Billing Adapter) implementation. The sample delivered here mainly addresses these objectives as scope and complements the information that is available in the WAP Developer Kit documentation, so for any latest up-to-date information on the WAP Developer Kit, refer to the product documentation.

The Scenarios covered in Sample Billing Adapter Code:

The sample billing adapter code covers the following scenarios:

The Input

Reads initial usage and notification counters from a file configured in web.config using the below parameter:

• •       <add key="UsageCounterData" value="UsageCounter.json" />

For Notification API Integration

Reads the following usage and notification data using REST API from all the resource providers registered in WAP:    

• • Plan – Contains Plan data created and deleted by WAP Administrator
  • AddOn – Contains AddOn data created or deleted by WAP Administrator
  • PlanAddOn – Contains AddOn data created or deleted on a Plan by WAP Administrator
  • PlanService – Contains resource provider data created, updated or deleted on a plan by WAP Administrator
  • AddOnService – Contains resource provider data created, updated or deleted on an AddOn by WAP Administrator
  • Subscription – Contains Subscription data created, updated or deleted on a Plan by WAP Tenant
  • SubscriptionAddOn – Contains Subscription data created or deleted on an AddOn by WAP Tenant

For Usage API Integration

Reads usage data for all resource providers from WAP using REST API

• • Usage – Contains the usage metrics for all the resource providers (VM Cloud, Web Cloud, …) registered in WAP

The Output

Output from the above Notification and Usage APIs are processed as below:

• • Each of the above data is stored (appended) in a separate file matching the Usage or Notification type (Usage, Plan, Subscription, etc.,) for that date in JSON format.
  • Updates the usage counter for reading the next set of usage and notification data (new data only) in the next polling interval (Repeats from “The Input” phase)

Note: “The Output” logic can be modified or replaced with other custom logic such as loading into the external system etc., depending on the requirement.

The Log

Logs are written into the Event Log and the Text file and the detail is as below:

• • Events are logged into “Application” event log under the name of “Sample Billing Adapter”. Some specific events that are logged in are the polling of Usage endpoint and the number of records read in that polling. If there is any error in the polling then it is logged in the same Application event log.
  • Log file counter to log the counters for Usage and Notification records read from the Usage endpoint on each polling

The Parts of Sample Billing Adapter Code:

The sample billing adapter code contains the following two parts in the Visual Studio (VS) project:

1. BillingPreloadClient.cs – Has a timer logic that triggers the Notification and Usage data process at the specified interval which is configurable using the parameter “BillingWorkerPeriod” in “web.config” file. The default is set to five minutes.
2. BillingService.cs – Has logic to read the Notification and Usage data and saves them in a file for that date and updates the usage counter for reading the next set of data in an incremental way.

The Billing Service implements the processing logic for extracting the Usage and Notification data which can be extended to implement other custom logic to integrate the data with external systems. By separating the data extraction logic from the custom code logic helps to maintain the code for each layer independently and add any extra functions as needed for the external system integration.

In a nutshell, the sample billing adapter when implemented using WAP, it looks and connects to the WAP Usage Service as depicted in the diagram below:

Sample Notification and Usage Data (for Reference only)

The sample data below is for reference only to show how the JSON output looks for the Usage and Notification data from the WAP.

Usage:

Plan:

Log file counter (Sample output)

More Information about Sample Billing Adapter Code:

The sample billing adapter code contains the following deliverables in it:

• Documents Folder: Contains the following two documents that describes about the source code, build and deploy the build to web server based on Internet Information Server (IIS).

• Readme for Billing Adapter sample (WAP version).docx – This document describes the source code details on the billing sample (Billing.csproj) VS project
• Readme for Deploying Billing Adapter sample (WAP version).docx – This document describes the deployment details on the sample Contoso Portal

• Source Folder: Contains the following folder for the source code

• WAPBillingAdapter – This folder contains the source code for the sample Contoso Portal (Billing.csproj) VS project

• Download Location: You can download the documents and source files from the following TechNet Gallery site.

Additional References:

• Windows Azure Pack Developers Kit
• Windows Azure Pack: Service Management API Samples