> 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/run-smartconnector-load-step.md).

# Run SmartConnector Load Step

A Run SmartConnector load step runs a Bulk Action SmartConnector from a parent workflow, with its own configuration, error handling, and returned scopes.

## Overview

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

**Purpose**: Explains how a Run <code class="expression">space.vars.smartconnector</code> load step launches a Bulk Action <code class="expression">space.vars.smartconnector</code>, passes <code class="expression">space.vars.entities</code> and scopes, handles errors, and behaves during a dry run.
{% endhint %}

A Run <code class="expression">space.vars.smartconnector</code> load step is a load step type that runs a Bulk Action <code class="expression">space.vars.smartconnector</code> from inside a parent <code class="expression">space.vars.smartconnector</code>'s execution. It lets one <code class="expression">space.vars.smartconnector</code> delegate a batch of work, for example a Bulk Action against a set of <code class="expression">space.vars.entities</code>, to another <code class="expression">space.vars.smartconnector</code>. It then waits or continues based on how that child execution finishes.

The step type sits alongside <code class="expression">space.vars.object</code> Upload as one of the two Load Step types available in a <code class="expression">space.vars.smartconnector</code>'s Load phase. Whereas an <code class="expression">space.vars.object</code> Upload step writes <code class="expression">space.vars.entities</code> directly, a Run <code class="expression">space.vars.smartconnector</code> step hands execution to a child <code class="expression">space.vars.smartconnector</code>, passes data into it through scopes, and can capture data back out through returned scopes. That flexibility makes it the building block for composing multi-stage automation chains by assembling smaller, reusable <code class="expression">space.vars.smartconnectors</code>.

### What is a Run SmartConnector Load Step?

A Run <code class="expression">space.vars.smartconnector</code> step is a load step that runs another <code class="expression">space.vars.smartconnector</code>, the child, as part of the current SmartConnector's execution, the parent. It can appear anywhere among a <code class="expression">space.vars.smartconnector</code>'s load steps, and a single <code class="expression">space.vars.smartconnector</code> can also include more than one Run <code class="expression">space.vars.smartconnector</code> step.

Each child execution carries a `parent_execution_id` back-reference to the execution that launched it, and its generated input file is named to trace back to that source, for example `Vendor Sync - Load Step 3.csv`.

## Adding the Step

1. In the main menu, choose **Data** then **SmartConnector**.&#x20;
2. Choose or create a new SmartConnector, then select the cloud icon to add a load step.
3. In the dropdown list, choose **Run SmartConnector.**\
   &#x20;

   <div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FCBUFjKFqMDa50zFBiZVL%2Fkizen-load-connector-step.png?alt=media&amp;token=a352af89-5e79-4ad7-97e8-77173ef7fa0d" alt="SmartConnector load step dropdown showing Object Upload and Run SmartConnector options, with Run SmartConnector selected." width="375"><figcaption></figcaption></figure></div>
4. In the dialog that opens, select the <code class="expression">space.vars.smartconnector</code> to run. The dropdown includes supported child types (Bulk Action <code class="expression">space.vars.smartconnectors</code>) and excludes the current <code class="expression">space.vars.smartconnector</code>. Names longer than 100 characters are truncated with an ellipsis.
5. Configure the Bulk Action child's Scope, <code class="expression">space.vars.entity</code> ID, Error Handling, and Return Scopes.

## Configuring a Bulk Action Child

Configuring a Bulk Action child sets a set of fields, all specific to that <code class="expression">space.vars.smartconnector</code> type.&#x20;

* **Scope:** The scope on the current <code class="expression">space.vars.smartconnector</code> that supplies the list of <code class="expression">space.vars.entity</code> IDs to send to the child, selected from a dropdown listing the current <code class="expression">space.vars.smartconnector</code>'s existing scopes.
* **Record ID Field:** The variable within that scope holding the <code class="expression">space.vars.entity</code> IDs. It must be a UUID variable, or a string variable whose values are cast to UUIDs, values that are not valid UUIDs are dropped rather than failing the step. The dropdown groups variables by Execution, Additional, and Load Step.
* **Included Records:** Shown only when the <code class="expression">space.vars.entity</code> ID Field comes from a prior load step's output. Options are All Matched <code class="expression">space.vars.entities</code> (default), Created <code class="expression">space.vars.entities</code>, and Updated <code class="expression">space.vars.entities</code>, using the same created and updated designations used for firing <code class="expression">space.vars.automations</code> on created or updated <code class="expression">space.vars.entities</code>.
* **Wait for \<Child SmartConnector> to Complete:** Toggle, enabled by default. With it on, the parent pauses until the child execution finishes. With it off, the parent moves to its next step immediately and is not affected by the child's outcome.
* **Error Handling:** Set the error handling options for the step, covered below in [Error Handling](#error-handling).
* **Return Scopes**: Optional list mapping an output scope of the child to a new scope name on the parent. Shown only when **Wait for \<Child SmartConnector> to Complete** is on. See [Passing Records and Returning Scopes](#passing-records-and-returning-scopes) below for how returned scopes behave.

In the <code class="expression">space.vars.smartconnector</code>'s load step overview, the new step reads **Run SmartConnector**, with the selected child <code class="expression">space.vars.smartconnector</code>'s name shown as the detail text.

If the <code class="expression">space.vars.entity</code> ID Field comes from a CSV load step, that load step must target the same Custom <code class="expression">space.vars.object</code> as the selected Bulk Action child. <code class="expression">space.vars.Kizen\_company\_name</code> validates this when the parent connector is saved.

## Error Handling&#x20;

A Run <code class="expression">space.vars.smartconnector</code> step has four error handling controls. The first two always apply. The last two only appear when Wait for Completion is on, since they describe outcomes of an execution the parent is actively waiting on.

* **If There Are Zero Records**: Skip or Error. Controls what happens when the scope feeding the child resolves to no record IDs.
* **If \<Child> Is Inactive (default: Queue an Execution)**: Queue an Execution, Skip this Step, or Error. Controls what happens when the selected child <code class="expression">space.vars.smartconnector</code> is inactive.
* **If \<Child> Errors (default: Ignore, shown only when Wait for Completion is enabled)**: Ignore or Error. When set to Error, a child failure puts the parent execution into an error status as well. When set to Ignore, the child's failure does not affect the parent's status.
* **If \<Child> Is Canceled (default: Continue, shown only when Wait for Completion is on)**: Continue or Cancel this Execution. Controls whether the parent carries on to its next load step or is canceled along with the child.

## Passing Records and Returning Scopes&#x20;

Records flow down from the parent to the child, and scopes can flow back up from the child to the parent.

Sending <code class="expression">space.vars.entities</code> down: the parent sends the child the record IDs held in the Record ID Field, from the selected Scope. When Included Records narrows that to Created Records or Updated Records, only the IDs matching that filter are sent. All Matched Records sends every ID in the variable as-is.

Returning scopes up: an output scope of the child can be mapped back into the parent as one of its own scopes, for later load steps to read. This is only available when Wait for Completion is on, since the parent needs the child to finish before it has anything to carry back.

* A returned scope maps a source to a name. The source must be an existing output scope of the child, including a scope the child itself returned from one of its own children, so returned scopes bubble up across multiple layers of nested <code class="expression">space.vars.smartconnectors</code>.
* The name must be a valid `api_name` and cannot collide with a scope the parent already has. Two run steps returning the same name are rejected when the connector is saved.
* The columns for a returned scope are stored on the load step itself, so the parent doesn't have to walk the child chain to know its shape. Each column keeps the type of whatever originally produced it, data source or matched records, at every level of the chain, so it never takes on a type that describes the connector that passed it along.
* Once a returned scope exists, a later CSV or Run <code class="expression">space.vars.smartconnector</code> step in the same save can read it by name like any other scope on the connector.

## Guardrails and Edge Behavior

Several guardrails keep a Run <code class="expression">space.vars.smartconnector</code> load step from creating an invalid or unrecoverable configuration.

* **No self-run or cycles**: A <code class="expression">space.vars.smartconnector</code> cannot run itself, and a child that would make a connector run itself, directly or through its own chain, is refused with a warning when the step is saved.
* **Ignoring errors requires no downstream dependents**: Setting On Error to Ignore is rejected at save time if any later load step reads a scope that step returns. The check covers every load step the connector will have after the save, including ones referenced only by ID, so it cannot be avoided by saving a partial configuration.
* **Failed or skipped children still produce data**: When a child fails and the error is ignored, or the child is skipped because it is inactive or received zero records, the parent writes each scope that step would have returned as an empty file with the correct columns and moves on. A failed-and-ignored child is treated the same as one that never ran. Steps downstream, and connectors further up the chain, see this as ordinary data with no rows and handle it the way they would handle any scope that produced nothing, which can itself fail their execution if they require records.
* **Renaming a returned scope in the child updates the mapping in its immediate parent only:** The rename does not propagate further up a multi-level chain.
* **Validation runs at save, at run start, and at activation:** A load step fails validation if it reads a scope or variable that no longer exists, reads something a later load step produces, reuses a scope or column name, or points at a deleted variable. Activation is checked separately because steps can be reordered and scopes reassigned while editing, so the configuration is only proven when it is put to use.
* **Scope or connector removal leads to Needs Attention, not silent failure**: If a returned scope stops existing on the child, it is removed from every mapping up the chain that returned it, along with the execution variables it contributed, but nothing is set inactive immediately. A step that still reads the removed scope fails on its next run and puts the connector in Needs Attention. Deleting the child <code class="expression">space.vars.smartconnector</code> altogether behaves the same way, failing the parent with the configuration issue to correct.
* **Waiting has its own edge cases**: Reordering load steps while one of them has an execution in Waiting invalidates that execution, and if the run step a parent is waiting on is deleted or repointed at a different <code class="expression">space.vars.smartconnector</code> before the child finishes, the parent fails with the reason instead of waiting indefinitely.
* **Choosing a child connector is a permissions decision**: It is checked when the step is saved. If the person saving it does not have the All SmartConnector permission and does not own the connector being pointed at, the save is rejected on `smart_connector_to_run`.

See [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md) for more on the Waiting state, concurrency limits, and cancellation behavior.

## Dry Run Behavior

A dry run of the parent cascades to the child. When a Run <code class="expression">space.vars.smartconnector</code> step executes during a dry run, its child execution is also a dry run.

Because dry runs roll back each chunk as they go, the child does not see the parent's already rolled-back state. Instead, it receives a snapshot built from the rows tied to the <code class="expression">space.vars.Kizen\_company\_name</code> IDs produced by the latest load step that points at the same Custom <code class="expression">space.vars.object</code> as the child.

Two load steps that upload to the same Custom <code class="expression">space.vars.object</code> are not currently supported together in a dry run. This is a known limitation.

***

## What's Next

Running a <code class="expression">space.vars.smartconnector</code> covers the Waiting state, concurrency limits, and cancellation cascades that a [Run SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md) step interacts with. [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md) compares Run <code class="expression">space.vars.smartconnector</code> against <code class="expression">space.vars.object</code> Upload load steps. [Execution Variables](/docs/concepts/smartconnectors/smartconnector-execution-variables.md) explains how scopes and variables carry data between steps and connectors. [Export, Import, and Duplication](/docs/concepts/smartconnectors/smartconnector-export-import-and-duplication.md) covers how Run <code class="expression">space.vars.smartconnector</code> steps behave when a <code class="expression">space.vars.smartconnector</code> is copied or moved between businesses.

<details>

<summary>Related Topics</summary>

* [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md)
* [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md)
* [SmartConnector Execution Variables](/docs/concepts/smartconnectors/smartconnector-execution-variables.md)
* [SmartConnector Export, Import, and Duplication](/docs/concepts/smartconnectors/smartconnector-export-import-and-duplication.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.