Skip to main content

Dependency Mapping

Dependencies define how data flows between endpoints. When one endpoint needs values from another (like user IDs), you create a dependency mapping.

Understanding Dependencies​

Example: To collect messages for each channel, you need channel IDs first.

channels endpoint → extracts channel IDs → messages endpoint

The dependency mapper lets you:

  1. Define which endpoint provides values
  2. Specify the JSON path to extract
  3. Choose iteration mode (each value vs. first only)
  4. Map to target endpoint parameters

Creating Mappings​

Using the UI​

Open the endpoint editor (the Test & Configure tab in a draft, or the endpoint explorer in a published connector). Then:

  1. Test the source endpoint to see its response data
  2. In the interactive JSON viewer, click the field containing the IDs you need
  3. Drag the value onto the target endpoint's parameter drop zone — or use the mapping dialog to enter a JSON path directly
  4. Choose iteration mode:
    • Iterate: Run target endpoint for each value (auto-selected when the path contains an array wildcard like [*])
    • First: Use only the first value

Example: Channel Messages​

Step 1: Test "List Channels" endpoint
        Response: { "channels": [{ "id": "C123" }, { "id": "C456" }] }

Step 2: Click "channels[*].id" in the JSON viewer

Step 3: Drag to "Get Channel Messages" endpoint
        Target parameter: channel_id (in path)

Step 4: Select "Iterate" mode
        Result: Will call /channels/C123/messages, /channels/C456/messages

JSON Path Syntax​

Extract values using JSON paths:

PathDescriptionResult
data[*].idAll IDs from data array["id1", "id2", "id3"]
users[*].profile.emailNested field from array["a@x.com", "b@x.com"]
data[0].idFirst ID only"id1"
meta.organization_idSingle value from object"org123"

Array Notation​

  • [*] - All items in array
  • [0] - First item
  • [-1] - Last item

Parameter Locations​

Specify where the extracted value goes:

LocationUse For
pathURL path templates like /users/{user_id}
queryQuery parameters like ?channel_id={channel_id}
bodyRequest body fields (POST/PUT/PATCH endpoints)

The body location is valid for endpoints configured with Body Parameters.

Iteration Modes​

Iterate Mode (Default)​

Runs target endpoint once for each extracted value:

Source returns: ["C123", "C456", "C789"]
Target runs 3 times:
  - /channels/C123/messages
  - /channels/C456/messages
  - /channels/C789/messages

First Mode​

Uses only the first extracted value:

Source returns: ["C123", "C456", "C789"]
Target runs 1 time:
  - /channels/C123/messages

Use first mode when:

  • Only need one example
  • Source provides identical values
  • Testing dependency works

Dependency Order​

The system automatically determines execution order:

  1. Endpoints with no dependencies run first
  2. Dependent endpoints wait for their sources
  3. Use the order field to prioritize within the same dependency level

Example order:

1. users.list (no dependencies)
2. channels.list (no dependencies)
3. user.profile (depends on users.list)
4. messages.history (depends on channels.list)

Alternatives to Complex Dependency Chains​

Paired Variables​

When you need correlated values from two sources (e.g., user IDs paired with their organization IDs), consider using Paired Variables instead of creating multiple mapping chains. Paired variables let you combine outer/inner value sources with modes like cartesian, positional, join, or nested.

Merged Variables​

When you need to aggregate the same type of data from multiple endpoints (e.g., IDs from several list endpoints), use Merged Variables to combine them into a single iteration set.

Testing Dependencies​

  1. Configure all mappings
  2. Test source endpoints first to populate data
  3. Run iterate test on dependent endpoints
  4. Review results to verify correct data flow

What to Verify​

  • Values extracted correctly
  • Substitution works as expected
  • All dependent endpoints receive values
  • No circular dependencies

Troubleshooting​

No Values Extracted​

Causes:

  • JSON path is incorrect
  • Source endpoint returned empty data
  • Wrong array notation

Solutions:

  1. Test source endpoint individually
  2. Verify JSON path matches response structure
  3. Check for typos in path

Wrong Values Extracted​

Causes:

  • Path points to wrong field
  • Array index issue
  • Nested object confusion

Solutions:

  1. Use JSON viewer to navigate response
  2. Click on exact field needed
  3. Verify path before dragging

Target Endpoint Fails​

Causes:

  • Parameter location wrong (path vs query vs body)
  • Parameter name mismatch
  • Extracted value format issue

Solutions:

  1. Check target endpoint's expected parameters
  2. Verify parameter name matches
  3. Check if value needs transformation (see Response Transformations)

Circular Dependencies​

The system will detect and prevent circular dependencies:

  • A depends on B, B depends on A
  • A depends on B, B depends on C, C depends on A

Reusable Variables​

For values that need to be used across multiple endpoints, consider using Reusable Variables instead of creating individual mappings.

Variables let you:

  • Name a data extraction once
  • Apply to multiple endpoints
  • Add conditional filtering
  • See all uses in one place

See Reusable Variables for details.

Conditional Filtering​

When a source array contains mixed data, use Conditional Variables to filter:

Source: blocks[*] contains pages, databases, text blocks
Filter: type = 'page'
Result: Only page blocks are used

Filter conditions include:

  • equals / not_equals
  • contains / starts_with / ends_with
  • exists

See Conditional Variables for the full guide.

Best Practices​

  1. Minimize depth - Deep chains increase failure points
  2. Test the full chain - Partial tests miss integration issues
  3. Handle empty results - Source with no data shouldn't break dependents
  4. Consider parallelization - Independent endpoints can run concurrently
  5. Document complex mappings - Use notes for non-obvious dependencies
  6. Use variables for reuse - Don't duplicate the same mapping
  7. Filter at source - Use conditional variables to reduce iteration count
  8. Use paired variables for correlation - When you need values from two sources in sync

Next Steps​

Technical Reference​

For algorithm details, see: