Advanced Filter in Action Builder

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.

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. To use the Advanced Filter, you first need to create an action by configuring all the necessary API settings for your request, such as the URL, API method, query parameters, and so on. Once these settings are completed, click "Send" to execute the API request, which will then return the 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 ' '

Math Operations in JMESpath

The Math Operations in JMESPath feature enables users to perform basic arithmetic operations directly within advanced filters in the action builder. This enhancement simplifies data processing by allowing mathematical calculations to be applied to responses dynamically.

With this feature, users can perform the following operations:

• Addition (+) – Combine numerical values.
• Subtraction (-) – Find the difference between values.
• Multiplication (*) – Multiply values together.
• Division (/) – Perform standard division.
• Exponentiation ()** – Raise a number to a power.
• Modulo (%) – Determine the remainder of a division.
• Floor Division (//) – Divide and round down to the nearest whole number.

This feature supports operands in various formats, including integers, floats, and numeric strings, ensuring flexibility in handling different data types.         

Demo Video of Math Operations in JMESpath            

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]"