Session and reference currency

Release version: Xanadu

Updated August 1, 2024

2 minutes to read

Summarize

Summarized using AI

Summary of Session and reference currency

ServiceNow AI Platform® manages currency values using two types of currencies:session currencyandreference currency. This dual-currency approach supports multi-currency environments and ensures consistency in currency calculations across the platform.

Show full answer Show less

Session currency

Defined by the user’s locale or single-currency mode settings.
Displayed to users in a localized format with appropriate currency symbols and number formatting (e.g., decimal separators vary by locale).
Users can enter currency values in their session currency or a different currency; the system stores the input currency code separately.
The session currency is determined by properties like glide.i18n.singlecurrency, glide.i18n.singlecurrency.code, or the user’s locale default.

Reference currency

The system’s standard currency used for internal calculations and aggregations.
Determined by system locale settings (e.g., glide.system.locale) or Java default locale.
Currency values entered by users are converted to this reference currency using current exchange rates and stored alongside the original values.
Filtering, sorting, and aggregation operations rely on reference currency values to maintain consistency across heterogeneous currency data.

How currency values are stored

Each currency or price field stores three pieces of information:

Value as entered by the user
Currency code of the entered value
Value converted to the reference currency using the latest exchange rate

Key considerations and potential issues

Since filtering and aggregations use reference currency values but display session currency formats, results may appear inconsistent to users.
Conversion rate fluctuations can cause sorting and aggregation orders to differ from what users expect based on the session currency.
Lists filtered by currency fields might not sort as users anticipate due to this dual-currency handling.
Currency formatting is based on user locale rather than the currency code, potentially causing confusion in display.
Different users with different session currencies may see inconsistent currency value representations, complicating collaboration.

Practical impact for ServiceNow customers

Understanding the distinction between session and reference currency is critical when working with currency fields in ServiceNow AI Platform®. Customers should be aware that:

All currency inputs are stored with both original and reference currency values to support accurate calculations.
Filtering and aggregation results are based on reference currency, which may differ visually from session currency values shown.
Locale settings affect how currency values are displayed, influencing user experience.
Administrators should consider these factors when configuring multi-currency environments and when interpreting currency data in reports, filters, and lists.

The default, or standard, currency fields in the ServiceNow AI Platform® use two kinds of currency, Session and Reference.

Session currency: The session currency is defined for the user by the user’s locale or single-currency mode.
Reference: The system local determines the reference currency, and is the standard used across the entire instance.

Each time you enter a value into a currency or price field, the system stores three pieces of information:

Value as entered, in the user's locale.
Currency code, in the user's locale.
Value converted to the reference currency using the current exchange rate.

Note:

In multiple-currency mode, the currency code saved in the currency field may not be the same as the session currency code. For example, the session currency could be the Euro and the number entered could be the Japanese Yen.

Session currency

When users view a currency value, they can see the value as entered or in the session-currency format. The format contains the:

Currency symbol
Value converted to the session currency and shown in a localized number format.

The user’s locale determines the session currency format.

The number format can differ in features such as the decimal separator based on the locale. For example, the US formatting is 1,234,567.89, while German formatting is 1.234.567,89. The ServiceNow AI Platform® determines the session currency in the following sequence:

Single-currency mode setup using glide.i18n.single_currency and glide.i18n.single_currency.code.
Default currency for the user’s locale.

Reference currency

To perform calculations on heterogeneous currency values, the ServiceNow AI Platform® stores currency values converted to a system currency, referred to as the reference currency. Every currency field contains a reference currency value. The system determines the reference currency in the following sequence:

System locale set using the property glide.system.locale
Java default locale, typically en.US

The filtering and aggregation features use the reference currency value to perform calculations on default currency fields. These features can yield inaccurate results because of conversion rate changes.

Issues with currency fields

Users are often confused by the results of filtering, sorting, and displaying currency fields because the system works with at least two currencies for each value: the session currency and the reference currency.

Note:

Aggregations and filtering of currency fields use the reference currency, and the user sees the session currency. Because of changing conversion rates, the filtered reference currency values might not result in the same order as the session currency values would suggest. The same issue happens with aggregations.

The user might see the following issues:

Lists filtered on currency fields might not be in the expected order. It uses the reference currency values for filtering but displays session currency values.
Aggregation of currency fields may not produce the expected results because reference currency values are aggregated, and then converted to the session currency.
Currency values may not appear as expected because currency values are formatted based on the user's locale and not on the currency code.

This confusion may be the result of the difference between session and reference currencies, changing conversion rates, and different session currencies used by different users.