Mapping dashboard

The Mapping dashboard appears when you click a unit on the Pipeline dashboard. You use this to create mappings between two units. Specifically, this dashboard is used to map attributes of one unit with parameters on a second unit.

As with most tasks in Xapix, a mapping is done using drag and drop. Simply drag an attribute from the source unit to the target unit. A valid location in the target is highlighted to show where to drop the attribute.

Attributes and parameters

Attributes are non-editable name / value pairs in the source unit, whereas parameters are editable name / formula pairs in the target unit.

For example, attributes "first_name" and "last_name" in the data source getDriverbyID are mapped to parameters of the same name in a target data source or endpoint.

The name of a parameter can be edited only under certain situations. You don't normally need to change the parameter name. You can modify the value of the parameter by using formulas.

Parameter formulas

How does a parameter get its value from an attribute in a mapping? The value of a parameter is actually a formula that queries a specific value in a JSON-type object in an attribute.

The syntax of a query is defined as a set of dot-separated fields:

<unit>.<path>.<attribute>

where

  • <unit> is the name of the data source unit or flow unit

  • <path> is the parameter type in the unit

  • <attribute> is the value passed to the parameter

Formulas can be created using the following methods:

References

A reference is the most basic type of formula which follows the basic syntax described above. Here is a simple reference formula that follows the object structure of a given data source:

getdriversbyid.body.data.first_name

where

  • getdriversbyid.body.data is the data source

  • body.data is the path to the attribute

  • first_name is the name of the attribute

This reference formula resolves to the value:

"George"

In the following figure, attribute first_name is mapped to a parameter having the formula described above. Additional mappings are also shown.

Clicking the Gear icon next to the parameter makes the formula field editable.

Modifying a reference formula

Let's try a small change to show you how you can use a reference formula with Axel-f function. We use the REST endpoint xapix-io-api-data/vehicle-demo/variants.json and the data source allVariants.

Using this reference formula, we modify it so that every returned record's base price is in US dollars rather than Euros.

allVariants.body.[].base_price_EUR

To modify this reference formula, we do the following steps.

Steps
Steps
  1. Locate the parameter base_price_EUR and click the Gear icon.

  2. In the Name field, change the name of the parameter from base_price_EUR to base_price_USD.

  3. The Formula field contains the following: allvariants.body.[].base_price_EUR

  4. Using the Axel-f functions MAP, FN and ROUND, change the formula to: MAP(FN(x, ROUND(x * 1.1, 2)), allvariants.body.[].base_price_EUR)

  5. Save changes by clicking the checkmark next to the Name field.

  6. Click Done.

  7. You need to republish the project after making changes. Click Publish Project.

Xapix helps you use the Formula field. See Entering functions.

Running the curl command returns three vehicle records but with the base price provided in USD:

[{
"base_price_USD": 25802.46,
"engine_type_id": 547290,
"extras": ["FULL_CASCO", "LEATHER_SEATS_03"],
"fuel_consumption_lkm": 12.6,
"in_stock": true,
"model_id": 947432,
"topspeed_kmh": 220,
"variant_id": "QLM_KROSUS_4_DOORS_LIMO"
}, {
"base_price_USD": 17002.46,
"engine_type_id": 547170,
"extras": ["FULL_CASCO", "LEATHER_SEATS_01"],
"topspeed_kmh": 180,
"variant_id": "QLM_KROSUS_2_DOORS"
"fuel_consumption_lkm": 9.2,
"in_stock": true,
"model_id": 947438,
}, {
"base_price_USD": 40102.46,
"engine_type_id": 547290,
"extras": ["FULL_CASCO", "LEATHER_SEATS_03", "ARMOR"],
"fuel_consumption_lkm": 18.6,
"in_stock": true,
"model_id": 947434,
"topspeed_kmh": 200,
"variant_id": "QLM_KROSUS_4_DOORS_HEAVY"
}]

Using Axel-f functions

The second method is using Axel-F functions. You can use them in combination with references, as well as with operators.

Xapix has developed an extensive set of functions called Axel-F functions that combine the most understandable syntax from Excel© and the speed of the programming language Clojure. These functions have a syntax similar to Excel formulas and other spreadsheet functions.

Axel-F includes additional functions to work with lists such as MAP, FILTER, SORT, LENGTH and CONCAT. It also includes Lambda (anonymous) functions, such as FN. However, unlike spreadsheet functions, they do not include cell references or reference operations.

To take a simple example, you can use a CONCATENATE function with references to two attributes to generate a third value based on those references.

CONCATENATE(data.vehicle_1.make, "-", data.vehicle_1.vin)

where:

  • Axel-F function - CONCATENATE

  • Attributes - data.vehicle_1.make and data.vehicle_1.vin

  • Operator - "-"

Functions

Xapix provides aids to entering formulas in the Formula field:

  • Auto-completion - When you start typing a function in a formula field, Xapix will suggest functions. When you enter a letter in the formula field, you are given suggestions to auto-complete the formula. For example, entering c reveals a list of all function beginning with c such as CONCAT, CONCATENATE, and so on.

  • Syntax errors - You are alerted to any errors in syntax. The formula shows a checkmark next to the field only if you have entered a formula with correct syntax, otherwise, you have to correct any error before the formula is accepted.

  • Next level elements - After entering an attribute element, type a period (.) to show a list of valid next level elements to select.

  • Built-in Help text - Help text is available for each function. Click the Book link next to a function in the dropdown list of function lists.

Creating custom parameters

You can create custom parameters, such as mapping to more than one attribute.

For example, using an endpoint that has two body parameters: first_name and last_name, w_e can create a third parameter called _full_name. Here are the formulas for each of the parameters:

  • getdriversbyid.body.data.first_name

  • getdriversbyid.body.data.last_name

We create a new parameter called full_name using the following formula:

CONCATENATE(getdriversbyid.body.data.first_name," ",getdriversbyid.body.data.last_name)

To create this custom parameter, do the following steps.

Steps
Steps
  1. In the Formula field, type the letter c. From the list of functions that appears, scroll down to CONCATENATE.

  2. After the opening parenthesis, drag the attribute first_name to the formula field. Xapix adds this attribute to the formula: CONCATENATE(,getdriversbyid.body.data.first_name

  3. Delete the initial comma after the opening parenthesis.

  4. Add a comma after the reference to the first_name attribute. We also need a space between the two words, so add " " to create the space.

  5. Drag the attribute last_name to the formula field. Xapix adds this attribute to the formula as well: CONCATENATE(getdriversbyid.body.data.first_name, " " , getdriversbyid.body.data.last_name

  6. Close off the formula with a final parentheses. CONCATENATE(getdriversbyid.body.data.first_name, " " , getdriversbyid.body.data.last_name)

  7. Click the checkmark next to the parameter name. The Endpoint now has a new parameter full_name.

  8. Click Done to save the changes.

  9. You can test the changes using the generated sample curl command.

Operators

The third type of method is using operators. You use them together with references and formulas.

The Formula field supports many types of operators. A complete description of valid operators is provided in Formula operators.

Let's show this using a simple example. Using the values of two attributes from two different data sources, generate a new parameter value called total_price_EUR.

To use operators in a formula, do the following steps:

Steps
Steps
  1. The original formula for this parameter is: findvariantbyid.body.base_price_EUR

  2. Add the second attribute findEngineById to the formula: findvariantbyid.body.base_price_EUR, findenginebyid.body.price

  3. Remove the comma and add a (+) between the attributes: findvariantbyid.body.base_price_EUR + findenginebyid.body.price

  4. Xapix generates the resultant value.

  5. Click the checkmark next to the parameter name to save your changes.

  6. Click Done to save the changes.

  7. You can test the changes using the generated sample curl command.