About the Billing Adapter Sample

Applies To: Windows Azure Pack

The Billing Adapter Sample is a Microsoft Visual Studio 2012 solution available from https://www.microsoft.com/en-us/download/details.aspx?id=41146. The sample architecture comprises of two parts - a billing adapter core engine and a system specific billing adapter component. The core engine interacts with the Windows Azure Pack Billing API and provides easily consumable interfaces. The system-specific component is composed of a client that communicates with the actual billing system coupled with implementations of select interfaces from the core engine. Two system specific billing adapters and clients are provided for - WHMCS and HostBill. For any other billing system, a new implementation should be created.

The core engine has its own database to maintain state and support failure recovery. The two system-specific examples provided by the sample include databases to provide identity mapping support. These databases are implementation specific and might not be required when creating your own billing adapter implementation.

General Sample Observations

• The billing adapter can be run as a Windows service or as a console application. For more information, see How to Build and Run the Billing Adapter Sample.

• The billing adapter can be hosted anywhere, as long as it can connect to the Windows Azure Pack billing APIs and to the billing system. If any of the responders are used (Blocking API or Pricing API) then the Windows Azure Pack should also be able to access the billing adapter.

• The billing adapter core engine provides a strongly typed interface to handle metered usage. However, neither of the billing systems implemented in this sample provide metered usage out of the box without acquiring additional add-ons.

Aspects of the Core Engine

The following describes aspects of the core engine. For information about the sample project, see About the Billing Adapter Core Engine Sample Files

Simplification & Abstraction

The core engine abstracts the complexity of the Billing Rest API into an easy-to-use interface by strongly typing the information gathered via the Usage Rest API. For more information about the Usage Rest API, see Windows Azure Pack Usage Service Usage REST API Reference.

Error Handling

The core engine abstracts errors from the system specific implementation by performing any retries internally. For errors originating from Windows Azure Pack (which are considered temporary errors, such as a network failure), the core engine will keep retrying until a successful response is returned. For errors originating from the billing adapter (which might be either temporary or permanent), the core engine will retry up to five times. After five times, the error will be considered as permanent and the core engine will stop the processing engine, waiting for the system administrator to analyze the error and manually fix it. The core engine writes the error messages to the Microsoft Windows Event Log. The engine sleeps for a predefined time between retry attempts. For information about app.config, see About the Billing Adapter Core Engine Sample Files.

High Availability & Master/Slave Selection

For high availability and scalability purposes, it is possible to deploy the billing adapter on multiple machines. All responders (blocking API and pricing API), if enabled, will run on all instances. Master & slave selection will ensure that only one instance of each processor (notification events and usage records), if enabled, will run at a time, across processes and machines.

Logging

Logs can be viewed in Microsoft Event Viewer. They are available in the Microsoft-WindowsAzurePack.BillingAdapter channel under the Applications And Services Logs section.

State Management

The billing adapter engine keeps the required state in its own database, so that it can recover from failures. This ensures that already "commited" events (which were successfully processed by the system specific implementation) will not be processes more than once.

Aspects of the System Specific Components

The sample includes two billing system specific implementations (for WHMCS and HostBill billing systems). If you have a different billing system, you are required to provide your own implementation of the billing adapter interfaces. When writing your own implementation, some guidelines need to be followed (see below). These guidelines are demonstrated in the provided system specific implementations, therefore, it is recommended to use one of the existing implementations as template and modify them according to your needs.

Handling Retries

Code should be idempotent/re-entrant. If an error occurs while processing a request, the billing adapter engine will attempt to deliver the request again. The implementation should be able to handle retry attempts and clean\fix half handled events. The included sample implementations check the current billing system state before trying to make a modification to the billing system. They also leverage a mapping database to discover if an event was already processed successfully.

Aspects of the HostBill and WHMCS Sample

Both sample implementations interact with the billing system database directly (due to a lack of required API calls). The billing system database internal structure might change between versions, which means that the sample implementations might break. The WHMCS sample implementation was tested on WHMCS version 5.2.7 and the HostBill implementation was tested on HostBill version 4.9.8. If your billing system version is different, you should re-test current implementations for compatibility. The provided implementations read the expected version from the app.config (for more information about app.config, see About the Billing Adapter Core Engine Sample Files) and will not run if the billing system version does not match the expected version.

Both implementations implement event notification processing and blocking API responders. HostBill also implement the pricing responder.

See Also

About the Billing Adapter Core Engine Sample Files
About the Billing Adapter System Specific Sample Files