> 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

{% 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 <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 will not 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> inactive stops all processing immediately
* Toggling it back to active does not retroactively process data that arrived while it was inactive. However, any executions that were queued during the inactive period will begin processing on reactivation (assuming max 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>
* <code class="expression">space.vars.entity</code> IDs in the output are not populated since no <code class="expression">space.vars.entities</code> get created.

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 affect live data.

***

## 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

{% hint style="warning" %}
**Caution:** Canceling a live run does not 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. If you need to reverse the results of a run, that must be handled manually or through a separate process.
{% 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). These can be downloaded using the three-dot menu of any execution listed on the Executions Tab.

#### XLS Output Report

The XLS Output Report is a spreadsheet that captures the full results of the run. It is 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` are not 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 to do and what the outcome was. Rows that failed validation, could not be matched, or produced warnings are all visible here.

In a dry run, the report reflects what would have 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 is 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.

{% 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 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/running-a-smartconnector.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.