In other articles, we showcase how to set up and configure a Field Mapping:
In this guide, we explain the different options to map the field values.
Mapping modes
The App Owner and Consumer can use 2 ways to define a mapping:
UI mode: This allows the user to navigate through the properties three from the integration raw response. The selected field gets translated into a JSON path definition.
Advanced mode: This allows the user to manually enter or adapt a JSON path definition or use a JSON example to select the property.
Both modes will result in a JSON path definition that will be used when returning a Unify response.
Advanced mapping with JSON Path
The field mapping is based on the JSON path syntax, which can handle simple & complex query expressions with deep nesting and arrays.
💡 JSONPath is a query language for JSON, similar to XPath for XML.
It allows you to select and extract data from a JSON document. You can use a JSONPath expression to traverse the path to an element in the JSON structure.
JSONPath allows you to query JSON objects and drill into nested structures to extract specific values. This is useful when:
The property you need is nested or requires traversal of the JSON structure.
You want to apply a function or expression to transform a value.
The property name is dynamic or conditional based on another value.
To define an advanced custom mapping, you can toggle to “Advanced mode” and enter a JSON Path query.
"$.phones[?(@.type=='mobile')].phone"
This would extract the mobile phone number by filtering for the phone number object with the type mobile.
In addition to being able to manually enter a JSON Path query, Apideck is extending “Advance Mode” to include by using WayFinder.
WayFinder allows you to click through your JSON response to compose a valid JSONPath dynamically.
Some more examples of JSON Path queries:
Simple JSON Path:
$['firstWorkingDay']
⇒ returns a simple valueAdvanced JSON Path: Deeply nested property:
$['env:Envelope']['env:Body']['wd:Get_Workers_Response']['wd:Response_Data']['wd:Worker']['wd:Worker_Data']['wd:Personal_Data']['wd:Personal_Information_Data']['wd:Personal_Information_For_Country_Data']['wd:Country_Reference']
⇒ returns a simple value
Advanced JSON Path: using * to iterate over array items:
$['Invoice']['TxnTaxDetail']['TaxLine'][*]['TaxLineDetail']['TaxPercent']⇒ Returns values from an array of valuesAdvanced JSON Path: Using conditionals:
$['env:Envelope']['env:Body']['wd:Get_Workers_Response']['wd:Response_Data']['wd:Worker'] ['wd:Worker_Data']['wd:Employment_Data']['wd:Worker_Job_Data']['wd:Position_Data']['wd:Job_Profile_Summary_Data']['wd:Job_Family_Reference']['wd:ID'][?(@['_attributes']['wd:type'] == 'Job_Family_ID')]['_text']
⇒ Returns the value from an array of objects, where the object property matches a certain “type”