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​

In the following example a LoyJoy process variable firstname is written into the API with the key first_name.

Image1

Depending on the process module this mapping is used to write JSON, XML or other data formats. It is upon the external API which format is expected and which field are required or accepted.

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.

Image3

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.

Image4

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)

Image5

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.

Image6

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.

Image7