Each channel (e.g. Shopify) available in the nChannel platform includes a set of supported actions (e.g. GET Product, PUT Order). One of the most important channel action settings to consider is where in the business document the business reference exists.

The business reference configuration tells nChannel what field in the document to use to identify the record. It'll use the value of that field to try to look up a remote ID to determine whether a PUT should update an existing record or create a new record. This mechanism is how nChannel avoids duplicating records and how it's able to update records that were not created in the system by sync through nChannel.

Every channel profile comes with the channel's default business reference already set. The majority of the time this will not need to change. That default is set by the person who developed the channel, based on what the "standard" behavior of the endpoint is. For example, if system A almost always uses a field called "Reference Number" to uniquely identify a sales order, that's what the default business reference will be set to.

The business reference settings are shown in the "Advanced" section of channel action settings (you may need to click to "Show" link to display them).

Each action on each channel profile will have a different set of fields. Which fields are available is determined by the channel (e.g. Shopify's PUT Product will have different fields than Bigcommerce's PUT Product). There will always be at least one field, marked as "Primary Document".

Primary and Secondary Documents

Every channel action makes mention of a primary document and some also make mention of secondary documents. The primary document is the business document represented by the action. For example, if you are configuring a PUT Sales Order, the primary document is the sales order.

However, some business documents carry other stuff with them. For example, when PUTing a sales order, it's very common that the business document also has a Customer record included in it. This is a secondary document, because it is a fully qualified business document, but it's not the thing you are PUTing.

The system may need to know where the business reference is for a secondary document. PUTing a Sales Order is another good example. Before the sales order is inserted, nChannel checks to see if the customer attached to that sales order exists. Then based on that, it either adds the sales order to the existing customer in the endpoint OR creates a new customer (according to your data flow settings). For nChannel to make that insert vs update determination on the secondary document (the customer), it will need its business reference too!

If an action has more than one secondary business reference, there is no order of importance. They all simply represent other documents that are built into the primary one.

Changing the Business Reference Configuration

Changing the business reference configuration is easy, but great care should be taken when doing so. Simply click "Edit" and enter a new JSONata expression that describes where in the business document the business reference value will be found. You'll probably want to look at the document's schema or an example document when doing so.

Because it's a JSONata expression, it is possible to concatenate two fields. Sometimes this is necessary when there isn't one single field that clearly uniquely identifies a record. Customer Addresses are a good example. They rarely have an identifier, so it's common to see their business reference be a concatenation between Street Address 1, Street Address 2, and Zip Code.

Use the JSONata Exerciser to be very clear about what your new business reference configuration will produce. It needs to output a single string of text that can be used as an identifier, not a block of JSON.

Remember the output of this JSONata expression is what will be correlated with the document's remote ID in that system. So, keep the following in mind:

  1. The business reference should value not change over time. If the same record passes through nChannel more than once (perhaps a create and then some updates), the JSONata expression for the business reference configuration should resolve to a consistent value. When the system sees a new value, it will consider it a new record and create instead of update in the endpoint.
  2. The business reference configuration has to resolve to a single value. If your configuration produces an object (a block of JSON), the system will fail to identify records correctly.
  3. Only change the business reference if you need to. Consider whether you actually need to change the business reference configuration or if the requirements are not optimal and should be adjusted. (It's more frequently the latter.)

One scenario where this is likely to be used is when the customer utilizes an endpoint where the web services can be heavily customized. Dynamics NAV is a good example. When the endpoint implements a customized web service to correlate with a given action, it may include a completely customer-proprietary document schema. In that case, you'll need to identify what the business reference location is in THAT document and change the default (which is based on an out of the box endpoint).

Note: There is a defect open whereby occasionally the field for the primary document will be repeated as a secondary document. It exists for some actions on some channels. If configuring one of these actions, just set both of the matching fields to the same JSONata value.