Configuring currency conversion

You can configure currency conversion functionality in NexJ Studio and create currency conversion fields for your NexJ application.

Currency conversion fields enable users to display and filter monetary values in the currency that they choose.

Configure currency conversion for your NexJ application when you want to provide users with fields in which values can be converted between currencies. Use currency conversion fields to provide functionality such as:

Allowing users to enter a monetary value in a currency and view the converted value in a different currency.
Displaying amounts entered in multiple currencies using a single currency.
Filtering and accruing amounts entered in multiple currencies using a single currency.

To configure currency conversion, you first enable it in the environment for your NexJ application in NexJ Studio.

Info

Before enabling currency conversion, you must provide exchange rates through integration with a third-party data provider.

By default, currency conversion is disabled. If Capital Markets functionality is enabled, then currency conversion is also enabled.

After you enable currency conversion, currency conversion fields are available by default in the following areas in NexJ CRM:

For B2B wealth management deployments:
Opportunity records
Displays expected and actual values in a user's preferred currency using the current day's exchange rate.
For capital markets deployments:
Company records
Displays market capital values in a user's preferred currency using the current day's exchange rate.
Holdings tab
Displays holding and calculated commission values in a user's preferred currency using the current day's exchange rate.
Transactions tab
Displays transaction amounts and commission amounts in a user's preferred currency using the exchange
rate for the transaction date.
For ad hoc reporting deployments:
Visualization tab
Displays monetary values on the axes and in chart text in a user's preferred currency.
Summary tab
Displays fields of monetary values in a user's preferred currency.
Live Detail tab
Displays fields of monetary values in a user's preferred currency.
Export Details
Displays the monetary symbol and values in a user's preferred currency.

You can also create custom fields in NexJ Studio that convert the currency type entered by a user into their preferred currency type.

Info

After you configure currency conversion, you must redeploy your NexJ application to make currency conversion functionality available to users.

Enabling currency conversion

Enable currency conversion in an environment to allow developers to convert values between currencies for the NexJ application.

Before enabling currency conversion, you must provide exchange rates through integration with a third-party data provider.

To enable currency conversion for your NexJ application:

In NexJ Studio, navigate to the Deployment layer.
In the Environments tab, open the environment for your NexJ application.
In the Source view, set the currencyConversionEnabled parameter in the <Environment> tag to true.
The <Environment> tag should now look similar to the following:
TEXT
```
<Environment authDomain="<EXAMPLE.COM>" ... currencyConversionEnabled="true" ...
 user="admin">
```
Click the Save button to save your changes to the environment.

Currency conversion is enabled for your NexJ application.

You can now create custom fields in NexJ Studio to convert currencies in your NexJ application.

Converting currency values

Create custom fields in NexJ Studio to convert values between currencies for your NexJ application. You create custom fields that use events from the ExchangeRate class.

To convert a currency value in NexJ Studio, use the convertAmount static event. The convertAmount event converts a currency value using the exchange rate for a specified date. If a date is not specified, the exchange rate for the current date is used. If the exchange rate for a specified date is not available, the event searches for the most recent exchange rate from the specified date. If the event cannot find a recent exchange rate, it returns 1 as the rate.

Info

For more information, see the getExchangeRate event in the ExchangeRate class in NexJ Studio.

The convertAmount event can be called in both the client and the model. The event does not check whether currency conversion is enabled, so it is recommended to include a check on Currency'ENABLE_CURRENCY_CONVERSION.

Using the convertAmount event

The following code converts $500 Canadian dollars (CAD) to US dollars (USD) using today's exchange rate:
(ExchangeRate'convertAmount (CurrencyEnum'get 'USD) (CurrencyEnum'get 'CAD) 500)

The following code converts $500 Canadian dollars to US dollars using the exchange rate for January 31, 2015:

SCHEME

(ExchangeRate'convertAmount (CurrencyEnum'get 'USD) (CurrencyEnum'get 'CAD) 500
 #m2015-01-31T00:00:00.000000000)

Converting persisted attributes

If you convert persisted attributes using an exchange rate, you must also include an event to recalculate the attributes when the exchange rate is modified. Otherwise, new values are not converted for persisted attributes when the exchange rate is updated.

Info

For more information, see the implementation of the updateExchangeRate event in the ExchangeRate class in NexJ Studio.

Creating currency conversion fields

You should create fields in which currency conversion can occur as string fields. This ensures that when currency conversion is disabled, the fields display using the short currency format, and when currency conversion is enabled, the fields display using the long currency format.

Info

You can use the currencyConversion.scm library to help create the string fields. For examples of how to use string fields, see the implementation of currency conversion in the Transactions and Holdings tabs for capital markets.

Summing currency values

Currency values are summed using two methods depending on whether currency conversion is disabled or enabled.

For example, if a company has three transactions with the commissions $100 USD, $50 CAD, and $25 AUD, the total commission is summed as follows:

If currency conversion is disabled, the system sums the direct commission values of each transaction, regardless of the listed currency. In this case, the sum of the commissions is $175. The system assumes that values are listed using only one currency.
If currency conversion is enabled, the system sums the normalized commission values and then converts values. For example, the system converts the values to USD using the exchange rates from the dates of the transactions, sums the values, then converts the total to the user's preferred currency using today's exchange rate.

Seeding exchange rates

Before you can perform currency conversions using the ExchangeRate class, you must configure an exchange rate provider.

The exchange rate provider must supply all exchange rates that will be used in currency conversions. A complete set of exchange rates must be supplied for each day. When you seed exchange rates for a specific day, you must seed all exchange rates for the day. The system does not support seeding a partial list of exchange rates.

Info

Exchange rates cannot be seeded daily. To perform currency conversions using today's exchange rate, you must use a batch action or script.

When seeding exchange rates for a new day, if you add a new financial date that is the most recent date, you must call the updateLatestFinancialDate event. This indicates to the system that the exchange rate is the most recent. Financial dates must be unique per day. You cannot seed more than one financial date for the same day, even if the financial dates have different times.

Exchange rates must be bidirectional. For example, the exchange rates for converting between US dollars (USD) and British pounds (GBP) must include rates for USD to GBP and GBP to USD. The exchange rates must also include a rate to convert from a currency to itself. For example, the exchange rates for converting US dollars must also include a rate for converting from USD to USD. The rate to convert a currency to itself should be set to 1.

Seeding exchange rates for capital market transactions

You seed exchange rates for capital market transactions with normalized or direct transaction or commission values. Normalized values are values that have been converted to a common currency, for example USD. Direct values are values that have not been normalized. If direct values are seeded, the system calculates normalized values using today's exchange rate.

Updating exchange rates

You can update and correct exchange rates using the updateExchangeRate non-static event from the ExchangeRate class. The event updates an exchange rate and recalculates normalized values of capital market transactions.

Info

When you update an exchange rate, you should ensure that associated exchange rates are also updated. The system does not ensure that exchange rates between two currencies are reciprocal. For example, if you update the exchange rate for US dollars to British pounds, the system does not check to ensure that the rate for GBP to USD is the reciprocal of the updated USD to GBP.