Default currency values in scripts

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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 highlights best practices for accessing, displaying, setting, and performing calculations on currency values while respecting user locale and session currency contexts. Understanding these methods ensures accurate currency handling, display formatting, and conversions in your ServiceNow applications.

    Show full answer Show less

    Key Features

    • Display vs. Calculation: Use getDisplayValue() to show currency values formatted for the user’s locale and session currency. For calculations, use APIs returning unformatted numbers like getValue() or getCurrencyValue(), then convert strings to floats with parseFloat().
    • Currency Identification: Methods like getCurrencyCode(), getSessionCurrencyCode(), and getReferenceCurrencyCode() provide the ISO currency codes for the entered, session, and reference currencies respectively.
    • Setting Currency Values: Use setValue() to assign currency values. Provide either a plain number (assumed session currency) or prefix the value with the 3-letter ISO code and a semicolon for other currencies (e.g., JPY;4369.21).
    • Aggregations and Conversions: GlideAggregate operations on currency fields return reference currency values. Convert these to the user’s session currency before display to avoid confusion from rate changes.
    • Decimal Precision: Currency values store up to four decimal places but typically display two. APIs handle decimal places differently—some remove trailing zeros inconsistently. You can configure the system to use two decimal places globally.
    • Deletion Handling: When deleting records with currency fields, delete records individually rather than using deleteMultiple() to ensure associated currency records are properly removed.

    Practical Methods to Access Currency Fields

    MethodDescriptionExample Return
    getValue()Returns unformatted currency value in session currency1563.72
    getReferenceValue()Returns unformatted currency value in reference currency1152.48
    getSessionValue()Returns unformatted currency value in session currency1563.72
    getCurrencyValue()Returns unformatted entered currency value21345.67
    getDisplayValue()Returns formatted currency value for session currency and locale€1.563,72
    getCurrencyDisplayValue()Returns formatted currency value as entered and locale¥21.345,67
    getCurrencyString()Returns entered currency value prefixed by ISO codeJPY 21345.67
    getCurrencyCode()Returns ISO currency code for entered currencyJPY
    setValue()Sets currency value with optional ISO prefix4369.21 or JPY 4369.21

    Key Outcomes

    By applying these methods and best practices, ServiceNow customers can accurately handle multi-currency data in their scripts, ensuring proper formatting, calculation, and conversion aligned with user session and system reference currencies. This leads to consistent financial data presentation, avoids calculation errors due to formatting mistakes, and supports multi-currency environments effectively.

    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