Learn how to interpret Zap JSON exports to understand your automation workflows. This guide explains how to read step configurations, trace data lineage across monday.com columns, and troubleshoot common lifecycle issues.
Understanding the Zap Pipeline
A Zap JSON file represents a linear sequence of events. By reading the JSON structure, you can map out the exact pipeline an order or item goes through.
flowchart TD
A["1. Catch Hook (Trigger)"] --> B["2. Get Column Values (monday.com)"]
B --> C["3. Format Data (Python)"]
C --> D["4. External API (e.g., Geocoding)"]
D --> E["5. Change Multiple Column Values"]When reviewing a Zap JSON file, look for the array of steps. Each step contains metadata about its application (e.g., monday.com, Code by Zapier), its action (e.g., Get Column Values), and its configuration.
Tracing Data Lineage: What changes Column X?
The most critical skill when reading these JSON files is determining what changes a specific piece of data across an order's lifecycle.
To find out what affects a specific monday.com column (e.g., text_mky5xz73), you must trace its ID through the JSON file's input and output mappings.
| Lifecycle Phase | JSON Step | Action | How Data is Handled |
|---|---|---|---|
| Ingestion | Step 2 | Get Column Values | Reads the raw data from text_mky5xz73. |
| Transformation | Step 3 | Python Code | Takes the raw string, strips control characters, expands abbreviations (e.g., Ave → Avenue), and splits it into structured keys (streetOnly, city, zip). |
| Enrichment | Step 4 | Google Geocoding | Passes the structured fullAddress to an external API to retrieve Latitude/Longitude. |
| Mutation | Step 5 | Change Column Values | Overwrites text_mky5xz73 with the cleaned address, writes Lat/Long to a Location column, and explicitly clears other columns. |
Look for intentional wipes: If a column is suddenly empty, check the final "Change Multiple Column Values" step in the JSON. Workflows often explicitly clear (set to empty) legacy text or color columns to wipe out prior manual entries.
How to Read a Zap JSON File
Use this step-by-step approach to audit any Zap JSON file in your repository.
- 1
Identify the Trigger payload
Locate the first step (Step 01). Determine what kicks off the workflow. For example, a
hook_v2trigger expects a payload containing an identifier, such asevent.pulseId. This tells you the Zap operates on a single monday.com item. - 2
Audit Custom Code logic
Locate any Python or JavaScript code steps. Read the script to understand the business logic. Look for regex patterns, string splitting, or hardcoded exclusions (e.g., filtering out placeholder unit values like
-,none, orn/a). - 3
Check External API calls
Identify HTTP requests or native API steps. Verify the endpoints (e.g.,
maps.googleapis.com/maps/api/geocode/json) and the parameters passed to them. - 4
Map the final state mutations
Examine the final action steps. This is where the workflow writes data back to the database or board. Map the output variables from previous steps to their destination column IDs.
Troubleshooting Common Issues
When an order is stuck or data looks wrong, the JSON export can point you to the root cause.
Why did the Zap fail to run entirely?
Check the paused state in the JSON metadata. It is common for action steps to be flagged as paused in an export if the Zap was mid-edit or disabled for testing. Confirm the live state in the Zapier dashboard.
Why is the API returning an authentication error?
Check the API step for hardcoded credentials. If an API key is hardcoded directly in the request URL or headers rather than pulled from a stored, secure variable, it may have expired or been revoked.
Why are unit numbers missing or formatted incorrectly?
Review the Python code step (Step 03). The issue is likely in the parsing logic. Check if the code correctly extracts internal markers (like #, Unit, Apt, Ste) or if it aggressively truncates the street line at the last recognized suffix, accidentally discarding valid unit data.
Why is a specific column randomly blank?
Look at the final "Change Multiple Column Values" step. The Zap might be configured to explicitly clear certain columns (setting them to empty) to ensure only freshly parsed data remains. If a column shouldn't be cleared, this mapping needs to be removed.
Hardcoded Variables
Always audit JSON exports for hardcoded API keys, environment-specific URLs, or fixed column IDs. If a monday.com board is duplicated or migrated, hardcoded column IDs (like text_mky5xz73) will break the workflow.