Skip to main content

Mappings

Mappings allow either to send data such as process variables from LoyJoy to an external API, or to extract data from an external API and write it into LoyJoy process variables.

Send Data from LoyJoy to External API​

When process modules such as the CleverReach module send data, the API usually expects data in JSON format. To send information to the API, you can use mappings. LoyJoy follows the JSON pointer standard to send information to the API.

Mapping to JSON property based on Target JSON Pointer​

In the following example a LoyJoy process variable firstname is written to JSON with the key first_name. Please note, that the key first_name is denoted by the JSON pointer /first_name, i.e. the leading slash / is required by the JSON pointer standard.

Image1

{
   "first_name": "John"
}

Mapping to JSON object based on Target JSON Pointer​

In the following example a LoyJoy process variable street is written into the JSON object store_address with the key street.

Image2

{
   "store_address": {
      "street": "Main Street 20"
   }
}

Mapping to JSON array based on Target JSON Pointer​

In the following example a LoyJoy process variable street is written the first element of the JSON array addresses at position 0, with the key street.

Image3

{
   "addresses": [
      {
         "street": "Main Street 20"
      }
   ]
}

Retrieve Data from External API into LoyJoy​

When process modules such as the API client module retrieve data from an API, the data is usually in JSON or XML format. To extract information from the JSON and XML responses, you can use mappings. LoyJoy follows the JSON pointer and XPath standards to extract information from JSON and XML responses.

Mapping for JSON based on Source JSON Pointer​

To declare variables in LoyJoy use the field Target variable in LoyJoy and to extract information from the JSON in the response use the field Source JSON pointer to enter a JSON pointer. Consider the following example.

Image11

This mapping requires the JSON payload to have the key personal_consultant. For example, consider the following response.

{
   "personal_consultant": "John Doe",
   "store_address": {
      "street": "Main Street 20",
      "city": "Münster",
      "zipcode": "48147"
   }
}

You can then use the variable consultant in the chat.

To extract nested information of a JSON payload, chain the fields with a / i.e. to extract the city as the variable city use /store_address/city.

Image12

Mapping for JSON based on Source Expression​

By default the source JSON pointer is used to extract information from the JSON response. However, you can also use an expression to extract information from the JSON response. This is useful if you want to extract information from the JSON response that is not directly accessible with a JSON pointer. For example, consider the following JSON response.

{
   "personal_consultant": "John Doe",
   "store_address": {
      "street": "Prinzipalmarkt 10",
      "city": "Münster",
      "zipcode": "48143"
   }
}

To extract all keys of the store_address object, you can use the following expression based on the objectKeys function and the root object.

objectKeys(root.store_address)

Image13

This will return the following array.

["street", "city", "zipcode"]

To extract all values of the store_address object, you can use the following expression.

objectValues(root.store_address)

This will return the following array.

["Prinzipalmarkt 10", "Münster", "48143"]

Generally, you can use any expression that is valid in LoyJoy to extract information from the JSON response. This includes dynamic array access based on variables such as

root.store_address[varContainingValueCity]

Mapping for XML based on XPath Expression​

To extract information from an XML response, you can use an XPath expression. For example, consider the following XML response.

<response>
   <personal_consultant>John Doe</personal_consultant>
   <store_address>
      <street>Main Street 20</street>
      <city>Münster</city>
      <zipcode>48147</zipcode>
   </store_address>
</response>

To extract the city as the variable city use the XPath expression /response/store_address/city.

Image14

Also you can use XPath to extract attributes of an XML element. For example, consider the following XML response.

<response>
   <personal_consultant>John Doe</personal_consultant>
   <store_address>
      <street>Main Street 20</street>
      <city>Münster</city>
      <zipcode>48147</zipcode>
      <coordinates lat="51.960664" lon="7.626134"/>
   </store_address>
</response>

To extract the latitude as the variable latitude use the XPath expression /response/store_address/coordinates/@lat.

Image15