Customizing mappings in Pipe17

Overview

Managing order operations in Pipe17 requires configuring connections with external systems. Pipe17 provides multiple ways to control how data is sent and received, enabling users to customize mappings to align with their business needs.

Mappings define how Pipe17’s entity schema corresponds to external system schemas. For example, you can map the "name" field on Shopify orders to the "Order ID" field in Pipe17.

Example of mapping the "name" field on Shopify orders to the "Order ID" field in Pipe17

Mapping Architecture

Baseline Mappings

Baseline mappings serve as factory-defined templates maintained by Pipe17. These mappings are shared across all integrations and ensure consistent data flow between systems.

• Any modifications to baseline mappings affect all integrations of that connector. 
• Changes are versioned, allowing users to compare different mapping versions. 

Comparing the current baseline mapping version to v42.

Custom Mappings

Custom mappings allow users to override baseline mappings for specific needs. If a custom mapping modifies a field already mapped in the baseline, the custom version takes precedence.

Example:

• Baseline Mapping: Maps the "status" field from Shopify to Pipe17's status field.
• Custom Mapping Override: Maps "active" instead of "status" to Pipe17’s status field.

This customization ensures that all Shopify products are treated as "active" in Pipe17, regardless of their original status in Shopify.

When a baseline mapping is customized:

• The system creates a copy of the baseline mapping and applies the changes.
• Users can view only custom mappings in the "Custom only" view.

Note: Override mappings have the same target as the baseline mapping. If the target is different, then it is a new custom mapping.

Custom Mapping Use Cases

Mappings can be customized to:

• Modify the default behavior of a baseline mapping.
• Disable a baseline mapping if it’s unnecessary.
• Map additional fields that are not included in the baseline.

Advanced: How Schema Converter evaluates mappings

Mapping conversions are handled by the Pipe17 schema converter library. Entity mappings are processed following the steps below:

1. If there are custom mappings, merge with the baseline mappings. This is also the default state of the UI when you view all mappings. The merge process is as follows:
   1. Iterate through each custom mapping.
   2. If the target matches with a baseline mapping, override that mapping field.
   3. If there is no matching target, add the mapping rule to the bottom as a new custom mapping.
2. Pass the merged mapping rules along with the document to map to the schema converter. The schema converter will then evaluate all enabled rules from top-down. Schema converter supports special patterns as well, as described in Advanced Use Cases.

Customizing Mappings

Since mappings control data flow between external systems and Pipe17, changes should be made carefully. Follow these guidelines when developing, testing, and monitoring mapping changes.

Creating Mappings

1. Click "View documentation" to open the reference panel.
2. Check the external schema details to determine how the mapping should be structured.
3. Add a new mapping if the required field is not mapped by default.

Advanced Use Cases

Pipe17 mappings follow the schema converter format, which processes JavaScript-based transformations with special syntax rules.

Example: Using `[$0]`

line_items[$0].name → result.lineItems[$0].name

• line_items is an array.
• Each item in `line_items` maps its `name` field to the `result.lineItems` array.
• Important: The `[$0]`  syntax must be present in both the source and target for proper conversion.

Additional advanced options include:

• Lookup tables: Map source data based on predefined values.
• Fallback values: Define default and missing values if the source mapping logic evaluates to undefined or null. This is typically used to guarantee a value for required fields.

Example: Baseline mapping of Shopify order status to Pipe17 order status

In this example, the `active` field of a Shopify order is mapped to the `status` field of a Pipe17 order. 

1. The lookup table maps `true` to `active` and `false` to `inactive`. If the field is not `true` or `false`, then the lookup table will not find a match, which will update the value to `undefined`. 
2. We specify that if the value is undefined, we set it to `active`. 
3. In this way, even if the Shopify order's `active` field is an unexpected value, we guarantee that it will be mapped to a legitimate order status value in Pipe17.

Testing Mappings

Before saving changes, test mappings to ensure expected behavior:

1. Paste a source document on the left-hand side of the mapping tool.
2. If Pipe17 has already ingested entities, load an existing document.
3. Otherwise, retrieve a document from your external integration for testing.

Monitoring Mapping Changes

Once mappings are modified and saved, monitor their impact on data flows:

• Use the Events page to track how mappings affect incoming data.
• For Shopify order mappings, observe events related to Shopify order creation.
• To minimize disruptions, specify integration settings to pull only test orders into Pipe17.

Summary

Customizing mappings in Pipe17 allows precise control over data synchronization. By following best practices in development, testing, and monitoring, users can optimize their order operations while maintaining accuracy and consistency across systems.