Skip to main content

Working with JSON

Almost every Wrkflow works with JSON. App integrations and API Wrk Actions return JSON response bodies. Downstream Wrk Actions usually need specific values from those bodies, not the full payload.

The Data Manipulation suite in the Wrk Action library includes a JSON category for that work. The two Wrk Actions you will use most often are Retrieve values from JSON and Retrieve all items from a JSON array. Together they cover most extraction and per-item processing patterns on the platform.

JSON category in the Wrk Action library listing Retrieve all items from a JSON array, Retrieve values from JSON, Query JSON using SQL, and other JSON Wrk Actions

Retrieve values from JSON​

Use Retrieve values from JSON when you have a JSON object (or a single item) and need named values for later steps.

  1. Pass the JSON into the Wrk Action (usually from a previous API response in the Data Library).
  2. Specify one or more JSON Path expressions for the fields you need.
  3. Map each path to a Custom Output with a unique, high-context name.

Those Custom Outputs become Data Library items you can bind into downstream Wrk Action inputs. Prefer clear names such as customer_email or invoice_total so later configuration stays readable.

Use this Wrk Action for nested paths, JSON Path functions, and for pulling several fields from one payload in a single step. For simple top-level key aliases on an existing Wrk Action output, Custom Outputs alone can be enough.

Retrieve all items from a JSON array​

Use Retrieve all items from a JSON array when the payload is an array and you want every item processed by the steps that follow.

This Wrk Action divides on the array. Downstream Wrk Actions run once per item, in parallel. That is similar to multi-threading: faster execution when items are independent. Because of that:

  • Items cannot share state or talk to each other while they run
  • Items are not processed in a guaranteed order

For more on how divides work, see Divides.

You can also define Custom Outputs that match top-level field names on each array item. Wrk extracts those field values automatically for each divided item.

Nested fields inside array items​

If you need values nested inside each object in the array, pair the two Wrk Actions:

  1. Retrieve all items from a JSON array to divide on the array (and optionally extract top-level fields).
  2. Retrieve values from JSON on each item to pull nested paths into Custom Outputs.

That combination is the most common way to work with JSON and JSON arrays on Wrk.

Filter, aggregate, or order before you process​

If the array needs aggregation, filtering, or ordering before you divide or extract fields, use Query JSON using SQL first. Run your SQL against the JSON, then pass the result into Retrieve all items from a JSON array or Retrieve values from JSON as needed.

Which Wrk Action to use​

GoalWrk Action
Extract one or more fields (including nested paths) from a JSON objectRetrieve values from JSON
Process every item in a JSON array in parallelRetrieve all items from a JSON array
Nested fields on each array itemDivide with Retrieve all items from a JSON array, then Retrieve values from JSON
Filter, aggregate, or reorder JSON before processingQuery JSON using SQL
Alias a top-level JSON key on an existing Wrk Action outputCustom Outputs

Video overview​

This video covers:

  • Using JSON Path to retrieve values from JSON
  • Using SQL to transform and aggregate JSON