Currency

A currency value is used to represent monetary values. It has two properties:

The Amount property is a decimal value.  

The Code property is a string that holds either a 3-character ISO 4217 code or the value NOT_SET.

Adding or Subtracting Currency Values in Expressions

When you add or subtract currency values, the currency codes of the currency values should be the same. For example, the following expression is valid at runtime:

MakeCurrency(5.00, “USD”) + MakeCurrency(10.00, “USD”)

This expression evaluates to a currency value with an amount of 15.00 and a code of “USD” ( United States Dollars ). 

The following expression causes an error at runtime because the currency codes are not the same (Euros and Dollars):

MakeCurrency(5.00, “EUR”) + MakeCurrency(10.00, “USD”)

The following expression is valid:

MakeCurrency(5.00, NOT_SET) - MakeCurrency(10.00, NOT_SET)

This expression evaluates to a currency value whose amount is -5.00 with a NOT_SET currency code.

Multiplying or Dividing Currency Values in Expressions

When performing multiplication or division, the left-hand side should be a currency value and the right-hand side should be an integer or decimal.  For example:

MakeCurrency(5.00, “EUR”) * 10.0

This expression results in a currency value of 50.00 whose code is “EUR” ( 50.00 Euros ).  If you do decide to put a currency value on both sides of a multiplication or division operation, the result is going to be a decimal, not a currency value.  For example:

MakeCurrency(5.00, “EUR”) * MakeCurrency(10.00, “USD”)

This expression returns a decimal value of 50.00. Technically, multiplying a currency value by another currency value is not supported. However, the parser adds implicit casts and recognizes that it can convert both currency values to decimals. It then multiplies the decimal values. The above expression, when parsed, actually looks like this at runtime:

ToDecimal(MakeCurrency(5.00, "EUR")) * ToDecimal(MakeCurrency(10.00, "USD"))
 

Tip: When you write an expression in the Custom Calculation Builder dialog box, click on the CPU with the play button to see what the runtime expression will look like.  

Obtaining the Symbol for a Currency

There is no "Symbol" property for a currency. However, you can use an expression to return the correct currency symbol:

GetCurrencySymbol(MakeCurrency(5.0,”USD”))

This expression returns $.

Adding a Currency Variable

To add a currency variable:

1. In the Processes list, double-click the Variables container in your process. IPA Designer displays the Variables workspace in the center pane.

2. For a state or task, right-click in the blank area of the Variables tab, point to Add, and then click Currency.  IPA Designer displays the Add Variable dialog box (see figure).
   
   

3. Enter a name, label, and description:

   1. In the Name text box, type the name of the variable. The variable name must begin with a letter.

   2. In the Label text box, type the label to identify the variable on work item pages.

   3. In the Description text box, type a brief description of the variable.

4. If you want to create the variable as a collection (see the section on Collections of Variables), select the check box labeled Contains a collection of variables.

5. Select the variable's security, accessibility, and database reporting settings:

   1. In the Security list box, expand the list box to select from a list of security specifications previously created in Interaction Administrator. (If no security specifications are defined, only NOT SET and Literal are available.)

   2. In the Accessibility list, either accept the default accessibility value of Private or expand the list box to select from the list of accessibility settings.

   3. To include the variable's value in the reporting database, select the "Include the final value …" check box.

6. (Optional) To limit the variable's possible values to a specific list:

   1. Select the check box labeled Limit values to list. IPA Designer displays an Available Values text box (see figure).
      
      

   2. Click the Collection  icon at the right end of the text box. IPA Designer displays the Edit Currency Collection dialog box (see figure).
      
      

   3. Click Plus  to add a row to the list. Double-click the row, type a currency value to add, then press Enter.

   4. Repeat (c) to add more currency values as needed.

   5. (Optional) Type the desired number of decimal places in the Display decimal places text box.

   6. Click OK to return to the Add Variable dialog box.

Note: If you limit the variable's values to a list, you cannot set minimum or maximum values for the variable. In addition, you must set an initial value that appears in the list.

7. (Optional) To set a minimum or maximum value click the down arrow button at the right of the Minimum or Maximum value row, then enter the desired value in the text box.

8. (Optional) To change the default display and precision of two decimal places, enter the desired integer value (from 1 to 28) in the Display decimal places text box.

9. (Optional) If you want to set an initial value for the variable:

   1. Type the value in the Initial Value box.

   2. To set a currency code, select it from the list. Otherwise, click and then click NOT_SET.

   3. If the variable is a collection, click the Collection icon and add items.

10. Click Add.
    
    IPA Designer adds your new variable to the variable list in the Variables workspace.

Properties of Currency Variables

Property	Description
Name	The name by which you refer to the variable in your process. The name must begin with a letter or underscore (_). It can contain digits (0 to 9), but cannot contain any other characters, including spaces or punctuation. Best practice: If the name consists of multiple words, begin the first word with an upper-case letter and begin other words with uppercase letters.
Label	The label that identifies the variable on work item pages.
Description	A brief description of the variable and its purpose, sufficient to explain the variable to someone who knows nothing about why it was created.
Collection	Indicates whether or not the variable is a collection of values.
Security	A list of users or workgroups allowed to see the value of the variable. In Interaction Administrator, create security specification groups to include users and workgroups that can see particular data items. In IPA Designer, each variable's Security Specification property has a list box with in which the designer can choose from the Interaction Administrator groups available for that variable. For more information, see the IPA Technical Reference.
Accessibility	How the process can use the variable. For more information, see Variable Accessibility.
Include final value in reporting database	Indicates whether or not to include the currency value in the process reporting database.
Limit values to list	Indicates whether or not the user can only enter values on a specific list or within a specific range.
Minimum Value	The smallest decimal value to which the variable can be set. Optional.
Maximum Value	The largest decimal value to which the variable can be set. Optional.
Display Decimal Places	The number (1 to 28) of digits displayed to the right of the decimal point. Default value is 2. This property is specific to amount values. It behaves similarly to Decimal data types when bound to text boxes or grids on work item pages.
Initial Value	The value and currency of the variable when the process starts. The default amount is 0.00. The default currency code is the ISO 4217 code for the locale where the Designer is running.