SmartConnector Load Steps
Audience: Administrators. Developers, Integrators, and Solution Architects
Purpose: Explains how load steps turn execution variables into Kizen Records, covering matching rules, mapping rules, conflict resolution, and post-load actions
Overview
Load steps are where execution variables become Kizen Records. Each load step defines how incoming rows are matched against existing Records, how variable values are written to fields, and what happens once the load completes.
What is a Load Step?
A load step defines how execution variables are written into a Kizen Object. It is the stage in the SmartConnector Workflow where resolved, typed values are turned into created or updated Records.
A single SmartConnector can have multiple load steps, and they always execute sequentially in the order they are defined. Ordering matters whenever one Object depends on another: parent Records must be created before child Records that reference them. For example, a SmartConnector 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 Object as its primary destination. A SmartConnector that needs to populate three Objects needs three load steps.
Matching Rules
Matching rules determine whether an incoming row corresponds to a Record that already exists in the destination Object. They are the first thing evaluated in a load step: before any values are written, the load step asks "is there already a Record 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 Record 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 Record is created or updated
If Single Match Found
Update Existing Record: Update the matched Record 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 Record 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 Record
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 Kizen, 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 Record.
Unarchive Record & Update: Unarchive the Record and update it with the incoming values
Unarchive Record Only: Unarchive the Record without updating its values
Create New Record: Push the archived Record aside (a timestamp is appended to its unique identifier) and create a new Record 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 Record. Where matching rules decide which Record 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.
Records cannot be created in Kizen 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 Record 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 Records. This is rare, and for good reason: unique identifiers that change over time break downstream integrations, saved filters, and API references.
Caution: Avoid designing Objects 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.
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 Record.
Unique identifier text: If you pass text, the system looks up a Record 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 Record in the referenced Object, 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 Kizen, 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 Records automatically. To populate both sides of a relationship in a single run, add a load step for the referenced Object earlier in the sequence.
Post-Load Actions
Post-load actions run after a Record has been created or updated by the load step. They cover Agentic Workflow behavior and cross-step variable passing.
Trigger Automations
A load step can specify Agentic Workflows to fire when it creates a Record, and separately when it updates a Record. 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, Agentic Workflows fire on Records created or updated by a SmartConnector, just as they would for any other Record operation in Kizen. If you do not want Agentic Workflows to run for Records written by a particular load step, you can suppress them in the load step's post-load configuration.
When you select Agentic Workflows to run on created or updated Records in the load step, the SmartConnector triggers them directly using the Manual trigger type. These run in addition to any normal triggers (such as field-updated or Record-created triggers) that would otherwise fire — unless you choose to suppress those normal triggers.
This gives you two independent layers of control:
Manual triggers: Agentic Workflows explicitly selected in the load step configuration, fired directly by the SmartConnector on the Records it writes.
Normal triggers: Standard Agentic Workflows (field-updated, Record-created, etc.) that fire on the underlying Record changes, which you can optionally suppress
Suppress Triggers
The suppress triggers option disables all triggers system-wide for Records processed by this load step; not just field-update and create Agentic Workflows, but every trigger type that would otherwise fire on those Records (including future trigger types added to the platform). This is useful when the load step is configured with a specific set of explicit Agentic Workflows and you want to guarantee that nothing else fires as a side effect. For example, during a bulk backfill where existing Agentic Workflows would create unwanted downstream activity.
Create Execution Variables from Matched or Created Entities
The Record 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-Object Workflow.
A typical pattern: you process the same dataset through two load steps with different matching schemes. The first load step matches Records by email and populates fields A and B, capturing the matched Record IDs as a variable. The second load step then uses those captured IDs to match the same Records — 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?
SmartConnector Diff Checking covers how SmartConnectors 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.
Last updated
Was this helpful?