Default currency values in scripts

  • Release version: Zurich
  • Updated July 31, 2025
  • 4 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 Default currency values in scripts

    This guide explains how ServiceNow customers can work with currency fields in scripts using GlideElement objects. It details the appropriate methods to retrieve, display, and set currency values while ensuring accurate handling of formatting, conversions, and calculations in multi-currency environments.

    Show full answer Show less

    Key Features

    • Display vs. Calculation: Use getDisplayValue() and related display APIs to show currency values formatted according to the user's locale and currency symbol. For calculations, always use APIs that return unformatted numeric strings (e.g., getValue(), getCurrencyValue()) and convert to floats with parseFloat() before processing.
    • Currency Codes: Retrieve the associated currency's 3-letter ISO code using methods like getCurrencyCode(), getSessionCurrencyCode(), or getReferenceCurrencyCode(). This is essential for managing multi-currency data accurately.
    • Setting Values: Use setValue() to assign currency values. If the value is in the user's session currency, provide a plain number or floating point string. If it is in another currency, prefix the value with the ISO currency code followed by a semicolon (e.g., JPY;4369.21).
    • Aggregations and Conversions: Currency fields aggregated via GlideAggregate return reference currency values. Always convert these to the user's session currency for display, considering that conversion rates may change over time.
    • Data Integrity: When deleting records with currency values, delete each record individually rather than using bulk deletion methods like deleteMultiple() to ensure associated currency data is properly removed.
    • Decimal Precision: Currency values store four decimal places by default but can be configured to two. APIs return varying decimal places: calculation methods return up to four decimals (with trailing zeros removed), display methods return between two to four decimals formatted per locale, and GlideAggregate respects the decimal setting. Numeric inputs are rounded appropriately.

    Methods Summary

    The following methods help access and manipulate currency fields:

    • getValue(), getSessionValue(): Return unformatted currency values in the user's session currency.
    • getReferenceValue(): Returns unformatted currency value in the reference currency.
    • getCurrencyValue(): Returns unformatted value as originally entered.
    • getDisplayValue(), getSessionDisplayValue(), getReferenceDisplayValue(), getCurrencyDisplayValue(): Return formatted currency values with symbols according to locale and currency context.
    • getCurrencyString(): Returns unformatted value prefixed by ISO currency code.
    • getCurrencyCode(), getSessionCurrencyCode(), getReferenceCurrencyCode(): Retrieve ISO currency codes for values in various contexts.
    • setValue(), setDisplayValue(): Set currency values either as unformatted numbers or formatted strings, optionally prefixed by ISO currency codes.

    Practical Considerations for ServiceNow Customers

    • Always use numeric APIs for calculations to avoid errors from formatted strings.
    • Prefix values with currency codes when setting values outside the session currency to maintain accuracy.
    • Convert aggregated reference currency values to session currency before display.
    • Delete currency records individually to prevent data inconsistencies.
    • Be aware of the system’s configured decimal precision and how it affects API returns and input rounding.

    You can use currency fields in scripts.

    These methods are available on GlideElement objects.

    To display currency values, use the getDisplayValue() display API. To work with currency values in any way other than display, use the APIs that return/accept unformatted numbers.

    Note:
    Before performing calculations on the value, do not use the getDisplayValue() methods and then process the string to remove formatting information.
    Methods such as getValue() and getCurrencyValue() return unformatted numbers as strings. To obtain the floating point value, use the JavaScript function parseFloat(), and then use resulting value to perform calculations. To obtain the currency associated with these values, use the APIs that return the currency code. You can also use the getCurrencyCode() methods to determine a field's currency. 
    var rate = parseFloat(current.base_rate);
var currencyCode = current.base_rate.getCurrencyCode();
    Use the setValue() method to set the value of a currency field. If this currency is the user’s session currency, use a plain number or the floating point number of a string containing it. Otherwise, prefix the value with the 3-letter ISO currency code. 
    var totalCost = rate*current.hourly_rate;
current.total_cost.setValue(currencyCode + ";" + totalCost);

    You are working with the reference currency value when you use GlideAggregate on currency or price fields. Be sure to convert the aggregate values to the user's session currency for display. The resulting value may not be what you expect. The conversion rate used for the currency or price field value, and for its reference currency, which is used for the aggregation, may have changed.

    When you delete a record containing a currency value, the platform deletes any associated currency records.
    Note:
    Do not use deleteMultiple() on tables with currency fields. Always delete each record individually.
    Currency values contain four decimal places.
    • APIs that return values such as getValue() return up to four decimal places. Trailing zeros are always removed.
    • APIs that return display values such as getDisplayValue() have at least two decimal places and up to four decimal places.
    • GlideAggregate returns four decimal places.
    You can have the system use two decimal places. When you set it to two decimal places, numeric values returned by the API contain two decimal places. Although currency conversion rates may have more decimal places, currency fields store only two decimal places. APIs that accept numeric values round decimal places to two places.
    • APIs that return values such as getValue() return up to two decimal places. The trailing zeroes are removed for values read from the database, but if a value such as 00 is set later, 1.00 can be returned. The number of trailing zeros returned is not consistent.
    • APIs that return display values such as getDisplayValue() contain up to two decimal places. It could sometimes return two places even for values such as 7.10, but could remove trailing zeros at other times. The number of trailing zeros returned is not consistent.
    • GlideAggregate returns two decimal places.
    Note:
    To learn how to change the number of decimal places used by the system, see Change default currency decimal places.
    The following example, the user’s locale is set to German (de.DE), and the reference currency set to USD. The values use a currency value of 21345.67 in Japanese yen, 1563.72 in Euros, and 1152.48 in US dollars.
    Table 1. Methods to access currency fields
    Method name Description Example
    getValue() Returns the currency value in the user's session currency as an unformatted number. 1563.72
    getReferenceValue() Returns the currency value in the reference currency as an unformatted number. 1152.48
    getSessionValue() Returns the currency value in the user's session currency as and unformatted number. 1563.72
    getCurrencyValue() Returns the currency value as entered as an unformatted number. 21345.67
    getDisplayValue() Returns the currency value in the user's session currency, formatted in the user's locale with a currency symbol. €1.563,72
    getSessionDisplayValue() Returns the currency value in the user's session currency, formatted in the user's locale with a currency symbol. €1.563,72
    getReferenceDisplayValue() Returns the currency value in the reference currency, formatted in the user's locale with a currency symbol. $1,152.48
    getCurrencyDisplayValue() Returns the currency value as entered formatted in the user's locale with a currency symbol. ¥21.345,67
    getCurrencyString() Returns the currency value as entered as an unformatted number, prefixed by the 3-letter ISO currency code, separated by a semicolon. JPY 21345.67
    getCurrencyCode() Returns the 3-letter ISO currency code for the currency value as entered. JPY
    getSessionCurrencyCode() Returns the 3-letter ISO currency code for the user's session currency. EUR
    getReferenceCurrencyCode() Returns the 3-letter ISO currency code for the reference currency. USD
    setValue() Sets the currency value as:
    • An unformatted number taken as a value in the user's session currency.
    • An unformatted number prefixed by a 3-letter currency code separated by a semicolon.
    		 4369.21 or JPY 4369.21
    setDisplayValue() Sets the currency value as:
    • A number formatted in the user's locale that is taken as a value in the user's session currency.
    • A number formatted in the user's locale prefixed by a 3-letter currency code separated by a semicolon.
    		 4369.21 or JPY 4369.21