a!currency() Function

Function

a!currency( isoCode, value, decimalPlaces, showSeparators, format, indicatorAlignment )

Localizes a currency value based on the given ISO currency code.

Parameters

Keyword Type Description

isoCode

Text

A valid ISO currency code. For example, "USD" or "EUR". This parameter is required.

value

Number (Decimal)

The value to be formatted.

decimalPlaces

Number (Integer)

Number of digits to display after the decimal mark. By default, it uses the localized format of the currency code. It also rounds to the specified decimal place. Valid values: 17 to -17.

showSeparators

Boolean

Optional flag indicating whether to display digit separators. For example, the comma in 1,234.56. Default: true.

format

Text

Optional field to specify how the currency should be formatted. Valid values: "LOCALE" (default), "CODE", "SYMBOL". For example, "CODE" would use USD and "SYMBOL" would use $. "LOCALE" would use either "CODE" or "SYMBOL" depending on the locale.

indicatorAlignment

Text

Determines the alignment format. Valid values: "LOCALE" (default), "START", "END". For example $1,234.56 or 1.234,56 $. "LOCALE" would use either "START" or "END" depending on the locale.

Returns

Text

Usage considerations

Using the isoCode parameter

This parameter is required and only accepts one valid ISO code, like "USD" or "EUR".

To display the generic currency symbol (¤), use "XXX" for the isoCode parameter.

Using the value parameter

If no value is passed, the function will just return the currency code or symbol of the entered ISO code.

Using the decimalPlaces parameter

If no decimalPlaces value is passed, the function uses the format of the entered ISO code. Most currencies will have two decimal places after the decimal separator but some will have three, four, or zero.

The decimalPlaces parameter also accepts negative values up to -17. Entering a negative value will effectively zero out the entered number of places on the integer side of the decimal point. For example if your value is 12345 and you enter -4 for the parameter value, the function returns 10000. If you enter -3, the function returns 12000. A value of -5 in this example would return 0.

Using the showSeparators parameter

The showSeparators parameter determines whether or not the function uses digit separators. How those digit separators appear is determined solely by the user's locale settings. For example, if the user's locale is set to English (US) digit separators appear as commas (,). If the user's locale is set to Spanish, digit separators will instead appear as periods (.).

If no showSeparators value is passed, the function shows separators by default.

Using the format parameter

The format parameter determines how the currency indicator should display, for example "CODE" (USD) or "SYMBOL" ($).

If no format value is passed, the function uses "LOCALE" by default. The "LOCALE" setting uses the logged in user's locale setting to determine whether to use a symbol or the ISO code for the currency indicator.

Using the indicatorAlignment parameter

The indicatorAlignment parameter determines where that currency indicator displays in relation to the value, for example, at the "START" or "END" of the value.

If no indicatorAlignment value is passed, the function uses "LOCALE" by default. The "LOCALE" setting uses the logged in user's locale setting to determine where to place the currency indicator.

Examples

Locale differences

Default behavior

1
2
3
4
a!currency(
  isoCode: "USD",
  value: 1234.56
)

If user's locale is set to English (United States), returns $1,234.56.

If user's locale is set to Español, returns 1.234,56 US$.

If user's locale set to Français (Canada), returns 1 234,56 $ US.

Override defaults

1
2
3
4
5
6
7
a!currency(
  isoCode: "USD",
  value: 1234.56,
  showSeparators: false,
  format: "CODE",
  indicatorAlignment: "START"
)

If user's locale is set to English (United States), returns USD 1234.56.

If user's locale is set to Español, returns USD 1234,56.

If user's locale set to Français (Canada), returns USD 1234,56.

Decimal places

Decimal rounding

1
2
3
4
a!currency(
  isoCode: "USD",
  value: 1234.5678
)

Returns $1,234.57. To maintain the precise value, you would change the decimalPlaces parameter to 4.

Negative decimalPlaces value

1
2
3
4
5
a!currency(
  isoCode: "USD",
  value: 1234.5678,
  decimalPlaces: -3
)

Returns $1,000.

Formatting

1
2
3
4
5
a!currency(
  isoCode: "USD",
  value: 1234.56,
  format: "SYMBOL"
)

Returns $1,234.56.

Changing the format value to "CODE" returns USD 1,234.56.

Indicator alignment

1
2
3
4
5
a!currency(
  isoCode: "USD",
  value: 1234.56,
  indicatorAlignment: "START"
)

Returns $1,234.56.

Changing the indicatorAlignment value to "END" returns 1,234.56 $.

Feature compatibility

The table below lists this function's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Incompatible
Sync-Time Custom Record Fields Incompatible
Real-Time Custom Record Fields Incompatible

Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.

Process Reports Compatible
Process Events Compatible

Old versions

There are older versions of this function. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

Old Versions Reason for Update
currency_22r4

Expanded currency localization capabilities. Now supports hundreds of currencies by accepting an ISO code and outputs a formatted currency value based on locale.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Open in Github Built: Fri, Mar 31, 2023 (07:34:44 PM)

On This Page

FEEDBACK