> 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/running-a-smartconnector.md).

# Running a SmartConnector

Learn how to activate, dry run, and live run a Kizen SmartConnector, interpret the XLS output report, and understand execution statuses and cancellation behavior.

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

**Purpose:** Explains the full SmartConnector execution lifecycle, from activation through dry run, live run, and reviewing results.
{% endhint %}

## Overview

To use a <code class="expression">space.vars.smartconnector</code> reliably and avoid unintended consequences, you need to understand how activation works, when to use a dry run, and how to read the output report.

***

## Activation

Before a <code class="expression">space.vars.smartconnector</code> can execute a live run, it must be activated. Validations are performed continuously as you configure the <code class="expression">space.vars.smartconnector</code>, so any configuration errors should already be surfaced before you reach activation. At activation, the system performs one additional check for queued executions.

A few important behaviors to understand around activation:

* If configuration steps are incomplete, the system displays a warning before allowing even a dry run to proceed.
* An inactive <code class="expression">space.vars.smartconnector</code> will queue incoming data but won't process it. This is intentional and useful during development. For example, you can keep a Webhook <code class="expression">space.vars.smartconnector</code> inactive while sending sample payloads to capture them for testing, without triggering a live run.
* Toggling a <code class="expression">space.vars.smartconnector</code> to inactive stops all processing of new executions (but already in-progress executions will be allowed to complete).
* When you toggle it back to active, any executions that queued while it was inactive begin processing (assuming the maximum concurrency is greater than zero). Before reactivating, the UI prompts you with the list of queued executions, so you can cancel them if needed.

***

## Dry Run

A dry run executes the full <code class="expression">space.vars.smartconnector</code> flow, including SQL processing, variable resolution, matching, and mapping, without writing anything to <code class="expression">space.vars.Kizen\_company\_name</code>. It is the safest way to validate your configuration before committing to a live run.

Key behaviors of a dry run:

* Accepts any compatible input file, not just the reference or sample file used during setup
* Produces the same XLS output report as a live run, so you can inspect exactly what would have happened
* Does not create, update, or modify any <code class="expression">space.vars.entities</code> in <code class="expression">space.vars.Kizen\_company\_name</code>
* Leaves Created <code class="expression">space.vars.entity</code> IDs blank in the output because no <code class="expression">space.vars.entities</code> get created
* Runs a load step's child SmartConnector as a dry run too

We recommend you do a dry run before executing a live run on a new or modified <code class="expression">space.vars.smartconnector</code>. The output report will surface any configuration issues, type mismatches, or unexpected row failures before they impact live data.

See [Run SmartConnector Load Step](https://app.gitbook.com/o/2vkHfb9S8jSOtuSOSYip/sites/site_Vt1Cu/s/Qd8ufpN7wkdnx7JtgoeZ/concepts/smartconnectors/run-smartconnector-load-step) for how a child's dry run snapshot works.

***

## Live Run

A live run processes the input file and writes matched and created <code class="expression">space.vars.entities</code> to <code class="expression">space.vars.Kizen\_company\_name</code>.

Key behaviors of a live run:

* <code class="expression">space.vars.entities</code> are created or updated in <code class="expression">space.vars.Kizen\_company\_name</code> as the <code class="expression">space.vars.smartconnector</code> processes each chunk of information.
* If a load step runs a child <code class="expression">space.vars.smartconnector</code> with Wait for Completion enabled, the parent execution pauses with a status of Waiting until the child finishes, then resumes.

Waiting executions don't count toward the <code class="expression">space.vars.smartconnector</code>'s concurrent execution limit because they aren't considered to be running. Queued executions start in the order they arrived, except that parents that are ready to resume will start before any queued executions. A run that finishes successfully shows as Completed in the executions list.

{% hint style="warning" %}
**Caution:** Canceling an in-progress live run doesn't undo already-processed data. Chunks of information that have been committed to <code class="expression">space.vars.Kizen\_company\_name</code> before cancellation remain in place. For a canceled in-progress run, you can download the SQL Output, and the execution’s status shows how many Records were modified. If you need to reverse the results of a run, you can do so manually or through a separate process. Canceling a queued live run is safe because it hasn't started yet.
{% endhint %}

***

## Run Outputs

Every run, whether dry or live, generates artifacts you can use to review and troubleshoot what happened. Each execution has two downloadable artifacts: the XLS Output Report and the SQL Output (ZIP). A canceled in-progress run is the exception and produces only the SQL Output.

#### XLS Output Report

The XLS Output Report is a spreadsheet that captures the full results of the run. It's sent to the user who initiated the run and is available from the three-dot menu on any execution in the Executions tab.

The report contains the following tabs:

* **SQL Output**: one tab per output table (scope), showing the data produced by the SQL processor. Output tables with names ending in `errors` aren't passed through to variable mapping
* **Execution Variable Resolution**: one tab per scope, showing how each variable was parsed and typed for every row
* **Load Step**: one tab per load step, showing per-row results including created, updated, skipped, errored, and any warnings

The Load Step tabs are the most useful for troubleshooting. Each row shows exactly what the <code class="expression">space.vars.smartconnector</code> attempted and the outcome. Rows that failed validation, couldn't be matched, or produced warnings are all visible here.

A Run <code class="expression">space.vars.smartconnector</code> load step can be skipped entirely rather than run, for example when its input scope returns zero records or its child <code class="expression">space.vars.smartconnector</code> is inactive and configured to skip. A skipped step is reported as skipped rather than completed, with a reason.

In a dry run, the report reflects what would've happened if the run had been live. <code class="expression">space.vars.entity</code> IDs are not populated in the load step tabs since no <code class="expression">space.vars.entities</code> were actually created.

#### SQL Output (ZIP)

The SQL Output is a ZIP of CSV files, one per output table produced by the SQL execution. It contains the same SQL output data shown in the SQL Output tabs of the XLS report, in a format that's easier to open, diff, or load into other tools. It's available from the three-dot menu on any execution in the Executions tab.

The SQL Output becomes available as soon as the SQL execution completes, which means you can inspect SQL results while the Load Steps are still running. This is useful for catching issues in the SQL output early, without waiting for the full run to finish.

***

## Execution Statuses

A <code class="expression">space.vars.smartconnector</code> can be in one of four statuses at any given time:

* **Setup in Progress:** The <code class="expression">space.vars.smartconnector</code> has been created but has never been activated. Activation requires at least a sample file and one load step.
* **Operational:** The <code class="expression">space.vars.smartconnector</code> is active. If a live run has completed, the most recent one completed without errors.
* **Operational (Needs Attention):** The <code class="expression">space.vars.smartconnector</code> is active but the last live run completed with errors. The <code class="expression">space.vars.smartconnector</code> will continue to accept and process runs. If the next live run completes successfully, the status changes to Operational automatically.
* **Inactive:** The <code class="expression">space.vars.smartconnector</code> has been deactivated and will not process any runs until reactivated.

### Canceling a Run

A run can be canceled at any time from the executions list. Canceling a parent execution also cancels any child executions it started that are still running.

{% hint style="warning" %}
**Caution:** Canceling a run does not roll back already-processed data. Any <code class="expression">space.vars.entity</code> written to <code class="expression">space.vars.Kizen\_company\_name</code> before the cancellation are committed and remain in place. Cancellation stops further processing but does not undo what has already been done.
{% endhint %}

***

## What's Next

Continue to [SmartConnector Settings](/docs/concepts/smartconnectors/smartconnector-settings.md) to learn how to configure the operational settings that govern how your <code class="expression">space.vars.smartconnector</code> behaves in production. <code class="expression">space.vars.smartconnector</code> Settings covers concurrent executions, notification emails, and the execution ended webhook, all of which are important for running <code class="expression">space.vars.smartconnectors</code> reliably at scale.

<details>

<summary><strong>Related Topics</strong></summary>

* [SmartConnector Settings](/docs/concepts/smartconnectors/smartconnector-settings.md)
* [SmartConnector Diff Checking](/docs/concepts/smartconnectors/smartconnector-diff-checking.md)
* [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md)
* [SmartConnector Execution Variables](/docs/concepts/smartconnectors/smartconnector-execution-variables.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/running-a-smartconnector.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.