Before you read any further => You are amazing!
You made it this far without dropping out.. Seriously, take a moment and think about your accomplishments in life.. Well done!

What you should know first

• You know how JSON works
• You know the basics of states

Introduction

A lot of the times your API's present the data in a different way than Tick needs in order to present for example a choice. With JmesPath you can pick the data you want and transform it in such a way it is usable by the Tick API.

At Tick we did not create this invention but use JmesPath very often. We hope you can enjoy it too!

Remember, it is a technical endeavour but if you know something about Xpath or Css selectors you will be fine

How it works

• Use a JmesPath expression, it is a technical endeavour but if you know something about Xpath, regular expressions or Css selectors you will be fine.

Example: We want to ask which order to continue working with, we already asked the order number so we called the external API giving us back customer data including orders

Let's assume your API returns the following data:

Dummy response

{
  "id": "dummySearchItem1",
  "name": "test",
  "orders": [
    {
      "id": "dummy1",
      "title": "test dummy (1)",
      "nrOfProducts": 6,
      "amountEuro": "€ 15,-",
      "isPaid": false
    },
    {
      "id": "dummy2",
      "title": "test dummy (2)",
      "nrOfProducts": 1,
      "amountEuro": "€ 44,-",
      "isPaid": false
    },
    {
      "id": "dummy3",
      "title": "test dummy (3)",
      "nrOfProducts": 2,
      "amountEuro": "€ 21,-",
      "isPaid": true
    }
  ]
}

You might want to put the entire response in a single state but for the purpose of this demonstration you want solely the orders to be stored.

Without transformation

When you don't want any transformation happening it is really simple, just use an expression from the root of your data. For example "orders" will present you with

"orders": [
{
    "id": "dummy1",
    "title": "test dummy (1)",
    "nrOfProducts": 6,
    "amountEuro": "€ 15,-",
    "isPaid": false
},
{
    "id": "dummy2",
    "title": "test dummy (2)",
    "nrOfProducts": 1,
    "amountEuro": "€ 44,-",
    "isPaid": false
},
{
    "id": "dummy3",
    "title": "test dummy (3)",
    "nrOfProducts": 2,
    "amountEuro": "€ 21,-",
    "isPaid": true
}
]

With transformation

When you want to present the data as a choice it needs to be in a Tick specified format of {Text: 'option text', Data: 'the stored value'}. If you want to directly store the API response in such a format you would create the expression "orders[].{Text: title, Data: id}"

This would result in the following output:

[
  {
    "Text": "test dummy (1)",
    "Data": "dummy1"
  },
  {
    "Text": "test dummy (2)",
    "Data": "dummy2"
  },
  {
    "Text": "test dummy (3)",
    "Data": "dummy3"
  }
]

For advanced expressions see the JmesPath documentation

Best practice

• Adapter result action:
  Store the data in a manner you can do multiple things with it. Are transformations really needed or just a pain later on?
• As Choice:
  Get the presentable-data from the earlier stored data

Example: Assuming the same Dummy response as show above from your external API

1. Create the adapter and store the data:
2. External API Customer Id => use expression "id" in the communicator state
3. External API name => "name" in the communicator state
4. Orders with the expression "orders"
5. Create a Choice question, for the options using the expression "[].{Text: title, Data: id}"

This way you are able to use the CustomerId in further adapter-actions.