Developing the Retrieve Process

The Retrieve process is designed to fetch the current exchange rates for specified currencies from a public provider and store them in a local database. This process involves three main tasks:

Retrieve Exchange Rates

The initial task, Retrieve Exchange Rates, allows users to decide which currencies they would like to retrieve the rates for.

Fetch and Store Rates

The second task is an automation task that retrieves the exchange rates from a public provider and saves them to the local database. This requires the definition of a data table to store the retrieved rates.

Notify Completion and Show Results

The third task notifies the users that the process has been completed and displays the retrieved exchange rates.

visual graph of the process

1. Retrieve Exchange Rates

The initial task, Retrieve Exchange Rates, allows users to decide which currencies they would like to retrieve the rates for. We will load the current setup to reduce data entry, so make sure to set the data root of the pool to "CurrencySetup".

Steps to Configure the "Retrieve Exchange Rates" Task:

Create a New Pool and Set Data Root:

Open the Process Designer in Emakin.
Create a New Pool:
- Click on the "New Pool" button to add a new pool to your process.
- In the pool creation dialog, name the pool "Exchange Rates".
- Set Data Root: During the creation of the pool, select the current data root "CurrencySetup". This will help to use the same data model as the setup.

Modify the Data Model:

We need to update the data model to reflect the rates to the form. We will use a table to retrieve and show the current rates.
Click on the data model on the main process screen. Move to the Types tab and click on "Add New Type".
Name the field as "CurrencyType" and insert the following nodes: From, To, Value, Date, Timestamp, CreateDate.

data model for CurrencyType

After creating the type, move to the Elements tab and expand the CurrencySetup node.
Add a new element as Rates and make sure to mark it as a container.
Click the details of the node to expand and insert a new element.
Select the "Current Schema" from the Target Schema and then select the new type (CurrencyType) we have just defined.
Give a name to the node (Rate) and select "Yes" to use it multiple times. This definition will let us create unlimited child nodes under the parent node.

Configure the Initial Task:

Inside the newly created "Exchange Rates" pool, an initial task will be automatically created.
Rename the Task:
- Click on the initial task to select it.
- Change the name of the task to "Retrieve Exchange Rates".
Add a Retrieve Action:
- Within the task configuration, add a "Retrieve" action.
- This action will be the one visible to end users when they open this task, allowing them to move to the next task.

Define Prework:

Prework:
- In the prework section of the "Retrieve Exchange Rates" task, add code to load existing setup data from the XML database if necessary.
  $Xml.Load('CurrencySetup/*');

2. Fetch and Store Rates

The second task is an automation task that retrieves the exchange rates from a public provider and saves them to the local database.

Steps to Configure the "Fetch and Store Rates" Task:

Create and Configure the Automation Task:

Click on the "Retrieve" action on the "Retrieve Exchange Rates" task.
Change the Type:
- Click on the task and select "Module" from the right panel.
Rename the Task:
- Change the name of the task to "Fetch and Store Rates".

Define Data Table:

Define a data table to store the retrieved exchange rates.
Open the main process screen.
Click Databases.
Click Add New Schema.
Enter a name (Currencies) and prefix (CRR) for the schema.
Click Add New Table.
Give a name to the table (ExchangeRates).
Add the following fields: Id, From, To, Value, Date, Timestamp, CreateDate.
Once you commit the process, Emakin will create the tables for you automatically.

Add API Call to Fetch Rates:

Use the Rest Service API Calls to fetch the exchange rates from a public provider.
Right click to the current task and select “Module“.
Insert the following code.

//removing deleted nodes on the form.
$Xml.CommitDeletes();

var client, request, response;

//iterate all the base currencies
$Xml.SelectAll('Currencies/Base', function() {
    //current base currency
    var base = this.Evaluate('Currency');
    
    var createDate = $Calendar.GetToday('');
    
    console.info('retrieving Latest Exchange Rates for ' + base);

    var symbols = '';

    //itearing all the target currencies for the current base currency to create the query string.
    this.SelectAll('Targets/Target', function(){
        symbols += this.Evaluate('Currency') + ',';
    })

    symbols = symbols.substring(0, symbols.length - 1);

    //A public rest API that provides the current rates.
    var url = 'https://api.apilayer.com/fixer/latest?symbols='+ symbols + '&base=' + base;
    
    client = $Rest.Create(url);
    //make sure to add the API Key you received from the provider
    client.AddDefaultHeader('apikey', 'XXX')
    
    request = client.Request();
    
    try {
        response = request.Get().ToJson();
    }
    catch (err) {
        throw err;
    }
    
    //iterating all the target currencies and inserting the rates for each of them.
    this.SelectAll('Targets/Target', function() {
        var target = this.Evaluate('Currency');
        
        //make sure to the usage of $Xml as it will help us to move to the root node.
        $Xml.SelectSingle('Rates').AppendChild('Rate', function() {
            this.SetValue('From', base);
            this.SetValue('To', target);
            this.SetValue('Value', response.rates[target]);
            this.SetValue('Date', DateTimeOffset.parse(response.date+'T00:00:00+01:00'));
            this.SetValue('Timestamp', response.timestamp);
            this.SetValue('CreateDate', createDate);
        }); 
    })
})

//inserting rates to the database. Since we use the same names for the fields in the XML and the data table, we do not need to map them additionaly.
$Database.ImportFromXml({
    TargetSchema : 'Currencies',
    TargetTable : 'ExchangeRates',
    XPath : 'Rates/Rate'
});


$WorkItem.SelectedAction = 'Done';

Store Data in Local Database:

After retrieving the rates, $Database.ImportFromXml method will write the data to the defined data table in the local database.

Proceed to the next step:

Add an action button to the task (Done) and create a new task named as “Exchange Rate Results“.
Select the “Done “action on the module task to proceed.

3. Exchange Rate Results

The third task notifies the users that the process has been completed and displays the retrieved exchange rates.

4. Design the Form

Steps to Configure the Form:

Create a New Form:
- Create a new form that will be used for the "Retrieve Exchange Rates" task.
Add Table Content for Base Currencies:
- Select the form and add a new Row Content from the Layout Controls. Select the Use Current Section option when you are doing it.
- Add a Table Content element to the row content. This table will be used to display and select the base currencies. Since the data model is already done, you can use the “From the Data Model“ section.
- Name this table content "BaseCurrencies".
- Make sure this table content is bounded to “Currencies“ node.
Add Text Field for Base Currency Code:
- Inside the "BaseCurrencies" table, add a text field for entering the base currency code.
- Name this field "Currency".
Add Nested Table Content for Target Currencies:
- Inside the "BaseCurrencies" table, add another Table Content element. This nested table will be used for entering the target currencies corresponding to each base currency.
- Name this nested table content "Targets".
Add Text Field for Target Currency Code:
- Inside the "Targets" table, add a text field for entering the target currency code.
- Name this field "Currency".
Configure the Table for Displaying Rates:
- Add another Table Content element to the form to display the retrieved exchange rates.
- Name this table content "ExchangeRatesTable".
Add Fields to Exchange Rates Table:
- Inside the "ExchangeRatesTable", add the following fields:
  - From Currency: Text field named "From".
  - To Currency: Text field named "To".
  - Exchange Rate: Text field named "Value".
  - Date: Date field named "Date".
  - Timestamp: Timestamp field named "Timestamp".
  - Create Date: Date field named "CreateDate".