Compound Aggregations
Compound Aggregations allow you to derive numerical measures from usage data by applying a calculation to one or more simple Aggregations. The calculation can also reference Custom Fields. You can then use these calculated measures as pricing metrics to set up usage-based pricing Plans for your Products. In this way, Compound Aggregations can help you to implement a wide range of pricing use cases for your Products.
This topic starts off by explaining the difference between Product-specific and Global Compound Aggregations:
The topic then illustrates the value of using Compound Aggregations with a usage-based pricing example, and explains how to create a Compound Aggregation to apply a calculation to simple Aggregations to satisfy the example pricing use case:
The final section provides helpful guidance on rules that apply to Compound Aggregations for referencing simple Aggregation values and the corresponding syntax you must use:
Creating Simple Aggregations? We strongly recommend that you create some simple Aggregations and are familiar with their purpose and their configuration as helpful preparation to creating and using Compound Aggregations. See Reviewing Aggregation Options.
Tip: Compound Aggregations - the "Complexity Crunchers" - see more! By exploiting the powerful m3ter Calculation Engine, there's virtually no limit to the flexibility Compound Aggregations give you for defining your precise pricing metrics. To see some worked examples of Compound Aggregations that illustrate how Compound Aggregations can quickly help you resolve complex UBP use cases, please review the Compound Aggregations - Examples and Syntax topic.
Product vs. Global Compound Aggregations
You can create Product Compound Aggregations, which belong to a specific Product, or Global Compound Aggregations, which are not tied to a specific Product:
You can use a Product Compound Aggregation to price only those Plans that belong to the same Product.
You can use a Global Compound Aggregation to price Plans belonging to any Product.
Note: Referencing Simple Aggregations in Product/Global Compound Aggregation Calculations! The simple Aggregations you can reference in the calculation for a Product-specific Compound Aggregation or a Global Compound Aggregation are the same - for details, see below Compound Aggregations - Referencing Values and Fields and Supported Syntax.
Example Use Case
Suppose you provide a service which allows your customers to develop and run software applications and host these applications on your service. You intend to charge customers for this application build-and-host service by total number of requests made to all of their applications being hosted in any given billing period. However, you want to offer customers a sign-up bonus for their first year of using your service, where the first 100 requests made to an application they host with you are free for each billing period - for example, if a customer has 3 applications hosted with you during the first billing period, they are due 300 free requests for the first Bill.
To set things up in m3ter to implement usage-based pricing for this type of case, you can use a Compound Aggregation:
First, create and configure a Meter which will record the number of applications hosted. You can send an event into m3ter each time one of your customers creates and loads an application into your service. Use this Meter field to create a simple Aggregation to give a Maximum value measure for hosted applications. Give this simple Aggregation a code of: unique_apps. (Note that for the example, we suppose that under the terms of the sign-up bonus if a customer reaches 5 applications in any given billing period, they are granted 500 free requests even if 2 of those applications are disabled before the end of the billing period.)
Second, create and configure a Meter to record the number of requests made by applications. You can then create a second simple Aggregation to Sum this data. Give this simple Aggregation a Code of: num_requests.
Third, create a Compound Aggregation that applies a calculation to the two simple Aggregations to give a number for chargeable requests:
Math.max(0, aggregation.num_requests - (aggregation.unique_apps * 100))
When you come to price up your Product Plans, you can now use this Compound Aggregation.
Important! Compound Aggregation Calculations Use Base Values of Simple Aggregations. If a simple Aggregation referenced by a Compound Aggregation has a Quantity per unit defined for pricing and billing purposes or a Rounding defined, then these will not be factored into the value used by the calculation. For example in this case, if the num_requests simple Aggregation referenced has a base value of 100 and has Quantity per unit set at 10, the Compound Aggregation calculation will use the base value of 100 not 10.
Tip: Calculation Expression - Referencing simple Aggregations and Supported Syntax? For details of how to reference the values of simple Aggregations in calculation expressions and the supported syntax, see below Compound Aggregations - Referencing Values and Fields and Supported Syntax.
Creating a Compound Aggregation
This section explains how to create a new Product Compound Aggregation for the example use case outlined above, and assumes the two simple Aggregations used have already been created for the same Product.
To create a Compound Aggregation:
1. Select Metering>Compound Aggregations. The Compound Aggregations page opens.
2. In the Product drop-down, select the Product for which you want to create the new Compound Aggregation. The Compound Aggregations page adjusts and lists:
Any existing Compound Aggregations created for the selected Product.
Any Global Compound Aggregations, which are clearly labeled.
Tip: Global Compound Aggregation? If you want to create a Global Compound Aggregation, which is not tied to a specific Product and which you can then use to price any of your Products, remove the selection - (Global) will then show for Product and the Compound Aggregations page will adjust to show only existing Global Compound Aggregations. When you select to Create Compound Aggregation, on the Create page the Product field will also then show (Global).
3. Select Create Compound Aggregation. The Compound Aggregations>Create page opens.
4. Enter the Compound Aggregation Details:
Name. For this example, enter a descriptive name, such as Requests minus free.
Code. Unique identifier. For this example, we've used requests_minus_free:
5. Enter the Compound Aggregation Settings:
Calculation. First select Advanced if you want to enter a specific calculation. The form adjusts to show a text entry box. Enter the expression for the required calculation referencing simple Aggregations:
Math.max(0, aggregation.num_requests - (aggregation.unique_apps * 100))
Important! Compound Aggregation Calculations:
Calculations Use Base Values of Simple Aggregations. If a simple Aggregation referenced by a Compound Aggregation has a Quantity per unit defined for pricing and billing purposes or a Rounding defined, then these will not be factored into the value used by the calculation. For example in this case, if the
num_requestssimple Aggregation referenced has a base value of 100 and has Quantity per unit set at 10, the Compound Aggregation calculation will use the base value of 100 not 10.Referencing Custom Fields with the same name in Calculations. If you intend to reference a Custom Field on an Account Plan in a Calculation for a Compound Aggregation used to Price Plans attached to an Account for billing, please ensure to use different names for any Custom Fields if there is more than one Account Plan attached to the Account. For example, you have two Account Plans attached to an Account and the Calculation used by the Compound Aggregation is designed to use a value from a Custom Field on one of the Account Plans. However, you have created Custom Fields with the same name but different values on each of the two Account Plans. The Calculation is then be unable to distinguish which value to use and billing charges will be unpredictable.
Tip: Add Aggregations? If you want to create a Compound Aggregation by merely adding two or more simple Aggregations, you can leave the selection at the default Add Aggregations. You can then use a drop-down to select the simple Aggregations you want to add together. Note that Add Aggregations is searchable - if your start to type the name of a simple Aggregation, the list of available simple Aggregations is filtered.
Unit. For this example, enter Requests. This will be used as a label for billing to indicate to your customers what they are being charged for.
Quantity per Unit. Enter the quantity by which you want to charge for the measured value. For example, if you want to charge your customers on a per-500 units used basis, enter 500. For the current example, enter 1.
Rounding. Specifies how you want m3ter to deal with non-integer, that is fractional number, Aggregation values. See Reviewing Aggregation Options for example. Four options:
None. Default
Down
Up
Nearest. Rounds up to the nearest half: 5.1 is rounded to 5; 5.5 is rounded to 6.
Note: Also used in conjunction with Quantity per unit setting. Rounds the number of units after the Quantity per unit has been applied. See Reviewing Aggregation Options for example.
Evaluate Null Aggregations. Optional setting - enable this if you want to allow null values from the simple Aggregations referenced in the Compound Aggregation to be passed in. Simple Aggregations based on Meter Target Fields where no usage data is available will have null values. Default is to have this disabled:
Tip: Set Default Values of Simple Aggregations to 0. If any of the simple Aggregations you reference in your Compound Aggregation calculation might have null values, you must set their Default Value to 0. This ensures that any null values passed into the Compound Aggregation are passed in correctly with value = 0.
6. Add any required Custom Fields to the Compound Aggregation. For more on Custom Fields, see Adding and Editing Custom Fields. We strongly recommend reviewing Working with Custom Fields before you create and use Custom Fields.
Important! Compound Aggregation Custom Fields not supported for calculations. Creating Custom Fields for Compound Aggregations is intended to support financial reporting use cases. Although you can define Custom Fields at both the Organizational level and individual Compound Aggregation level, they are not supported for use in Derived Field and Compound Aggregation calculations.
7. Select Create Compound Aggregation. The Compound Aggregation Details page opens:
Any new Compound Aggregations you've created become immediately available for pricing up your Product Plans. See Pricing Plans and Plan Templates.
Important: Create Simple Aggregations First! If you try to create a Compound Aggregation and you enter a Calculation that references a simple Aggregation that you have not yet created for your Product, you won't be able to save the Compound Aggregation and an error message will show.
8. If you want to edit a Compound Aggregation's details, select the Edit button, make your changes, and click Update.
9. If you want to remove a Compound Aggregation, return to the Compound Aggregations page and select the Delete button for the Compound Aggregation:
A confirmation popup opens.
10. Select Yes to confirm the delete action.
Compound Aggregations - Referencing Values and Fields and Supported Syntax
This section explains the syntax for referencing simple Aggregation values and Custom Fields in your Compound Aggregation calculations.
Tip: Full Details? Before you start to write Compound Aggregation calculations, we recommend you review the full details of the syntax and supported functions, variables, and operators you can use in you Compound Aggregation calculations at: Calculations Syntax and Supported Functions/Operators.
Referencing Simple Aggregation Values
You can reference the resultant values of simple Aggregations in a Compound Aggregation calculation using a simple Aggregation's Code. The general format is:
aggregation.<aggregationCode>
The simple Aggregations you can reference when you create a Product-specific Compound Aggregation or a Global Compound Aggregation are the same:
The calculation can reference all simple Aggregations – any Product-specific and any Global simple Aggregations.
Referencing Segmented Aggregation Values
You can also reference Segmented Aggregations in a Compound Aggregation. The segments defined for the referenced Segmented Aggregations that are made available for the Compound Aggregation depends on whether it references one or multiple Segmented Aggregations. For details with an example, see Compound Aggregations - Segments Available.
Compound Aggregations - Referencing Custom Fields
You can reference the default values for Custom Fields - those defined at Organization level - in your Compound Aggregation calculations:
organization.<fieldName>meter.<fieldName>product.<fieldName>account.<fieldName>accountPlan.<fieldName>plan.<fieldName>planTemplate.<fieldName>
Tip: More on Custom Fields? See Adding and Editing Custom Fields and Working with Custom Fields.
Additional Support
Login to the Support portal for additional help and to send questions to our Support team.