This article provides a detailed guide on defining and managing external IDs, which are essential for linking data records.
An external ID is a way to deterministically identify a given piece of data within an external system. iPaaS.com will use this ID to link iPaaS.com data to data in both your external system and other external systems connected via iPaaS.com.
Wherever possible, ensure IDs are visible in the UI to support error troubleshooting.
Note that mapping directly to an external ID field is not supported on TO iPaaS.com mappings (from iPaaS.com may be supported, depending on the integration and support for this from that API). For example, if the ID field of a customer is CustomerId, any value you write to that field in a mapping will be overwritten with the iPaaS.com-identified value for that field.
When defining an external ID for a child object, a concatenated format of <parentId>|<childId> is preferred. This allows you to identify the parent record along with the child when the child is updated. In many systems, you will not be able to directly pull the child (e.g., you may have an endpoint for customers that includes their shipping addresses, but not an endpoint to access the shipping address directly). In this case, a concatenated external ID is crucial.
If the ids in your external system might include a
|natively, then use a different separator.There may be cases where the child id is not universally unique, only unique within the parent. For example, an inventory record might not have an id for itself, but has a location ID that will be unique within the parent product. In this case, the concatenated format will be ideal:
<parentId>|<locationId>.
In most cases, the external id will be clear. A customer, an order, or a product should all have a unique, consistent ID field to use. There are some cases where this is not possible.
ParentOnly mappings will not have an ID to use because there is no underlying data. If the data type only has a single ParentOnly mapping, then the ID can simply be the parent’s ID. However, if there are multiple ParentOnly mappings, you may need to append an additional suffix to indicate which mapping was used. For example, a customer record might have a single billing address object, which would be mapped to a customer address via a ParentOnly mapping. A customer record might also have a single shipping address object, mapped via a ParentOnly mapping. In this case, you might name your billing ID
<parentId>|BILL, and your shipping<parendId>|SHIP. This will not be possible in cases where there are multiple ParentOnly mappings and it will not be clear from the parent which child is being mapped. In this case, we provide a fallback option: themappingCollectionId. This will give you an id that is unique per-ParentOnly mapping, which is supplied in theTranslationUtilities.GetPrimaryIdmethod. Using this feature requires that all relevant mapping support both add and update, as the ID of the mapping collection would otherwise change between the add mapping and the update mapping.For non-ParentOnly data that does not have a clear external ID, the integration may need a way to identify if the data already exists in the external system. For example, if a customer has no ID field, then the integration may need to check the external system for an email match. If the external system does not need to differentiate between existing data and new data (for example, an e-mail marketing platform might accept email addresses and no other info), then an external ID will not be required. The
TranslationUtilities.GetPrimaryIdcall can return null.
Linking child data on calls FROM iPaaS.com requires some additional handling in your integration. For parent data, it will be clear what the internal iPaaS.com ID was, so linking the internal and external IDs via the ResponseObject payload will be easy. For child data, it will not be obvious which child entry in the response originated from which child entry in the iPaaS.com source data. For this reason, we provide a field to use that will be populated with the existing iPaaS.com data on the request object passed to ModelCreateAsync/ModelUpdateAsync. You must populate this field on the response payload so that we can link them together. Here are code examples of the two steps required to utilize this:
Add the field to your child model. You may tag this field as
JsonIgnoreso that it does not get sent to your destination system:
[JsonIgnore]
public string Spaceport_SourceId { get; set; }
Modify your response object to migrate the request value to the response field:
var customerResponse = await Customer_POST(customerRequest);
foreach(var addressRequest in customerRequest.Addresses)
{
var addressResponse = await CustomerAddress_POST(addressRequest);
addressResponse.Spaceport_SourceId = addressRequest.Spaceport_SourceId;
//Link the incoming data to the outgoing data
customerResponse.Addresses.Add(addressResponse);
//Add the address response to the customer response so that we can extract the child IDs
}
return customerResponse;
If the child data is saved in the same call as the parent, you will need to use something in the child data to link the request to the response. For example, product inventory records will have a location id that is passed in that should be in the response. Link your records with this ID and then migrate the Spaceport_SourceId value:
var productResponse = await Product_POST(productRequest);
foreach(var inventoryRequest in productRequest.Inventories)
{
var inventoryResponse = productResponse.Inventories.Find(x => x.LocationId == inventoryRequest.LocationId);
if(inventoryResponse != null)
inventoryResponse.Spaceport_SourceId = inventoryRequest.Spaceport_SourceId; //Link the incoming data to the outgoing data
}
return productResponse;
There may be times when the Spaceport_SourceId is not sufficient to link the incoming and outgoing IDs. In that case, we provide TranslationUtilites.CollectAdditionalExternalIds, which will be called with the full source and destination objects. Build your external ID translations in the TranslationExternalId object and return that.