Multi-Table Response Mapping is a capability in the SuiteEngine API Engine that allows you to map a single element from an API response to create records in multiple Business Central tables simultaneously. This feature enables you to transform complex API responses containing related data into properly structured Business Central records without writing custom code.

Available in: API Engine version 1.17.0.0 and later

Your e-commerce platform (Shopify, BigCommerce, Amazon) returns product information that needs to be stored in both:

• Item Table - Base product information (SKU, Description, Price)
• Custom Extension Table - Marketplace-specific data (External ID, Sync Status, Channel-specific attributes)

Without Multi-Table Mapping:

• You'd need to make two separate API calls, OR
• Write custom code to split the data, OR
• Store everything in one table (limiting your data structure)

With Multi-Table Mapping:

• One API call retrieves the product
• API Engine automatically creates records in both tables
• Base items and extended data stay properly synchronized

Your Order Management API returns order line items that include fulfillment details:

{
  "order_id": "SO-12345",
  "lines": [
    {
      "item": "WIDGET-001",
      "quantity": 5,
      "fulfillment": {
        "warehouse": "WEST",
        "bin_location": "A-05",
        "pick_status": "Ready"
      }
    }
  ]
}

You need to create:

• Sales Line record - Item, Quantity
• Custom Fulfillment Detail record - Warehouse, Bin, Status

Multi-Table Mapping lets you configure both tables to receive data from the same line element in the response.

Products have variants (Color, Size combinations) that need to be stored in Item Variant table, while base product goes to Item table:

{
  "product": {
    "base_sku": "WIDGET",
    "name": "Widget Pro",
    "variants": [
      { "sku": "WIDGET-RED-L", "color": "Red", "size": "Large" },
      { "sku": "WIDGET-BLU-M", "color": "Blue", "size": "Medium" }
    ]
  }
}

Mapping:

• /product creates Item record (WIDGET)
• /product ALSO creates Product Info record (extended attributes)
• /product/variants/variant creates Item Variant records
  • Important: Variants should only link to the Item record, not the Product Info record

Multi-Table Mapping with Parent Sequence ensures variants correctly associate with the Item table parent.

The Parent Sequence field creates an explicit link between child mappings and their intended parent mapping. This tells the API Engine: "This child mapping only applies when processing THIS specific parent table."

Visual Example:

API Response: /products/product

┌─────────────────────────────────────────────────────────────┐
│         RecordNode A                RecordNode B            │
│         (Item Table 27)             (Product Info Table)    │
│                                                             │
│         Parent Sequence: 10         Parent Sequence: 10     │
│         (Links to TableNode)        (Links to TableNode)    │
│                                                             │
│         Creates Item Record         Creates Extension Record│
│              │                               │              │
│              │                               │              │
│         ┌────┴─────┐                    ┌────┴──────┐      │
│         │          │                    │           │      │
│    Field: SKU  Field: Name        Field: ID   Field: Price │
│    (Table 27)  (Table 27)         (Table 50100) (Table 50100)│
│                                                             │
└─────────────────────────────────────────────────────────────┘
                  │
                  │ Child RecordNode
                  │ (Item Variant Table 5401)
                  │
                  └─ Parent Sequence: 100
                     (Links to RecordNode A - Item Table)
                     NOT RecordNode B - Product Info Table

When the API Engine processes responses:

1. Finds all RecordNodes for the response path
2. Filters by Parent Sequence - Only processes RecordNodes that belong to the current parent
3. Automatically filters elements - Elements only apply to their designated table
4. Prevents duplicate processing - Each child processes exactly once for its correct parent

1. API response contains data for multiple Business Central tables

   • Example: Product info goes to Item table AND extension table

2. You need to maintain relationships across custom extension tables

   • Example: Sales lines link to custom fulfillment detail records

3. Different parts of the response need different table destinations

   • Example: Base product vs. variant data

4. You want to avoid multiple API calls to get related data

   • Example: Get products and variants in one call

1. Response has different paths for different tables

   • Use standard RecordNode mappings (no Parent Sequence needed)

2. Single table destination is sufficient

   • Simple mappings work fine

3. You need conditional table selection based on response values

   • Use Mapping Source Filters instead

Location: API Mappings page, "Parent Sequence" field

What to Enter:

• For top-level RecordNodes: Sequence number of your Function Root TableNode (usually 10)
• For child RecordNodes: Sequence number of the parent RecordNode
• For legacy mappings: Leave at 0 (backward compatible)

Example Configuration:

What This Means:

• Seq 100 and 200 are siblings (same parent, same path, different tables)
• Seq 300 is child of Seq 100 (variants belong to Items, not Extensions)
• Elements under each RecordNode automatically filter to the correct table

When you create Element mappings (field mappings), the Table No. on the Element must match the Table No. of its parent RecordNode.

Example:

RecordNode Seq 100: Table No. = 27 (Item)

✅ Correct Elements:
  - Seq 110: Table No. = 27, Field No. = 1 (Item No.)
  - Seq 120: Table No. = 27, Field No. = 3 (Description)

❌ Incorrect Element:
  - Seq 130: Table No. = 50100, Field No. = 1
  - This will be filtered out and NOT processed!

Why: Starting in v1.17, the API Engine automatically filters elements to match the RecordNode's table number, preventing incorrect field assignments.

Starting in v1.17, mapping sequence numbers must be greater than zero. This ensures Parent Sequence references are always valid.

If you have existing mappings with Sequence = 0:

• They will continue to work until you try to modify them
• When editing, you must assign a valid sequence number (1 or higher)
• Use the rename function to change sequence numbers if needed

Business Need: Import products from BigCommerce with both base product data and marketplace-specific information.

API Response:

{
  "data": [
    {
      "id": 987654,
      "sku": "WIDGET-001",
      "name": "Super Widget",
      "price": 49.99,
      "variants": [...]
    }
  ]
}

Mapping Configuration:

Base Product → Item Table

• Seq 100: /data/product → RecordNode, Table 27, Parent Seq: 10
• Seq 110: /data/product/sku → Element, Table 27, Field 1 (No.)
• Seq 120: /data/product/name → Element, Table 27, Field 3 (Description)

Extended Data → Custom Table

• Seq 200: /data/product → RecordNode, Table 50100, Parent Seq: 10 (same path!)
• Seq 210: /data/product/id → Element, Table 50100, Field 1 (External ID)
• Seq 220: /data/product/price → Element, Table 50100, Field 10 (External Price)

Result:

• Each product in the API response creates:
  • 1 record in Item table (WIDGET-001)
  • 1 record in Product Extension table (External ID: 987654)
• Both records created from the same /data/product element
• Elements automatically route to correct table

• No custom code required - Configure mappings, not programming
• Flexible data structure - Use standard BC tables + custom extensions
• Easy to maintain - Clear parent-child relationships
• Reusable patterns - Same approach works for any multi-table scenario

• Richer data - More information stored and accessible
• Better reporting - Data properly organized across tables
• Maintained relationships - Parent-child links preserved
• Single synchronization - One API call updates multiple tables

• Extensible - Add new tables without modifying core logic
• Type-safe - Table relations validate Parent Sequence references
• Testable - Clear mapping configuration enables comprehensive testing
• Documented - Parent Sequence makes relationships explicit

A: No! Parent Sequence is only required when you have multiple RecordNodes with the same Source ID path mapping to different tables. If your mappings use different paths for different tables, you don't need Parent Sequence.

Example of when NOT needed:

/orders/order → Sales Header
/orders/order/lines/line → Sales Line

These use different paths, so standard RecordNode works fine.

Example of when NEEDED:

/products/product → Item Table
/products/product → Product Extension Table

Same path, multiple tables - requires Parent Sequence.

A: Yes! You can have as many RecordNodes as needed sharing the same path. Each one can map to a different table, and you control which children belong to which parent using Parent Sequence.

A: They continue to work unchanged. Parent Sequence is optional - if you leave it at 0, the API Engine processes mappings the same way as before. This is fully backward compatible.

A: Yes! You can have some mappings with Parent Sequence and some without in the same API Function. The API Engine handles both styles seamlessly.

A: The child RecordNode will be filtered out and won't process. You'll notice missing records in your destination table. Check your Parent Sequence values and ensure they point to the correct parent mapping.

Parent Sequence is a field on API Mapping records. See API Mapping for general mapping concepts.

Parent Sequence applies specifically to RecordNode type mappings. See [API Mapping Source Types] for understanding RecordNode vs. Element vs. TableNode.

The data buffer stores parsed API responses. Multi-table mapping still uses the same data buffer - it just processes it multiple times for different tables. See API Data Buffer.

Introduced: Version 1.17.0.0 (September 2025)

Breaking Changes: None - fully backward compatible

New Fields:

• API Mapping table: "Parent Sequence" field (Field 61)

Modified Properties:

• API Mapping table: "Sequence" field now has NotBlank = true

• How to Configure Multi-Table Mappings (Coming Soon)
• How to Migrate Existing Mappings to Use Parent Sequence (Coming Soon)
• How to Troubleshoot Multi-Table Mapping Issues (Coming Soon)

• Multi-Table RecordNode Mapping - Technical Documentation - Complete architectural details, code flow, and developer guidance

• API Mappings - Understanding mapping fundamentals
• API Response Processing - How responses are processed

Want to try Multi-Table Mapping? Here's a simple example:

Scenario: Map product API to Item table AND custom Product Notes table

Step 1: Configure First RecordNode (Item Table)

Sequence: 100
Source ID: /products/product
Source Type: RecordNode
Table No.: 27
Parent Sequence: 10

Step 2: Configure Second RecordNode (Notes Table)

Sequence: 200
Source ID: /products/product    ← Same path as Seq 100!
Source Type: RecordNode
Table No.: 50100
Parent Sequence: 10             ← Same parent as Seq 100

Step 3: Add Element Mappings

For Item Table:
  Seq 110: /products/product/sku, Element, Table 27, Field 1

For Notes Table:
  Seq 210: /products/product/notes, Element, Table 50100, Field 10

Step 4: Test

• Execute your API Function
• Check: Do you have records in both tables?
• Verify: Are the fields populated correctly?

• Technical Issues: See Troubleshooting Guide
• Configuration Help: See Configuration Guide
• Migration: See Migration Guide

For additional assistance:

• Contact Suite Engine Support: [email protected]
• Reference Work Item: #125246
• Documentation Version: 1.0 (December 2024)