EDRs for Aggregated Usage

You can aggregate usage data from multiple messages into one or more Event Detail Records (EDRs) per device by session, time, or both. Specify aggregation parameters for a service context in the service type definition.

Note: All messages reporting data are merged into aggregated events, even if there is no rated quantity. For more information about this setting, see the discussion about EDRs for non-aggregated usage.

Unlike EDRs for non-aggregated usage that are generated per message, EDRs for aggregated usage can contain information from multiple messages. One message can create multiple EDRs if there is usage not created by the event initiator (secondary events). Secondary EDRs contain the aggregation of charges from multiple messages, but do not contain the usage amount. The SecondaryEventIdList in the MtxPrimaryEvent holds the event ID of each associated secondary event.

Note: For all usage events, aggregated or non-aggregated, separate events are always generated for each service context type.

You can aggregate data by session, time, or both. An EDR for aggregated usage is generated when the session context ends, when the time period ends, or when a quantity threshold is reached. If aggregation is by time period and by session, a separate EDR is created for each session that is active within the time period. If aggregation is not by time period or session, an event is generated for each Gy CC message that reports usage.

The following field types cannot be mapped into aggregated events:

arrays
blob
date
decimal
fieldkey
lists
struct
time

This applies even if the field is used as an aggregation grouping field.

Aggregation by Session

If an individual service context within the session terminates without terminating the whole session, an event is generated for the terminated service context. Individual contexts are terminated with a CC UPDATE message with the Reporting-Reason AVP set to FINAL (2).

Context Definition Properties shows context definition properties in which aggregation is by session.

Table 1. Context Definition Properties
Property	Value
Is Aggregation By Session	true
Is Aggregation By Time	none
Has Aggregation Quantity Limit	true
Is Aggregation Rating Quantity Limit	false
Aggregation Usage Quantity Limit	20
Aggregation Usage Quantity Limit Unit	mbytes

Aggregation by Time

When aggregating by time period only, the EDR can include data from multiple sessions, but there are separate EDRs for each context type within all the sessions. You can aggregate data in the following time periods:

Hourly (1) — Values are 1, 2, 3, 4, 6, 8, or 12.
Daily (2).

Note: Aggregation time periods start and end in the same day.

When rating duration (for example, a voice service type):

A usage event is generated when usage is reported.
Authorization determines the event time.
Usage reported in a single message is not segmented.
The complete duration is in the period in which usage started.

For example, if usage is reported in a single Gy CC message and starts at 3:30 and ends at 4:15, one EDR is generated for the 3:00 to 4:00 period. Quota validity time does not affect event generation. For example, if aggregating hourly, and 10 minutes of usage is reported in a single message, and that usage begins at 9:55 (authorized at 9:55), the entire 10 minutes is included in the 9:00-10:00 aggregation.

Important: Time period boundaries are on the hourly coefficient or day and are based on the subscription time zone.

When rating, a configurable data buffer time (default is 10 minutes) delays the generation of the EDR for aggregated usage to allow for messages that can arrive after the end of a time period. When the time period ends (plus the configured delay), an event is generated. If no more usage is reported until the session ends, then no additional event is generated when the session ends. If there is more usage, then another event is generated when the session ends which shows the later usage.

The following code shows a context definition in which aggregation is by time.

<context_type aggregation_period_type='1' id='54324' name='Context that aggregates hourly'>
        <quantity_info aggregation_period_type='1' auth_full_beat='false' has_aggregation_quantity_limit='false' is_aggregation_by_session='false' is_aggregation_by_time='true' is_aggregation_rating_quantity_limit='false' is_quota_adaptive='false' quantity_selector='service_specific' />
    </context_type>

Grouping by MDC Field

In addition to aggregating usage data by session, time, or both, aggregated usage events can be grouped by a combination of MATRIXX Data Container (MDC) fields. MDC fields can include custom attributes that are included in the applied offer field for simple and aggregated events.

Mapped fields are specified in the service type or event type definition in My MATRIXX in Field Mappings. Each element specifies a message, subscriber, or device field to copy into the event. Aggregation Group Field in each field map specifies whether a separate aggregated event must be generated for each different value of the field. If multiple field mappings set Aggregation Group Field, a separate event is generated for each combination of field values. A field that is not set is considered to have a distinct null value for this purpose.

When an EDR for aggregated usage is triggered at the end of an aggregation, separate EDRs are generated for each unique value of any specified combination of custom MDC fields. For example, assume the following:

Aggregation is by time, and data usage begins at 4:30 PM and ends at 6:00 PM.
Only one service context exists.
An MDC field grouping is specified for CountryCode and RATType.
Half the usage is in CountryCode DEU and half is in CountryCode CZE.
In CZE, half the usage is RATType LTE and half the usage is 3G.

This scenario generates the following:

EDRs triggered by time (4-5 and 5-6)
A total of 4 EDRs:
- 4-5, DEU, LTE
- 5-6, DEU, LTE
- 5-6, CZE, 3G
- 5-6, CZE, LTE

The following is an example of a field mapping with field grouping enabled.


Source Container Name	Source Field Name	Destination Container Name	Destination Field Name	Aggregation Group Field
DemoDiamRoMsg	RATType	txNoGDataEvent	RATType	True
DemoDiamRoMsg	CountryCode	txNoGDataEvent	CountryCode	True

Important: If you map an MDC field to an EDR and you expect the value of that field to change within a session, you must aggregate on that field. If you do not aggregate on that field, the MATRIXX Charging Application uses the first value of the first occurrence of that field in a message to include in the EDR and other values for that field are ignored.

For more information about adding fields to an EDR, see the discussion about adding fields to EDRs.

EDRs for Aggregated Usage Triggers

Event aggregation is triggered by time, session, or usage quantity limit. Usage quantity limit specifies aggregation ends after a usage quantity threshold has been reached. A usage quantity trigger must be set in combination with time and session-based aggregation. If a quantity trigger is specified, a quantity limit does not cause the usage reported within a single Gy CC message to be segmented. For example, if a 100 MB quantity limit is specified, the current accumulated quantity is 90 MB, and a message reporting 20 MB of usage is received, a single EDR is generated for 110 MB of usage.

Session Aggregation Trigger — An EDR for aggregated usage is generated for a session when usage ends for that session.
Time Aggregation Trigger — An EDR for aggregated usage is generated when a time boundary is reached.
Combined Session and Time Aggregation Trigger — An EDR for aggregated usage is generated when usage ends for a service context or when a time boundary is reached, whichever is first.
Session Aggregation and Quantity Trigger — An EDR for aggregated usage is generated when usage ends for a service context or when a quantity boundary is reached, whichever is first.
Time Aggregation and Quantity Trigger — An EDR for aggregated usage is generated when a time boundary is reached or when a quantity boundary is reached, whichever is first.

Aggregated Usage Parameters

You define aggregation parameters for service types and service context types using My MATRIXX. The following parameters can be set for each service context within a service type:

Is Aggregation By Session — When set, aggregation is by session.
Is Aggregation By Time — When set, aggregation is by time. In such cases, you must also configure the Aggregation Period Type parameter, which specifies the length of the aggregation period (Hourly, Daily). When the aggregation period type is hourly, set an hourly interval in Aggregation Period Interval (values are 1, 2, 3, 4, 6, 8, or 12). Each period starts at the beginning of every hourly coefficient or day.
Important: It is possible that an interval of a periodic balance might no longer exist in the in-memory database when an aggregation period is closed. If this happens, the aggregated usage event does not have GrossAmountAfter for the updated periodic balance.
Has Aggregation Quantity Limit — When set, a specified usage quantity threshold triggers the generation of an EDR. This is used in addition to aggregating by session, time, or both. You must configure the following parameters:
- Is Aggregation Rating Quantity Limit — If true, aggregation uses the rated amount. If false, aggregation uses the reported raw amount.
- Aggregation Usage Quantity Limit — Specifies the total usages that triggers an EDR.
- Aggregation Usage Quantity Limit Unit — Specifies the usage quantity unit.

Service types also have a Group Aggregation parameter in their Event Field Mapping settings. When set, aggregated data is grouped by MDC fields. Field-based aggregation of usage data is determined by the field identified in the Event Field Mappings information in the service type definition. This attribute is used when event aggregation is enabled. When not aggregating, it has no effect.

Note: The field cannot be a list, array, or struct field.

For a complete description of the service type definition, see My MATRIXX Help.

Data usage messages can arrive after a time boundary is reached. For this reason, you can configure an aggregation buffer that allows usage for a period not reported to the Charging Server until after the period boundary to be included in the aggregation period.

Gross Balance Amounts

For aggregated usage events, you can configure if the GrossAmountAfter field for updated balances is included in MtxBalanceUpdate. If a balance is updated while aggregation is in progress, the GrossAmountAfter is the balance amount after the transaction. Otherwise, the GrossAmountAfter is the balance amount at the time when the aggregation period ends.

Note: It is possible that GrossAmountAfter is not the exact amount after charges because balances can be impacted by other activities outside of the current aggregation context between the charges and the end of an aggregation period. For example, consider the following transactions:


	Amount at Start	Time 1	Time 2	Amount at End
Device 1 Usage Charge		$1		The `GrossAmountAfter` balance of the aggregated usage event for Device 1 is $98 because it is the amount when the event is generated, but not the amount $99 after the usage charge of $1.
Device 2 Usage Charge			$1	The `GrossAmountAfter` balance of the aggregated usage event for Device 2 is $98 which is exactly the amount after the usage charge of $1.
Group Balance Amount	$100	$99	$98	$98

To add the GrossAmountAfter field to MtxBalanceUpdate, answer y to the following question during engine configuration: create_config.info question: Global:Should GrossAmountAfter be provided for every updated balance in aggregated usage events (y/n)?

Event Time and Event Duration

EDRs can be aggregated by time and session, and can be grouped by a custom field, or a combination of these parameters. EDRs for aggregated usage can be triggered by session, time, or quantity. The event time is determined differently based on the type of aggregation:

Aggregation by Session Only
Event start times and end times are the start and end times of usage within the session associated with the aggregation (associated with the service context, and field values). More specifically, the start time is the EventTime in the message with the first authorization request for associated usage, and the end time is the EventTime in the message terminating the session or session context (CC TERMINATE, Session TERMINATE, or CC UPDATE with reporting reason of FINAL, and session expiration).
Aggregation by Time Only
Event start times and end times are the start and end time of the aggregation period. However, if there is no usage associated with the aggregation at the start of the period, then the start time is the beginning of associated usage. Similarly, if there is no usage associated with the aggregation at the end of the period, then the event end time is the end of associated usage (the EventTime in the message ending the last associated session context).
Note: If aggregation is by time (for example, hourly) and there are two sessions with the same service context in that period, both sessions are included in the aggregation.
Aggregation by Session and Time
Event start times are the beginning of usage associated with the session (first authorization time) if that usage begins within the time period. Otherwise, the event start time is the period start time. The end time is the end of the associated usage (end of session or service context in session) if the end is within the time period. Otherwise, the event end time is the end of the period.

Event Duration is in microseconds and is derived from the start and end time of usage.

If a quantity limit is reached within a session, or within a time period, then events are generated for what has accumulated to that point. If there is additional usage within the session or time period, then additional events are generated for that usage. The EventTime for the later usage is the time from the message which reported the usage that crossed the quantity limit. For example, for an hourly aggregation with a 100MB threshold, if usage is 150MB between 3:15 PM and 3:30 PM and the 100MB threshold is reached at 3:25, an EDR is generated for the 3 PM to 4 PM period with an EventTime of 3:15 PM and a Duration of 10 minutes. A second EDR is generated for the 3 PM to 4 PM period with an EventTime of 3:25 PM and a Duration of 5 minutes.

If usage aggregation is grouped, the end time is tracked for each group. The Duration is based on either the latest usage end time or the period end time depending on whether there are any sessions associated with the grouping at the end of the period.

Aggregation by Time

If aggregation is hourly, one aggregation period could be from 3 PM to 4 PM. If a first usage message occurs within the 3 PM to 4 PM aggregation period at 3:15, then 3:15 PM is the EventTime for the EDR generated for this segment.

When usage terminates within an aggregation, an EDR is generated for that period and indicates the EventTime and Duration for that period. For example, for the 3 PM to 4 PM aggregation period, if usage stops at 3:45 PM, an EDR is generated for the 3 PM to 4 PM period, with an EventTime of 3:15 and a Duration of 30 minutes.

If usage spans multiple segments, the duration for a single period is the EventTime to the end of the period. The EventTime for any period after the initial period is the start of that period. For example, if usage starts at 3:45 PM and finishes at 4:30 PM, two EDRs are generated for hourly aggregation. The first EDR is generated for the 3 PM to 4 PM period with an EventTime of 3:45 PM and Duration of 15 minutes. A second EDR is generated for the 4 PM to 5 PM period with an EventTime of 4 PM and a Duration of 30 minutes.

If usage aggregation is by time and a quantity trigger is specified, the EndTime for the EDR is the same as the EventTime of the message that caused the quantity limit to be reached. The StartTime of the next EDR is the same as the EndTime of the previous EDR.

Aggregated Usage Processing

Usage data is aggregated in the Activity database and when an EDR for aggregated usage is triggered, it is stored in the Event database. Use the following APIs to view in-progress aggregations:

Devices — View in-progress aggregated events on the specified device.
- REST — GET /device/{SearchTerm}/aggregation
- SubMan — MtxRequestDeviceQueryAggregation
Subscribers — View in-progress aggregated events on all devices owned by the specified subscriber.
- REST — GET /subscriber/{SearchTerm}/aggregation
- SubMan — MtxRequestSubscriberQueryAggregation

Event IDs returned for in-progress aggregations are a unique identification within the query results only. These are not the final event IDs generated when aggregations close and EDRs are generated.

Note: When a device is removed from a subscriber, any pending aggregations are closed and events are generated.

For more information about the SubMan APIs, see MATRIXX Subscriber Management API.