Create exchange rate providers
- 15 minutes to read
This article describes how to set up an exchange rate provider.
This article describes the steps that are required in order to set up an exchange rate provider. For the purpose of illustration, the OANDA exchange rate service is used throughout this article. By following the steps that are described in this article, you will create a functional exchange rate provider. The code is production code. You can find the source in the ExchangeRateProviderOanda class. You can reference this class as you read through this article. To request an OANDA test account and receive information about the OANDA exchange rate service, go to http://developer.oanda.com/exchange-rates-api/.
- Import currency exchange rates – The process that retrieves exchange rates from exchange rate providers and imports them. This process is a system operation that supports batch processing.
- Exchange rate provider – An X++ class that is responsible for retrieving exchange rates from external sources.
- Exchange rate provider registration – The process of enabling an exchange rate provider so that it can be used. By default, exchange rate providers aren't registered when they are deployed.
- Exchange rate provider configuration – The configuration settings of an exchange rate provider that determine how it will be used.
- Exchange rate service – A free or paid subscription service that provides a list of exchange rates that have been published. Foreign Exchange Rates Powered by OANDA is an example of a service that provides exchange rates.
- The framework – The import currency exchange rates framework that coordinates the retrieval of exchange rates from providers and appropriate storage of the exchange rates.
The following illustration shows the main interfaces and classes that make up the exchange rate provider framework, and the relationships among them. New exchange rate providers should be derived from the IExchangeRateProvider interface. Exchange rate providers are written in X++. Because X++ is a .NET language, it's easy to use the Microsoft .NET Framework in our provider. Here are the interfaces and classes that are shown in the illustration:
- IExchangeRateProvider – By implementing this interface, you enable the exchange rate provider framework to recognize a class as an exchange rate provider.
- IExchangeRateProviderFrameworkFactory – This interface enables the exchange rate provider to construct various types of provider framework classes that represent some of the interfaces in the illustration.
- IExchangeRateProviderSupportedOptions – The exchange rate provider supports several options when rates are imported. The exchange rate provider uses this interface to inform the framework about the options that it supports.
- IExchangeRateProviderConfig – Each exchange rate provider can have a unique configuration. This interface enables the provider to retrieve this configuration.
- IExchangeRateProviderConfigDefaults – The exchange rate provider can create and provide default values for its configuration. The user can change these values on the Configure exchange rate providers page (General ledger > Currencies **> **Configure exchange rate providers).
- IExchangeRateRequest – This interface represents data that is specific to a request to import exchange rates. This data includes the date range, options, and the currency pairs to retrieve rates for.
- IExchangeRateCalendar – This interface represents an exchange rate calendar that is used to retrieve the next working day (Monday through Friday).
- IExchangeRateResponse – The exchange rate provider uses this interface to store the currency pairs and the exchange rates that are returned from the service.
- IExchangeRateResponseCurrencyPair – The exchange rate provider uses this interface to store the details for a specific currency pair that is returned from the service.
- IExchangeRateResponseExchangeRate – The exchange rate provider uses this interface to store a specific exchange rate for a specific currency pair.
- ExchangeRateProviderOanda – This example of an exchange rate provider that is implemented by Microsoft connects to the OANDA service to return exchange rates.
Writing an exchange rate provider
Code examples are taken from the ExchangeRateProviderOanda class. Follow these steps to create an exchange rate provider.
In the Currency model, create a class that implements the IExchangeRateProvider interface.
Add the following constants and variable declarations to the class.
Implement the get_Name method. A label should be used to enable proper translation. A user can change the name that is provided here when that user sets up the provider’s configuration information.
Implement the get_Id method. This method returns a globally unique identifier (GUID) that is used to uniquely identify this provider.
Implement the set_Factory method. The exchange rate provider framework will invoke this method to set an object that implements the IExchangeRateProviderFrameworkFactory interface on your provider. This factory can be used to instantiate new objects that represent some of the interfaces from the previous illustration.
Implement the GetSupportedOptions method. This method indicates whether the exchange rate provider supports some framework features:
- Set the doesSupportSpecificCurrencyPairs property to true only if the exchange rate service requires that a source and destination currency be passed to get an exchange rate. Many exchange rate services return rates for a fixed currency or a given set of currency pairs. For these services, the value of this option should be set to false. If prices that a service charges are based on quotas on the number of rates, a value of true will cause the IExchangeRateRequest interface to contain only those currency pairs that are configured for an exchange rate type on the Exchange rate page (General ledger > Currencies > Exchange rates). The provider can then specifically request these rates from the service and therefore lower the cost.
- Set the fixedBaseIsoCurrency property to the three-character International Organization for Standardization (ISO) currency code that represents the fixed base currency of the exchange rates that are returned from the exchange rate service. If the exchange rate service doesn't support a fixed base currency, return an empty string. For example, the euro is often used as a fixed base currency. When you create a new provider, be sure to research the exchange rate service so that you can select the correct value.
- Set the singleRateForDateRange property to true if the service can return a single rate that represents the whole date range. For example, you can use this setting to return a single exchange rate that represents the average exchange rate for a month. If the service doesn’t support this functionality, set this property to false.
Implement the GetConfigurationDefaults method. Configuration defaults are name-value pairs that represent the default configuration settings for the exchange rate provider. These settings are automatically loaded when the provider is registered, but the user can change them. Take the required precautions when you convert these strings into usable values. The value field is stored as an encrypted field in SQL. Therefore, sensitive data such as an application programming interface (API) key will be more secure.
Implement the ValidateConfigurationDetail method. This method enables the exchange rate provider to validate the configuration information that the user modified on the Configure exchange rate providers page.
Implement the EnumNameForLookup method. This method enables the exchange rate provider to enable a lookup for a specific ExchangeRateProviderPropertyKey key. Just return the name of an existing enumerated type for the appropriate key. If this feature isn't required, return an empty string.
Implement the GetExchangeRates method. This method uses the configuration information and the IExchangeRateRequest interface that is provided to call out to the exchange rate service and return the appropriate instance of the IExchangeRateResponse class. When you write this method, consider these important points:
- Any configuration information that is required should be retrieved from the IExchangeRateProviderConfig interface. A call to the GetPropertyValue method on that interface will provide the string representation of the property value for the property key that is provided. Take the required precautions when you convert this string value to another type.
- Do any required validation up front. For example, OANDA requires that an API key be supplied on every service call. If this API key isn't set, the service will fail. Verify that the API key isn't set, and exit early to receive an appropriate error message.
- Some providers require explicit currency pairs when exchange rates are requested. These providers are the same providers that set the IExchangeRateProviderSupportedOptions.doesSupportSpecificCurrencyPairs property to true. In this case, you must use the currency pairs that the IExchangeRateRequest interface provides to drive the retrieval process. The OANDA provider implementation that follows shows a good example of this type of provider. Typically, providers that don't support specific currency pairs return data for a fixed set of currency pairs. In this case, the currency pairs that the IExchangeRateRequest interface provides can be ignored. Providers should return all the rates that are available, and the framework will then import the correct rates, based on the user’s decision about whether to automatically create the required currency pairs. The CentralBankOfEuropeProvider provider is a good example of this type of provider.
- The IExchangeRateRequest interface has a property that is named ImportDateType. This property indicates the dates that should be used to retrieve exchange rates from the service. The two values that are available are CurrentDate and DateRange.
- CurrentDate retrieves the most current exchange rate from the exchange rate service. When this value is passed to the provider, the framework also sets IExchangeRateRequest.FromDate and IExchangeRateRequest.ToDate to the system date of the Application Object Server (AOS) computer that is making the request. If exchange rate services support the retrieval of exchange rates for specific dates, the date that the framework provides should be passed. However, if the exchange rate service instead provides a call to get the most current exchange rate (regardless of the date), the date that is returned must be validated to make sure that it's less than or equal to the requested date.
- DateRange retrieves the exchange rates for a specific date range. Only exchange rates in the specified date range should be allowed. If an exchange rate service requires that specific dates be included in the request, this process is straightforward. However, if an exchange rate service instead returns a group of historical dates that might be outside the valid range of dates, the provider must filter out the dates that aren't relevant before it passes the dates back to the framework.
- When exchange rates are returned, always use the date that the exchange rate service provides instead of the dates that the instance of the IExchangeRateRequest class supplies. In this manner, you help guarantee that the exchange rate that is returned is associated with the correct date, because an exchange rate service might occasionally return rates for dates that weren't expected. For example, if an exchange rate is requested for a date in the future, some providers return the most recent exchange rate instead of throwing an error or returning nothing.
- If you encounter errors when you try to retrieve exchange rates from the exchange rate service, don't throw custom error messages. The framework will alert the user that there is an issue by throwing generic error messages that state that the expected currency pairs could not be retrieved from the provider. If you must log additional errors, use CurrencyEventSource. For an example, see the catch statement and the if condition for the oandaKey variable in the following code.
Implement the following helper methods. These methods are specific to this example and aren't required for every provider.
Compile the ExchangeRateProviderOanda class. The provider will be run as part of a SysOperation. It's helpful to understand the following framework classes and methods when you debug issues:
- ExchangeRateProviderFactory.initialize() – This method creates instances of the exchange rate providers, and is called when exchange rates are registered or imported. If your provider isn't instantiated, start to debug here.
- ExchangeRateProviderRegistration.initialize() – This method searches for providers, so that they can be registered. If you can't see your provider on the registration page, start to debug here.
- ExchangeRateImportOperation.import() – This method drives the import process by calling the necessary provider and storing the exchange rates.
- ExchangeRateProviderConfig – This class provides access to configuration information for the providers.
Because there are no limits to the method that the exchange rate providers use to get exchange rates, the framework enables some interesting scenarios. Here are some ideas that you might want to explore:
- Providers that retrieve exchange rates from other exchange rate types – This scenario would enable synchronization of exchange rates among various exchange rate types. This functionality could be useful in situations where many exchange rate types exist, to maintain isolation between different ledgers.
- Providers that use Extensible Stylesheet Language Transformations (XSLT) to transform any format for an exchange rate service into an instance of the ExchangeRateResponse class – If this scenario were implemented, users could add the XSLT transform that is required for their exchange rate service, and the application would support the service. Provider-specific code wouldn't be required.
- Some exchange rate provider services charge for every rate that is consumed – Consider combining the first idea in this list with a limit on the number of rates that you retrieve from the service, for scenarios where you're charged for each rate that is consumed from the service.
Setting Up The Environment
Before actually creating the flowchart, we will cover some preliminaries that make flowcharting in Excel a bit easier.
Creating a Grid (Optional)
A grid is not required, but it makes creating flowcharts with uniform shape sizes easier, especially when coupled with the Snap to Grid feature, which we will cover in the next section.
The grid is created by changing the column widths to match the standard row height. Assuming that you're using the default font of Calibri 11, the standard row height is 15 pts, which equals 20 pixels. To create the grid, change the column widths to 2.14 (= 20 pixels). (In case you're curious, the units for Excel column widths are based on the average number of characters that will fit within a cell.)
Follow the steps as described below these images:
Click on the top left corner of the spreadsheet.
Right-click on any column and click on “Column Width”.
Enter 2.14 in the dialog and click OK.
Snap to Grid / Shape
When Snap to Grid is turned on, anytime you add, move, or resize a shape, the edges of the shape will “snap” to the nearest grid line. Snap to Shape provides the same behavior, except shapes are snapped to the edges of other shapes. You can turn on both Snap to Grid and Snap to Shape by clicking the Page Layout tab, then click the Align dropdown, as shown in the image on the right.
Beyond the obvious reasons, setting the page layout before creating the flowchart is important for several reasons:
- If you plan to copy the flowchart from Excel to Word, or some other application, matching the margins to the target is important. Word, for example, has different normal margins than Excel.
- If the flowchart direction is left to right, the page layout is typically in landscape orientation.
- When you display page breaks, they act as a visual boundary to check whether shapes fall within a page.
To set the layout, click the Page Layout tab and use the Margins, Orientation, and (paper) Size dropdowns to change the settings if needed.
Themes: Be careful changing the Theme on the Page Layout tab. It not only alters the font and color scheme, but it also changes the row heights and column widths, which will affect how many shapes fit on a page.
Creating the Flowchart
Inserting a Flowchart Shape
To add the first shape, starting by clicking the Insert tab, where you should see a Shapes dropdown button. Clicking the Shapes dropdown displays the gallery of shape types shown below.
You can add a shape to the worksheet either by double-clicking a shape in the gallery, or by single clicking a shape and drawing its outline on the worskheet while holding the left mouse button down. If you double-click to add the shape, the shape will be placed in a somewhat arbritrary location on the sheet and have a height of 0.67” and a width of 1.0”.
Insert Shapes Gallery
Adding More Flowchart Shapes
After you add the first shape, you'll notice that a Format tab (shown below) becomes available on the ribbon anytime that you click on a shape. We'll cover formatting in a bit, but in regard to adding shapes, the Format tab duplicates the Shapes gallery that we saw above. This makes it handy to add a shape then continue to add shapes in serial fashion.
Adding Text to a Shape
This is straightforward - just click on the shape and start typing. If you need to edit the text in the shape click in the center of the shape, and not on the edges. Clicking the text in the center will put you into edit mode, but clicking the shape's border will select the shape itself.
Adding Connector Arrows Between Shapes
Connector arrows are added to the worksheet the same way flowchart shapes are - via the Shapes gallery. After clicking the line type in the gallery, follow these steps to add it to the flow diagram:
- Hover the mouse over the first shape and you will see the available connection points highlighted by red dots. Click the left mouse button down on the desired connection point.
- While still holding the left mouse bbutton down, drag the line to the next shape, where again the connection points are highlight.
- Release the left mouse button on a connection point, and the line will be selected with both end points highlighted by red dots. If an endpoint has a clear dot, it indicates that the connector wasn't connected.
Adding Labels and Callouts
There are two common ways to add notes to a flowchart.
- Text box labels:
Text boxes are often used to label the connectors coming out of decisions. Callouts are commonly used to add side comments, with their shape indicating that they are not a process step. Both can be added via the Insert Shapes gallery.
Formatting the Flowchart
There are so many formatting options in Excel, that it's too much to cover in a single article. The sections below show how to do basic shape and line formatting. There is a special dialog worth mentioning. If you right-click on a shape and select Format Shape from the context menu, the format dialog will display and let you make changes to a wide
When one or more shapes is selected, the Format tab displays the style gallery shown below. Note that the styles changed in Excel 2013. The shape styles are set by their theme number, so if you use one of the purple styles in Excel 2010, for example, and then open it in Excel 2013 or Excel 2016, it will display with the new orange theme.
If you are sharing the document with Excel 2003 users, note that the last row of styles will not render well in Excel 2003. If you are sharing the file with Excel 2000 users (i.e., the file is saved in .xls compatibility mode), the last two rows of styles will not render well.
Formatting Connector Lines
When one or more connector lines is selected, the Format tab displays the line style gallery shown below. As with the shape styles, new line styles were also introduced in Excel 2013. Excel 2013 / Excel 2016 lines are also thinner and have no drop shadow. This is a good thing because the thicker lines and shadows were known to cause screen and print rendering problems.
Fonts are set for shapes the same way that they are for cells. Select the shape then set the font and font size on the Home tab.
Other Formatting Tips
- You can also use the Format Painter tool on the Home tab to quickly copy a format from one shape to another.
- The Shape Fill dropdown lets you apply different fill colors and gradients and also allows you to insert a picture as a shape's background.
- The Shape Outline lets you change the line color, thickness, dash style, and arrow heads.
- The Shape Effects dropdown has a number of stylistics effects you can apply such as Shadow, Glow, Reflection, and more.
Editing the Flowchart
This section covers editing guidelines that are specific to Excel 2007-2010 only. For more tips that apply to all versions of Excel, scroll down to the Editing Excel Flowcharts section.
The simplest way to select a single shape is to click on the border. You can select multiple shapes by holding the Ctrl key as you click. Once a shape is selected, you can toggle through the shape selections using the Tab key. Starting with Excel 2007, there is also a Selection Pane tool, accessible from the Format tab of the ribbon. The Selection Pane lists all the shapes by their names, not their text, so it isn't all that useful.
Aligning the Flowchart
If you created a grid and used Snap to Grid, hopefully you won't need to align any shapes after the fact, but in case you do, the Format ribbon tab has several features that are supposed to make this easier. under the Align dropdown menu, there are several options to align the selected shapes to the Left, Center, Right, etc. The left and rright alignment tools do what you would expect, but the centering tool moves all the shapes to the average center position, typically shifting all of them from their original position. As such, I typically recommend aligning shapes manually.
Changing a Flowchart Shape To Another Type
To change a shape, select it with your mouse, and then click on the Format tab. In the upper left, click the Edit Shape dropdown and select a new shape type, as shown in the image below. there is a bug in Excel 2007 and 2010 that you need to be aware of when using this tool. Changing a shape type causes any line connected to the shape to become unconnected. Connected lines will move with a shape when the shape is moved. Unconnected lines will not. Unconnected lines are also known to render strangely when printed or saved to PDF. In short, make sure to reconnect the lines after changing a shape type.
Edit Shape menu item
Insert connector - step 1
Insert connector - step 2
Insert connector - step 3
Excel 2007 - 2010 Shape Style Gallery
Excel 2013 Shape Style Gallery
Excel 2007 - 2010 Line Style Gallery
Excel 2013 Line Style Gallery
Setting Up The Environment
Enable the Drawing Toolbar
The first step to drawing flowcharts in Excel is to make the Drawing toolbar visible. This can be done by selecting View > Toolbars > Drawing from the main menu or by clicking the Drawing toolbar icon on the main Excel toolbar:
Drawing toolbar button
Create a Flow Chart Grid (Optional)
This step is optional, but it makes for a nicer flowcharting environment. To create a flow chart grid in Excel, select all the cells by clicking on the corner of the spreadsheet, as shown in the picture below-left. Then, right click on one of the columns and select Column Width. As shown in the picture below-right, enter 1.71 for the column width (which equals 17 pixels). The standard row height is 12.75 points, which also equals 17 pixels on most systems, so you get a nice tight square grid.
The standard row height is dependent on the default font. The default font in Excel 2000-2003 is Arial 10, so your settings may be different if you have a different font set as default.
Enable The Excel Snap to Grid Feature (Recommended)
This isn't required, but turning on the snap to grid function makes flowcharting in Excel so much easier I can't imagine creating flow charts without it. This feature makes the shapes align to the Excel worksheet cells when you add them, re-size them, or move them. It's great for ensuring your flowchart symbols are uniformly sized and aligned.
To turn snap to grid on, simply click the Draw button on the Drawing toolbar. Then, click Snap then To Grid, as shown below.
Excel Drawing toolbar - snap to grid
Set the Page Size and Boundaries
It's always good to know your limits, and making flow charts is no exception. You need to set the page size and then do a print preview because this will display the page breaks.
To setup the page properties, click File > Page Setup... from the main menu. Set properties such as portrait or landscape, paper size, and margins and close the form. One consideration you should make when setting the properties is where the flow chart will be published. For example, if you copy and paste the flow chart into Word, then it's good to remember that Word's default lateral page margins are 1" less than Excel's (i.e., 1/2" on both the left and right sides).
After the page properties are set, click the Print Preview button on the main toolbar. Alternately, you can click File > Print Preview from the menu. Close the preview screen and the page breaks should now be visible. If there is nothing on the worksheet yet to preview, Excel will pop open an error message. If it does, just click OK - the page breaks should now be visible anyway.
Create the Flow Chart Swim Lanes and Title Block (Optional)
If you're creating a Deployment Flow Chart, an Opportunity Flow Chart, a Process Relationship Flow Chart, or any other type of flow chart that requires swim lanes or swimming pools, then it's a good idea to create the structure of the flow chart before adding the flow chart symbols.
A full explanation of each of these specialized types of flow charts deserves an article of its own. But quickly, you can create the flow chart column and row headers in two ways. The first way is to use Excel's cell merging and borders. This is the easiest way if you plan on publishing the flow chart in Excel.
The second way is to create the headings with Process flow chart symbols and create the swim lane dividers with autoshape lines. The advantage to this method is that the swim lane heading shapes and dividing lines can be selected along with the flow chart symbols, so you can easily copy and paste the whole diagram if you're going to publish the flow chart in Word or some other Office application.
In the flow chart swim lane examples below, the swim lanes on the left were created using cell borders and the swim lanes on the right were created using process flow chart symbols and autoshape lines. As you can see, the appearance is identical.
Swim lanes example
Also, if you plan to add a title block, including the process name, author(s), and revision info, then doing so before creating the flow chart is a good idea.
Add a Flow Chart Symbol
To add a flow chart symbol to the worksheet, you need to click the AutoShapes button on the Drawing toolbar, then click Flowchart, then select the shape you want to add, as shown in the picture below:
Excel flowchart autoshapes toolbar
The mouse cursor will change to a crosshair. Left click on the worksheet location where you want the top left corner of the flow chart symbol to be and drag the mouse until the flow chart symbol is the size you want. See the flow chart terminator symbol below for an example.
Add flowchart symbol example
Adding Text to a Symbol
To add text to an Excel flow chart symbol, simply click on the symbol and start typing. Note: If you've created Word flow charts before, this is one of the differences between creating flow charts in Excel and flow charts in Word. In Word, you have to right-click on the shape and select Add Text from the context menu.
Add a Connector (Flow Line) Between Two Symbols
[Note: A Flow Line is an arrow showing the order of the process steps. In Excel, flow chart lines are called Connectors. But Connector is also the name for a flow chart symbol used to depict a labeled node indicating a jump to another part of the flow chart. I will typically use the term "Flow Line" to avoid confusion, but in this section Flow Line and Connector are used interchangeably.]
Connectors are named as such because the lines actually connect to the flow chart shapes. When a shape is moved around, a Connector will remain attached to the shape, whereas a standard Excel line or arrow will not be connected.
To add a flow line between two shapes, first select the Connector type you want to use, as shown in the picture below. Tip: The Elbow Connector is versatile for flow lines because it will look just like a straight connector when the shapes are aligned.
Excel Connectors toolbar
After you've clicked on a Connector type, the mouse will change to a crosshair. Click on the edge of the first flow chart symbol and drag the mouse over to the edge of the second flow chart symbol, then release the mouse button. A faint dashed line will show the path of the flow line. When you hover the mouse over a flow chart symbol, the possible connection points will show as blue dots. Also, the mouse cursor will change to a bomb site when you're near one of the connection points (see the picture below).
Adding connector arrows
When an Excel flowchart Connector is connected to a flow chart symbol, the ends of the Connector are red dots. If one of the Connector ends is not connected it shows as a green dot. The figures below show a unconnected flow line on the left and a connected flow line on the right. To connect a flow line like this, just click and drag the endpoint to the correct spot.
A yellow diamond (not shown) on a Connector is a line routing handle. You can click and drag that to re-route the connector line without changing the position of the endpoints. It's a handy feature, especially when a long flow line is routed behind other shapes.
Sometimes you need to add a note or explanation for a flow chart process step that doesn't fit into the flow chart symbol. For these circumstances you can add a callout. Callouts are added from the Excel Drawing toolbar in the same way that you add a flow chart symbol or flow line.
Formatting Flow Chart Symbols
Many of the formatting features are available on the Excel Formatting toolbar (e.g., bold, italic, horizontal text alignment), and many others are available on the Excel Drawing toolbar (e.g., fill color, line color, line thickness, drop shadow).
Some of the formatting options are only available on the Format AutoShape dialog, such as vertical text alignment. This form can be opened by double-clicking on the outside border of the flow chart shape. Some of the more advanced formatting options are available in the Fill Effects sub-dialog, including gradient fills, textures, and adding pictures to flow chart symbols. The Fill Effects dialog is opened by clicking on the Fill Color dropdown as shown in the picture below.
Format AutoShape dialog
Change a Flow Chart Symbol Type
Sometimes you decide a different flow chart symbol is needed. It's a common practice to make all shapes Process symbols (rectangles), but there's a lot of semantic information in symbols that conveys added meaning at-a-glance when you use more specific symbol types. To change a flow chart symbol type, first select the symbol. Then select the new shape from the Change AutoShape menu as shown below.
Change autoshape type
Aligning and Distributing Flow Chart Symbols
After you move or resize flow chart shapes, the alignment may get thrown off. Plus, if you resize a bunch of shapes to make them bigger, the spacing between the shapes may get scrunched up. Excel has a tool that can be found under the Draw menu on the Drawing toolbar to assist the Align or Distribute functions.
To use these functions, you must first select the shapes you want to align or distribute, then simply select the one of alignment (left, center, right, top, middle, bottom) or distribution (horizontally or vertically) functions to get the flow chart squared up. Alignment is self-explanatory, but distribution will take a set of shapes and spread out the distance between them uniformly.
Select all Excel cells
Set column width
Connector not attached to shape
Connector attached to shape