Cello How-To Guide · How-To – Usage Metering Add the messageInspectorBehavior endpoint behavior...

Cello How-To Guide

Usage Metering

2

How-To – Usage Metering

Contents 1 Metering the Usage ..................................................................................................................................... 3

1.1 Overview of the Usage Metering System ............................................................................................ 3

1.2 How usages are measured? ................................................................................................................. 3

1.3 How to register usages? ....................................................................................................................... 4

1.4 Understanding Metering Variable ....................................................................................................... 4

1.4.1 Register Metering Variable using API .............................................................................................. 5

1.4.2 Meter Usage: Block Status ............................................................................................................... 6

1.4.3 Meter Usage : Block Types ............................................................................................................... 7

1.5 Metering APIs ....................................................................................................................................... 7

1.5.1 Increment Usage – Example 1.......................................................................................................... 7

1.5.2 Increment Usage – Example 2.......................................................................................................... 8

1.5.3 Decrement Usage ............................................................................................................................. 8

1.5.4 Reset Usage ...................................................................................................................................... 8

1.5.5 Usage Audit ...................................................................................................................................... 9

1.5.6 Usage Audit APIs .............................................................................................................................. 9

1.5.6.1 To get the usage amount for a given period .................................................................................... 9

1.5.6.2 To get the usage amount for a given period .................................................................................. 10

1.5.6.3 Metering Search Condition Model ................................................................................................. 10

1.5.6.4 Metering Search Condition Model ................................................................................................. 11

1.5.6.5 To get the usage count for a given Tenant .................................................................................... 11

1.5.6.6 To get the usage log details ........................................................................................................... 11

1.6 Configure Metering Service ............................................................................................................... 12

1.6.1 Steps to configure metering component for Web Service Calls .................................................... 12

1.6.2 Steps to configure metering component for InProc Calls .............................................................. 13

2 Contact Information ................................................................................................................................... 14

3


1 Metering the Usage

Applications providers cannot successfully monetize their services in the absence of a system that tracks and

reports on tenant utilization. CelloSaaS provides Usage Metering Engine which audits the

transactions/usages done by the Tenants. These Metered data will act as the base for billing for tenants who

have chosen Pay per use model.

1.1 Overview of the Usage Metering System

Cello Metering Engine uses Usage Variables, a flag configured for each Feature or module which requires

metering capability. These Flags will be incremented upon successful consumption of a feature.

1.2 How usages are measured?

Usages are measured in units, whenever a functionality is used or data transacted once it can be considered

as 1 unit of usage, but there is no thumb rule of unit consideration ie, for certain scenarios, multiple

transactions can be considered as 1 unit of usage. For Cello Metering service to track of the usage, the

developer has to call the usage auditing service and increment/decrement the usage to 1.

Based on the frequency of the billing, the threshold will be reset to 0 in case of post-paid, else reset to the

threshold amount i.e. 10000 or whatever maybe the usage count in case of pre-paid model.

Example:

Feature Name Description Usage Variable Consumption

Create Employee Feature used to create an

employee

Create_Employee 0

Apply Leave Feature used to Apply Leave Apply_Leave 0

These usages could be either incremented or decremented based on billing mechanism.

On successful consumption of these Features, developers have to call the Cello Metering APIs and Increment

the usage counters based on the number of transactions. Click here for more information about the

metering APIs.

http://techcello.com/downloads/apiguide/html/Methods_T_CelloSaaS_BusinessEdition_ServiceProxies_LicenseManagement_MeteringProxy.htm

4


1.3 How to register usages?

CelloSaaS utilize Metering variables to keep track of the Customer’s usages. These variables are flags

mapped against each module/feature in the application. In the below illustration, a module contains multiple

usages such as Usage-1, Usage-2.....Usage-n.

1.4 Understanding Metering Variable

Usage Variables are the base for metering the transactions by the Tenants. These usage variables has to be

identified during the development time itself against each and every module based on the metering

requirement of the application.

Example:

Let’s Consider a SaaS based Recruitment Solutions offered in Pay as you go model. Below are some of the

Features provided by the Solution? They are

1. Job Posting

2. Job Opening

3. Send Email to Candidate etc

The Product owner would like to capture the usage of these features by every Tenant and invoice them

accordingly.

To achieve the above scenario with Cello Billing Engine, the developer has to first register these variables

against the respective features and Modules in the CelloSaaS Metadata.

5


1.4.1 Register Metering Variable using API

The Metering Variables can be registered using Fluent API along with Modules and Feature Configuration, to

know more about Package Configurations, Refer “How to register application specific Modules” in Package

Management Topic.

Once the Metering variables are registered, compiled and run, the create package screen will be

automatically updated with variables [Refer the below Screenshot]

1. Navigate to Subscription Manage Package Click on Create

2. Scroll down to the bottom of the page and look for “Set usage Maximum Capacity”.

Create Subscription Page

6


Create Price Plan

1.4.2 Meter Usage: Block Status

Block Status refers to the state of the Usage once the set threshold has been exhausted by the Customer.

The usage block status can be anyone of the following statuses, they are

Status Description

WithinLimit Usage limit is not exceeded.

OverUsageAllowed Usage limit is exceeded but this usage has over usage limit set to true.

CrossedLimit Usage limit is exceeded and doesn’t have over usage limit.

1. If the usage type parameter is “BlockUsage” then the return status are below

2. If method returns CrossedLimit, then you should not continue the process instead throw an exception

like “Your usage limit exceeded”.

7


Note: If method returns CrossedLimit, then you should not continue the process instead throw an exception

like “Your usage limit exceeded”.

1.4.3 Meter Usage : Block Types

Block Types refers to type of usage block that you want to enforce once the usage threshold set for the

edition is exhausted.

The Types of Block Types are

BlockUsage – Regular Usage Threshold setup, once the customer reaches threshold no action

will be taken against the user, it is the responsibility of the developer to either allow or disallow

the user from accessing the application further.

Cumulative – The usage will be continuously incremented or decremented based on the

configuration and no action will be taken against reaching the threshold.(Recommended for the

long term Subscriptions i.e Half Yearly or Yearly)

1.5 Metering APIs

1.5.1 Increment Usage – Example 1

Namespace: CelloSaaS.ServiceContracts.LicenseManagement

Assembly: CelloSaaS.ServiceContracts (in CelloSaaS.ServiceContracts.dll)

bool IncrementMeterUsage(string tenantId,string usageCode,double amount)

Example

public void IncrementMeterUsage()

{

string tenantId = UserIdentity.TenantID;

string usageCode = "SampleUsage";

double amount = 1.0;

IMeteringService meteringService =

ServiceLocator.Resolve<IMeteringService>();

bool incrementedUsage = meteringService.IncrementMeterUsage(tenantId,

usageCode, amount);

}

http://techcello.com/downloads/apiguide/MeteringService/N_CelloSaaS_ServiceContracts_LicenseManagement.htm

8


1.5.2 Increment Usage – Example 2

1.5.3 Decrement Usage

1.5.4 Reset Usage

.



bool DecrementMeterUsage(string tenantId,string usageCode,double amount)

Example

public void DecrementMeterUsage()

{


string usageCode = "SampleUsage";

double amount = 1.0;

IMeteringService meteringService = ServiceLocator.Resolve<IMeteringService>();

bool incrementedUsage = meteringService.DecrementMeterUsage(tenantId, usageCode,

amount);

}



/// Resets the meter usage amount to 0.

[OperationContract]

[WebInvoke(Method = "POST", UriTemplate = "/ResetMeterUsage", BodyStyle

= WebMessageBodyStyle.Wrapped)]

bool ResetMeterUsage(string tenantId, string[] usageCodes);

public bool ProcessInvoice(InvoiceDetails entity)

{

string status = LicenseProxy.ValidateUsageLicense("BlockUsage", “ToDoUsage", 1, UserIdentity.TenantID);

if (!LicenseConstant.WithinLimit.Equals(status) && !LicenseConstant.OverUsageAllowed.Equals(status))

{

throw new InvoiceException("Your usage limit is exceeded.");

} else {

// process invoice

// …

// finally increment the usage amount

MeteringProxy.IncrementMeterUsage(UserIdentity.TenantID, " ToDoUsage ", 1.0);

}

}



9


1.5.5 Usage Audit

The usage audit keeps track of each and every action done by each tenant in the application when the

metering and billing is enabled as per the subscription owned by the Tenant. These audit data is stored in the

Cello Audit metadata. As a Policy, CelloSaaS will not stop the tenants from using the application even after

crossing the set usage limit; it is the responsibility of the developer to call the respective API to validate

whether a customer has reached the usage limit as per the subscription and stop allowing the user from

accessing a Feature or module.

To View the Usage Audit Information, Navigate to Monitor Usage

1.5.6 Usage Audit APIs

1.5.6.1 To get the usage amount for a given period



Dictionary<string, double> GetUsageAmount(

string[] usageCodes,

DateTime fromDate,

DateTime toDate,

string tenantId

)

Example

public void GetMeterUsage()

{


string usageCode = "CompanyUsage";



double usageAmount = meteringService.GetMeterUsage(tenantId, usageCode);

}


10


1.5.6.2 To get the usage amount for a given period

1.5.6.3 Metering Search Condition Model


Service Contract: IMeteringService

/// Returns current usage amount used by the tenant.

/// <param name="searchCondition">The search condition.</param>

/// <returns></returns>

UsageSearchResult SearchUsageDetails(UsageSearchCondition searchCondition)

/// Searches the usage metering log

/// <param name="meteringSearchCondition">search condition</param>

/// <returns></returns>

MeteringSearchResult SearchMeteringLog(MeteringSearchCondition meteringSearchCondition)

public class MeteringSearchCondition { /// <summary> /// Gets or sets the Tenant Identifier public string TenantId { get; set; } /// <summary> /// Gets or sets usag code public string UsageCode { get; set; }

/// <summary> /// Gets or sets the identifier of user who created log public string LoggedBy { get; set; } /// <summary> /// Gets or sets the Start Date public DateTime StartDate { get; set; } /// <summary> /// Gets or sets the Start Date public DateTime EndDate { get; set; } /// <summary> /// Sort Column name public string SortString { get; set; } /// <summary> /// Sort Direction public string SortExpression { get; set; } /// <summary> /// Set Total Count of records found by the search criteria public bool SetTotalCount { get; set; } /// Page number to fetch /// </summary> public int PageNumber { get; set; } /// Page Size to fetch public int PageSize { get; set; } }

11


1.5.6.4 Metering Search Condition Model

1.5.6.5 To get the usage count for a given Tenant

1.5.6.6 To get the usage log details



double GetMeterUsage(

string tenantId,

string usageCode

)



Dictionary<string, List<MeteringLog>> GetMeteringLogDetails(

string tenantId,

Nullable<DateTime> startDate,

Nullable<DateTime> endDate

)

Example:

public void GetMeteringLogDetails()

{

string tenantId = "B590CD25-3093-DF11-8DEB-001EC9DAB123";

DateTime? startDate = Convert.ToDateTime("4/1/2010");

DateTime? endDate = Convert.ToDateTime("4/15/2010");



Dictionary<string, List<MeteringLog>> meteringLogDetails =

meteringService.GetMeteringLogDetails(tenantId, startDate, endDate);

}

public class UsageSearchCondition

{

/// Gets or sets the tenant id.

public string TenantId { get; set; }

/// Gets or sets the usage codes.

public string[] UsageCodes { get; set; }

/// Gets or sets the module codes.

public string[] ModuleCodes { get; set; }

}



12


1.6 Configure Metering Service

CelloSaaS offers you to configure metering feature to any of your business service just with XML

Configurations without changing the code.

1.6.1 Steps to configure metering component for Web Service Calls

A WCF service named InvoiceService which has an operation named ProcessInvoice. In order to meter the

operation by incrementing the “ToDoUsage”. Let’s make changes in the configuration to achieve this.

Step 1: Open EntityPermissions.config file and add the below xml configuration.

Step 2: Open Web.config file and make the below changes inside system.serviceModel section.

<add name="BL">

<Entity>

<add name=”YouApp.ServiceContracts.IToDoService”> // Your Service Contract method

<EntitySubElement>

<add name="ProcessToDo" UsageCode=“ToDoUsage" UsageMode="Increment"/>

</EntitySubElement>

</add>

</Entity> </add>

<extensions>

<behaviorExtensions>

<add name="messageInspector" type="CelloSaaS.Services.WCF.LoggingBehaviorExtensionElement, CelloSaaS.Services" />

<add name="meteringInspector" type="CelloSaaS.Services.WCF.MeteringExtensionElement, CelloSaaS.Services" />

</behaviorExtensions>

</extensions>

<behaviors>

<endpointBehaviors>

<behavior name="messageInspectorBehavior">

<messageInspector />

<meteringInspector/>

</behavior>

</endpointBehaviors>

</behaviors>

13


Add the messageInspectorBehavior endpoint behavior to your business WCF Service endpoints.

The meteringInspector watches every WCF calls and whenever the configured Operation call is

matched, it Increments/Decrements the specified Usage in the system

1.6.2 Steps to configure metering component for InProc Calls

Similar to Metering WCF Service Call, In-Proc service calls can also be metered via configuration.

Step 1: Navigate to policyInjection.config file under the WebApp folder and make the below changes.

Add the necessary business service contracts to the above matchingRules. And create your business service instance using the below code.

IInvoiceService invoiceService = ServiceLocator.Resolve<IInvoiceService>(); invoiceService.ProcessInvoice(invoiceEntity); Note: Configuration based metering has its disadvantage like the usage is incremented/decrement regardless the method fails due to some reason.

<add name="Application Metering">

<matchingRules>

<add type="Microsoft.Practices.EnterpriseLibrary.PolicyInjection.MatchingRules.NamespaceMatchingRule, Microsoft.Practices.EnterpriseLibrary.PolicyInjection" name="Namespace Matching Rule">

<matches>

<add match=" YouApp.ServiceContracts.IInvoiceService" ignoreCase="false" />

<add match=" YouApp.ServiceContracts.IProductService" ignoreCase="false" />

</matches>

</add>

</matchingRules>

<handlers>

<add name="Metering Handler" type="CelloSaaS.Services.MeteringCallHandler, CelloSaaS.Services" />

</handlers>

</add>

14


2 Contact Information Any problem using this guide (or) using Cello Framework. Please feel free to contact us, we will be happy to

assist you in getting started with Cello.

Email: [email protected]

Phone: +1(609)503-7163

Skype: techcello

mailto:[email protected]

Date post:	22-May-2020
Category:	Documents
Upload:	others
View:	8 times
Download:	0 times

Cello How-To Guide · How-To – Usage Metering Add the messageInspectorBehavior endpoint behavior...

Documents