Filters For Source Files In Flow Configurations

In this article:

• Setting Up A JSON Filter
• Setting Up A XPath Filter
• Setting Up A RegEx Filter 

Filters allow users to better manage which data transactions ultimately get sent into their system by reducing any unwanted or redundant messages. Customers can set up filters for JSON, XML, and text-based source files within the Flow configuration screen. Options include a simple JSON filter or a more advanced JSONata filter for JSON documents, an XPath filter for XML documents, and a RegEx filter for pattern matching in text-based files.  

Setting up a JSON Filter

Using basic key/value pairs or JSONata expressions, users can quickly define which JSON files get processed while discarding the rest.

You can set up a JSON filter by navigating to your flow configuration screen.

Click the panel labelled Filters to reveal the JSON Filter options. By default Disabled is selected.

In the dropdown, you can enable JSON filtering by selecting either of the following options:.

1) Simple: This filter mode allows users to filter by defining a key-value pair. For the key column, fill in the simple path to the field. A simple JSON path to a property within a nested object is written with a  “.” between every object key from JSON root to the target field. You would then put what value you would expect for the key. Any files that match that criteria will be processed by Chain.io and can be found in the “Search” screen where you can view the flow executions. Any file that does not meet the criteria will be filtered out and discarded (not visible or processed in portal.chain.io). 

Simple Mode JSON Filter Example: If someone wants to filter all JSON files where the carrier is NOT Maersk they could setup a simple JSON filter as such:

Example Input:

Simple JSON filter:

2) Advanced: This allows you to take advantage of using JSONata expressions to build more complex filtering logic. To learn more about the JSONata you can visit: https://docs.jsonata.org/overview and to practice writing your own JSONata expressions using your own data, you can use https://try.jsonata.org/

Advanced JSONata filter:

In the previous example, the correct way to filter on carrier name using the advanced mode would be to write this JSONata expression: carrier.name = "Maersk A/S"

Setting up an XPath Filter

Using XPath expressions, customers have the ability to filter data within their source files from being processed by the Flow execution. To add an XPath Filter, navigate to your flow configuration and open the Filters panel:

Select Enabled from the dropdown then click the Add button to add a new Xpath Filter Expression:

In the field the appears add your XPath expression.

Setting up a RegEx Filter

Using regular expressions, customers have the ability to filter data within their source files from being processed by the Flow execution. To add a RegEx Filter, navigate to your flow configuration and open the Filters panel:

Select Enabled from the dropdown then click the Add button to add a new Regular Expression Filter:

In the Regular Expression Filter field, add you RegEx:

If there are any Flags needed for this RegEx, add those in the Flags field:

Testing Your Filters

Once you've configured one or more filters, you can test them against a sample file before saving — no need to wait for a real transaction to see whether your filter logic works as expected.

Click the Test Filters button in the flow's right-hand navigation.

Note: This button is disabled until at least one filter is configured on the flow.

This opens the Test Filters dialog. Paste an XML or JSON document into the text box, or drag and drop a file directly onto it. Files up to 1 MB are supported, and Chain.io automatically detects whether the document is XML or JSON.

Click Run Test to evaluate your sample against every filter on the flow.

Reading the results

Each filter is listed with a pass/fail indicator, plus an overall verdict at the bottom of the dialog:

Verdict    Meaning

? Green    The file would be accepted into this flow

? Red    The file would be rejected by this flow

? Orange — type mismatch    All your filters target one format (XML or JSON) but you uploaded the other

Depending on your flow's setup, results are grouped into up to three sections:

Required Filters — For Cargowise source file types, these are XPath filters Chain.io automatically applies at compile time (for example, confirming a CargowiseXUS file is a Universal Shipment document). You don't configure these yourself, but they can still cause a file to be rejected.

Configured Filters — The JSON, XPath, RegEx, or JSONata filters you've set up on this flow, as described earlier in this article.

Organization Filters — CargoWise organization-level filters (e.g., recipient org restrictions), shown only when the flow's source connection or file type has them configured.

A note on filter types and file formats

Filters are matched to the format of the file you upload:

XML documents: XPath and RegEx filters are evaluated. JSONata filters show as N/A since they only apply to JSON.

JSON documents: JSONata and RegEx filters are evaluated. XPath filters show as N/A, and the Required/Organization Filters sections aren't shown, since those are CargoWise (XML) specific.

Tip: If you've made changes to your filters but haven't saved them yet, the dialog will show a banner reminding you that you're testing against unsaved changes.

Diagnosing a file that didn't show up where expected

If a file you expected to see in a flow's execution history never turned up, filters are one of the most common culprits — the file may have been silently discarded because it didn't match a configured filter, a compiler-added required filter, or an organization filter.

To check:

1. Get a copy of the source file that should have triggered the flow (from your source system, or from whoever sent it).
2. Open that flow's configuration and click Test Filters.
3. Paste in or drop the file and click Run Test.

If the result comes back red, the failing filter(s) will be highlighted, telling you exactly which rule rejected the file — no need to guess or ask support to trace it manually.