Working with Compound Aggregation Calculations - m3ter Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

For many usage-based pricing use cases, you can use Compound Aggregation calculations to reference one or more simple Aggregations and resolve complex pricing requirements - they’re the complexity crunchers! By exploiting the powerful m3ter Calculation Engine, there’s virtually no limit to the flexibility they give you for defining the precise pricing metrics you need. And it’s worth noting that you can create a Compound Aggregation that does not reference a single simple Aggregation, giving you a pricing metric not determined by metered usage, but is nevertheless essential for your complex, mixed-pricing use case. This topic explains the different types of field you can reference in your Compound Aggregation calculations and the correct formats for those field references:

• Referencing Simple Aggregation Values
• Referencing Custom Fields in Compound Aggregations
• Referencing Bill Period Values

Important! If you’re reviewing this topic for help in using Compound Aggregation calculations, please also see further details of the operators, variables, functions, and type casts at m3ter Calculation Engine.

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.

You can reference Segmented Aggregations in a Compound Aggregation. The segments defined for the referenced Aggregations that are made available to the Compound Aggregation depend on whether it references one or many Segmented Aggregations - see Compound Aggregations - Segments Available.

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, if a simple Aggregation referenced has a base value of 100 and has a Quantity per unit set at 10, any Compound Aggregation calculation that references it will use the base value of 100 and not 10.

Referencing Custom Fields in Compound Aggregations

You can reference the values for Custom Fields defined at both Organization level or individual entity in your Compound Aggregation calculations using the following format for the following entities:

• organization.<fieldName>
• product.<fieldName>
• account.<fieldName>
• accountPlan.<fieldName>
• plan.<fieldName>
• planTemplate.<fieldName>
• meter.<FieldNames>

When you reference a Custom Field in a calculation, the value defined for the Custom Field at the Organizational level will be used unless you’ve also defined a Custom Field at the individual entity level. If a Custom Field has also been defined at the individual entity level, this value will be used:

• But see important note on Exception below regarding Meter Custom Fields.

Important! Aggregation and Compound Aggregation Custom Fields. You can also define Custom Fields for Aggregations and Compound Aggregations. However, these Custom Fields are NOT supported for referencing in Compound Aggregation calculations.

Exception - Referencing Individual Meter Custom Fields

The exception to the general rule is:

• meter.<fieldName>

Even if you’ve created a Custom Field at the individual Meter level, the default value defined for the Custom Field created for Meter at the Organizational-level will be used for the calculation. This is because a Compound Aggregation might reference multiple Aggregations and therefore multiple Meters, which leaves it ambiguous as to which individual Meter’s Custom Field value should be used for the calculation.

Tip: See Also? For creating Custom Fields in the Console, see Managing your Organization. You can use the Create/Edit Console pages for individual entities to set up Custom Fields. For API calls, see the CustomField section of our API Ref Docs. For more background on Custom Fields, see Working with Custom Fields.

Referencing Bill Period Variables

You can reference the following twelve bill period variables in your Compound Aggregation calculations:

• ts.hoursInPlanArrearsPeriod
• ts.datesInPlanArrearsPeriod
• ts.daysInPlanArrearsPeriod
• ts.hoursInPlanAdvancePeriod
• ts.datesInPlanAdvancePeriod
• ts.daysInPlanAdvancePeriod
• ts.hoursInBillArrearsPeriod
• ts.datesInBillArrearsPeriod
• ts.daysInBillArrearsPeriod
• ts.hoursInBillAdvancePeriod
• ts.datesInBillAdvancePeriod
• ts.daysInBillAdvancePeriod

How these variables work to determine bill periods can be understood against three distinctions:

• In Arrears Period vs. In Advance Period:

• In Arrears. The arrears period is the time when usage is accrued - the period between the previous bill and this one.

  • In Advance. The advance period is the period during which advance charges would appear on the bill - the period between this bill and the next one.

• Bill vs. Plan:

• Bill Period. Bill period is determined by the billing frequency. For example, if you bill on the 15th of each month, then your bill period will be 28 days from 15th Feb - 15th March, or 30 days from 15th November - 15th December, and so on.

  • Plan Period. A Plan period may be shorter than the bill period, because the Plan might start or end mid-way through the bill period.

• Hours vs. Days vs. Dates. More care is needed with this 3-way distinction, because users might be working from different timezones, and timezones can change due to deliberate seasonal clock adjustments, such as Daylight Saving Time changes. For example, on 27th March 2022 in the UK (Europe/London timezone) clocks were put forward one hour, so that day was only 23 hours long:

• Hours. The number of whole hours in the period. Note this isn’t “clock” hours - it’s just any arbitrary 60-minute period. For example: 12:00 - 14:00 would be 2 hours; 12:37 - 14:37 would be 2 hours; but 12:37 - 14:36 would only be 1 hour - it’s almost 2 hours, but not quite, and therefore only contains one entire 60-minute period.

• Note that with the example above (using Europe/London timezone), the period 1st March 2022 00:00 to 1st April 2022 00:00 wouldn’t have 31*24=744 hours, it only has 743 due to the time change. If the timezone was UTC on the other hand, this same period would have 744 hours.

  • Days. The number of whole days in the period. This automatically accounts for the configured Organization timezone and automatically accommodates any clock adjustments such as daylight savings. Similarly to hours, it’s not calendar days, but entire 24-hour periods (or in some cases, actually 23 or 25 hours if the period spans a Daylight Savings change)

• For example: 25th March 2022 14:00 - 30th March 2022 14:00 would be 5 days (even though there are only 23 hours on 27th March due to the daylight savings clock adjustment).

  • Partial days are not counted, so 25th March 2022 14:00 - 30th March 2022 13:00 would only be 4 days (because it’s an hour short of being a 5th full day).
  • Dates. the number of distinct calendar dates in the period in the configured Organization timezone. This is different to days:

• For example: 25th March 2022 14:00 - 30th March 2022 13:00 would be 6 dates - 25th, 26th, 27th, 28th, 29th, and 30th. The time components don’t matter here.