Articles on: Q&A

How to Sort, Filter and Transform Complex JSON Data

When working with data from different sources, it's common to encounter complex or deeply nested JSON structures. These can be difficult to work with directly in templates — both for you and your end users.


To address this, you can define data settings that let you sort, filter, and transform your data, all without modifying your source system. Whether you're creating templates in the editor or via the API, these settings give you full control to customize your data — letting you create new fields, flatten nested arrays, and reshape the structure to fit your needs.


In this article, we’ll focus on how to work with Data settings directly in the editor.


Data Settings


To access the Data settings in the editor, open your template and navigate to File → Data settings from the top menu.


Data settings include three options:


  1. Sort by
  2. Filter by
  3. Transformation


Data Settings


These settings allow you to prepare and organize your data before it’s used in the template. Instead of working with raw or complex data, you can filter records, sort them, and create custom fields in one place. By defining this logic at the data level, you keep your templates simple, focused, and ensure consistent output across the document.


Filtering and Sorting Input Data


Filtering and sorting are essential tools for managing and organizing your data before it is used in your templates. These options let you control exactly which records appear and in what order, making your documents clearer and more relevant.


Sorting and Filtering in Data Settings apply at the data level to arrays of objects. To sort or filter data inside a single object, use Advanced Settings in a table or container, or a suitable expression using our expression language in the desired component.


Sort by


The Sort by option allows you to define one or more rules to order your data based on specific fields. Each sorting rule includes:


  • Data Field: Select the field you want to sort by.
  • Order: Choose whether to sort in Ascending or Descending order.


Rules are applied in the order you add them, enabling precise control over the data sorting.


Filter by


The Filter by option lets you include only the records that meet certain criteria. Each filter rule has three fields:


  • Data Field: Select the field you want to filter on.
  • Operator: Choose the comparison operator (e.g., is, contains, greater than).
  • Value: Enter the value that the field is compared against.


You can add multiple filter rules, which are combined using the logical AND operator. This means only records satisfying all conditions will be included.


If you want to filter records where at least one condition is met, select Expression as the operator. This allows you to write custom expressions using our expression language to combine conditions with an OR operator.


Use Case: Creating Completed Orders Report


When working with JSON datasets containing multiple orders, it is important to control which records appear in the output PDF and in what sequence. By default, all orders in the dataset will be rendered, but you may want to include only relevant orders and present them in a logical order.


Data settings allow you to apply filtering and sorting rules before the data reaches the template:


  1. Filter by can exclude orders that should not appear in the PDF (e.g., only include orders where status is Completed).
  2. Sort by ensures that orders are rendered in a consistent sequence (e.g., newest first, highest total first, alphabetical order by customer).


This ensures that PDFs are clear, consistent, and aligned with business requirements — all without modifying the source JSON.


Example JSON Dataset


[
   {
      "order_id": "1001",
      "customer": "Alice Johnson",
      "status": "Completed",
      "order_date": "2025-09-14",
      "total": 129.99
   },
   {
      "order_id": "1003",
      "customer": "Bob Smith",
      "status": "Pending",
      "order_date": "2025-09-20",
      "total": 59.50
   },
   {
      "order_id": "1002",
      "customer": "Charlie Davis",
      "status": "Completed",
      "order_date": "2025-09-18",
      "total": 249.00
   },
   {
      "order_id": "1005",
      "customer": "Diana Evans",
      "status": "Completed",
      "order_date": "2025-09-22",
      "total": 179.75
   },
   {
      "order_id": "1004",
      "customer": "Ethan Ford",
      "status": "Canceled",
      "order_date": "2025-09-21",
      "total": 89.99
   }
]


Example Data Settings


To generate a report that includes only completed orders, sorted by order date from newest to oldest, the following Data settings are applied:


Filter by:

  • Data Field: status
  • Operator: IS
  • Value: Completed


Sort by:

  • Data Field: order_date
  • Order: DESC


Outcome


From the dataset above, only the following Completed orders will appear in the PDF, sorted from newest to oldest by order_date:


  1. Order ID: 1005 — Diana Evans — 2025-09-22 — $179.75
  2. Order ID: 1002 — Charlie Davis — 2025-09-18 — $249.00
  3. Order ID: 1001 — Alice Johnson — 2025-09-14 — $129.99


Orders with status set to Pending or Canceled (Order ID 1003 and 1004) will be excluded.


Each order will be rendered according to the defined template, producing professional, consistent, and accurate reports while preserving the integrity of the original dataset.


Data Transformation


Data Transformation in the editor allows you to create new fields, modify existing values, or generate entirely new arrays based on your JSON dataset. This ensures that your templates remain flexible and maintainable, even when working with complex datasets.


Data Transformation has two fields:


  • New Field/Array Name – Enter the name of the new field or array you want to create.
  • Expression/Value – Define the value, formula, or expression that the new field/array should evaluate to.


You can add multiple transformations to the same dataset by clicking the plus (+) button on the right side of the Expression/Value field, allowing you to create several new fields or arrays in one place.


Use Cases


1. Creating and reusing a new data field


Sometimes you need a calculated or derived value that does not exist in the original dataset. For example, you can define a new field using an expression (e.g., combining first_name and last_name into a full_name) and then reuse this field in multiple parts of the template or in other expressions. This ensures consistency and avoids repeating complex calculations across the template.


Example JSON Dataset


{
  "first_name": "Alice",
  "last_name": "Johnson"
}


Example Data Transformation


To create a new field that combines first_name and last_name into a single full_name:


New Field/Array Name: full_name

Expression/Value: {first_name}~" "~{last_name}


The item will have a new field full_name added:


{
  "first_name": "Alice",
  "last_name": "Johnson",
  "full_name": "Alice Johnson"
}


2. Generating multiple outputs from a single array


You may need to generate multiple records in your output even if the source dataset contains only a single record with a quantity field. For example, if an item in an order has a quantity of 4, you might want to automatically create 4 separate entries, one for each unit, instead of showing only the aggregated quantity.


With Data Transformation, you can use expressions to “expand” arrays and create a new array based on existing data. This allows you to control how many times a record is repeated in the output, which is especially useful for generating labels, barcodes, or similar repeated elements.


Example Input JSON


{
  "production_order": {
    "order_id": "PO-202",
    "warehouse": "Berlin Factory",
    "materials": [
      {"item": { "name": "Wood Panel", "sku": "WD-11" },"quantity": 2},
      {"item": { "name": "Metal Leg", "sku": "ML-45" },"quantity": 4},
      {"item": { "name": "Varnish", "sku": "VR-07" },"quantity": 1}
    ]
  }
}


Transformation Expression


To generate an expanded list of materials where each record is repeated according to its quantity, the following Data Transformation is applied:


  • New Field/Array Name: custom_array
  • Expression/Value:

flatten(map({production_order::materials},'iterate(1..reference[_key]["quantity"], "reference", reference[_key])',{production_order::materials}))


Explanation:


  • map(...) iterates over the materials array.
  • iterate(1..quantity, ...) repeats each record as many times as defined by its quantity.
  • flatten(...) ensures the nested iterations are combined into a single flat array.


Example Output JSON


{
  "production_order": {
    "order_id": "PO-202",
    "warehouse": "Berlin Factory",
    "materials": [
      { "item": { "name": "Wood Panel", "sku": "WD-11" }, "quantity": 2 },
      { "item": { "name": "Metal Leg", "sku": "ML-45" }, "quantity": 4 },
      { "item": { "name": "Varnish", "sku": "VR-07" }, "quantity": 1 }
    ]
  },
  "custom_array": [
    { "item": { "name": "Wood Panel", "sku": "WD-11" }, "quantity": 2 },
    { "item": { "name": "Wood Panel", "sku": "WD-11" }, "quantity": 2 },
    { "item": { "name": "Metal Leg", "sku": "ML-45" }, "quantity": 4 },
    { "item": { "name": "Metal Leg", "sku": "ML-45" }, "quantity": 4 },
    { "item": { "name": "Metal Leg", "sku": "ML-45" }, "quantity": 4 },
    { "item": { "name": "Metal Leg", "sku": "ML-45" }, "quantity": 4 },
    { "item": { "name": "Varnish", "sku": "VR-07" }, "quantity": 1 }
  ]
}


The new custom_array array contains 2 wood panels, 4 metal legs, and 1 varnish — each as an individual record. This makes it possible to generate separate labels, barcodes, or rows in your output document, without modifying the original dataset.


Conclusion


Using Data settings, including Sort, Filter, and Transformation, allows you to prepare and format your data at the data level before it is rendered in your templates. This ensures consistent and predictable output and gives you full control over how complex datasets are represented in PDFs.


Updated on: 01/10/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!