DEV Community

Cover image for AgentScript built-in functions: json_path()
Exploring Agentforce
Exploring Agentforce

Posted on

AgentScript built-in functions: json_path()

#salesforce #agentforce #agentscript #sfdx

AgentScript has a built-in json_path() function for extracting data from objects and lists using JSONPath-style expressions.

The basic syntax is:

json_path(variable, path, defaultValue?)
Enter fullscreen mode Exit fullscreen mode

The first argument is the data you want to query. The second is the path that describes what to select. The third is optional and specifies the value to return if no match is found.

A simple example

Let’s say an Agentforce action returns a list of Cases and saves it in a variable:

cases = [
  { "data": { 
    "CaseNumber": "000123", "Status": "New", "Priority": "High" 
  } },
  { "data": { 
    "CaseNumber": "000125", "Status": "Closed", "Priority": "Low" 
  } },
  { "data": 
    { "CaseNumber": "000127", "Status": "New", "Priority": "Medium" 
  } }
]
Enter fullscreen mode Exit fullscreen mode

You can select a field from the first Case:

json_path(@variables.cases, "$[0].data.CaseNumber")
Enter fullscreen mode Exit fullscreen mode

Result:

["000123"]
Enter fullscreen mode Exit fullscreen mode

$ refers to the object you are querying, it's the root of the path. The return value is always a list.

Working with the whole collection

This is where json_path() becomes more useful. The * wildcard lets you select a field from every item:

json_path(@variables.cases, "$[*].data.CaseNumber")
Enter fullscreen mode Exit fullscreen mode

Result:

["000123", "000125", "000127"]
Enter fullscreen mode Exit fullscreen mode

You can also select a range of items. For example, the first two Cases:

json_path(@variables.cases, "$[0:2]")
Enter fullscreen mode Exit fullscreen mode

Result:

[
  { "data": { "CaseNumber": "000123", "Status": "New", "Priority": "High" } },
  { "data": { "CaseNumber": "000125", "Status": "Closed", "Priority": "Low" } }
]
Enter fullscreen mode Exit fullscreen mode

Filtering the collection

But json_path() can do more than select values — you can also filter a collection based on conditions.

For example, select only Cases with Status = "New":

json_path(@variables.cases, "$[?(@.data.Status == 'New')]")
Enter fullscreen mode Exit fullscreen mode

Result:

[
  { "data": { "CaseNumber": "000123", "Status": "New", "Priority": "High" } },
  { "data": { "CaseNumber": "000127", "Status": "New", "Priority": "Medium" } }
]
Enter fullscreen mode Exit fullscreen mode

You can combine the filter with field selection:

json_path(
  @variables.cases, 
  "$[?(@.data.Status == 'New')].data.CaseNumber"
)
Enter fullscreen mode Exit fullscreen mode

Result:

["000123", "000127"]
Enter fullscreen mode Exit fullscreen mode

And you can use multiple conditions:

json_path(
  @variables.cases,
  "$[?(@.data.Status == 'New' && @.data.Priority == 'High')].data.CaseNumber"
)
Enter fullscreen mode Exit fullscreen mode

Result:

["000123"]
Enter fullscreen mode Exit fullscreen mode

Here:

?() → filter the collection
@ → the current item
== → compare a value
&& → require both conditions

A note about filtering support:

Salesforce's official documentation currently documents json_path() for accessing list items and using wildcards, but does not document filtering expressions like the examples above.

I tested filtering in a sandbox and it works as expected, but I’d be cautious about relying on it in production - untill Salesforce officially documents it.

AgentScript now has really limited native ways to work directly with collections. The useful part of json_path() is that it gives AgentScript this way to work directly with collections returned by actions — selecting, narrowing, and extracting the data you need without adding Apex or Flow.

Resources:
Reference an Item in a List

Top comments (0)