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:
- Navigate to Mediation > Meters.
- Add a new meter and select Map as the processor type.
- In the Map Settings page, provide the following:
Field | Description |
---|---|
Name |
Enter a display name for the processor. (e.g., |
Source Field |
Specify the name of the field from the incoming event payload that you want to process.. |
Action |
|
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., |
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.
- Use
- Numeric operations
- Use
parseFloat(value) * 100
to convert and scale a numeric value.
- Use
- Conditional logic
- Use
value === 'A' ? 'Alpha' : 'Other'
to apply conditional transformations.
- Use
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.
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
orchargeNumber
). - 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