About the Billing Adapter Core Engine Sample Files
Applies To: Windows Azure Pack
The Windows Azure Pack billing adapter sample consists of a billing adapter core engine and system specific code for interacting with a specific billing system. The sample files are in the Billing folder. This topic discusses the billing adapter core engine project sample source code. The billing adapter core engine sample files are under the BillingAdapter\Billing folder in the Windows Azure Pack samples package. For information about the system specific sample source code, see About the Billing Adapter System Specific Sample Files.
BillingAdapter
The billing adapter engine has four "sub-engines", each providing a different functionality. Each sub-engine is completely orthogonal to other sub-engines, meaning that each has its own configuration and each can be enabled\disabled without affecting other sub-engines. The billing adapter engine project provides four strongly typed interfaces matching each of the sub-engines. The system-specific implementation can choose to implement part or all of the interfaces and enable\disable the matching sub-engines according. When implementing the pricing responder interface, the billing approval responder interface must also be implemented.
The four interfaces are
IBillingNotificationProcessor
IBillingUsageProcessor
IBillingSubscriptionResponder
IBillingPricingResponder
Interface |
Description |
Source File |
|---|---|---|
Billing Notification Processor |
Provides strongly typed events corresponding to the Windows Azure Pack Usage Service API events. Implement this interface if you want to receive event notifications from Windows Azure Pack and synchronize them to your billing system. Events include plan, add-ons and subscription modifications. For more information about the Usage Service Rest API, see Windows Azure Pack Usage Service Usage REST API Reference. |
IBillingNotificationProcessor.cs |
Billing Pricing Responder |
This interface includes strongly typed events to respond to real-time pricing queries. Implement this interface if you want to return pricing information from your billing system in Windows Azure Pack. An example of this interface implementation can be found in the HostBill sample. For more information about the pricing Rest API, see Windows Azure Pack Usage Service Pricing REST API Reference. |
IBillingPricingResponder.cs |
Billing Subscription Responder |
This interface includes strongly typed events to respond to blocking billing approval requests. Implement this interface if your billing system includes logic to approve or deny a user creating or deleting plan subscriptions and add-on subscriptions. For more information about the Billing Approval Rest API, see Windows Azure Pack Usage Service Billing Approval REST API Reference. |
IBillingSubscriptionResponder.cs |
Billing Usage Processor |
Provides strongly typed events for retrieving tenant usage records. Implement this interface to retrieve aggregated tenant usage information for all of the Windows Azure Pack resources providers. For more information about the resource provider usage data Rest API, see Windows Azure Pack Custom Resource Provider Usage REST API Reference. |
IBillingUsageProcessor.cs |
Controllers
The billing adapter core engine provides two sub-engines (Billing Pricing Responder and Billing Subscription Responder) to listen to incoming requests from the Windows Azure Pack system. These requests are handled by the Web API controllers in the Controllers folder. These controllers convert the incoming REST requests into strongly typed events and send them to the appropriate interface implementation (IBillingSubscriptionResponder and IBillingPricingResponder).
Event Notification and Usage Record Processing
Each of these is a scheduler that periodically wakes up and queries the Windows Azure Pack system for new information, converting it to strongly typed events and calls the matching event on the appropriate interface (IBillingNotificationProcessor or IBillingUsageProcessor). Both schedulers perform a similar logic:
Make sure the current processor is currently the master. If not, they sleep for a predefined time. See the app.config section for more information.
Retrieve the current state from the state store.
Read new events from the Windows Azure Pack system.
Convert the events to strongly typed events and invoke the system-specific interface implementation.
Handle any errors.
Billing Pricing Responder
To report errors from the IBillingPricingResponder implementation, two exception objects are provided, PricingNotFoundException and PricingUnknownException, which can be used to indicate that the requested product was not found or there is no pricing information for this product.
Configuration
The billing adapter uses the app.config file to change the billing adapter settings. After a successful build, the app.config file will be placed next to the billing adapter executable and the file renamed to have the same name as the billing adapter executable with an additional .config suffix (for example, Microsoft.WindowsAzurePack.Samples.Billing.exe.config). Modifying this file requires restarting the billing adapter process.
Note
The app.config file contains the settings for both the billing adapter core and the system-specific implementation. If you provide your own system-specific implementation, you can choose to store your system-specific settings elsewhere.
The following describes the settings in the app.config file:
Utilities - App.Config
The file app.config contains fields that can be modified as needed for a billing adapter and Windows Azure Pack deployment. Field changes should be made after compilation and before running the binary. The following describes the key fields.
<connectionStrings>
Connection strings for the database(s) used by the billing adapter. The StateManage connection string is used by the billing adapter core engine to store its internal state. The IdentityMappingManager connection string is used by the system-specific implementation to store mapping between Windows Azure Pack identities and the billing system identities. If you provide your own system-specific implementation, you might not need this database.
<appSettings>
The appSettings section contains the settings for the billing adapter core engine and the system-specific implementation. The settings are grouped, based on their prefix, and control different sub-engines.
The following are the Billing Adapter Assembly settings:
Setting |
Description |
|---|---|
BillingAdapter.Assembly |
The billing adapter assembly containing the system-specific implementation. |
BillingAdapter.Type |
The full name of the type in the BillingAdapter.Assembly which implements the system-specific interfaces. If this type doesn't implement a specific interface, but the matching sub-engine for this interface is enabled, an error will occur and the billing adapter process will not start. |
The following are application settings for the Billing Notification Processor:
App Setting |
Description |
|---|---|
NotificationProcessor.Enabled |
Set to true if implementing the NotificationProcessor interface; this will enable the scheduler for the Notification Processor. |
NotificationProcessor.EndpointBaseAddress |
The Windows Azure Pack event notification REST endpoint URI. The Event Notification Processor will use this endpoint to read event notifications from the Windows Azure Pack system. |
NotificationProcessor.EndpointUsername, NotificationProcessor.EndpointPassword |
Username and password for the Windows Azure Pack Event Notification endpoint. The Event Notification Processor will use these credentials when reading events from the WAP event notification endpoint. |
NotificationProcessor.ReadBatchSize |
The maximum batch size that will be used when reading event notifications from the Windows Azure Pack event notification endpoints. If you experience network performance issues, consider changing this value. |
NotficationProcessor.PollingIntervalSeconds |
The amount of time that the scheduler will sleep between ticks. The scheduler is non-overlapping therefore the sleep period will only begin once a full read is completed. |
NotificationProcessor.ErrorBackoffIntervalSeconds |
After an error, this is the amount of time the scheduler will sleep before retrying. |
NotificationProcessor.IsMasterExpirationInSeconds |
Only one scheduler instance is allowed to run across all processes and machines. This scheduler is called the master. When a scheduler instance is selected to be the master instance, it keeps pinging the state database. If the master database doesn’t ping for a period longer that this value, another scheduler instance will attempt to become the master. The master instance pings the state database only during the scheduler processing (it doesn't ping during scheduler sleeps), therefore, it is recommended that this value be several times greater than the maximum possible sleep time for the scheduler, which is the maximum of NotficationProcessor.PollingIntervalSeconds and NotificationProcessor.ErrorBackoffIntervalSeconds. Setting this value to a too long period will lead to slower master failover. |
The following are application settings for the Billing Usage Processor:
App Setting |
Description |
|---|---|
UsageProcessor.Enabled |
Set to true if implementing the UsageProcessor interface; this will enable the scheduler for the Billing Usage Processor. |
UsageProcessor.EndpointBaseAddress |
The endpoint used by Windows Azure Pack to make the Rest API calls. The sample .config file has a default value, but you will want to specify your own endpoint server. |
UsageProcessor.EndpointUsername, UsageProcessor.EndpointPassword |
Username and password for the Windows Azure Pack Usage endpoint. The Usage Processor will use these credentials when reading events from the Windows Azure Pack Usage endpoint. |
UsageProcessor.ReadBatchSize |
The maximum batch size that will be used when reading event notifications from the Windows Azure Pack event notification endpoints. If you experience network performance issues, consider changing this value. |
UsageProcessor.PollingIntervalSeconds |
The amount of time that the scheduler will sleep between ticks. The scheduler is non-overlapping therefore the sleep period will only begin once a full read is completed. |
UsageProcessor.ErrorBackoffIntervalSeconds |
After an error, this is the amount of time the scheduler will sleep before retrying. |
UsageProcessor.IsMasterExpirationInSeconds |
Only one scheduler instance is allowed to run across all processes and machines. This scheduler is called the master. When a scheduler instance is selected to be the master instance, it keeps pinging the state database. If the master database doesn’t ping for a period longer that this value, another scheduler instance will attempt to become the master. The master instance pings the state database only during the scheduler processing (it doesn't ping during scheduler sleeps), therefore, it is recommended that this value be several times greater than the maximum possible sleep time for the scheduler, which is the maximum of UsageProcessor.PollingIntervalSeconds and UsageProcessor.ErrorBackoffIntervalSeconds. Setting this value to a too long period will lead to slower master failover. |
The following are settings applied to all responders:
App Setting |
Description |
|---|---|
Responders.EndpointBaseAddress |
The local base address for the responders endpoints. The billing adapter will create a listener using this base address. The same base endpoint is used for both responders (the billing adapter engine will append different paths for each responder). If Hypertext Transfer Protocol Secure (HTTPS) is used, an SSL certificate need to be configured out of band on the same port. For more information, see https://msdn.microsoft.com/en-us/library/ms733791(v=vs.110).aspx. |
Responders.EndpointUsername, Responders.EndpointPassword |
Basic authentication credentials for the responders endpoint. |
Responders.Notification.Enabled |
Set to true to activate the subscription responder (Billing Approval API). The billing adapter system-specific implementation must implement the IBillingSubscriptionResponder interface. |
Responders.Pricing.Enabled |
Set to true to activate the pricing responder (Pricing API). The billing adapter system-specific implementation must implement the IBillingPricingResponder interface. |
The following are Billing Adapter application settings:
App Setting |
Description |
|---|---|
BillingAdapter.Assembly |
Path to the billing adapter. |
BillingAdapter.Type |
Path to the billing adapter. If the code here does not match the values set for the “Enable” values in the app.config, there will be an error upon running. |
As an example, the provided app.config contains placeholder setting for both the WHMCS and the HostBill billing systems. In a production deployment, it is not necessary to have both. You should keep the settings matching your billing adapter system-specific implementation. If you implement your own adapter, it is up to you to decide whether to have the settings in app.config or elsewhere (in a database for example).
Some settings to note are:
App Setting |
Description |
|---|---|
WHMCS.ExpectedVersion / HostBill.ExpectedVersion |
Mandatory field. The billing adapter engine will compare this version value to the configured billing system version. If they do not match, it will produce an error and prevent the adapter from running. The purpose of this check is to prevent the billing adapter from operating on an un-tested billing system. |
WHMCS.MySqlConnectionString / HostBill.MySqlConnectionString |
A connection string (with write permissions) to the billing system MySql database. It is used by the adapter system-specific implementation to update the billing system database directly when there is not a matching API call. |
WHMCS.EndpointUsername, WHMCS EndPointPassword |
The WHMCS endpoint username and password. |
HostBill.ApiId, HostBIll.ApiKey |
The HostBill Identifier and API key. |
WHMCS.ProductGroupName, HostBill.CategoryName |
Plans are created under a group\category in the billing systems. This value specified the group\category to be used. The group\category must exist (manually created) prior to running the billing adapter process. |
WHMCS.DefaultCurrencyCode |
Specifies the default currency code for WHMCS when creating new subscription orders. |
WHMCS. DefaultPaymentModule / HostBill.DefaultPaymentModule |
WHMCS.DefaultPaymentMethodModule \ HostBill.DefaultPaymentModule. Specifies the default payment method to be used when placing new subscription orders. |
WHMCS. DefaultBillingCycle / HostBill.DefaultBillingCycle |
Specifies the default billing cycle for new subscription orders, if it is not defined in the user settings. |
WHMCS.EnableUserCreation / HostBill.EnableUserCreation |
In production environments, all Windows Azure Pack users should pre-exist in the billing system. However, for testing scenarios, it might be useful to create users on the fly, if they do not exist in the billing system. When set to True, if a user doesn't exist in the billing system, it will automatically be created when a subscription event is received from Windows Azure Pack. |
WHMCS.EnableOrderMailConfirmation |
Set to true to send a mail confirmation when a subscription is being created. |
Note
In the billing adapter sample, having EnableUserCreation set to True will cause the billing adapter to create user accounts within the billing system “on-the-fly” as it processes events from Windows Azure Pack. If False, it will reject the operations if they are sent via the real-time API, and halt processing if they are found in the Rest API.
A true provider would have an identity management system in place to control user account creation. Ideally, this would occur before clients are allowed to purchase subscriptions within Windows Azure Pack, and the billing adapter should never encounter an operation for a user account that does not exist in the billing system.
In order to make the billing adapter sample work “out-of-the-box” this option is provided to create user accounts as the sample processes events. Accounts are created with an email address only. All other fields are empty.