Step 9: Using External API Calls to Retrieve Currency Exchange Rates

Estimated Reading Time:  9 minutes

Introduction

So far, your application takes in employee travel requests. If employee email addresses use the correct company email domain, they can select their departure and arrival airport, as well as see the estimated cost and remaining travel budget. But what if the employee is flying internationally and charged using a different currency? To calculate this, your application must retrieve the current currency exchange rate externally, and do the conversion calculations based on the airports selected.

You can use an API (application programming interface) call to retrieve the necessary information outside of your module. APIs APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. let applications and software communicate with each other and exchange information. In this use case, you'll use an External API call to request the current currency exchange rates from an external currency exchange software. Then, you'll use that information to make calculations and display an accurate estimated cost to the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product..

You can preview an example of this completed use case step here: https://training.unqork.io/workflow/6477ae9823c3b8819426dc0b.

Learning Objectives

In this use case article, you'll learn how to set up API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. calls to configure currency exchange rates.

Open Your Workflow-Type Application

Start by opening the workflow-type application you previously created in the Workflow Builder.

1.

From the Workspaces page, locate your module by selecting (Search magnifying glass) and entering Creator Workshop Workspace [your name].

2.

In your Workspace, select View App on your application tile. Your application title will be [initials] + “Creator Workshop App” + [date you created the application].

3.

From the menu to the left of the Application page, select  Workflows.

4.

Click on your Creator Workshop App workflow tile.

Add the Calculating Country Codes and Exchange Rates Snippet

Instead of adding and configuring each component for your currency exchange, you'll use a snippet. This snippet holds the configuration you need to get the current currency exchange rate and the estimated cost converted to USD.

Adding the Snippet

To add the snippet to your module:

1.

Open the Employee Travel Information module.

2.

Minimize all Field Group and Panel components in your module.

3.

Click the Snippets button at the top of the component tray.

4.

In the  Search Snippets search tool field, enter Calculating Country Codes and Exchange Rates.

5.

Open the Local Snippets group drop-down.

6.

Drag and drop the Calculating Country Codes and Exchange Rates snippet at the bottom of your canvas.

7.

Save your module.

Organizing the Snippet in Your Module

Next, organize the components in the snippet into your module.

1.

Drag and drop the finalRate (Current Exchange Rate)  Text Field component into the top of the left column of your colEmployeeBudgetInfo Columns component.

2.

Drag and drop the employeeConvertedEstimatedCost (Employee Estimated Cost (Converted))  Text Field component into the top of the right column of your colEmployeeBudgetInfo  Columns component.

3.

Drag and drop the fgCountryCodes (Calculating Country Codes) Field Group component in the fgEmployeeTravelInformation (Employee Travel Information Fields) Field Group, placing it below the Calculating Default Values Field Group.

4.

Drag and drop the fgExchangeRates (Calculating Exchange Rates) Field Group component in the fgEmployeeTravelInformation (Employee Travel Information Fields) Field Group, placing it below the fgCountryCodes (Calculating Country Codes) Field Group.

5.

Delete the panelCountryCodesAndExchangeRates (Calculating Country Codes and Exchange Rates) panel.

6.

Save your module.

Review the Calculating Country Codes and Exchange Rates Snippet

Now, let's review what you added to your module. Expand all of the panels in your Employee Travel Information module to help you reference each component.

1.

In the Employee Travel Information module, the employeeArrivalAirport Address Search component provides basic address information for the end-user's Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox. selected airport, including a two-digit country code.

2.

In the fgCountryCodes (Calculating Country Codes) Field Group, dwfCountryCodeConverter Data Workflow component gets the two-digit country code from the employeeArrivalAirport Address Search component. The Data Workflow then stores the two-digit code in the countryCodeTwo Hidden component.

3.

The plugCountryCodes Plug-In component uses the Get Rows from Reference Data Internal Service. This call retrieves all the columns and rows from a Data Collection called AlphaCountryCodes,. This Data Collection contains all the country codes, their country names, and their currency codes. The Plug-In also filters all of that data it retrieves and outputs only the currency code for the two-digit country code stored in the countryCodeTwo Hidden component. The application takes the country of the end-user's Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox. arrival airport and stores that country's currency code in the currencyCode Hidden component.

4.

In the fgExchangeRates (Calculating Exchange Rates) Field Group, the plugExchangeRates Plug-In component uses the currency code value in the currencyCode Hidden component to perform an external API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. call. This call gets the current currency exchange rate of the currency code. This is the same currency of the country where the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. arrives. The current currency exchange rate is then stored in the exchangeRate Hidden component.

5.

In the fgExchangeRates (Calculating Exchange Rates) Field Group, the dwfFinalRate Data Workflow component takes the value from the exchangeRate Hidden component. The dwfFinalRate  Data Workflow calculates and displays the final exchange rate in the finalRate (Current Exchange Rate)  Text Field component.

6.

The calcEmployeeConvertedEstimatedCost  Calculator component then uses the current estimated cost in USD and the current exchange rate to determine the converted estimated cost. The output of the Calculator component displays in the employeeConvertedEstimatedCost (Employee Estimated Cost (Converted))  Text Field component.

Review the External API Call

While your configuration for this use case step is complete, knowing how your external API call gets the information from an external source is important. The external API In Unqork, an External API (application programming interfaces) connects to services outside of the Unqork platform. APIs are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. call in this use case takes place in the plugExchangeRates Plug-In component.

Here are the steps that your application uses to make the external API call: 

1.

The plugExchangeRates Plug-In component's Service Type is set to External, making it an external API request.

2.

The Data Source URL field tells the Plug-In where to make the API request, configured using Services Administration.

3.

This external API requests information from the external source using a Get Request Type. The Get Request Type uses the following essential query parameters in the plugExchangeRates Plug-In component's Inputs table to make the API call successful:

4.

Looking at the Inputs table, you can see the values entered in the first two rows. The currency base is set to USD and a unique App ID is entered for this external API In Unqork, an External API (application programming interfaces) connects to services outside of the Unqork platform. APIs are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. call. This App ID was generated by signing up for a free account on the API website. When building your own app, you can use the same ID provided in this use case.

5.

The last parameter is the Property ID of the currencyCode Hidden component, which contains the currency codes.

View and Test the Workflow-Type Application in Express View

Before moving on to the next article, Preview your workflow in Express View Express View is how your end-user views you application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. to test your configuration. Enter sample information with a valid company URL email address, and progress to the Employee Travel Information screen. In the Employee Arrival Airport field, try entering airports in different countries. If working as expected, the Current Exchange Rate, Employee Estimated Cost (USD), and Employee Estimated Cost (Converted) fields will dynamically change values to match the currency exchange rate.

When testing role-specific screens on your Express View preview, use the Role-Based Access Control (RBAC) settings to view your application how your end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. would. At the top of your Express View preview, select Show to open the Express RBAC Control. In the Preview as: field, switch between the Administrator and trainingApplicant  roles to view and test each part of your application.

TIP  Having trouble with your configuration? Visit our Troubleshooting the Creator Workshop Configuration article to help identify and resolve any errors on your application.

Recap

In this use case, you finalized your employee role travel request submission process. You added and organized a snippet in your Employee Travel Information module, and added a configuration to retrieve currency exchange rates based on the arrival airport selected by the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.. The snippet creates an estimated cost of the arrival airport currency and converts it to USD. It then displays the estimated and converted costs to the end-user.

Once the employee enters their information and the cost calculations are made, the employee's travel request submits. For the next step, you want a manager role to review the employee's submitted travel requests. In the next use case, you'll create a manager role and a review screen for managers to approve or deny employee travel requests. You'll also add notifications to confirm the request was submitted and that it's ready for manager review.