A trace key is the value assigned to a field, such as Internal Id, that uniquely identifies a record. Knowing the trace key allows you to reference one specific record within a flow.
The trace key is useful when examining and troubleshooting an integration:
- Error Management automatically resolves similar errors based on the trace key
- The record’s trace key is the key field that identifies a record when auditing flow event data
Searching by this value makes records easier to identify in integrator.io reports and error information.
The trace key contains metadata automatically determined by integrator․io as the field most likely to be unique for an endpoint and record. In most cases, you can accept the default trace key.
View a record’s trace key
You will encounter trace key values in either of the following locations:
- A downloaded flow event CSV file (generated at Tools > Reports) – in the first column, traceKey
- Error field details, as shown below
Caution: A trace key may not exceed 128 characters. If an ID is very long or if you’re building an exceptionally complex custom trace key, any value longer than 128 characters will be truncated. The incomplete value could potentially obscure the difference between records, in the unlikely occurrence that two or more trace keys are identical only up to the string length displayed.
Override the default trace key
Assigning a custom trace key offers you flexibility for meeting your business requirements and any later troubleshooting.
In certain cases, integrator.io will not be able to distinguish a unique value for a record, thus leaving the trace key blank. When that happens, you’re encouraged to override the default, as described in the following sections.
Note that the override settings are available only for custom, or “DIY,” flows and do not appear in Integration app flow steps.
Set a trace key in an export or listener
In a custom flow, you can specify an alternate field, fields, or concatenated value that you want to use as a trace key.
Since you’re specifying a custom trace key for the data’s source application in an export or webhook listener, the new trace key value is always referenced throughout the flow.
For example, a record might contain the following structure, and you’ve noticed that product_code is assigned as the trace key field:
{
"record": {
"product_name": "Pillow Case",
"product_code": 144,
"updated_at": "2021-04-15 10:08:29",
"created_in": "Store View B",
"category": 8,
"inventory": 40,
"color": "goldenrod",
"addresses": []
}
}
For troubleshooting purposes, you might want to make the trace key more specific or more human-readable than “144,” as follows:
- In Flow Builder, click the export to edit it.
- Expand the Advanced section.
- Enter a field, such as
{{record.product_name}}, or a handlebars expression, such as{{join "-" record.product_name record.product_code}}, in the Override trace key template setting.- Optionally, you can click the Open handlebars editor (
) button to test how the template will resolve with a sample record.
- Optionally, you can click the Open handlebars editor (
- Save and close the export.
- a transformation to exported data, reference its fields in the trace key template without the path
record...– for example, enter simply{{product_name}}. - a JavaScript hook to the exported data, reference its fields in the trace key template without the path. In the Script editor, the Function input shows the result data generated; and, you can set the traceKey path accordingly.
The same procedure applies to a listener. Continuing with this example, the trace key would be displayed – and searchable – as “144, Pillow Case: goldenrod” for the sample record, above, with the template shown below:
Set a trace key for imported one-to-many records
If an import contains a one-to-many lookup, meaning that you are syncing source child records that should each be used as the main record, you have an additional opportunity to provide a custom trace key template for the additional records.
Once again, integrator.io will attempt to assign a default trace key for each child record, but the override gives you more flexibility in tailoring the value for your requirements.
The child record trace key template value always includes the parent record trace key in the format,
<parent_record_trace_key> - <child_record_trace_key>
...where <parent_record_trace_key> is the default record trace key or the override you set, as explained earlier.
Then, when you create or edit a one-to-many import in Flow Builder or via Resources > Imports, your custom Override child record trace key template value will be shown for the <child_record_trace_key>.
Trace key overrides
Trace key overrides are based on the configurations you set in the export and import of your flow.
| Export setting | Import setting | Error occurs in the import step (Trace key for an error seen in the “Error fields” tab) |
|---|---|---|
Trace key template value is set by the user (for example, order_id) |
One-to-many configuration is not set | Error will have a trace key value that is computed in the export step (that is, order_id) |
Trace key template value is set by the user (for example, order_id) |
One-to-many configuration is set; but, the child trace key is not set |
If the system cannot set a default child trace key, then the error will have a trace key value that is computed in the export step (that is, If the system can set a default child trace key, then the error will have the trace key in the format, <order_id> - <child_record_trace_key>
|
Trace key value is set by the user (for example, order_id) |
One-to-many configuration is set; and, the child trace key is set to order_line_item[*]
|
Error will have a trace key value that is a combination of export and import configuration (that is, order_id - order_line_item[*]) |
| Trace key template value is not set by the user | One-to-many configuration is set; and, the child trace key is set to order_line_item
|
If the system cannot set a default trace key, then the error will have a trace key value that is computed in the import step (that is, If the system can set a default trace key, then the error will have the trace key in the format, <parent_record_trace_key> - <order_line_item>
|
Comments
It may be helpful - to add another TIP to this page. This is something we discovered while investigating -
TIP: If you have applied a JS Hook to exported data, reference its fields in the trace key template editor will show the Function Input - as the result data generated after the Hook is applied - and the traceKey path then should be set accordingly.
https://docs.celigo.com/hc/en-us/requests/177340
Thanks, Bhushan! We've included the tip.
Please sign in to leave a comment.