Action Builder: Advanced Filter

Introduction

Action Builder supports the use of the Advanced Filter which allows admins to transform the API response in an Action into a new format. The Advanced Filter leverages the JMESPath query language to format the default API Response into any format that an admin would want to use in Workflow Builder.

This feature is particularly useful for filtering and sorting API responses from third parties and transforming the API response into a desired structure.

Example Use Case

Imagine that you are fetching order information from a 3rd party API Service that returns all orders given an Order ID. The default response returns a structure like:

{
    "orders": [
        {
            "price": "$20.00",
            "status": "Delivered",
            "id": 1
        },
        {
            "price": "$35.00",
            "status": "In Transit",
            "id": 2
        },
        {
            "price": "$10.00",
            "status": "Delivered",
            "id": 3
        }
   ]
}

Let's say you would like to only select the id of the cheapest "Delivered" order and the third party does not support this filtering on the request. The only way to obtain this information is to use transformations after the API Request is made.

To do this, you can leverage JMESPath queries in the Advanced Filter in Action Builder. For example to sort the "Delivered" orders by price, you can use the JMESPath query like:

sort_by(orders[?status == 'Delivered'], &price)[*]

Which will return the following object:

[
  {
    "price": "$10.00",
    "status": "Delivered",
    "id": 3
  },
  {
    "price": "$20.00",
    "status": "Delivered",
    "id": 1
  }
]

Now that the data is in the desired format, you can leverage it however you choose. The following section shows you the full end to end experience of Advanced Filter in Action Builder.

How to Use

1. In order to use the Advanced Filter, you must first create an action as you normally would by setting all API settings of your request, e.g. URL, API Method, Query Parameters, etc. Once these have been configured, clicking Send will execute the API Request and return an API Response.
2. Once the response is returned, admins will see a toggle labeled Advanced Filter. Keeping this toggle Off will allow users to leverage the search functionality of the default response.
3. Switching the toggle On will display the Advanced Filter input box.
4. Users can enter JMESPath expressions to transform the API Response into a desired format. The transformed response will appear in a new Result. 
5. You can then select any of the keys in the transformed Result to store that path in the API Response to a Context Variable.

And that's it! You can now save the action and add it to any workflow as you normally would. When the action is executed during a conversation, the Advanced Filter will transform the API Response to the expected format. From there, any CV that was selected will be filled from the path designated by the Advanced Filter.

JMESPath Resources

JMESPath can look complicated for new users. However, the JMESPath Specification is well defined and maintained. In addition, there are useful tutorials and examples outlined on the JMESPath website.

If you need help writing a JMESPath query to transform your API Response, please reach out to your assigned IE who will help ensure your requirements are met.

Additional Use Case

It is possible to leverage the Advanced Filter to set a default value in case an object does not exist in the API Response or is null.

For example, let's say a path to the key designated in a response is path.to.order.number and the value at that path represents the number of orders for a user. You can set the advanced filter like:

{result: path.to.order.number || `0`}

This will set the designated Context Variable value to 0 if this path is null during action execution.

In addition, the same can be done for string values:

{result: path.to.order.title || 'No Product Title'}

This will set the title to No Product Title if the path is null.

JMESPath requires that numbers be placed in backticks ` ` and strings in single quotes ' '

Context Variables

The Advanced Filter now supports Context Variables, making the feature more powerful and useful. Check out the following videos for potential use cases.

Custom Functions

Forethought supports all built in JMESPath functions as well as custom functions that meet current business needs.

• split - used to split a string into a list of substrings based on a specified separator

json = { "id": "123 : 456" }

// returns ["123", "456"]
"id | split(@, ' : ')"

// returns "123"
"id | split(@, ' : ')[0]"