Currency exchange Entity - Data Load Guide

Created by Shyam Sayana, Modified on Tue, 2 Jun at 9:38 AM by Shyam Sayana

TABLE OF CONTENTS

The Currency Exchange Entity — Data Load Guide
- Post data load behavior
Currency Exchange entity in Inspect Data
- View exchange rates
- Edit exchange rates

The Currency Exchange Entity — Data Load Guide

The Currency Exchange Entity is the mechanism by which exchange rates enter the planning system. Rates are loaded via a structured data file and are period-specific — meaning each planning period(Month/Week) can carry a different rate.

What is the Currency Exchange Entity?

It is a pre-configured ETL (data load) entity that:

Accepts exchange rate files from your source system or finance team
Maps each rate to a specific from-currency, to-currency, and time period (month/week)
Populates the system's exchange rate table used for all currency conversions in planning

Required File Structure

Your currency exchange data file must contain the following columns:

Column	Description	Example
FROM_CURRENCY	ISO-4217 code of the source currency	`USD`
TO_CURRENCY	ISO-4217 code of the target currency	`EUR`
EXCHANGE_RATE	Conversion factor (1 unit of FROM = N units of TO)	`0.921500`
DATE_OF_RECORD	The date this rate applies to (maps to time bucket)	`2024-01-01`

Step-by-Step: How to Load Currency Exchange Rates

Step 1 — Prepare your file

Obtain the latest exchange rates from your finance team or source system
Ensure rates are provided per planning bucket(month/week) — one row per currency pair per period
Validate that all currency codes are valid ISO-4217 codes
Save the file in the required format (CSV or as configured. You can download the template from the Data Management > Dataload History > Import > Currency Exchange)

Step 2 — Navigate to the Data Load screen

Go to Data Management → Data Load History --> Click Import button --> File Upload
Select the Currency Exchange entity from the entity list

Step 3 — Upload your file

Click Upload and select your prepared exchange rate file
The system will validate the file structure and flag any errors before processing

Step 4 — Review and confirm

Review the entity mapping
Click Submit to trigger the data load job

Step 5 — Verify the load

Monitor the job status in Data Management → Data Load History
A COMPLETED status confirms rates are now live in the system
A FAILED status means errors were found — check the error log for details

Common Data Load Errors and Fixes

Validation Rule	Likely Cause	Expected Value / Criteria	Fix / Resolution	System Rejection Message
Invalid Currency Code	ISO code not recognized	CURRENCY_FROM and CURRENCY_TO must be valid ISO-4217 codes	Use exact ISO-4217 codes — e.g. EUR not EURO, GBP not POUNDS	"Invalid currency code in CURRENCY_FROM/TO."
Tenant Currency Not Enabled	The currency code is a valid ISO code, but not enabled for your tenant	Currency must be active in the tenant configuration	Enable the currency in Tenant Settings or contact your system administrator	"Invalid currency code in CURRENCY_FROM/TO."
Period Not Found	Date does not map to a planning time bucket	Date must fall within the configured planning horizon and align to a valid planning period	Verify the date falls within your planning horizon and matches a valid period boundary	"Period not found for DATE_OF_RECORD."
Invalid Date Format	Date format does not match tenant configuration	Date must follow the configured tenant format (e.g. DD/MM/YYYY)	Correct the date format to match your tenant's configured date standard	"Invalid date format in DATE_OF_RECORD."
Duplicate Exchange Rate	Same currency pair loaded more than once for the same period	Only one rate per currency pair per period is permitted	Remove duplicate rows — retain the most current or correct rate for each period	"Duplicate exchange rate found for currency pair and period."
Missing Exchange Rate	The rate value is blank, null, or zero	VALUE must be a non-zero decimal number	Populate a valid exchange rate greater than zero for every record	"Missing exchange rate value."
Invalid Numeric Value	Value contains text, special characters, or invalid formatting	VALUE must be a valid decimal number only	Remove any non-numeric characters (e.g. currency symbols, commas as thousands separators)	"Value must be numeric or decimal."
Missing Mandatory Fields	One or more required fields are blank or null	All four mandatory fields must be populated: CURRENCY FROM, CURRENCY TO, DATE OF RECORD, VALUE	Populate all mandatory fields before submitting the file	"Missing or null mandatory field."
Unconvertible Currency Pair	No exchange rate exists for a required currency pair in the system	A valid rate must exist for every currency pair used in planning	Load a global fallback rate or a per-item specific rate for the missing currency pair	"No exchange rate available for the specified currency pair."

Bidirectional conversion

Exchange rates must be maintained in both directions for every currency pair so that the system can convert values regardless of direction. Each pair, therefore, needs two records:

Currency From → Currency To
Currency To → Currency From

Example: USD ↔ INR — if 1 USD = 100 INR on 23-Jan-2026, the exchange rate file must contain both records:

Currency from	Currency to	Exchange Rate	Exchange Date
USD	INR	100	01/23/2026
INR	USD	0.01	01/23/2026

The reverse rate must be the mathematical inverse (1/100 = 0.01) and should use the same exchange date.

If the tenant has N currencies enabled, exchange rates must be provided for every pair in both directions. For example, with USD, INR and EUR enabled, the file must include:

USD ↔ INR
USD ↔ EUR
INR ↔ EUR

Bucket alignment and missing-period handling

Weekly bucket: use the start-of-week date.
Monthly bucket: use the start-of-month date.
For current and future buckets, the application uses the latest exchange rate provided.
For past buckets, the application uses the source bucket rate if one was provided at the bucket level.
If exchange rates are missing for one or more planning buckets, the application fills forward using the most recent available bucket rate. The same forward-fill applies to both historic and future gaps.

Example: the USD → INR rate is missing for May 2025 and Jun 2025. The application uses the April 2025 rate for both missing buckets. Similarly, if rates are missing for Apr-Jun 2026, the application uses the most recent available rate (e.g. Mar 2026) to populate them.

Post data load behavior

The latest values in the most recent file override any earlier values for the same currency pair and bucket. For example, if Dec 2026 was 93.678 in a previous file and the new file provides 91.997, the new value replaces the old one.
All dependent time series and metrics are automatically recomputed in the UI using the new rates.

Currency Exchange entity in Inspect Data

After the data load completes (for either data source), the Currency Exchange entity becomes available in Inspect Data. From here, you can review the loaded exchange rates and, if the currency rate attribute is editable, you can update them directly in the UI.

View exchange rates

Click the Currency Exchange entity in Inspect Data to see the list of all uploaded conversions across currencies, dates, and rate values.

Edit exchange rates

The exchange rate can be edited only if the edit option is enabled for the attribute in the Admin App. To edit:

Click the Edit button to enable editing mode.
Update the exchange rate for the required date, From currency and To currency. Multiple rates can be updated in a single editing session.
The Save button becomes enabled once changes are made.
Click Save to commit the changes — this triggers a data load process and the updates are persisted once the load completes successfully. Click Cancel to discard.

Once the updated rates are processed, the application recalculates all currency-converted values wherever currency conversion is applied. Monetary measures that depend on conversion are refreshed using the new rates.