Currency Lookup processor - field and error reference

This topic describes the configuration fields of the Currency Lookup processor, supported options, and the main error codes you may see when using this processor.

Configuration fields

Field	Description
From currency	Defines the source currency for each event. You can configure: Static currency - The same currency is used for all events. Example: From currency = USD. From event field - The processor reads the source currency code from a specific event field. Example: From currency field = sourceCurrency. In the UI, you select whether the “From” value is a fixed currency or taken from an event field.
To currency	Defines the target currency for each event. You can configure: Static currency - The same target currency is used for all events. Example: To currency = EUR or To currency = USD. From event field - The processor reads the target currency code from a specific event field. Example: To currency field = billCurrency
Rate Type	Defines which exchange rate type to use. The processor uses rate types provided by Oanda. You can configure: Static rate type - One rate type applies to all events, for example: MIDPOINT BID ASK From event field - The processor reads the rate type from an event field, for example: rateTypePreference.
Date Field and Time Format	The processor needs a date or timestamp to look up the correct rate for that day. Date field - The event field that contains the date or timestamp, such as: transactionDate usageDate eventTimestamp Time format - A pattern that matches the date or timestamp format in the event data. Examples: yyyy‑MM‑dd yyyy‑MM‑dd’T’HH:mm:ss y The processor uses your tenant’s timezone together with this date to locate the correct daily rate.
Rate Field Name	The event field where the processor writes the exchange rate. Example names: fxRate exchangeRate appliedRate This field is numeric and represents the FX rate only. To calculate a converted amount, you typically multiply the original amount by this rate in a subsequent processor.
Caching options (if exposed)	For high‑volume meters, you can tune caching options: Cache size - Maximum number of FX rate entries held in memory. Example: cacheSize = 200000 Cache expiration - How long a cached rate is kept before it is refreshed. Example: cacheExpireAfterWriteMs = 7200000 (2 hours) Larger caches and longer expiration reduce calls to the FX service but may hold rates for longer periods; choose values that satisfy your accuracy and performance needs.

Error codes

If the processor cannot find a rate, encounters an unsupported currency code, or is missing the date field, it does not stop the meter. Instead, it routes the affected event to an error stream and attaches an error code that indicates the reason. You can monitor and optionally reprocess these events once you have corrected the data or chosen a fallback behavior.

Common error codes include:

Error	Description
CURRENCY_LOOKUP_RATE_NOT_AVAILABLE	The FX rate for the requested currency pair and date could not be found. This can occur if the provider does not have data for that day or for that combination.
CURRENCY_LOOKUP_UNSUPPORTED_CURRENCY	The currency code is not supported by the FX provider or is invalid.
CURRENCY_LOOKUP_MISSING_DATE_FIELD	The event is missing the date field required for lookup, or the field is empty.
RATE_NOT_AVAILABLE / RATE_NOT_SYNCED	No rate is available for that date yet, or data has not yet been synced.

Examples

Example 1: Simple USD to EUR conversion

All transactions are in USD and you want to convert them to EUR for reporting.

{
  "fromCurrency": { "type": "STATIC", "currency": "USD" },
  "toCurrency": { "type": "STATIC", "currency": "EUR" },
  "rateType": { "type": "MIDPOINT" },
  "dateField": { "field": "transactionDate", "timeFormat": "yyyy-MM-dd'T'HH:mm:ss" },
  "rateField": "fxRate"
}

In this example, a field such as “fxRate”: 0.92 is added to each event.

Example 2: Dynamic source currency

If your event data includes a field like “sourceCurrency”, you can let the processor pick it up dynamically.

{
  "fromCurrency": { "type": "FROM_EVENT", "field": "sourceCurrency" },
  "toCurrency": { "type": "STATIC", "currency": "USD" },
  "rateType": { "type": "BID" },
  "dateField": { "field": "usageDate", "timeFormat": "yyyy-MM-dd" },
  "rateField": "exchangeRate"
}

This example can be used in the case of global usage data coming in from multiple countries.

Example 3: Advanced setup with caching

If you process large volumes of data and want faster performance.

{
  "fromCurrency": { "type": "FROM_EVENT", "field": "localCurrency" },
  "toCurrency": { "type": "FROM_EVENT", "field": "billCurrency" },
  "rateType": { "type": "FROM_EVENT", "field": "rateTypePreference" },
  "dateField": { "field": "eventTimestamp", "timeFormat": "yyyy-MM-dd'T'HH:mm:ss.SSSZ" },
  "rateField": "appliedRate",
  "cacheSize": 200000,
  "cacheExpireAfterWriteMs": 7200000
}

In this example, up to 200,000 recent FX lookups are kept in memory and refreshed every 2 hours.