> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-load-step-design-best-practices.md).

# SmartConnector Load Step Design Best Practices

{% hint style="success" %}
**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.
{% endhint %}

## Overview

Load steps are order-dependent and <code class="expression">space.vars.object</code>-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 <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.entities</code> to an <code class="expression">space.vars.object</code> with a relationship field that references <code class="expression">space.vars.entities</code> created by an earlier step, the parent <code class="expression">space.vars.object</code> must be loaded first. Relationship fields require the referenced <code class="expression">space.vars.entity</code> to exist at the time the mapping rule runs.

Design your load step sequence so that any <code class="expression">space.vars.entity</code> a later step depends on is always created by an earlier step. For more information on load step sequencing, see [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md).

### One Object Per Load Step

Each load step targets a single <code class="expression">space.vars.object</code>. This is a platform constraint, not a configuration option.

When a load step completes, it automatically generates a list of <code class="expression">space.vars.Kizen\_company\_name</code> IDs for the <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.entities</code>. This is the entity variable pattern, and it is the recommended approach for passing <code class="expression">space.vars.entity</code> references between steps in a multi-<code class="expression">space.vars.object</code> <code class="expression">space.vars.smartconnector</code>.

Because each load step corresponds to a single <code class="expression">space.vars.object</code> 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](/docs/concepts/smartconnectors/smartconnector-load-steps.md).

### Use Stable Unique Identifiers

When configuring matching rules, use stable, built-in identifiers to find existing <code class="expression">space.vars.entities</code>: `name` for <code class="expression">space.vars.objects</code> and `email` for clients and <code class="expression">space.vars.contacts</code>. Matching on fields whose values are likely to change over time risks failing to find the existing <code class="expression">space.vars.entity</code>, which can result in duplicate <code class="expression">space.vars.entities</code> or missed updates that are difficult to clean up after the fact.

Choose unique identifiers that are stable for the life of the <code class="expression">space.vars.entity</code>. 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](/docs/concepts/smartconnectors/smartconnector-load-steps.md).

***

## What's Next

The next topic is [SmartConnector Running and Testing Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-running-and-testing-design-best-practices.md), which covers the practices that reduce the risk of a live run producing <code class="expression">space.vars.entities</code> you did not intend, even for a <code class="expression">space.vars.smartconnector</code> that has already passed configuration review.&#x20;

<details>

<summary>Related Topics</summary>

* [SmartConnector Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices.md)
* [SmartConnector SQL Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-sql-design-best-practices.md)
* [SmartConnector Execution Variable Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-execution-variable-design-best-practices.md)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-load-step-design-best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.