Currency Exchange Rate Sync Installation Guide

The ‘Currency Exchange Rate Sync’ App runs a daily sync of currency conversion rate data to your Salesforce instance, creating DatedConversionRate records for all of your enabled currencies. This is part of Salesforce’s Advanced Currency Management feature, which makes reporting on the total Amount of Opportunities that closed at various times across various currencies seamless and accurate.

The steps for installation are as follows:

1. 1-Click Setup
2. Sources
3. Supported Currencies
4. Prerequisites
5. Installing the Package
6. Setting Permissions
7. Navigating to the App
8. Scheduling the Data Sync
9. Reporting
10. Possible Errors
11. Advanced Configuration
12. FAQs
13. Creating a Support Ticket
14. Changelog

1-Click Setup

Most people will be happy with the 1 click setup. Go to the Currency Exchange Rate Sync Record page and click ‘Daily’ in the upper left. You can optionally do backfills and bulk deletes with a few more clicks.

Sources

You have the ability to set which sources the exchange rate data is pulled from. If you set the ‘Sources’ field to ‘imf’, you will only get exchange rate data from the International Monetary Fund. Combining sources is sometimes necessary because not every source has every currency. More info on sources. List of all sources. The source that provides an exchange rate is a field in the API response body, which can be seen in HTTP Request Logs.

Supported Currencies

The App supports 150 of the currencies supported by Salesforce. More info on currencies. List of all supported currencies. There is over 20 years of historical data.

Prerequisites

In order to install, you will need to check the box Activate Multiple Currencies within 'Setup' -> 'Company Information'. Note that once Multiple Currencies is enabled, it cannot be disabled. If you are enabling advanced currency management for the first time, take note of Considerations of Enabling Multiple Currencies as well as About Advanced Currency Management. As always, you are advised to work in a Sandbox before working in production.

Under 'Setup' -> 'Manage Currencies', be sure that 'Advanced Currency Management' is enabled. This is the feature that allows different exchange rates at different dates as opposed to a single exchange rate for all time. Without it, Salesforce will not allow the insertion of DatedConversionRate records.

Installing the Package

Go to the AppExchange Page and click ‘Get it Now’.

You should choose Install for Admins Only. Otherwise, Salesforce will grant Create, View, Edit, Modify to both Custom Objects to all users. This means they will be able to see the App Configuration and the Logs and be able to make changes. The log records are not sensitive, but it is also not relevant to most Salesforce Users. There are two Permission Sets, Admin and a Read Only, which can be used for sharing permissions with non-Admin Users.

To install, press the 'Install' button. A popup will come checking that you are okay to send or receive data from 'api.mycompanylist.com'. This is because the Package makes API calls to this host in order to pull in the latest exchange rate data. Note that connections are SSL/TLS encrypted.

Check the box 'Yes, grant access to these third-party web sites', and press 'Continue'. You should receive an email that the package was installed successfully. Press ‘Done‘ to finish the installation.

Setting Permissions

If the App is being run by a System Administrator, no assignment of Permission Sets is necessary. However, other users can be enabled to view and update the App configuration by assigning the following Permission Sets:

• Currency Exchange Rate Sync Read Only
• Currency Exchange Rate Sync Admin

Even if a user is assigned ‘Currency Exchange Rate Sync Admin‘, they will still need the System Permission ‘Customize Application‘ assigned to be able to create or delete DatedConversionRate records. Note that system permissions cannot be deployed in a managed package.

Within Reports, there is a folder called ‘Currency Conversion Rate Sync‘. If you are granting access to this App via Permission Sets, it also makes sense to share this Report Folder with the same people, either through User specific sharing, or Public Groups.

Navigating to the App

There will be a new item in the 9 circle App Navigation called ‘Currency Exchange Rate Sync‘. Click it.

Navigate from ‘Recently Viewed‘ to the ‘All‘ List View.

An instance of the ‘Currency Exchange Rate Sync‘ App Object has been created during installation. This is an App configuration Object. There is only intended to be one record of this Object. Click on the only record.

The App should open up, and look a bit like this, if you don’t already have any DatedConversionRate records in Salesforce.

You can take these actions:

• Schedule / unschedule the Exchange Rate Data Sync
• Perform bulk backfills / deletes
• See errors that have occurred and optionally receive email alerts
• Visualize DatedConversionRate records
• Update App configuration and see configuration history
• See Logs of HTTP requests and emails
• Send a support ticket

After running a backfill and scheduling a daily job, and hitting refresh on all the components, the App looks like this.

Here are some things to notice:

• There is a value for ‘Previous Run’ and ‘Total Runs’ is 1 in the upper left ‘Currency Exchange Rate Sync’. This means the job has run once and is scheduled to run again on ‘Next Run’.
• There is data in the Data Table at the bottom of ‘Delete of Backfill Date Range of DatedConversionRate Records’, and 36 records selected. If I were to hit ‘Delete’, these are the records that would be deleted. If I were to hit ‘Backfill’, these records would not be overwritten.
• There is a line chart and a table of values in ‘DatedExchangeRate Records’. It’s easy to verify that the data looks correct. In this case the base currency is USD, so, as expected, EUR is a little bit less than 1, because 1 USD buys about 0.92 EUR today. The conversion rate answers the question, “How many units of this currency can I buy with one unit of base currency?”.
• In the bottom right, ‘Exchange Rates Uploaded / Deleted’, we see a count for the number of Exchange Rate datapoints have been deleted and created by day, by counting the field ‘Num Dated Conversion Rates’ on HTTP Request Logs.

Scheduling the Data Sync

You can easily schedule / unschedule the Exchange Rate Data Sync in the upper left hand side panel.

A common choice is to schedule the sync Daily.

After pressing the ‘Daily‘ button, the details of the Apex Job that is now scheduled will appear.

A minute later, by hitting ‘Refresh’, you should see a value for ‘Previous Run‘ and that ‘Total Runs‘ is now 1.

The options and their corresponding cron statements are:

• Daily: XX XX XX * * ?
  • XX XX XX represents the current time 30 seconds in the future
• Monthly: 0 0 0 1 * ?
  • First of the month
• Quarterly: 0 0 0 1 */3 ?
  • First of the month every 3 months
• Annually: 0 0 0 1 1 ?
  • First of the year

You may want to use a different cron expression. The Class ‘SchedulableDatedConversionRateSync‘ is declared as ‘Global‘ to make this possible. In order to achieve this, you must execute some anonymous apex via the Developer Console. In the upper right, click on the gear icon and select 'Developer Console'.

A window will pop open titled 'Developer Console'. Within the menu item 'Debug', select 'Open Execute Anonymous Window'.

A window should popup titled 'Enter Apex Code'. Enter the following Apex code and hit 'Execute'.

System.schedule('SchedulableDatedConversionRateSync', '0 0 10 * * ?', new mcl.SchedulableDatedConversionRateSync());

This example will create a scheduled job called ‘SchedulableDatedConversionRateSync‘, which will run every day at 10:00:00 AM. Feel free to modify the name and cron expression accordingly.

The Job will appear within the ‘Currency Exchange Rate Sync’ component, as well as your Salesforce Scheduled Jobs within 'Setup' -> 'Apex Jobs' (/lightning/setup/ScheduledJobs/home)

Reporting

Within 'Reports' -> 'All Folders', you will see a folder titled ‘Currency Conversion Rate Sync‘. Open it up.

Inside are 4 Reports:

• HTTP Requests: Currency Conversion Rate
  • One log per HTTP request, showing request and response fields, with a plot showing the number of HTTP Requests by day
• Errors: Currency Conversion Rate Sync
  • One log per error encountered. Does not include Async Apex Errors
• Exchange Rates Uploaded / Deleted
  • HTTP Requests to Salesforce and a plot of the number of DatedConversionRate records Inserted / Deleted
• Exchange rates Downloaded
  • HTTP Requests to api.mycompanylist.com and a plot of the number of DatedConversionRate records received.

These reports can be useful for verifying that the sync is working as expected and showing what errors are occurring if any. You can consider creating Report Subscriptions to notify you if something is wrong. Additionally, you also have the option to enable Error Email Alerts within the App’s configuration.

Advanced Configuration

With the App’s record detail, there are several advanced configuration options.

API Parameters

The Currency Exchange Rate API Documentation contains in depth explanations of the API parameters that you can modify.

Email Alerts

You can configure the Sync to send email alerts to the recipients of your choice, and optionally exclude certain errors. Here is an example configuration that will send an email to ‘elliot@mycompanylist.com’ every time an error is encountered that isn’t a Bad HTTP Request nor a Missing Currency Exception.

Currency Mappers

In case you want to customize which currency in Salesforce maps to which currency in api.mycompanylist.com, or you want to add a multiplier to the exchange rate, this can be achieved via the Currency Mapper Custom Metadata Type. Within 'Setup' -> 'Custom Metadata Types' -> 'Currency Mappers' -> Manage Records, you can add and modify these records.

The field ‘Label’ corresponds to the ISO Code on the Salesforce side of the sync, while the field ‘Currency Mapper Name’ refers to the ISO Code on the api.mycompanylist.com side of the sync.

Possible Errors

App Installation Error: ‘Missing Organization Feature: MultiCurrency’.

Solution: Enabling MultiCurrency is required for this App to be installed. See prerequisites for more info on enabling. Then, retry installation.

Error Log: CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY

If Salesforce HTTP Requests are responding with a 400 and a response body with content like this:

{"hasErrors":true,"results":[{"referenceId":"referenceIdAED2023_12_14","errors":[{"statusCode":"CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY","message":"entity type cannot be inserted: Dated Conversion Rate","fields":[]}]}

There are two possibilities:

1. Advanced Currency Management is not enabled. Double check this as outlined in prerequisites.
2. The running user of the data sync, backfill, or delete does not have ‘Customize Application’ permission.
   • This can be granted on the Profile or via a Permission Set.
   • Or, you may wish to run these jobs under a different user that already has this permission assigned.

Buttons to schedule / unschedule job and backfill and delete are not showing

The LWCs only show the buttons to modify DatedConversionRate records if the running User has Customize Application permission. Here is what the ‘Currency Exchange Rate Sync’ and ‘Delete of Backfill a Date Range of DatedConversionRate Records’ panels look like to a User without this permission. There is no button perform a backfill, delete, nor to schedule / unschedule the job.

Once ‘Customize Application’ permission is assigned to the User, they will be able to insert and delete DatedConversionRate records and the missing buttons will appear. Customize Application is essentially the keys to the castle in Salesforce. The User has full access to modify (almost) all metadata within Setup. This is a requirement imposed by Salesforce, otherwise the User will get a ‘CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY’ error when attempting to Create or Delete DatedConversionRate records. Within About Advanced Currency Management, we see ‘Customize Application’ as the required permission to change currencies.

Visualization is not showing

In the upper right of the App you should see a plot of existing DatedConversionRate records. However, you may instead see the following text:

Please enable Lightning Web Security to visualize your DatedConversionRate records via chart.js. LWS is enabled within Session Settings by checking Use Lighting Web Security for Lightning web components and Aura components and hitting Save. Before enabling, please test in Sandbox, as described here.

If you want the visualization to show up, you need to enable Lightning Web Security, which allows Managed Packages to ship third party JS Libraries, such as chart.js, and load content in a secure way. This can be done under 'Setup' -> 'Session Settings' -> 'Use Lighting Web Security for Lightning web components and Aura components' (/lightning/setup/SecuritySession/home), and then hitting ‘Save‘ at the bottom of the page.

It is recommended to thoroughly test in a sandbox all of your Aura Components before doing this in production, as discussed here.

I cannot view Reports and I don’t see the Report Folder ‘Currency Exchange Rate Sync’

There is a Report component on the Currency Exchange Rate Sync Record Page that should show up below the panel ‘DatedExchangeRate Records’ and above the Log List View. There is also a Report Folder called ‘Currency Exchange Rate Sync‘ which contains Reports. If neither of these are showing, or you cannot see Reports inside the folder, have an Admin double check that the Report Folder ‘Currency Exchange Rate Sync’ is shared with you.

Backfill is producing Async Apex error ‘Apex heap size too large’

The historical data goes back over 20 years. Depending on the number of currencies you have enabled, backfilling a large span of time in a single action can lead to this error. In my testing, I was able to backfill 10 years at a time with 6 currencies enabled.

FAQs

• Does this app cost anything to run?
  • No, the app is free, and accessing https://api.mycompanylist.com/v1/exchangerate/* is also free.

• Do I need an API Key?
  • There is no requirement for an API Key or any authentication.

• Which currencies are supported?
  • At time of writing, api.mycompanylist.com supports 149 of 173 Salesforce support currencies with unique ISO codes

• What happens when I add currencies?
  • When a currency is added, it is automatically included in the sync going forward. However, previous exchange rates for new currencies are not automatically backfilled. This can be done via the backfill component.

• What happens when I change corporate currency?
  • Be careful not to change corporate currencies while the daily sync job is running, as this could cause incorrect data to be inserted for that run. Other than that, there will be no issue. Salesforce will automatically adjust past exchange rates. And, future runs of the data sync will automatically adjust data relative to the new corporate currency.

• How accurate is the exchange rate data?
  • The exchange rate data is sourced from a set of trusted sources, including the International Monetary Fund, the European Central Bank, and others. You can the ability to specify which sources may be used via the ‘Sources’ field. Additionally, care has gone into ensuring that the exchange rates synced were observed at a time that is within the Date that exchange rate occupies within Salesforce. More info is at exchangerate.pro.

• How far back does the historical data go?
  • The data goes back over 20 years.

Creating a Support Ticket

There is a built-in panel for submitting a support request or a feature request at the bottom of the left hand side. It will automatically have your Name, Email, and Org Id in the Subject field. Write up a description of the issue and hit ‘Send’.

If you wish to include attachments or prefer using your own email client, simply send an email to support@mycompanylist.com.

Changelog

• 2023-12-15
  • Initial Release