Understanding FX Currency values in lists and reports

  • Release version: Zurich
  • Updated July 31, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Understanding FX Currency values in lists and reports

    This topic explains how FX Currency values are displayed, filtered, and aggregated in ServiceNow lists and reports. FX Currency fields store multi-currency amounts and their display and behavior are governed by configurations in System Localization. Understanding these details helps you accurately view, filter, and report on currency values in different currencies within your ServiceNow environment.

    Show full answer Show less

    FX Currency Values in List Views

    • FX Currency field values appear as formatted currency strings via getDisplayValue(), with formatting controlled by Display Digits and Display Value Currency settings in System Localization > FX Currency Configuration.
    • Dependent FX Currency fields derive their currency instance from the associated original FX Currency field and follow its display configuration.
    • FX Currency fields in custom tables store references (sysid), so the column max length is 32 characters.

    Filtering FX Currency Values in Lists

    • Filtering on FX Currency fields uses the original currency type entered, not the reference currency.
    • When filtering by a specific currency, only records entered with that currency appear; converted reference currency values are excluded from filters.
    • Example: If values entered in EUR are shown as USD in the unfiltered list, filtering by USD only shows values originally entered in USD.

    Dependent FX Currency Fields

    • You can create dependent FX Currency fields that use alternate display configurations from the original FX Currency field.
    • Changes in the dependent field do not affect the original field’s values or settings.

    FX Currency Reporting, Aggregation, and Group By

    • FX Currency fields can be included in reports and display similarly to list views.
    • If Display Value Currency is set to “Display in Session Currency,” the report shows values in the user’s session currency.
    • Aggregations (e.g., SUM) of FX Currency values are returned as strings in the format currencycode:currencyvalue, such as USD:134.98.
    • Aggregation only works when all values are in the same currency; mixed currencies in a grouping return no aggregate value.
    • Grouping by FX Currency fields groups by both currency and amount, allowing you to analyze currency values accurately by their type.

    Practical Implications for ServiceNow Customers

    • Configure FX Currency display settings centrally to ensure consistent currency formatting in lists and reports.
    • Understand that filtering FX Currency fields works based on original entry currency, which may affect filtering results if multiple currencies exist.
    • Use dependent FX Currency fields to customize display without altering original currency data.
    • Be mindful that aggregation and grouping operations require uniform currency types to produce meaningful results.
    • Leverage these FX Currency features to create accurate financial reports and dashboards that reflect multi-currency transactions correctly.

    By default, the currency values that appear in the FX Currency fields in lists and reports are the values that you directly enter into the FX Currency fields. For reports, the aggregations of FX Currency fields are, by default, reference currency values.

    FX Currency values in list views

    In lists, FX Currency values appear as a formatted currency string returned from getDisplayValue().
    For an FX Currency field that depends on another FX Currency field, the currency value comes from the Currency Instance [fx_currency2_instance] record associated with the latter. The display value format is based on how you configured its display settings in System Localization > FX Currency Configuration.
    Note:
    An FX Currency field in a custom table is a reference field that stores the reference (sys_id) to the actual record. Because the sys_id is 32 characters, the Max length of the FX Currency column must be 32 (default).

    Filtering FX Currency values in lists

    In lists, FX Currency field filtering behaves differently than with standard currency fields. The filtering takes place using the currency type selected when a currency value is originally entered into an FX Currency field. It doesn't take reference currencies into account when you filter a list. So, if the unfiltered list contains FX Currency field entries in multiple currencies, a filtered list would only contain those records originally entered using the specified filtering currency.
    • For example, if you entered a currency value in Euros (EUR) and the reference currency is US Dollars (USD), the reference currency value may appear in an unfiltered list.
    • However, if you filter the list, and select USD as the currency, the currency value, originally entered in Euros, doesn't appear. In this case, only currency values originally entered in USD would appear.

    Dependent FX Currency fields

    Use of FX Currency view or dependent fields enable you to use alternate display configurations defined in System Localization > FX Currency Configuration for a particular FX Currency field. To learn more about FX Currency field configurations, see Configuring FX Currency field behavior.

    When you create an FX Currency field, you can mark it as dependent on another FX Currency field. Marking an FX Currency field as dependent enables it to use the configuration settings for the original FX Currency field to display the amount values in different currency. Any changes that you make to the dependent field don't affect the original FX Currency field.

    FX Currency reporting, aggregation, and group by

    You can select FX Currency fields for inclusion on reports, and they display in the same manner as in list views.
    • FX Currency fields appear as a formatted currency string returned from getDisplayValue().
    • If you set the Display Value Currency field in System Localization > All Properties to Display in Session Currency, the session currency assigned to the user running the report appears.

    You can aggregate like reference currency values within a Currency Instance record. The following is the aggregated FX Currency data format in the ServiceNow AI Platform®:

    Table 1. Aggregate FX Currency value
    Type Description
    String Value of the aggregation. If the values being aggregated are FX Currency values, the returned value is in the format currency_code:currency_value, such as:

    USD:134.980000

    Otherwise, the returned value is just the currency value, such as: 134.980000.
    Note:
    If the field contains FX Currency values of mixed currency types, the values cannot be aggregated. The value is returned as a semicolon (;).
    For example, if the Cost field on a transaction record is an FX Currency field, you can group by cost.amount or cost.currency.
    • Aggregation operations, such as SUM, translate as SUM(amount) or SUM(reference_amount). The aggregation source determines the translation when the currency associated with the currency values in the grouping is the same.

      For example, the aggregate value returned by GlideAggregate.getAggregate() is a string of the format USD; 1234.56. The total currency value is expressed in the single reference currency that is associated with all currency values in the grouping.

    • If there are different currencies associated with currency values in the grouping, then the aggregate value is empty. For example, if some of the currency values are in US Dollars, some are in Euros, and others in Yen, the aggregate value would be empty.
    You can also use a Group By command on FX Currency fields.
    • It is equivalent to grouping by currency and amount, or by reference_currency and reference_amount, as dictated by the aggregation source.
    • The value of the grouping is available by dot-walking on the FX Currency field, or using an API such as getDisplayValue().