15 Configuring Currency Options

This chapter describes how to configure currency options in Oracle Business Intelligence. When content designers create analyses, they often include data that shows currency, such as American dollars. As the administrator, you can perform various tasks that affect currency options that are available to users.

This chapter includes the following sections:

Changing the Default Currency for Analyses
Defining User-Preferred Currency Options

15.1 Changing the Default Currency for Analyses

You can change the default currency that is displayed, for example, from French Francs to Euros. For information about using formatting functions in Answers, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

To set the default currency:

Open the currencies.xml file in the directory
ORACLE_HOME/bi/bifoundation/web/display.
Search for the currency to make the default, for example, USD, CAD, PEN, or MAD.

Copy the entire currency element.

For example, copy the currency tag for the Euro:

- <Currency tag="int:euro-l" type="international" symbol="_" displayMessage="kmsgCurrencyEuroLeft" digits="2" format="$ #">
<negative tag="minus" format="-$ #" />
</Currency>

Search for the text string int:wrhs, located near the top of the file.
Select the entire element and replace it by pasting the copied element over it.
Replace the tag attribute so it reads int:wrhs.

For example, replace tag="int:euro-l" with tag="int:wrhs".
Restart the service for Oracle BI Presentation Services.

Caution:

The currencies.xml file is overwritten when applying an upgrade, a patchset, a bundle patch, or a one-off patch. If you have made changes to this file, reenter your changes in the new currencies.xml.

To specify the currency for a column in a customized subject area:

In Answers, modify the analysis that uses the subject area.
In the Analysis editor: Criteria tab, click the Options button for the currency column and select Column Properties to display the Column Properties dialog.
Click the Data Format tab and select the Override Default Data Format box.
In the Treat Numbers As box, select Currency.
In the Currency Symbol list, select User's Preferred Currency.
Complete the other options on the tab as appropriate.
If desired, save this setting as a systemwide default.
Click OK when you have finished, and repeat the preceding steps for any other columns to change.

Considerations for defining user-preferred currency:

To create a default for all users, set the CURRENCYTAG element using an INIT BLOCK.
If you configure a user-preferred currency, set the PREFERRED_CURRENCY element using an INIT BLOCK.

For more information about defining user-preferred currency options, see Section 15.2, "Defining User-Preferred Currency Options".

For more information about INIT BLOCKs, see "Working with Initialization Blocks" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

15.2 Defining User-Preferred Currency Options

Users can select the currency in which they prefer to view currency columns in analyses and dashboards in two ways:

In the Currency box on the My Account dialog: Preferences tab
In currency prompts

Figure 15-1 Example of the Currency Box on the My Account Dialog: Preferences Tab

Description of ''Figure 15-1 Example of the Currency Box on the My Account Dialog: Preferences Tab''

For information about setting the currency preference on the My Account dialog: Preferences tab or about currency prompts, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

You define the currency options that are to be displayed in the Currency box and in a currency prompt in the userpref_currencies.xml file. (These currency options must be for currencies to which your installation can convert columns.) Defining the currency options also controls whether the Currency box is available on the My Account dialog: Preferences tab and whether the Currency Prompt option is available on the Definition pane of the Prompt editor.

When you define these currency options, you can use one of two types of mappings:

Static — Produces a static list of currency options that all users see.
Dynamic — Produces a list of currency options that changes dynamically based on a logical SQL statement that you specify. This is useful, for example, to dynamically change the currency options so that each user sees a list specific to his or her account. Each user sees a subset of the total options available. For example, one group of users might want to select from only Global Currency 1 or Global Currency 2 while another group might want to select from different options.

Note:

For the user-preferred currency options to take effect, the following configuration also must be done in the Oracle Business Intelligence repository:

Creation of the PREFERRED_CURRENCY session variable.
Conversion setup of logical currency columns in the Business Model and Mapping layer
Creation of the userCurrencyPreference table using the currency information from your installation that enables you to dynamically change the currency options based on a logical SQL statement that you specify (required only if you use a dynamic mapping)

For information, see "Configuring Logical Columns for Multicurrency Support" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

You can set the contents of the user's preferred currency by using the PREFERRED_CURRENCY session variable. You define the UserCurrencyPreferences element in any one of the following files:

instanceconfig.xml file, or in userpref_currencies.xml files located in:

BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
yourfilename, where the instanceconfig.xml file contains an entry pointing to your file. For example,
```
<UserprefCurrenciesConfigFile>yourpath</UserprefCurrenciesConfigFile>
```
where, yourpath is the location of the file.

15.2.1 Defining User-Preferred Currency Options Using a Static Mapping

You can use a mapping to define a static list of options that all users see for selecting currency.

To define the user-preferred currency options using a static mapping:

Use a text editor to open the userpref_currencies.xml file located in the following directory:

BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

Add a UserCurrencyPreferences element as follows:

<UserCurrencyPreferences currencyTagMappingType="static">

</UserCurrencyPreferences>

For each currency option to be displayed in the Currency box or in currency prompts, add a UserCurrencyPreference element between the <UserCurrencyPreferences> tags using this format:
```
<UserCurrencyPreference sessionVarValue="sessionVarValuevalue" displayMessage="displayMessagevalue" displayText="displayTextvalue" currencyTag="currencyTagvalue"/> 
```
In this format:
- sessionVarValue="sessionVarValue " sets the session variable PREFERRED_CURRENCY. For its value, specify a string that uniquely identifies the currency, for example, gc1.
- (optional) displayMessage="displayMessagevalue" sets the presentation variable currency.userPreference to a localized value. To specify a localized value, you first must create the localized message for the currency in the usercurrencymessages.xml file. For information, see Section 14.2.1.2, "Localizing Messages for Users' Preferred Currency." Then, for the value of displayMessage, specify the WebMessage name that is identified in the usercurrencymessages.xml file for the currency. For example, if you created this English language entry in the usercurrencymessages.xml file:
```
<WebMessage name="kmsgMyCurrency1"><TEXT>My Currency 1</TEXT></WebMessage> 
```
  Then you would specify kmsgMyCurrency1 as the value of displayMessage.
- (optional) displayText="displayTextvalue" sets the presentation variable currency.userPreference to a value that is not localized. For its value, specify a string that identifies the currency, such as Global Currency 2.
  
  For more information about the currency.userPreference variable, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition
- currencyTag="currencyTagvalue" identifies the Currency Tag in the currencies.xml file whose displayMessage value is to be used to populate the Currency box on the My Account dialog: Preferences tab and currency prompts. (The currencies.xml file, which is located in ORACLE_HOME/bi/bifoundation/web/display, provides currency formats.)
Note:
The value of the currency.userPreference variable is obtained from the displayMessage and displayText attributes of the UserCurrencyPreference element using the following order of precedence:
1. displayText
2. displayMessage
If no values exist for displayText and displayMessage, then the value of the displayMessage attribute for the corresponding currency tag in the currencies.xml file is used.
Save and close the userpref_currencies.xml file.
Restart Oracle Business Intelligence.

For information, see Section 2.1, "About Managing Oracle Business Intelligence Processes."

15.2.2 Example: Static Mapping to Define User-Preferred Currency Options

The following example shows a userpref_currencies.xml file that uses a static mapping to define user-preferred currency options:

<UserCurrencyPreferences currencyTagMappingType="static">
   <UserCurrencyPreference sessionVarValue="gc1" displayText="Global Currency 1" currencyTag="int:USD" />
   <UserCurrencyPreference sessionVarValue="gc2" displayText="Global Currency 2" currencyTag="int:euro-l" />
   <UserCurrencyPreference sessionVarValue="gc3" displayText="Global Currency 3" currencyTag="loc:ja-JP" />
   <UserCurrencyPreference sessionVarValue="orgc" displayText="Org Currency" currencyTag="loc:en-BZ" /> 
</UserCurrencyPreferences>

Figure 15-2 shows how these values from the userpref_currencies.xml file are displayed in a drop-down list of currency options for a prompt on a dashboard page. The drop-down list is similar to what is displayed for the Currency box on the My Account dialog: Preferences tab.

Figure 15-2 Static Currency Options in a Prompt

Description of ''Figure 15-2 Static Currency Options in a Prompt''

15.2.3 Defining User-Preferred Currency Options Using a Dynamic Mapping

You can use a mapping to define a dynamic list of options that users see for selecting currency. The list changes dynamically based on a logical SQL statement that you specify. This is useful, for example, to dynamically change the currency options based on the user.

To define user-preferred currency options using a dynamic mapping:

Use a text editor to open the userpref_currencies.xml file that is located in the following directory:

BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

Add a UserCurrencyPreferences element as follows:

<UserCurrencyPreferences currencyTagMappingType="dynamic">

</UserCurrencyPreferences>

Add a UserPrefCurrencyLogicalSQL element between the <UserCurrencyPreferences> tags using this format:
```
<UserPrefCurrencyLogicalSQL>
SELECT column1, column2, column3 FROM userCurrencyPreference
</UserPrefCurrencyLogicalSQL>
```
In this format:
- column1 contains the values that are used to set the session variable PREFERRED_CURRENCY. Each value in this column is a string that uniquely identifies the currency, for example, gc1.
- column2 contains the currency tags in the currencies.xml file whose displayMessage values are to be used to populate the Currency box and currency prompts, for example, int:euro-1. (The currencies.xml file, which is located in ORACLE_HOME/bi/bifoundation/web/display, provides currency formats.)
- (optional) column3 contains the values used to set the presentation variable currency.userPreference. Each value in this column is a string that identifies the currency, such as Global Currency 2.
  
  Note:
  If you omit column3, then the values for the displayMessage attributes for the corresponding currency tags in the currencies.xml file are used.
  
  For more information about the currency.userPreference variable, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition
Save and close the userpref_currencies.xml file.
Restart Oracle Business Intelligence.

For information, see Section 2.1, "About Managing Oracle Business Intelligence Processes."

15.2.4 Example: Dynamic Mapping to Define User-Preferred Currency Options

The following example shows a userpref_currencies.xml file that uses a dynamic mapping to define user-preferred currency options:

<UserCurrencyPreferences currencyTagMappingType="dynamic">
UserPrefCurrencyLogicalSQL>
<!-- In this SELECT statement, column1 contains the values to set the PREFERRED_CURRENCY variable, column2 contains the currency tag values, and column3 contains the values to set the currency.userPreference variable. --> 
SELECT markets.userpreferences, markets.currencyTag, markets.userpreferencename FROM userCurrencyPreference
</UserPrefCurrencyLogicalSQL>
</UserCurrencyPreferences>

Table 15-1 shows sample results from the logical SQL statement.

Table 15-1 Sample Logical SQL Results

"Markets"."UserPreference"	"Markets"."CurrencyTag"	"Markets"."UserPreferenceName"
varchar	varchar	varchar
orgc1	loc:en-BZ	Org currency
gc2	int:euro-1	Global currency 2
lc1	int:DEM	Ledger currency
gc1	int:USD	Global Currency 1

Figure 15-3 shows how the values that are generated dynamically from the SQL statement in the userpref_currencies.xml file are displayed in a drop-down list of currency options for the Currency box on the Preferences tab of the My Account dialog. The drop-down list is similar to what is displayed for a prompt on a dashboard page.

Figure 15-3 Dynamic Currency Options in the My Account Dialog

Description of ''Figure 15-3 Dynamic Currency Options in the My Account Dialog''