SmartConnector Load Step Design Best Practices
Audience: Administrators, Developers, Integrators, Solution Architect
Purpose: Explains how to sequence and structure load steps so that parent-child relationships resolve correctly, each load step stays focused on a single object, and matching rules rely on stable identifiers that produce consistent, predictable results across runs.
Overview
Load steps are order-dependent and Object-specific. The sequence in which load steps run determines whether relationship fields can resolve correctly, and the identifiers used in matching rules determine whether the right Records are found consistently across runs. The practices on this page help ensure that load step configuration produces the results you expect from the first run onward.
Load Parent Objects Before Child Objects
Load steps run in sequential order. If a load step writes Records to an Object with a relationship field that references Records created by an earlier step, the parent Object must be loaded first. Relationship fields require the referenced Record to exist at the time the mapping rule runs.
Design your load step sequence so that any Record a later step depends on is always created by an earlier step. For more information on load step sequencing, see SmartConnector Load Steps.
One Object Per Load Step
Each load step targets a single Object. This is a platform constraint, not a configuration option.
When a load step completes, it automatically generates a list of Kizen IDs for the Records it matched or created. Name this variable on the final tab of the load step and reference it in a later load step's matching rules to act on those same Records. This is the entity variable pattern, and it is the recommended approach for passing Record references between steps in a multi-Object SmartConnector.
Because each load step corresponds to a single Object type, the run report is easier to interpret and individual steps are easier to debug in isolation. For more detail on the entity variable pattern, see SmartConnector Load Steps.
Use Stable Unique Identifiers
When configuring matching rules, use stable, built-in identifiers to find existing Records: name for Objects and email for clients and Contacts. Matching on fields whose values are likely to change over time risks failing to find the existing Record, which can result in duplicate Records or missed updates that are difficult to clean up after the fact.
Choose unique identifiers that are stable for the life of the Record. Avoid configurations where a business key that changes over time serves as the primary matching identifier.
For more information on how matching rules use unique identifiers, see SmartConnector Load Steps.
What's Next
The next topic is SmartConnector Running and Testing Design Best Practices, which covers the practices that reduce the risk of a live run producing Records you did not intend, even for a SmartConnector that has already passed configuration review.
Last updated
Was this helpful?