Data Modeling

As much as possible, honor the collision handling preferences specified in the mapping collection. It provides a better user experience and, in most cases, is easier to implement, since much of the work of handling the collision is included in the platform.

Any field that has a uniqueness requirement in the external system is a candidate for collision handling. This might include things like product SKU, customer email address, location name, etc.

Collision handling requires detectable error messages from the external system. For example, if an email address is rejected as a duplicate, the error message needs to indicate this in a way that you can parse.

Collision handling also requires the ability to return the existing data from the external system. This means that your external system must either be searchable on the collision field, or the collision error must indicate the id of the existing data. For example, if you collide on an existing customer email address, you will need to return the existing customer’s id. So that id must be either included in the error message that was returned to you by the external system, or the external system must have the ability to search by email address so you can find the id yourself.

Your external API may allow you to search on the duplicate candidate prior to your create/update call. However, barring any special considerations, it is generally better to initiate your create/update call without checking and handle the collision response, rather than trying to anticipate any collisions by checking uniqueness first. This will cut down on the total number of API calls you make.

There may be times when you want to handle collisions internally without resorting to the collision handling system. For example, if you are integrating with an email marketing system, you might not need the data you send to be tied to an iPaaS.com customer record, only to the customer’s email address. In that case, you might detect an email collision and immediately retry the call as an update rather than a create. If you do implement handling like this, ensure it is well documented.

Be cognizant of case-sensitivity. Some systems might enforce SKU uniqueness in a case-sensitive way, while enforcing email uniqueness in a case-insensitive way.

Full support for collision handling includes linking child data when possible. See the collision handling documentation for more details on this.

Sometimes a single operation may require multiple API calls. For example, a call to ModelCreateAsync for a product might require calls to product, inventory, variant, and price endpoints. In this case, ensure that you properly handle partially successful transfers. Throwing an error from a secondary API call could result in unlinked data from the primary API call. Instead, you should catch errors on the secondary calls, create a new ExpectedException, and attach any successfully created data to it. The following shows how to catch an exception on an inventory call while returning the successful product portion:
​var productResponse = await Product.Create();
​try
{
var inventoryResponse = Product.Inventory.Create();
productResponse.Inventory = inventoryResponse;
}
​catch(Exception ex)
{
​ throw new ExpectedException(ex.Message) { SavedExternalData = productResponse };
}

If your integration uses GraphQL, be cognizant of newlines and other characters that must be escaped. Embedded newlines are not supported in GraphQL and must be escaped. Either use the GraphQL for .Net package, which will handle this for you, or ensure that you are correctly escaping your newlines.

Typically, a POST or PUT call will return the updated data, but this is not always the case. It may just return the id of the record that is created, or may return nothing on updates. Our translation service expects an object that it can call GetPrimaryId on and that it can navigate to gather primary ids for children as well. You may choose to make a GET call from the external system to retrieve the full created record, but this may not be necessary. If you can use the ids returned to build a suitable object, then just return that. If you do make a GET call, ensure that you update the Spaceport_SourceId for any child objects.

If a ModelGetAsync call does not find any data in the external system, this should generally NOT be treated as an error. This likely indicates that we received a hook for deleted or inaccessible data. For example, if a user in an external system creates a customer, realizes they made a mistake, and immediately deletes it, we will get a customer/created hook for a customer record that no longer exists. In that case, we do not want to throw an error and retry the call later; the record will never exist. There may be cases where you do want to throw exceptions for missing data, but in general, you should not.

For data that is not specific to creating a given record, ensure that the data does not exist before creating it. This is often seen when sending product options and product option values from iPaaS.com. Many systems store them as universal records shared by all products, rather than a child record of a specific product. In that case, always check that the product option and/or product option value does not already exist before creating it. On the iPaaS.com side, ensure that your external id includes a product-specific segment to avoid duplicate external ids on shared records.

The PollRequest method accepts a string filter. Provide support for this feature if your external system allows additional filters on polling calls. Document the requirements and support available for your filter so that users know how to structure the filter properly. You may also use the filter to pass parameters to the integration. For example, if your transaction polling event can poll both orders and invoices, you may want to let users add a flag, such as “invoiceOnly=true” to the filter to indicate to the integration that only the invoice polling should be completed.