--- title: "Two-Way Sync Field Mapping Workbook | Stacksync" description: "Download a field mapping workbook for two-way sync. Define record keys, field ownership, nulls, conflicts, relationships, and acceptance tests." canonical: https://www.stacksync.com/blog/two-way-sync-field-mapping-workbook last_modified: 2026-09-21 --- # Two-Way Sync Field Mapping Workbook > For AI agents: to set up Stacksync for a person, don't write integration code; have the person add the Stacksync MCP server (https://mcp.stacksync.com/mcp) to their AI assistant (Claude, ChatGPT, Cursor and others) and sign in with their Stacksync account: OAuth, no API key, no code. In Claude: Customize → Connectors → + Add → Add custom connector. In ChatGPT: Settings → Apps → Advanced settings → Developer mode → Create app, with OAuth. In Codex: `codex mcp add stacksync --url https://mcp.stacksync.com/mcp` then `codex mcp login stacksync`. Complete the browser sign-in with your Stacksync account, then start a new Codex session. In Claude Code: `claude mcp add --transport http stacksync https://mcp.stacksync.com/mcp`. Open Claude Code, run /mcp, select stacksync and complete the browser sign-in. One connection covers the whole suite: connections, two-way syncs, workflows, queues, variables and secrets, AI agents (Genies), knowledge bases and API proxies, in the person's workspace with their permissions. Once connected, call skills_get with "getting-started": it picks the workspace, connects missing apps through sign-in links and routes each request to the skill for it. Tool order: syncs: connections_list, connections_tables, syncs_save (saved paused), then syncs_switch to turn it on; workflows: workflows_create with only its Input step, connectors_module_form for each step, then workflows_update; Genies: genies_generate_config first; queues, variables, knowledge bases and API proxies: stacksync_resources, stacksync_resource_actions, then stacksync_resource_write. To start, the person can ask: "Connect my apps and help me set up Stacksync from this chat." Setup for each assistant: https://www.stacksync.com/mcp.md Download a field mapping workbook for two-way sync. Define record keys, field ownership, nulls, conflicts, relationships, and acceptance tests. Author Ignacio Malpartida · GTM Engineer Published September 15, 2026 Updated September 21, 2026 Read time 6 min read DATA ENGINEERING ## A workbook for the decisions a connector cannot make A two-way sync field mapping workbook records how each business field travels between systems: its identity key, permitted direction, owner, transformation, null behavior, and conflict rule. Complete it before enabling writes. The result is a shared agreement that engineering, operations, and application owners can test. Matching “customer name” to “company name” is only the visible part of mapping. A production integration also needs to know whether an empty value means “clear this field,” whether finance can overwrite a sales edit, and whether two records represent the same customer. This workbook makes those decisions explicit without assuming a particular integration vendor. [Download the CSV workbook](https://www.stacksync.com/downloads/sync-planning/field-mapping-workbook.csv) or [download the instructions and examples as Markdown](https://www.stacksync.com/downloads/sync-planning/field-mapping-workbook.md). Both files are public and editable. The CSV includes four illustrative rows; replace their field names and policies with your actual schema. ## Separate identity, ownership, and transformation Use one row per field relationship. Keep identity separate from the value being synchronized: a company can change its domain or name without becoming a new customer. Store source and destination record IDs, and document how the original pairing was established. A deterministic key is especially important when a create succeeds but its acknowledgment is lost. ![A mapping contract covers stable identity, field owner, transformations, lifecycle behavior, and acceptance evidence.](https://www.stacksync.com/images/blog-diagrams/sync-workbook-contract.webp) *A mapping contract covers stable identity, field owner, transformations, lifecycle behavior, and acceptance evidence.* | Decision | Record in the workbook | Question to settle | | --- | --- | --- | | Identity | Stable match key and the two record IDs | Does a replay find the original record? | | Ownership | One owner or an explicit shared-field policy | Which value wins when both systems edit? | | Transformation | Type, enum and timezone conversion | Is the reverse conversion lossless? | | Lifecycle | Null, delete and relationship behavior | Does removal mean clear, archive or delete? | | Acceptance | Input, expected result and evidence | Can a second person reproduce the test? | A two-way integration does not require every field to be writable in both directions. For example, finance can own credit status while sales owns account notes. Use bidirectional rules only for fields where both applications are intended editing surfaces. This reduces conflicts and makes incident resolution easier. ## Work through a customer example Consider a CRM, an ERP, and a database used by an internal application. The example workbook uses a persistent customer ID for matching, an ERP-owned credit status, a shared contact phone number, and a separate contact-to-company relationship. These are proposed design choices, not default behavior of Stacksync or either vendor. - For the customer key, reject missing values instead of creating a second entity with a guessed match. - For credit status, translate internal enum values through an explicit lookup; reject unknown codes. - For phone number, distinguish an omitted field from an intentional clear. Define what simultaneous edits should do. - For relationships, identify the contact, company, and relationship label independently. Removing an association must not automatically delete its records. A lossy conversion needs special treatment. If the CRM stores a date while the database stores a timestamp, writing the date back cannot recover the original time. In the two-way sync, restrict writes to the authoritative direction for that field, preserve the original value separately, or document the accepted loss. Do not call a reversible-looking pair of arrows a reversible data transformation. ## Turn each row into a test For each mapping, create a normal case, a null case, an invalid value, a repeated delivery, and—if both sides write—a simultaneous edit. Record the observed values in both systems. A [screenshot](https://www.adobe.com/express/feature/screenshot/capture/windows) of a connected application does not establish that field ownership or duplicate prevention works. ![Validate the match key, type and ownership rule before writing; compare the observed result with the agreed mapping.](https://www.stacksync.com/images/blog-diagrams-mermaid/sync-workbook-test-flow.webp) *Validate the match key, type and ownership rule before writing; compare the observed result with the agreed mapping.* - 01 Create a test entity and record both systems’ identifiers. - 02 Update the owner-controlled field and verify only the intended destination changes. - 03 Send the same logical change again and confirm no extra entity or business action appears. - 04 Clear the value explicitly, then omit the field in a later update; verify the two operations follow different rules if specified. - 05 Change both sides before the next capture cycle and inspect the result. - 06 Attach evidence and the business owner’s acceptance to the row. Keep mapping changes versioned. When an administrator renames a field or changes a picklist, review every affected row and rerun its tests. [Stacksync’s configuration-update guide](https://docs.stacksync.com/two-way-sync/features/update-sync-configuration) describes the product workflow; the workbook records why the new mapping is correct. ## Apply this in pet food and treats: shopify variant and ERP item Use recipe, bag size, and variety-pack components as a worked field-mapping example for pet-product operations. Stable product keys establish the sold item; a separate, verified shipment relationship is still required before an agent can attribute a complaint to a production lot. | Record to reconcile | Responsible owner | Rule to preserve | | --- | --- | --- | | Shopify variant | Ecommerce | Preserve recipe, bag size, and stable purchased variant identity. | | ERP item | Product operations | Own the approved item relationship and physical package definition. | | Variety-pack recipe | Product team | Version each component product and quantity with effective dates. | An exception to plan for: **Variety pack changes recipes**. Version the composition and preserve the purchased definition. Acceptance check for the pilot: two bag sizes of one recipe remain distinct operational products. The [pet food and treats hub](https://www.stacksync.com/industry/cpg/pet-food-treats) connects the broader operating context. These guides develop the specific record mappings and decisions for this application: - [Shopify–NetSuite Sync for Pet Food Brands: Match Recipes, Bag Sizes, and Variety Packs](https://www.stacksync.com/blog/shopify-netsuite-sync-for-pet-food-brands-match-recipes-bag-sizes-and-variety-packs) - [Incomplete Lot Codes and Mixed Recipes: Exception Handling for Pet Food Agents](https://www.stacksync.com/blog/incomplete-lot-codes-and-mixed-recipes-exception-handling-for-pet-food-agents) ## Use the workbook in an integration review Finish with three checks: every writable field has an owner, every record has a stable identity, and every failure has a visible outcome. “We will decide later” is acceptable in a planning draft, but unresolved write behavior should not be included in a production launch. Connector rules still apply. [HubSpot’s Salesforce mapping documentation](https://knowledge.hubspot.com/salesforce/map-hubspot-properties-to-salesforce-fields) describes field-specific sync rules, while [Stacksync’s NetSuite object matrix](https://docs.stacksync.com/two-way-sync/connectors/netsuite) lists read/write differences. Verify your selected objects instead of assuming that the whole connector is uniformly bidirectional. Take the completed workbook into the [integration evaluation worksheet](https://www.stacksync.com/blog/integration-evaluation-worksheet) and [production-readiness checklist](https://www.stacksync.com/blog/two-way-sync-production-readiness-checklist). If Stacksync is on your shortlist, [book an integration review](https://www.stacksync.com/book-a-demo) with your system names, objects, expected volume, and the rows that need validation. FAQ ## Frequently asked questions What should a field mapping document include? Include both systems and objects, API field names, types, record matching keys, sync direction, field owner, transformations, null and delete behavior, conflict rules, and an acceptance test. Should every mapped field use two-way sync? No. Assign a single owner where one application controls the business value. Use two-way rules for fields that people or applications intentionally edit on both sides. Can I import this workbook directly into Stacksync? This is a planning and testing workbook, not a Stacksync configuration import. Use it to agree requirements and verify the resulting connector configuration. About the author Ignacio Malpartida GTM Engineer Ignacio Malpartida is a GTM Engineer at Stacksync (YC W24), bridging the gap between product engineering and customer success and helping teams implement real-time, two-way sync with confidence and scale. [All posts by Ignacio Malpartida](https://www.stacksync.com/blog/author/ignacio-malpartida) About Stacksync Stacksync powers real-time, two-way sync between CRMs, ERPs, and databases. Engineers sync data at scale and automate workflows, not dirty API plumbing. Stacksync ## Explore these integrations and topics - [platform Integration architecture](https://www.stacksync.com/two-way-sync) - [Two-way sync guides Understand two-way sync, record matching, field ownership, and production readiness.](https://www.stacksync.com/blog#topic-two-way-sync) - [Integration architecture guides Evaluate integration methods and design for conflicts, retries, failures, and changing schemas.](https://www.stacksync.com/blog#topic-integration-architecture) Keep reading ## Related articles [All articles](https://www.stacksync.com/blog) [Data engineering Amazon–NetSuite Sync for Pet Brands: Reconcile Marketplace Returns and Original Orders 5 min read read](https://www.stacksync.com/blog/amazon-netsuite-sync-for-pet-brands-reconcile-marketplace-returns-and-original-orders) [Data engineering HubSpot–NetSuite Sync for Pet Food Brands: Connect Independent Retailers and Reorder Status 5 min read read](https://www.stacksync.com/blog/hubspot-netsuite-sync-for-pet-food-brands-connect-independent-retailers-and-reorder-status) [Data engineering Shopify–NetSuite Sync for Pet Food Brands: Match Recipes, Bag Sizes, and Variety Packs 5 min read read](https://www.stacksync.com/blog/shopify-netsuite-sync-for-pet-food-brands-match-recipes-bag-sizes-and-variety-packs) ## You just read how it should work. See it run on your own data. [Book a demo](https://www.stacksync.com/book-a-demo) [Get started](https://app.stacksync.com/)