For a high-level overview and demonstration, refer to our Video Overview of setting up Field Mappings.
You will set up Field Mappings for each Object type included in your integration. You can add Field Mappings by selecting the “ADD FIELD” option from within the Object Mapping overview.
In most cases, you will include two Fields in each mapping - one from each End System. Each Field included on the list will be synced to contain the same value, based on the System of Record.
- Field Mapping Label: you can include any text you want in the label field. That text will be used to identify this Field Mapping when viewing the related Object Mapping.
- Field Name (Label): Once you select the Connector and Object type, you will be given a list of all available Fields to select from. The Field Name Label is the searchable value and typically corresponds to the display name of the Field in the End System.
- Field Name (Internal Value): In some End Systems, each field can be referenced by both a Label (external field name the front-end user sees) and an internal value (API name of the field). The internal value is displayed in grey below the label for reference and can be helpful when determining exactly which field has been selected in the case there are multiple similarly named fields in one of your End Systems.
- Read Only: The “read only” property will always default to “No” except when a field is already read-only in your End System. In those cases, “read only” will be permanently set to “Yes” within that Field Mapping. For additional information on read only settings and use case, please reference our When to use the Read Only Drop Down While Mapping a Field support article.
- Default Value: You can include a default value to be used for any field when a Record is first created. For additional information, please refer to the “Default Values” sub-section below.
- Most Recently Updated: Enabling this option for a particular Field Mapping will override the System of Record setting for that Field; instead Sync will give priority to the value that exists on the Most Recently Updated record. For additional information on Most Recently Updated settings, please refer to our [What Does Most Recently Updated Mean article]article: https://support.bedrockdata.com/hc/en-us/articles/360043504552-What-Does-Most-Recently-Updated-Mean-
BEST PRACTICE! We recommended that your Field Mapping Label (1) name is something that reflects the Fields included in the mapping.
For more information on creating and deleting Field Mappings, setting the System of Record, and other Field Mapping considerations, please see our Setting up and Managing Your Mappings support article.
You can use the “Auto-Generate Mappings!” button to automatically populate your mapping groups with all Fields that have the same Field Name in both of your End Systems. For more information on this feature, please see our article: Auto-Generate Your Mappings.
BEST PRACTICE! Just because Sync detects the same Field Name between End Systems does not mean the Field Types will match - be sure to review all auto-matched Fields, confirm the System of Record for each field, and delete any that are not applicable to your integration.
Mappings with Multiple Object Types
In some configurations, one or more of your End Systems will have multiple Record types that represent the lifecycle or stage of a particular Object. For example, in some End Systems the “lead” and “contact” Record types both represent an individual, but at different stages in the sales process. If you use multiple Record types, you will map the Field twice for that End System in each Field Mapping - once for each Record type (e.g. “lead” vs. “contact” or “prospect” vs. “customer”, etc.).
For more information about this configuration - especially how it relates to the System of Record - please see our article: How Does the System of Record Work?
Similar to Field Mappings, Relationship Mappings identify the Record associations you would like preserved in your End Systems. For example, if “Jane Smith” is the Owner of company record “ABC Industries” in one End System and you would prefer that she automatically be assigned as the Owner of the corresponding record in your other system, this can be achieved by adding a Relationship Mapping.
How is this different from using Field Mappings? When setting up your Field Mappings, you will likely see Fields that identify an associated Record such as the “Owner” of a “Company” as an option on the list of Fields you can map for each Object. However, if a “User ID” Field in End System A was mapped to the “User ID” Field in End System B, this would typically result in an error. This is because User IDs are almost always unique identifiers generated separately within each system. For example, Jane Smith’s user ID in End System A might be a serialized number such as “485798475” and an alphanumeric string such as “23jkh377s0-001” in End System B. Since these two values would not match, Sync would receive an error when trying to assign a Record across Systems.
To address this, Relationship Mappings take the extra step of normalizing related Record information between Systems - we know that “485798475” and “23jkh377s0-001” both represent the same person (Jane Smith) between End Systems, so when End System A sends a User ID of “485798475”, the Relationship Mapping translates this value to “23jkh377s0-001” before sending it to End System B.
This concept can generalize to all types of Relationships between multiple Object types: Contacts, Companies, Opportunities, and Users/Owners. For additional information about Relationship Mappings, please see our support article: Understanding Relationship Mappings.
Mapping Data from Related Records
When selecting the object of origin for a mapping, you may see some extra options in addition to the Object type for which the mapping is being created. These options correspond to Objects that have been related to the current Object in the Relationship Mappings tab and within your End Systems.
You may reference a value from a related Object when a Record is first created by selecting that Relationship as your selected Object. However, this Record Relationship does not allow this mapping to update the related Object; existing values can only be pulled one-directionally. For additional information, please refer to our support article “What Does Contact > Company” Mean?
There are some Fields that are always required by Sync, which are used as keys in the DeDuplication process that matches corresponding Records between End Systems. These DeDupe keys are always required in order for a Record to sync. Specifically, email addresses are always required for Contact Records and the company name is always required for Company records. For more information about DeDupe keys, please see our support article: How Does Formstack Sync Deduplicate & Index Records For All Objects?
In addition to Fields required by Sync, each of your End Systems might also have required Fields. We make these easy to identify by providing a warning message on the mapping overview page if there are any Fields that are marked as “required” in either End System that have not already been mapped. The warning message Sync provided will list each field that is currently required and not mapped.
For more information about managing requirements from your Sync portal or End Systems, see our support article: Managing Required Fields in Your Mappings.
TL;DR: When creating a new Record, Sync adheres to the Field requirements configured within Sync, as well as any required Fields for either End System. For example, if one of your End Systems requires a “First Name”, “Last Name”, and “Phone Number” in order to save a new Contact, Sync will also only be able to create this Contact if sending data to those Fields.
BEST PRACTICE! If there is a Field that is required in one End System, make the corresponding Field required in your other End System! Also, review any character or data requirements to ensure that any value input in one End System will be accepted by the other. Alternatively, you can use a default value to satisfy these Field requirements.
You can include a default value to be used for any Field when a Record is first created. This feature can be used to assist in satisfying Field requirements in the End System where new Records are being created. Note that this value will only be input if there is no value in the corresponding Field in the originating End System, or if there is no corresponding Field mapped. The default value can be overwritten by the user in the End System after the Record is created - the default value is applied only when the Record is created, but will not overwrite any updates made to the Field. For more information about default values, please see our support article: Set a Default Value For a Given Field.
Syncing Owner Relationships
Using Relationship Mappings to keep Record Owners in sync will only work if you’re using the native Owner Relationship in both of your End Systems. If you are using a non-native Field to assign ownership to a certain user or team, then the ownership association will need to be tracked and mapped differently. For additional information, please see our article: How to Keep Record Owners in Sync.
Alternatively, if you believe you are using the native Owner Relationship in each of your End Systems but ownership of your Records is not syncing correctly, check to ensure that the user’s primary email address used for their account is exactly the same in both End Systems - this is the DeDupe key for the Owner object.
Mismatched Field Types
Field Type is a very important consideration when mapping Fields between two End Systems. In almost all cases, Fields mapped together will need to be the same Field Type - text to text, number to number, date to date, etc. There are specific exceptions to this guideline that can allow for a one-directional synchronization of data; however, these should be avoided in favor of matching your Field Types between End Systems whenever possible.
For more in-depth information on this topic, please see our support article: Mapping Different Field Types.
Select Field Alignment
When mapping two Select Fields between End Systems, it is absolutely required for both option lists to match exactly - character for character. This includes spaces, capitalization, and special characters. If there is a missing character between the options in both End Systems, Sync will receive an error when attempting to create the Record.
It is extremely important to visually confirm that all Select lists match exactly prior to testing or turning on the integration. If these Field options change in any way after the integration is turned on, it is essential that you refresh field information within your Sync portal and update the corresponding Field Mapping as well.
BEST PRACTICE! If it is not important for users in both End Systems to be able to modify the data in a Select Field, consider creating a Text Field in the End System that is receiving the data. Users will be able to reference the data in the read-only Text Field without interacting with it and this will remove the need to continuously ensure those Field changes are kept in alignment between End Systems.
Field Label vs. Internal Value/Label
Sometimes there is a discrepancy between the label or value that a front-end user in your End Systems sees and the value that is actually being sent from that system’s API. Let’s explore the different places you might see this:
Field Label vs. API Name
The term “Field Name” generally describes either the Field Label or the API Name. The Field Label is the text seen by the front-end user that identifies the field when viewing a record within your End Systems(i.e. “First Name”). The API Name is the name used to identify a field in the API schema, typically excluding capitalization or spaces (i.e. “first_name”); you might see this name appear in an error message on the Dashboard.
Usually these names are very similar to each other but occasionally the Field Label might differ substantially from the API Name (e.g. “Notes” vs. “description_text”). If you see a reference to an API Name that you do not recognize, be sure to check the API Name (or “Internal Field Name”, sometimes) to confirm which Field is being referenced.
For additional information, please reference our support article: What is an API Name for a Field?
Field Option Label vs. Field Option Value
Select Fields contain a list of options that are available for a user to choose. In most End Systems, these options contain both a Field Value and a Field Label (not to be confused with the Field Label of the field itself).
The Field Label is the value the front-end user sees when selecting an option for the field within the End System. The Field Value (or “Internal Value”) is typically a hidden value for this selection assigned by the End System. Depending on the End System, this Field Value may or may not be editable by the System Administrator.
For additional information, please reference our support article: What is a Field Value versus a Field Label?
BEST PRACTICE! In addition to aligning all of the Select Fields in your mappings during the initial setup phase of your integration, be sure to alert all of your System Administrators that any future updates to the Field Labels in mapped Select Fields will need to be performed on the corresponding Field in your other System as well.
3.2 TL;DR Check List
Before moving on to the next step, complete the following tasks:
- Add Field Mappings to each Object Mapping Group
- Confirm all required Fields have been included
- Confirm Field Types match
- Confirm any Select Fields mapped together have option lists that match labels exactly
- Confirm the System of Record settings for each Field Mapping
- Add any default values, if applicable (uncommon)
- Add Relationship Mappings for each Object Mapping Group, if applicable
Once your Field Mappings are set up and prior to attempting to perform any testing, the Initial Index must be completed.
To view the next article in the Sync Set Up Guide, click here: Step 3.3 Initial Index