Advanced Transformer metadata

The Advanced Transformer provides access to metadata associated with the current event and pipeline execution.

You can use this metadata to add operational context such as processing session identifiers, event tracking information, source file details, pipeline information, tenant and entity identifiers, billing-related context, and processing timestamps to outgoing events.

This metadata helps downstream systems understand where records originated, how they were processed, and how they relate to specific meter runs or billing operations.

How metadata enrichment works

Each Advanced Transformer receives access to metadata associated with the current event and pipeline execution.

You can use this metadata to trace events back to a meter run, track source files and ingestion details, correlate records across systems, build audit trails, add billing context, and improve troubleshooting and observability.

A metadata field is available only if something earlier in the pipeline produced it. What you can read depends on the source type that ingested the event and the operators placed before the Advanced Transformer. If a field was not produced, the lookup returns nothing, so your code should not assume every field exists.

Pipeline metadata

Pipeline metadata is available for every processed record.

• tenantId: tenant identifier
• entityId: tenant entity identifier
• sessionId: meter run or session identifier
• operatorId: current operator identifier
• operatorName: current operator name
• pipelineId: pipeline identifier
• pipelineVersion: pipeline version

Record metadata

Record metadata is available depending on the source and upstream operators.

• traceId: end-to-end trace identifier
• eventId: event identifier
• schemaId: schema identifier
• fileName: source file name
• filePath: source file path
• fileSize: file size
• fileModificationTime: file last modified timestamp
• etag: source file ETag
• uploadTime: upload timestamp
• uploadDay: upload date
• chargeModelId: charge model identifier
• billingPeriodId: billing period identifier
• subscriptionRatePlanChargeTiers: charge tier information
• asyncRetryAttempts: current retry count
• asyncMaxRetryAttempts: maximum retry count

Read metadata in a script

Use context.getMetadataValue('fieldName') to retrieve a single metadata value.

exports.step = function (payload, context) {
  payload.sessionId = context.getMetadataValue('sessionId');
  return payload;
};

Use JSON.parse(context.getMetadataJson()) to retrieve the full metadata object.

exports.step = function (payload, context) {
  const metadata = JSON.parse(context.getMetadataJson());
  payload.traceId = metadata.traceId;
  return payload;
};

When each metadata field is available

Using an S3 (or file) source

fileName, filePath, fileSize, fileModificationTime, and etag are populated by the file reader, so you can read them in any Advanced Transformer downstream of that source.

Example: stamp each event with the file it came from.

exports.step = function (payload, context) {  
 payload.sourceFile = context.getMetadataValue('fileName'); 
 // e.g. "SummaryInputData.json"  return payload;
};

Using a streaming source (for example, a Kafka topic)

fileName / filePath / etag lookups return nothing, because there is no source file. Rely on eventId / traceId / uploadTime instead.

Reading enrichment output

To use chargeModelId, billingPeriodId, or subscriptionRatePlanChargeTiers, place the Advanced Transformer after the enrichment or subscription lookup step and before rating.

exports.step = function (payload, context) {
  payload.chargeModelId = context.getMetadataValue('chargeModelId');
  return payload;
};

Example metadata

The following example illustrates metadata that can be available for a typical event processed through a pipeline.

{
  "traceId": "bc9b4161aea5537424e2932be5e01880|1_b",
  "eventId": "bc9b4161aea5537424e2932be5e01880|1",
  "uploadDay": "2026-05-29",
  "fileName": "SummaryInputData.json",
  "filePath": "s3://bucket/path/SummaryInputData.json",
  "entityId": "8a90cd6c-96ff-6e56-0197-0adde0df1342",
  "sessionId": "R-00007391",
  "uploadTime": 1780041460621,
  "operatorName": "Advancedd Transformer",
  "pipelineId": 3352,
  "pipelineVersion": "0.0.1",
  "fileModificationTime": 1780041453000,
  "fileSize": 340,
  "schemaId": 1072,
  "tenantId": 14183,
  "etag": "a38ce9d3a8c8e18802dd9d578674f29f",
  "operatorId": "86ffc2bf-9106-4f04-bff5-f8f841f4e3c3"
}

The metadata available for an event depends on the source type and the operators configured in the pipeline, so some fields might not be present for all events. For file/object‑store sources like S3; charge fields (chargeModelId, billingPeriodId, subscriptionRatePlanChargeTiers) only exist between an enrichment/subscription‑lookup step and the rating step. Async‑retry fields only exist on async‑call operators.

The output schema can be obtained from the Schema Registry. Create or locate the schema that matches your transformed events, then select it in the operator.

A practical rule of thumb is that pipeline metadata is always safe to read, while other metadata depends on the source type and on which operators run earlier in the pipeline. Always handle missing values gracefully.