Currency Exchange Rates

Database Structure

Ucommerce now comes with a database table and entity for storing currency exchange rates.

Column name	Description
FromCurrencyId	Foreign Key reference to source Currency.
ToCurrencyId	Foreign Key reference to target Currency.
Rate	Decimal value of the exchange rate.
Guid	Global unique identifier for the row.

Default data

During installation, in order for functionality that relies on exchange rates existing in the database to not fail, a migration script will insert default data for the currencies that are installed by default. This data will be overwritten on the start-up of your application by a pipeline that will reach out to a third-party API for up-to-date values. In case the system cannot reach the third-party API, or a custom implemented solution can't update the values, the default values will be used.

Current exchange rates

Ucommerce will update the values in the ExchangeRates table during the InitializePipeline. The ExecuteUpdateExchangeRatesPipelineTask will asynchronously execute the UpdateExchangeRatesPipeline, which updates all values from the "uCommerce_ExchangeRate" table and creates new records for currency combinations that do not exist yet. This pipeline uses the ICurrencyExchangeRateService to get the exchange rates from an external web service.

How to change the behavior of exchange rates

Change source of current exchange rates

You can change where Ucommerce will load up-to-date exchange rates from by creating a custom implementation of the ICurrencyExchangeRateService. The custom implementation can reach out to a different web service, or read the values from practically anywhere.

    
     /// <summary>
        /// Service that returns a conversion rate decimal value between two currencies.
        /// </summary>
        public interface ICurrencyExchangeRateService
        {
            /// <summary>
            /// Return decimal value of conversion rate between the two currencies.
            /// </summary>
            /// <param name="sourceCurrencyCode">Currency ISO code for source currency. (from)</param>
            /// <param name="targetCurrencyCode">Currency ISO code for target currency. (to)</param>
            /// <returns></returns>
            decimal GetRateBetween(string sourceCurrencyCode, string targetCurrencyCode);
        }

The custom implementation needs to be registered in our IOC container with the ID "CurrencyExchangeRateService" in order for it to be used over the default implementation.

Related article: Registering a custom component

Change when the exchange rates are updated

It is possible to change when the exchange rates are updated, by either moving the task that is responsible for it or executing the task at your convenience.

The task responsible for executing the ExchangeRatesPipeline is registered as the first task in the InitializePipeline with the ID "Initialize.ExecuteUpdateExchangeRatesPipelineTask.Async".

You can see the original configuration by opening the Initialize.config configuration file located in the "/Ucommerce/Pipelines/System" folder. You will notice that there is a component for an asynchronous task, that wraps the actual task as a parameter called "pipelineTaskName". This is required if the task is to run in an asynchronous manner.

You can register this task as part of any pipeline inside Ucommerce using the "Initialize.ExecuteUpdateExchangeRatesPipelineTask.Async" ID. Alternatively, you can programmatically run the UpdateExchangeRatesPipeline, using the following syntax:

    
    	var updateExchangeRatesPipeline = PipelineFactory.Create<IPipelineArgs<UpdateExchangeRatesRequest, UpdateExchangeRatesResult>>("UpdateExchangeRates");
    
        var args = new UpdateExchangeRatesPipelineArgs(new UpdateExchangeRatesRequest(),
    			   new UpdateExchangeRatesResult());
    
         updateExchangeRatesPipeline.Execute(args);

Change the default behavior of the UpdateExchangeRates pipeline.

If you want more granular control over what happens during the execution of the UpdateExchangeRatesPipeline, you are free to customize the pipeline using partial-components. The ID of the pipeline is "UpdateExchangeRates", this is the ID you need to specify in your partial-component. You can see the default configuration of the pipeline and all tasks involved in the Catalogs.UpdateExchangeRates.config file which can be found in the "/Ucommerce/Pipelines" folder.

You should work with this pipeline if you want to:

Change the way currencies are loaded, or where they are loaded from.
Change which currencies are taken into consideration when the system creates the ExchangeRate entities.
Add extra functionality that should happen when this pipeline is executed.

Documentation