Skip to main content

Map as a processor

Zuora

Map as a processor

The Map processor in Zuora Mediation allows you to selectively retain, rename, drop, or transform fields from usage events. It is commonly used to normalize data formats, reduce payload size, or prepare fields for downstream enrichment, filtering, or rating.

Use cases for Map processor

Use the Map processor in the following instanes:

  • To rename input fields to match your target schema.
  • To remove unnecessary or redundant fields.
  • To transform field values using simple JavaScript logic (e.g., uppercase conversion, numeric scaling).
  • Zuora recommended you standardize incoming event structure before it reaches later pipeline steps.

Configure a Map processor

To configure a Map processor in the UI:

  1. Navigate to Mediation > Meters.
  2. Add a new meter and select Map as the processor type.
  3. In the Map Settings page, provide the following:
Field Description
Name

Enter a display name for the processor. (e.g., Standardize Fields).

Source Field

Specify the name of the field from the incoming event payload that you want to process..

Action

Select Keep to retain or Drop to remove the field.

Target Field

Enter the name of the output field. Use this to rename the source field if needed.

Transform Value

(Optional) Enable this option to apply transformation logic to the field’s value using JavaScript.

Target Field Value

This field appears when Transform Value is enabled. Enter JavaScript code to modify the field value. You can also specify the data type (e.g., Text, Number). Use value to reference the current field value.

Example

Input Event

{
  "CustomerId": "abc123",
  "UsageDate": "2025-06-01T00:00:00Z",
  "Quantity": 100,
  "Region": "us-west"
}

Map Processor Configuration

Source Field

Action

Target Field

Transform Value

Target Field Value

CustomerId

Keep

customer_id

Yes

value.toUpperCase()

UsageDate

Keep

usage_date

No

Quantity

Drop

Region

Keep

geo_region

Yes

value.replace('-', '_')

Output Event


{
  "customer_id": "ABC123",
  "usage_date": "2025-06-01T00:00:00Z",
  "geo_region": "us_west"
}

Using JavaScript with Transform Value

When the Transform Value option is enabled, you can use JavaScript to modify the field’s value. The following examples illustrate supported operations:

  • String manipulation
    • Use value.trim() to remove leading and trailing spaces.
    • Use value.toLowerCase() to convert text to lowercase.
  • Numeric operations
    • Use parseFloat(value) * 100 to convert and scale a numeric value.
  • Conditional logic
    • Use value === 'A' ? 'Alpha' : 'Other' to apply conditional transformations.

Recommendations

To ensure efficient and consistent data processing, follow these recommendations:

  • Use the Drop action early to reduce the data size for downstream processors.
  • Use Target Field renaming to maintain consistency in the output schema.
  • Test transformation logic with sample events before deployment.
  • Limit complex transformations to maintain optimal pipeline performance.

Duplicating Fields

The Map processor supports mapping the same input field to multiple output attributes. This is useful when multiple ABP charges require the same input field but mapped to different attribute names.

Use Case for duplicating fields

Consider the following example:

If your input contains a field called productTier and you need to pass it as tier to one ABP charge and as skuLevel to another, you can add both mappings using the Add Field option in the UI.

 To enable support for multiple mappings of the same source attribute:

  • Click Add Field in the Map processor UI.
  • Select the same Source Field as needed for multiple mappings.
  • Enter a different Target Field name for each mapping.
  • Ensure each Target Field name is unique. Duplicate target field names are not supported.

Map as a processor.png

Sorting events in batch mode using the Aggregator

The Aggregator processor supports sorting input events by a specified field before aggregation. This feature applies only to batch-mode meters and ensures consistent, predictable ordering of events within each key group.

Configuration

To enable sorting, configure the Sort Field in the Aggregator settings.

  • Sort Field: Enter the name of the field to sort by. The field must be convertible to an unsigned long—for example, an epoch timestamp or a numeric sequence.
  • Both ascending and descending sort orders are supported.
  • Sorting is applied within each key group (for example, events grouped by accountNumber or chargeNumber).
  • To simulate a global sort, use an empty key or assign a constant value (such as global) to the key.

Example: Sorting by eventTime within key groups:

If eventTime is used as the Sort Field and accountNumber is the key, the Aggregator will sort all events for each account by timestamp before performing aggregation.

Input


[
  { "accountNumber": "ACC-001", "eventTime": 1718203000, "usage": 8 },
  { "accountNumber": "ACC-001", "eventTime": 1718201000, "usage": 2 },
  { "accountNumber": "ACC-002", "eventTime": 1718202000, "usage": 5 },
  { "accountNumber": "ACC-002", "eventTime": 1718204000, "usage": 3 }
]

Output


{
  "ACC-001": [
    { "eventTime": 1718201000, "usage": 2 },
    { "eventTime": 1718203000, "usage": 8 }
  ],
  "ACC-002": [
    { "eventTime": 1718202000, "usage": 5 },
    { "eventTime": 1718204000, "usage": 3 }
  ]
} 

Global Sorting

To sort all events across accounts, set the key field to an empty string ("") or use a constant value such as global.

Pipeline Mode Requirement

This feature is supported only in batch mode. Batch mode is defined as a pipeline with:

  • No Kafka source
  • No Streaming API
  • No incremental S3 source
Unsupported Scenario

The following configuration is not supported:

  • S3 source + Kafka sink

To use batch mode sorting, consider updating the sink to one of the following:

  • S3
  • Event Store
  • Zuora Usage