Skip to navigation
ExtensibilityMediationMeter ComponentsProcessorsAccumulator processor

Accumulator processor - field reference

View as Markdown

This topic describes the configuration fields of the Accumulator processor, available options, and how the release triggers behave.

General configuration

Field

Description

Name

A user‑friendly name for the processor instance. Use a name that clearly indicates what is being accumulated (for example, “Hourly usage per account”).

Operator ID

An auto‑generated unique identifier for this processor.

Partition By (Group By fields)

Fields that define the grouping key for accumulation. Each unique combination of these fields creates a separate state bucket.

Examples:

  • accountId
  • accountId + subscriptionId
  • deviceId + region

Choose grouping keys that reflect how you want to track counters or totals. High‑cardinality keys create many buckets and increase memory usage.

Release trigger configuration

Timeout Type

Controls which notion of time is used to decide when to emit accumulated results:

  • Processing Time Based - Uses the system or ingestion time on the Mediation platform. Period boundaries are driven by wall‑clock time, regardless of the timestamps in the events.
  • Event Time Based - Uses a timestamp from each event to determine which period an event belongs to. Period boundaries are aligned with the event’s own time, not when the event arrived.

Timeout Duration

Defines how long each accumulation period lasts before a release is eligible. Supported units typically include:

  • Minute
  • Hour
  • Day
  • Calendar month

Duration is based on calendar time, not on “first event plus duration”. For example:

  • If you choose 1 hour and the first relevant time is 4:26 PM, the next hour boundary is 5:00 PM, not 5:26 PM.
  • If you choose 1 day and the current day is December 19 at 4:26 PM, the next day boundary is midnight on December 20.
  • If you choose 1 month and today is December 20, the next month boundary is January 1, not January 20.

Event Time Field and Time Format

Only used when Timeout Type is Event Time Based.

  • Event Time Field - The event field that contains the timestamp used for event‑time windows, such as usageDate or eventTimestamp.
  • Time Format - The pattern that describes how the time is formatted in the event field, especially if you do not use a standard ISO timestamp. Examples include “yyyy‑MM‑dd” or “yyyy‑MM‑dd’T’HH:mm:ss”.

Processing‑time triggers:

  • Periods are defined purely by clock time on the Mediation platform.
  • All events ingested during a given time interval (for example, 09:00–09:15) contribute to the state for that period.
  • At the end of the interval (for example, 09:15), the Accumulator emits the accumulated values for each partition.
  • Events that arrive after the boundary contribute to the next interval, even if their event timestamps indicate an earlier time.

Event‑time triggers:

  • Periods are based on the timestamp within the event (for example, usageDate), not on arrival time.
  • Events whose event times fall in the same period (for example, 10:00–11:00) contribute to the same window, regardless of when they arrive.
  • Once a period is considered closed and emitted, late events with timestamps in that period are not retroactively added; they typically fall into a currently open window or must be handled by downstream correction logic.
  • To avoid racing with very late events, the system may wait a short buffer (for example, a few minutes) after the nominal boundary before closing a window and emitting results.

Accumulate fields configuration

Defines which fields are accumulated and which operations are applied. For each field you can configure:

Field

Description

Source Field

The numeric or comparable field from incoming events to track (for example, quantity, amount, duration).

Operator

The type of accumulation operation, such as:

  • SUM: running total of the source field.
  • COUNT: number of events in the partition.
  • MIN: smallest observed value.
  • MAX: largest observed value.
  • AVG: average value, often computed by tracking sum and count.
  • FIRST / LAST: first or most recent value seen in the partition.
  • DELTA: change between successive values, if applicable.

Result Field

The field name where the Accumulator stores the accumulated value. You can:

  • Use a new name to add a new output field.
  • Reuse the source field name to overwrite the original value with the accumulated one.
  • For each partition and period, the Accumulator typically outputs a single summary record containing the accumulated fields.
  • The original individual events are not all forwarded by this processor; instead, you receive one result row per partition per release.
  • When you use a new result field name, source fields may be dropped from the output if that is how the meter is configured.

Advanced accumulation configuration

Use this mode when built‑in field operations are not sufficient.

Field

Description

Language

Choose JavaScript or Python for the custom logic.

Script

You provide a function that receives incoming events and current state, and returns an array of output events. For example:

  • Initialize missing state for a partition.
  • Update that state using the new event.
  • Return a snapshot record when you want to emit now, or return an empty array to suppress output until a later point.
  • Returning an empty array means “no output for this event.”
  • The script is responsible for shaping the output schema; only include fields needed downstream.
  • Complex logic and large volumes can be resource‑intensive. If you expect very high event volumes with advanced accumulation, coordinate with Zuora Global Support.

Examples

Example 1: Hourly event-time release

Configuration:

  • Partition By: accountId
  • Timeout Type: Event Time Based
  • Timeout Duration: 1 hour
  • Event Time Field: usageDate

Incoming events (for example account A):

  • 10:05 with quantity 3
  • 10:42 with quantity 2
  • 11:10 with quantity 5

Processing:

  • Window 10:00–11:00 (event time) accumulates events #1 and #2 → running total = 5.
  • At 11:00 event time, the node releases the current state for account A (total 5).
  • Event #3 has event time 11:10, so it belongs to the 11:00–12:00 window. That window will be released at 12:00 event time.
  • If an event for 10:15 arrives late (after 11:00 event time release), it is not included in the already released 10:00–11:00 output. It will accumulate in the current open window. If you need corrections, handle them downstream.

Example 2: 15‑minute processing‑time release

Configuration:

  • Partition By: subscriptionId
  • Timeout Type: Processing Time Based
  • Timeout Duration: 15 minutes

Incoming events (for example subscription S):

  • 09:01 ingested → qty 4
  • 09:05 ingested → qty 1
  • 09:16 ingested → qty 2

Processing:

  • From 09:00 to 09:15 (processing time), the running total becomes 5.
  • At 09:15, the node releases the total = 5.
  • Event at 09:16 starts the next processing window; it will be included in the 09:15–09:30 output.
  • Out‑of‑order event times don’t affect window boundaries under Processing Time; the release schedule follows the clock.

Example 3: Track running usage per account and emit hourly results by event time

Configuration:

  • Partition By: accountId
  • Accumulation: SUM quantity → totalQuantity
  • Release Trigger: Event Time Based
  • Duration: 1 hour
  • Event Time Field: usageDate

Incoming events (for example account Z):

  • 13:04 (usageDate), qty 2
  • 13:40, qty 5
  • 14:05, qty 3

Processing:

  • 13:00–14:00 window total grows to 7 (2 + 5).
  • At 14:00 (event time) → emit: { accountId: Z, totalQuantity: 7 }.
  • 14:05 goes into the 14:00–15:00 window. At 15:00 event time, emit whatever the 14:00–15:00 total is.
  • The release aligns with the business time on events, which is ideal for billing cycles and audits.