Learn how SynchUP relates two records in two different systems with that system's unique identifiers using internalId and externalId
Internal IDs
When a new entity is created in a system, it is assigned a unique identifier. The method of generating these identifiers varies across systems. Some systems use incrementing numbers (e.g. 1, 2, 3), while others use GUIDs (e.g. b14da2c7-44f8-4d67-a621-2138e9c78b10). There are even systems that allow you to define alphanumeric patterns (e.g. 1234-abcd). Additionally, each system has its own name for these unique identifiers, such as id, customer number, or edp. Regardless of the type or name of the identifier used in your system, SynchUP ensures consistency by normalizing it to what we refer to as the internalId.
For instance, let's consider the following scenario. In your system, you have just created a brand new customer record. This customer, named "Marcus Gilbert," has provided the email address "marcus@synchup.com". The system that the record was created in has assigned it a unique identifier of "1234". When SynchUP retrieves this record from your system, the data will be presented as follows:
Now we understand that when an entity is created in a system, that system automatically assigns a unique identifier to it. In most systems, this unique identifier cannot be programmatically assigned and is read-only.
So, what does this mean in the context of your SynchUP Jobs? Let's consider a scenario where you have set up a SynchUP Customer Job to retrieve new Customer records from system A and then create those same records in system B. While SynchUP will retrieve all the data for the customer record from system A, it will only be able to create everything in system B except for the internalId. This internalId will be automatically generated by system B. That scenario might look like the following:
External IDs
Because most systems automatically generate their unique identifiers, it can be challenging to maintain relationships between related records in different systems. Matching on mutable data like email is risky and may lead to data loss. This is why SynchUP utilizes the concept of externalId to preserve data relationships between corresponding records in separate systems.
When SynchUP creates or updates records in the destination system, it captures the internalId from the origin system. Each SynchUP Data Pusher can be customized to map this relationship to any desired field. Typically, this information is stored in a configurable value such as an attribute or custom field.
At this stage, we have successfully captured the unique identifier from system A and recorded it on the record of system B. This valuable information not only allows you to easily identify the related records between the two systems, but it also greatly aids SynchUP in performing future updates for that specific record.
If you are utilizing SynchUP for bidirectional data synchronization, we can take this a step further. In the scenario of bidirectional data synchronization, you will have a second Job configured to retrieve data from system B and create or update that data in system A. In this case, that Job will subsequently execute a similar action and record the internalId of the record in system B as the externalId on the record in system A.
By utilizing SynchUP, the bi-directional data synchronization is now complete, and the two records in each system are related through internal and external Ids. Going forward, it will become effortless for you to identify the related records in each of your systems. Additionally, SynchUP will now have the advantage of easily recognizing the related records, eliminating the need for less accurate record matching techniques.
Mapping externalId with SynchUP
The storage of externalId can be easily configured by users in SynchUP. Each SynchUP Data Puller and Data Pusher provides a setting that allows users to specify the storage location for this value. SynchUP is designed to be highly flexible, accommodating the different capabilities and features of various systems, ensuring that it can be configured to meet your individual needs.
What have you learned?
After reading this article, you should have come away with the following information:
- Most systems automatically generate unique identifiers for individual records
- These unique identifiers are almost always read-only and may not be modified by third parties
- Each system has their own name for these unique identifiers
- SynchUP normalizes these values and refers to it as the internalId of a record
- When using SynchUP to sync data between two systems, a Job may be configured to record the internalId of the origin system as the externalId in the destination system
- Each Data Puller and Data Pusher on a Job for SynchUP will allow a user to define where externalId is stored in the respective system
- If these settings are defined, SynchUP may utilize these values in order to easily identified data that is related between the two systems, removing the need to perform record matching techniques
Further your education
It is important to note that there may be instances where SynchUP encounters data that does not have a matching relationship through internalId and externalId. This could be due to duplicate data, pre-existing data, or even mistakes. In such cases, SynchUP employs record matching techniques to address this situation. To learn more about how SynchUP performs record matching techniques, please refer to this resource: SynchUP Record Matching