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:
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:
|
| Rate Type |
Defines which exchange rate type to use. The processor uses rate types provided by Oanda. You can configure:
|
|
Date Field and Time Format |
The processor needs a date or timestamp to look up the correct rate for that day.
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.
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:
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.