Composite Meters

A composite meter tracks a total composite amount for each period, including a breakdown into component values based on a collection of field values and aggregation selectors, as shown in Figure 1.

Component values track aggregations by defined categories — Figure 1. Composite Meter

Daily component values can be used independently or used with components that are based on fields and aggregation selectors.

To create composite views using conventional meters, you could define multiple meters in which one meter was intended to be an aggregate view of one or more other meters. For example, consider the following scenarios.

Scenario 1. Create 3 meters so that meter 3 is the aggregate view of meters 1 and 2.
- Meter 1 is usage paid with overage.
- Meter 2 is usage not paid with overage.
- Meter 3 is the total usage for a service type.
Scenario 2. Create a meter to measure usage in each country and create a meter to measure total usage.
- Meter 1 defines a separate meter definition for each individual country, each with a filter to show usage only for that country.
- Meter 2 measures the total usage.

Composite Meter Benefits describes the difference between creating multiple meters and creating composite meters based on these two scenarios.

Table 1. Composite Meter Benefits
Issue	Multiple Meters	Composite Meter
Consistency Between Meters	You must ensure that the component values include all the same usage or charges as the meter that measures the total amount, and that two or more component values never measure the same usage or charges. In scenario 1, a composite view would not be achieved if one meter measures only peak time usage and the other two meters measure usage at all times.	A composite meter is a single definition of what is metered and applies to the composite value and all component values.
Rounding	Meters are rounded to a configured precision. Even if all meters involved are rounded to the same precision, the sum of the component values does not always equal the value in the meter intended to be the aggregate of the other meters.	The sum of the component values is always equal to the composite value.
Defining Multiple Component Values	Pricing must be updated if the set of all possible values for a field to be used for aggregating changes, for example, in scenario 2, the set of all country codes. In scenario 2, a separate meter template must be defined for each country, each using a separate filter for that country. If new countries are formed, the pricing must be updated accordingly.	A composite meter can be defined such that a separate component value exists for each possible field value or combination of fields. If the set of component values changes, no pricing changes are required.
Maintaining Multiple Component Values	In scenario 2, a wallet must include a meter instance for each country, regardless of whether there is any usage within that country in a particular meter period, greatly increasing the amount of subscriber data.	Component value instances are dynamically generated on an as-needed basis rather than creating all possible instances.

A composite meter is defined in a balance template with an aggregation field list. Each element of the aggregation field list is either a field or an aggregation selector. An aggregation selector is a pricing object used in defining aggregation groupings, and an aggregation instance is the component value generated in the wallet based on an aggregation grouping definition.

A composite meter is a periodic meter with periods that close, and can be any of the following:

Usage meter that counts the accumulated total usage.
Usage meter with the turnstile meter property to count instances of usage.
Charge meter that counts the accumulated total charge.
Charge meter with the turnstile meter property to count instances of charges.

Note: Composite meter periodic cycles cannot be expressed in hours or minutes.

A composite meter tracks a total composite amount for each period, including a breakdown into component values based on a collection of field values and aggregation selectors. A composite meter can also produce a daily component value for each day.

Note: If you use a composite meter for a normalizer or a scale basis, to set credit limits or define soft thresholds, the composite value is used; you cannot use the component value for these purposes.

A composite meter can be defined such that there is a separate component value for each possible field value or combination of fields specified in a usage message. For example, a single meter definition can specify that there is a separate component value for every country code specified in a usage message and no pricing changes are required if the set of all country codes changes. Instances of component values are dynamically generated on an as-needed basis rather than creating all possible instances.

Virtual meters associated with a composite meter hold only the composite value; component values are not created for a virtual meter instance. Credit limits and thresholds on composite meters apply to the composite value only and are used to trigger notifications or grants.

For details about collecting composite data for specified groups and subscriptions, use the GET /service/group/{SearchTerm:.+}/wallet/{ResourceId}/composite_meter and GET /service/subscription/{SearchTerm:.+}/wallet/{ResourceId}/composite_meter APIs described in MATRIXX Business API SDK.

For more information about creating aggregation selectors, see the discussion about creating an aggregation selector in My MATRIXX Help.

For more information about adding aggregation selectors and fields, see the discussion about configuring meter template aggregations in My MATRIXX Help.

Filters

Use filters on composite meters to view charge or usage that impacts the composite value or any component value matching the filter. To limit composite values, define the filter and field in the composite meter. For example, define a two-dimensional set of meter values to represent the meter quantity on international data usage segregated by country with aggregate usage per day and per month, and filter out all but a few countries and view aggregation groupings for each country that passes the filter.

Events

When a composite meter is updated, the events include one record for the composite value for the meter period, one record for the cumulative value for the meter period for each impacted aggregation grouping, and one or more records for each impacted daily value.

When a composite meter period closes, an MtxMeterPeriodCloseEvent Event Detail Record (EDR) is generated. The EDR is an historical record including the period and the final meter value and generates the resource ID of the meter. For more information about the MtxMeterPeriodCloseEvent EDR, see the discussion about MtxMeterPeriodCloseEvent in MATRIXX Integration.

When a composite meter period closes based on the configured time after the period ends, a meter period close event is generated with the final composite value, and a component meter period close event is generated for each aggregation grouping generated within the period, including the resource ID of the meter. When daily components are used, a component meter sub-period close event is generated based on the configured time interval after the end of a day, with the final value for the daily component. Event Types and MDC Containers lists the event types and associated MDC container.

Table 2. Event Types and MDC Containers
Event Type	MDC Container	Description
meter_period_close	MtxMeterPeriodCloseEvent	Meter period close event.
component_meter_period_close	MtxComponentMeterPeriodCloseEvent	Component meter period close event.
component_meter_subperiod_close	MtxComponentMeterPeriodCloseEvent	Component meter sub-period close event.

Note: The MDC container for the event types listed in Event Types and MDC Containers can also be a custom sub-class. Although the MDC container for component_meter_period_close and component_meter_subperiod_close is the same, different custom sub-classes can be generated for these event types.

The meter period close event has the final composite value for an aggregation grouping and the component meter period close event has the final component value for an aggregation grouping; when daily components are used, these events have the cumulative value within the period for the aggregation grouping. The meter period close event has the event IDs for each component meter period close event generated for the period and the resource ID of the meter.

For composite meters with daily component values and aggregation groupings, one component meter sub-period close event is generated for every aggregation grouping generated within the meter period. When a meter period closes (MtxMeterPeriodCloseEvent), and when a period for a component value of a composite meter closes (MtxComponentMeterPeriodCloseEvent), the resource ID of the meter is generated.

For composite meters with daily component values and no aggregation groupings, one component meter sub-period close event is generated for the entire meter for the day and no component meter period close event is generated because it would not give additional information beyond what is in the meter period close event (the composite value). The composite value and a cumulative value would be the same.

For more information about the event types listed in Event Types and MDC Containers, see the discussion about event types and the discussion about event fields in MATRIXX Integration.

Responses and Notifications

When a composite meter is returned in balance query responses and notifications, the component values are shown together with the composite meter value. You can use the component ID to adjust or reset a component value; you cannot adjust or reset the composite value. When you adjust a component value, the composite value is adjusted with the individual component value. For aggregation groupings, information is shown for the current and preceding periods only; use MtxComponentMeterPeriodCloseEvent to view aggregation groupings for prior periods. When daily component values are used, for each aggregation grouping, information about the current day and preceding day are returned, including the date and time of the start of day, the daily component value, and component meter. When daily components are used, only the daily value component IDs are included; no component IDs are included for the aggregation groupings. Use the MtxBalancePeriodInfo SubMan API to view a specific period of a periodic balance or meter in a query response or notification, including a list of each element created for the selected period. For more information about MtxBalancePeriodInfo, see the discussion about MtxBalancePeriodInfo in MATRIXX Integration.

Reset and Adjustment

Composite meters can be reset to zero (0) or adjusted through the SubscriberAdjustBalance SubMan API. For composite meters, these operations must be targeted to a specific component value and not the composite value. If a composite meter includes a daily component value, only the daily value can be adjusted, not the cumulative value for an aggregation grouping. Each component value includes a numeric component ID. To specify the target component value, the numeric component ID is included in the request to indicate the target component value. The component ID is returned in the query results.

Virtual composite meters hold only the composite value; component values are not created for the virtual meter instance. A reset or adjustment on a virtual composite meter is targeted at the composite value and does not include a component value ID.