Creating Exchange Rate Providers in Microsoft Dynamics AX 2012 for Open Exchange Rates

Microsoft Dynamics AX 2012 has the frame work for integrating currency exchange rates from exchange rate providers. Please reference Creating Exchange Rate Providers for Microsoft Dynamics AX 2012. The referenced document from Microsoft shows how to customize the frame work to work with Oanda Exchange Rates .

There are other providers, some which offer a fee based API and others which offer a free API. Doing research on these providers led me to Open Exchange Rates. They offer an API at no cost for personal use, and a fee based API for Enterprise users, which is fairly competitive with other providers.

This blog entry uses the referenced document from Microsoft as a guide to create a provider class in Dynamics AX specifically for use with the free version of Open Exchange Rates, and the fee based Open Exchange Rates API.

A challenge with using this provider is that it uses JSON instead of XML.

The provider class we will create will be the fee based provider. The fee based provider allows for selection of base currency, and specific currency pairs.

Create the class as ExchangeRateProviderOpenExchRates and have it extend the ExchangeRateProvider as shown in the class declaration below.

Note: The ExchangeRateProviderIdAttribute is a unique ID that you will need to supply. You can obtain a unique ID from http://createguid.com

	[ExchangeRateProviderAttribute,
	ExchangeRateProviderIdAttribute('F3D5E522-7EFD-4CBF-895E-6DF6596DF8DF')]
	class ExchangeRateProviderOpenExchRates extends ExchangeRateProvider
	{
	str serviceUrl;
	str serviceUrlForDateRange;
	str serviceClient;
	int serviceTimeout;
	List rates;
	List dates;
	//AppId for account identification when sending requests to Open Exchange Rates
	//You will need to get your own Appid from https://openexchangerates.org
	#define.AppId("get your own appId")
	#define.ServiceTimeout("serviceTimeout")
	#define.ServiceURL("ServiceUrl")
	#define.OPENEXCHRATESDateFormat("yyyy-MM-dd")
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Now create a method called getConfigurationDefaults. This method will provide the default URL used to make requests to the provider.

	public ExchangeRateProviderConfigDefaults getConfigurationDefaults()
	{
	ExchangeRateProviderConfigDefaults configurationDefaults = ExchangeRateProviderConfigDefaults::construct();
	configurationDefaults.addNameValueConfigurationPair(#ServiceTimeout, '5000');
	//Requires Enterprise account
	configurationDefaults.addNameValueConfigurationPair(#ServiceURL, 'http://openexchangerates.org/api/historical/%1.json?app_id=%2&base=%3&symbols=%4');
	return configurationDefaults;
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Next create the getExchangeRates method. This method is responsible for constructing the URL to request the currency information from the provider, and store the results in the currency exchange rate tables of Dynamics AX.

	public ExchangeRateResponse getExchangeRates(ExchangeRateRequest _exchangeRateRequest)
	{
	ExchangeRateResponse response = ExchangeRateResponse::construct();
	ExchangeRateResponseCurrencyPair currencyPairResponse;
	ExchangeRateResponseExchangeRate exchangeRateResponse;
	ExchangeRateRequestCurrencyPair currencyPairRequest;
	ExchangeRateProviderConfig config = ExchangeRateProviderConfig::construct();
	RetailCommonWebAPI webApi;
	RetailWebRequest webRequest;
	RetailWebResponse webResponse;
	str openExchRatesRequestString;
	date currentDate;
	CurrencyExchangeRate exchangeRate;
	ListEnumerator rateEnumerator, dateEnumerator;
	System.DateTime fromDate, fromUTCDate;
	System.TimeZone localTimeZone;
	int compareResult;
	str JSONOut;
	str dateForRequest;
	rates = new List(Types::Real);
	dates = new List(Types::Date);
	localTimeZone = System.TimeZone::get_CurrentTimeZone();
	// Iterate over the requested currency pairs. This is only required for providers
	// that support specific currency pairs.
	_exchangeRateRequest.initializeCurrencyPairEnumerator();
	while(_exchangeRateRequest.moveNextCurrencyPair())
	{
	serviceTimeout = str2int(config.getPropertyValue(this.getProviderId(), #ServiceTimeout));
	serviceUrl = config.getPropertyValue(this.getProviderId(), #ServiceURL);
	// Process each date separately.
	fromDate = _exchangeRateRequest.parmFromDate();
	compareResult = fromDate.CompareTo(_exchangeRateRequest.parmToDate());
	while (compareResult <= 0)
	{
	currencyPairRequest = _exchangeRateRequest.getCurrentCurrencyPair();
	currencyPairResponse = ExchangeRateResponseCurrencyPair::construct();
	currencyPairResponse.parmFromCurrency(currencyPairRequest.parmFromCurrency());
	currencyPairResponse.parmToCurrency(currencyPairRequest.parmToCurrency());
	// All rates are requested with a display factor of 1 for this provider. If the
	// rates internally are represented using a different exchange rate display
	// factor, the framework will make the necessary adjustments when saving the
	// exchange rates.
	currencyPairResponse.parmExchangeRateDisplayFactor(ExchangeRateDisplayFactor::One);
	// convert to UTC which is required by OPENEXCHANGERATES
	fromUTCDate = localTimeZone.ToUniversalTime(fromDate);
	dateForRequest = fromUTCDate.ToString(#OPENEXCHRATESDateFormat);
	// Build the request URL.
	openExchRatesRequestString = strFmt(serviceUrl,
	dateForRequest,
	#AppId,
	currencyPairRequest.parmFromCurrency(),
	currencyPairRequest.parmToCurrency());
	// Configure the request for OPENEXCHRATES.
	webApi = RetailCommonWebAPI::construct();
	webRequest = RetailWebRequest::newUrl(openExchRatesRequestString);
	try
	{
	// Invoke the service
	webResponse = webApi.getResponse(webRequest);
	JSONOut = webResponse.parmData();
	// Parse the JSON to retrieve the rate and date.
	this.readRate(JSONOut,currencyPairRequest,DateTimeUtil::date(Global::CLRSystemDateTime2UtcDateTime(fromDate)));
	rateEnumerator = rates.getEnumerator();
	rateEnumerator.moveNext();
	dateEnumerator = dates.getEnumerator();
	// Create the Exchange Rate Provider Response.
	dateEnumerator.moveNext();
	exchangeRate = rateEnumerator.current();
	currentDate = dateEnumerator.current();
	if (currentDate != dateNull() && exchangeRate)
	{
	exchangeRateResponse = ExchangeRateResponseExchangeRate::construct();
	exchangeRateResponse.parmValidFrom(currentDate);
	exchangeRateResponse.parmExchangeRate(exchangeRate);
	currencyPairResponse.addExchangeRate(exchangeRateResponse);
	currentDate = dateNull();
	exchangeRate = 0;
	}
	}
	catch (Exception::CLRError)
	{
	// The service call did not complete. Swallow the exception and try the next
	// currency pair. The framework will be able to determine which currency
	// pairs were successfully retrieved and will display the appropriate
	// warnings to the user.
	}
	response.addOrUpdateCurrencyPair(currencyPairResponse);
	rates = new List(Types::Real);
	dates = new List(Types::Date);
	fromDate = fromDate.AddDays(1);
	compareResult = fromDate.CompareTo(_exchangeRateRequest.parmToDate());
	}
	}
	return response;
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Next create the getName method. This method is used by Dynamics AX to populate the list of providers that Dynamics AX has been modified to support.

	public ExchangeRateProviderName getName()
	{
	return "Open Exchange Rates";
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Once the getName method is created, create the getProviderId method. This method simply returns the unique GUID that was assigned in the class declaration.

	public ExchangeRateProviderId getProviderId()
	{
	return 'F3D5E522-7EFD-4CBF-895E-6DF6596DF8DF';
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Next create the getSupportedOptions method.

	public ExchangeRateProviderSupportedOptions getSupportedOptions()
	{
	ExchangeRateProviderSupportedOptions supportedOptions = ExchangeRateProviderSupportedOptions::construct();
	supportedOptions.parmDoesSupportSpecificCurrencyPairs(true);
	supportedOptions.parmDoesSupportSpecificDates(false);
	supportedOptions.parmFixedBaseIsoCurrency('');
	return supportedOptions;
	}

view raw gistfile1.cs hosted with ❤ by GitHub

The last method that needs created is the readRate method. It is responsible for parsing the JSON response string from the provider, and storing the exchange rate and currency information in the Lists.

	private void readRate(str _jsonString,ExchangeRateRequestCurrencyPair _currencyPairRequest,date _currentDate)
	{
	Map ratesMap = new Map(Types::String,Types::Real);
	MapEnumerator me;
	//I have not found a good way to deserialize JSON, so I have written custom code to parse the JSON string
	void getRates()
	{
	int pos = strScan(_jsonString,'"rates": {' ,0,strlen(_jsonString))+10; // determine position of currency rates in JSON string
	str temp = subStr(_jsonString,pos,strLen(_jsonString)-pos); // get currency rates into temp string
	List listRates = strSplit(temp,","); //split the currency rate string into a list
	List listCountry; //list used to temporarily store country specific currency and rates
	ListEnumerator lir,lic; //enumerators for rates and country specific rates
	str strRate;
	str strCountry;
	str strCountryRate;
	lir = listRates.getEnumerator();
	//look through all rates
	while (lir.moveNext())
	{
	//strRate includes both the ToCurrency Code and the Rate
	strRate = lir.current();
	//split the country specific rate into it's own list so we can add it to the ratesMap
	listCountry = strSplit(strRate,":");
	lic = listCountry.getEnumerator();
	//get the 'TO' country specific currency
	if (lic.moveNext())
	{
	strCountry = lic.current();
	//get the 'TO' country specific rate
	if (lic.moveNext())
	{
	strCountryRate = lic.current();
	strCountry = strReplace(strCountry,'"','');
	//build map of 'TO' country specific currencies and rates
	ratesMap.insert(subStr(strCountry,strLen(strCountry)-2,3),any2real(strCountryRate));
	}
	}
	}
	}
	//Parse JSON string into ratesMAP
	getRates();
	if (ratesMap.exists(_currencyPairRequest.parmToCurrency()))
	{
	rates.addEnd(ratesMap.lookup(_currencyPairRequest.parmToCurrency()));
	dates.addEnd(_currentDate);
	}
	}

view raw gistfile1.cs hosted with ❤ by GitHub

The version of the class that supports the free API is basically the same except for the URL request string. The free version only supports 2 options. The APPId, and the date parameter. The result is a currency list for all supported currencies but it is USD based. However the class filters to just the currency conversion needed by date. To modify the class to use the free version, simply change the getConfigurationDefaults method as follows:

	public ExchangeRateProviderConfigDefaults getConfigurationDefaults()
	{
	ExchangeRateProviderConfigDefaults configurationDefaults = ExchangeRateProviderConfigDefaults::construct();
	configurationDefaults.addNameValueConfigurationPair(#ServiceTimeout, '5000');
	//using free account
	configurationDefaults.addNameValueConfigurationPair(#ServiceURL, 'http://openexchangerates.org/api/historical/%1.json?app_id=%2');
	return configurationDefaults;
	}

view raw gistfile1.cs hosted with ❤ by GitHub

Now that the class has been created, it can be used in currency configuration and setup within Dynamics AX.