# SmartConnector Load Steps

{% hint style="success" %}
**Audience**: Administrators. Developers, Integrators, and Solution Architects

**Purpose**: Explains how load steps turn execution variables into <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entities</code>, covering matching rules, mapping rules, conflict resolution, and post-load actions
{% endhint %}

## Overview

Load steps are where execution variables become <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entities</code>. Each load step defines how incoming rows are matched against existing <code class="expression">space.vars.entities</code>, how variable values are written to fields, and what happens once the load completes.&#x20;

### What is a Load Step?

A load step defines how execution variables are written into a <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code>. It is the stage in the <code class="expression">space.vars.smartconnector</code> <code class="expression">space.vars.workflow</code> where resolved, typed values are turned into created or updated <code class="expression">space.vars.entities</code>.

A single <code class="expression">space.vars.smartconnector</code> can have multiple load steps, and they always execute sequentially in the order they are defined. Ordering matters whenever one <code class="expression">space.vars.object</code> depends on another: parent <code class="expression">space.vars.entities</code> must be created before child <code class="expression">space.vars.entities</code> that reference them. For example, a <code class="expression">space.vars.smartconnector</code> that loads vendors and products should run the vendor load step first so that products have a resolvable reference to load against.

Each load step targets exactly one <code class="expression">space.vars.object</code> as its primary destination. A <code class="expression">space.vars.smartconnector</code> that needs to populate three <code class="expression">space.vars.objects</code> needs three load steps.

***

## Matching Rules

Matching rules determine whether an incoming row corresponds to a <code class="expression">space.vars.entity</code> that already exists in the destination <code class="expression">space.vars.object</code>. They are the first thing evaluated in a load step: before any values are written, the load step asks "is there already a <code class="expression">space.vars.entity</code> that matches this row?"

Each rule pairs a destination field with an execution variable, configured through the **Field for Matching** and **Variable to Match** dropdowns. Multiple rules can be added with **+ ADD FIELD MATCH RULE** and are evaluated cumulatively in the order they are listed. The variable type must match the destination field type; if an execution variable you expected to see is not appearing in the dropdown, the most common cause is a type mismatch. Check the variable's declared type and adjust it to match the field before troubleshooting anything else.

#### **Upload Functions**

Each field match rule includes four dropdowns under the **Upload Functions** section, one for each match outcome:

**If No Match Found**

* **Create New Record:** Create a new <code class="expression">space.vars.entity</code> using the incoming row's values
* **Go to Next Field Matching Rule & Ignore Matches:** Move to the next field match rule
* **Do Not Upload Row:** Skip the row entirely; no <code class="expression">space.vars.entity</code> is created or updated

**If Single Match Found**

* **Update Existing Record:** Update the matched <code class="expression">space.vars.entity</code> with the incoming values
* **Go to Next Field Matching Rule (Constrained):** Apply the next field match rule as an additional filter on the current candidate
* **Go to Next Field Matching Rule & Ignore Matches:** Discard the current match and apply the next field match rule independently to find a different candidate
* **Do Not Upload Row:** Skip the row entirely

**If Multiple Matches Found**

* **Do Not Upload Row:** Skip the row entirely; no <code class="expression">space.vars.entity</code> is created or updated
* **Go to Next Field Matching Rule (Constrained):** Apply the next field match rule as an additional filter on the current candidate set, narrowing it down toward a single <code class="expression">space.vars.entity</code>
* **Go to Next Field Matching Rule & Ignore Matches:** Discard the current candidates and apply the next field match rule independently to find a different set

If a field has enforced uniqueness in <code class="expression">space.vars.Kizen\_company\_name</code>, a multiple-match scenario cannot occur in practice, but the dropdown still requires a configured value. Configure it as a safeguard.

**If Archived Match Found**

This dropdown handles the case where the only match is an archived <code class="expression">space.vars.entity</code>.

* **Unarchive Record & Update:** Unarchive the <code class="expression">space.vars.entity</code> and update it with the incoming values
* **Unarchive Record Only:** Unarchive the <code class="expression">space.vars.entity</code> without updating its values
* **Create New Record:** Push the archived <code class="expression">space.vars.entity</code> aside (a timestamp is appended to its unique identifier) and create a new <code class="expression">space.vars.entity</code> in its place
* **Go to Next Field Matching Rule (Constrained):** Apply the next field match rule as an additional filter on the current candidate
* **Go to Next Field Matching Rule & Ignore Matches:** Discard the archived match and apply the next field match rule independently
* **Do Not Upload Row:** Skip the row entirely

***

## Mapping Rules

Mapping rules define which execution variables are written to which fields on the matched or newly created <code class="expression">space.vars.entity</code>. Where matching rules decide which <code class="expression">space.vars.entity</code> to act on, mapping rules decide what values it ends up with.

As with matching rules, the variable type must be compatible with the destination field type. Type compatibility is validated at configuration time. If an execution variable is missing from the dropdown for a given field, verify the variable's type first.

<code class="expression">space.vars.entities</code> cannot be created in <code class="expression">space.vars.Kizen\_company\_name</code> without a unique identifier, so the unique identifier field must always be included in the mapping. This is enforced at configuration; a load step that does not map the unique identifier will not save.

#### Conflict Resolution

Each mapped field has a conflict resolution setting that controls what happens when the destination field already has a value:

* **Overwrite (Clear field if blank):** Always write the incoming value. If the incoming value is blank, the field is cleared.
* **Overwrite (But Skip if Blank):** Write the incoming value when present. If the incoming value is blank, leave the existing value untouched.

  **Only Update Blank:** Write the incoming value only if the field on the existing <code class="expression">space.vars.entity</code> is blank. Existing values are never overwritten.

For multi-value fields (such as dynamic tags and multi-relationship fields), one additional option is available:

* **Only Add Options:** Add any new values from the incoming data to the field without removing existing values.

Overwrite mode can be applied to the unique identifier field itself to rename <code class="expression">space.vars.entities</code>. This is rare, and for good reason: unique identifiers that change over time break downstream integrations, saved filters, and API references.

{% hint style="warning" %}
**Caution:** Avoid designing <code class="expression">space.vars.objects</code> where the unique identifier is expected to change. Renaming via overwrite should be reserved for one-off corrections, not used as a routine data flow.
{% endhint %}

#### Relationship Fields

Relationship fields accept either of two input formats:

* **Record UUID:** If you pass a UUID, it's interpreted directly as the ID of the related <code class="expression">space.vars.entity</code>.
* **Unique identifier text:** If you pass text, the system looks up a <code class="expression">space.vars.entity</code> whose unique identifier field matches the value exactly. The match must be exact (case-sensitive, no partial matches).

In both cases, the input must resolve to an existing <code class="expression">space.vars.entity</code> in the referenced <code class="expression">space.vars.object</code>, or the row will fail to process.

**SmartConnectors do not create missing related Records:** If a relationship field references an entity that does not exist in <code class="expression">space.vars.Kizen\_company\_name</code>, the field is skipped and logged as a warning and the rest of the row still processes, but the relationship is not set. This is an intentional difference from the CSV uploader, which creates missing related <code class="expression">space.vars.entities</code> automatically. To populate both sides of a relationship in a single run, add a load step for the referenced <code class="expression">space.vars.object</code> earlier in the sequence.

***

## Post-Load Actions

Post-load actions run after a <code class="expression">space.vars.entity</code> has been created or updated by the load step. They cover <code class="expression">space.vars.automation</code> behavior and cross-step variable passing.

#### Trigger Automations

A load step can specify <code class="expression">space.vars.automations</code> to fire when it creates a <code class="expression">space.vars.entity</code>, and separately when it updates a <code class="expression">space.vars.entity</code>. These are configured directly on the load step: one list for create, another for update.

**Automations fire automatically on SC-created or updated Records by default:** By default, <code class="expression">space.vars.automations</code> fire on <code class="expression">space.vars.entities</code> created or updated by a <code class="expression">space.vars.smartconnector</code>, just as they would for any other <code class="expression">space.vars.entity</code> operation in <code class="expression">space.vars.Kizen\_company\_name</code>. If you do not want <code class="expression">space.vars.automations</code> to run for <code class="expression">space.vars.entities</code> written by a particular load step, you can suppress them in the load step's post-load configuration.

When you select <code class="expression">space.vars.automations</code> to run on created or updated <code class="expression">space.vars.entities</code> in the load step, the <code class="expression">space.vars.smartconnector</code> triggers them directly using the **Manual** trigger type. These run *in addition to* any normal triggers (such as field-updated or <code class="expression">space.vars.entity</code>-created triggers) that would otherwise fire — unless you choose to suppress those normal triggers.

This gives you two independent layers of control:

* **Manual triggers:** <code class="expression">space.vars.automations</code> explicitly selected in the load step configuration, fired directly by the <code class="expression">space.vars.smartconnector</code> on the <code class="expression">space.vars.entities</code> it writes.
* **Normal triggers:** Standard <code class="expression">space.vars.automations</code> (field-updated, <code class="expression">space.vars.entity</code>-created, etc.) that fire on the underlying <code class="expression">space.vars.entity</code> changes, which you can optionally suppress

#### Suppress Triggers

The **suppress triggers** option disables *all* triggers system-wide for <code class="expression">space.vars.entities</code> processed by this load step; not just field-update and create <code class="expression">space.vars.automations</code>, but every trigger type that would otherwise fire on those <code class="expression">space.vars.entities</code> (including future trigger types added to the platform). This is useful when the load step is configured with a specific set of explicit <code class="expression">space.vars.automations</code> and you want to guarantee that nothing else fires as a side effect. For example, during a bulk backfill where existing <code class="expression">space.vars.automations</code> would create unwanted downstream activity.

#### Create Execution Variables from Matched or Created Entities

The <code class="expression">space.vars.entity</code> resolved or created by a load step can be captured as an execution variable for use in subsequent load steps. This is the primary mechanism for passing context across load steps in a multi-<code class="expression">space.vars.object</code> <code class="expression">space.vars.workflow</code>.

A typical pattern: you process the same dataset through two load steps with different matching schemes. The first load step matches <code class="expression">space.vars.entities</code> by email and populates fields A and B, capturing the matched <code class="expression">space.vars.entity</code> IDs as a variable. The second load step then uses those captured IDs to match the same <code class="expression">space.vars.entities</code> — but configured with a "Do Nothing" action — so rows already handled in the first pass are skipped, while remaining rows are matched by phone and have fields C and D populated.

This is what makes sequential ordering meaningful; without cross-step variables, each load step would be an isolated operation with no way to coordinate which rows have already been processed.

***

## What's Next?

<code class="expression">space.vars.smartconnector</code> Diff Checking **(Topic Coming Soon)** covers how <code class="expression">space.vars.smartconnectors</code> compare incoming rows against the previous run's output to skip unchanged data. Understanding its built-in behavior and its limitations is essential for anyone running recurring imports that depend on predictable update behavior.

<details>

<summary>Related Topics</summary>

* Smart Connector SQL Processing **(Topic Coming Soon)**
* Smart Connector External Data Sources  **(Topic Coming Soon)**
* Smart ConnectorExecution Variables **(Topic Coming Soon)**

</details>


---

# Agent Instructions: 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:

```
GET https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-load-steps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.