# SmartConnector Core Concepts

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

**Purpose:** Defines the structural foundation of <code class="expression">space.vars.smartconnectors</code>.
{% endhint %}

## Overview

<code class="expression">space.vars.smartconnectors</code> move your data from point A to point B reliably, and in a predictable orde&#x72;**.** No matter what type of <code class="expression">space.vars.smartconnector</code> you're working with, data always follows the same path: it comes in, gets transformed, and gets written to <code class="expression">space.vars.entities</code>.

***

## Why SmartConnectors Matter

At scale, manual data entry and one-<code class="expression">space.vars.entity</code>-at-a-time <code class="expression">space.vars.automations</code> break down. <code class="expression">space.vars.smartconnectors</code> are built for the operations that can't be handled any other way, moving large amounts of data reliably, repeatedly, and without human intervention.

A well-designed <code class="expression">space.vars.smartconnector</code> integration enables:

* Reliable bulk data ingestion from external systems
* Consistent, repeatable <code class="expression">space.vars.entity</code> creation and updates at scale
* Predictable load behavior with full execution logging and reporting
* Clean data governance through type enforcement and diff checking
* Reusable <code class="expression">space.vars.workflow</code> logic across multiple <code class="expression">space.vars.smartconnector</code> types

Without <code class="expression">space.vars.smartconnectors</code>, teams often resort to fragile workarounds: manual CSV uploads, overloaded <code class="expression">space.vars.automations</code>, or custom scripts that are difficult to maintain and impossible to audit.

***

## Foundational Definitions

The following terms are used throughout all <code class="expression">space.vars.smartconnector</code> documentation.

| Term                                                                           | Definition                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SmartConnector**                                                             | A batch data integration tool that reads structured input, optionally transforms it via SQL, maps it to typed variables, and writes <code class="expression">space.vars.entities</code> to one or more <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.objects</code>. Designed for operations on hundreds to millions of <code class="expression">space.vars.entities</code>.                         |
| [SmartConnector Types](/docs/concepts/smartconnectors/smartconnector-types.md) | The mechanism by which a <code class="expression">space.vars.smartconnector</code>receives its input data. All three connector types: Spreadsheet, Webhook, Scheduler, share identical <code class="expression">space.vars.workflow</code> behavior from the variable mapping step onward.                                                                                                                                                                 |
| **Execution (Topic Coming Soon)**                                              | A single end-to-end run of a <code class="expression">space.vars.smartconnector</code>, from data intake through load step completion. Each execution is logged with status, timing, and a downloadable report.                                                                                                                                                                                                                                            |
| **Execution Variable (Topic Coming Soon)**                                     | A typed variable used by load steps. Every column that exits the SQL processor (or the input file, for Spreadsheet connectors without SQL) must be declared as an execution variable before it can be used in a load step.                                                                                                                                                                                                                                 |
| **Additional Variable (Topic Coming Soon)**                                    | A typed variable that is not derived directly from the input data but can be used within the connector's <code class="expression">space.vars.workflow</code> for supplemental logic.                                                                                                                                                                                                                                                                       |
| **Load Step (Topic Coming Soon)**                                              | A configured stage within a connector that writes execution variable data to a <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code>. A <code class="expression">space.vars.smartconnector</code> may contain multiple load steps; they always run sequentially.                                                                                                                               |
| **Matching Rule (Topic Coming Soon)**                                          | Logic applied within a load step to determine whether an incoming row corresponds to an existing <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entity</code>. If no match is found, a new <code class="expression">space.vars.entity</code> can be created; if one match is found, it is updated; if multiple are found, the row is skipped.                                                         |
| **Mapping Rule (Topic Coming Soon)**                                           | Logic applied within a load step that controls how execution variable values are written to fields on a matched or newly created <code class="expression">space.vars.entity</code>; only Update Blank, Overwrite (Clear Field if Blank), Overwrite (But Skip if Blank)                                                                                                                                                                                     |
| **Dry Run (Topic Coming Soon)**                                                | A test execution mode that processes the full <code class="expression">space.vars.workflow</code> and produces a detailed XLS report without writing any data to <code class="expression">space.vars.Kizen\_company\_name</code>. Use dry runs to validate configuration before going live.                                                                                                                                                                |
| **Live Run (Topic Coming Soon)**                                               | A full execution that processes input data and writes <code class="expression">space.vars.entities</code> to <code class="expression">space.vars.Kizen\_company\_name</code>. A <code class="expression">space.vars.smartconnector</code> must be active before a live run can execute.                                                                                                                                                                    |
| **Diff Check (Topic Coming Soon)**                                             | An efficiency feature that compares each incoming row against a hash of execution variable values from the most recent successful execution. Rows that have not changed are automatically skipped.                                                                                                                                                                                                                                                         |
| **Reference Data (Topic Coming Soon)**                                         | Existing <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code> data made available inside the SQL processing environment. Reference data can be filtered using saved filter groups and queried alongside input file data.                                                                                                                                                                      |
| **SQL Processing (Topic Coming Soon)**                                         | An optional (Spreadsheet) or required (all other <code class="expression">space.vars.smartconnector</code> types) transformation layer that processes the input file before variable mapping. Runs in a CHDB (local ClickHouse) environment.                                                                                                                                                                                                               |
| **Active / Inactive (Topic Coming Soon)**                                      | The activation state of a <code class="expression">space.vars.smartconnector</code>. Only active <code class="expression">space.vars.smartconnectors</code> can execute live runs. Activating a <code class="expression">space.vars.smartconnector</code> triggers full configuration validation. A <code class="expression">space.vars.smartconnector</code> is automatically deactivated when its SQL configuration is changed and not yet re-validated. |

## Conceptual Model

Every <code class="expression">space.vars.smartconnector</code> moves data through the same <code class="expression">space.vars.workflow</code>, regardless of <code class="expression">space.vars.smartconnector</code> type:

<div data-with-frame="true"><figure><img src="/files/C1xX4FJkCfuSTWcNtvJt" alt="" width="563"><figcaption></figcaption></figure></div>

The diagram above illustrates this flow. Here is what each stage means in practice:

* **Input** is the starting point for every <code class="expression">space.vars.smartconnectors</code> run. Depending on the <code class="expression">space.vars.smartconnectors</code> type, this is either a file uploaded manually (Spreadsheet), a batched payload from an external system (Webhook), or a generated timestamp (Scheduler). Regardless of source, all input is treated as a structured file before it moves to the next stage.
* **SQL processing** is optional for Spreadsheet <code class="expression">space.vars.smartconnectors</code> and required for all other <code class="expression">space.vars.smartconnector</code> types. Non-spreadsheet <code class="expression">space.vars.smartconnectors</code> receive data in formats such as JSON (Webhook) or a generated timestamp (Scheduler); SQL is the mechanism that extracts and shapes that data into structured rows before it can be mapped.
* **Execution variables** are the typed interface between SQL output and the rest of the workflow. Every column that is returned by SQL must be declared as a variable with an explicit data type. This is the point where type validity is enforced: invalid required variables fail the row, not the entire run.
* **Load steps** consume execution variables and write <code class="expression">space.vars.entities</code> to <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.objects</code>. A single <code class="expression">space.vars.smartconnector</code> can contain multiple load steps, and they always run in order. Sequence matters: if one <code class="expression">space.vars.object</code> depends on <code class="expression">space.vars.entities</code> from another, the parent <code class="expression">space.vars.entities</code> must be created first.
* **A single SmartConnector can write to multiple Objects** by chaining load steps, each targeting a different <code class="expression">space.vars.object</code>

{% hint style="info" %}
**Note**: For structural and relational detail on how these components interact, see <code class="expression">space.vars.smartconnector</code> Data Model (**Coming Soon**).
{% endhint %}

***

## High-Level Components

The table below introduces each component at a glance. Each row links to the full topic where that component is documented in depth.

| Component                                    | What It Is                                                                                                                                                                             | How It Works                                                                                                                                                                                                                                                    | Why Use It                                                                                                                                                                                               |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SQL Processor (Topic Coming Soon)**        | A transformation layer that runs before variable mapping.                                                                                                                              | Accepts the input file as a table in a CHDB (ClickHouse) environment. Queries write results to the `output` schema; those tables become the input to variable mapping.                                                                                          | Reshape, filter, join, or enrich raw input data, including JSON from webhooks or reference data from <code class="expression">space.vars.Kizen\_company\_name</code>, before it reaches the load step.   |
| **Execution Variables (Topic Coming Soon)**  | Typed declarations that represent each column exiting the SQL processor or input file.                                                                                                 | Every column must be explicitly declared with a data type. Invalid required variables fail the row, not the entire run.                                                                                                                                         | Enforce type safety and provide a stable, named interface that load steps reference by variable name.                                                                                                    |
| **Additional Variables (Topic Coming Soon)** | Variables not sourced directly from input columns.                                                                                                                                     | Defined separately from execution variables and available for use within the <code class="expression">space.vars.workflow</code>.                                                                                                                               | Inject supplemental values or support more complex <code class="expression">space.vars.workflow</code> logic without requiring them in the source file.                                                  |
| **Transformation Flow (Topic Coming Soon)**  | The ordered sequence of steps between data intake and <code class="expression">space.vars.entity</code> writing.                                                                       | Moves data through SQL processing, variable mapping, and load steps in a defined order.                                                                                                                                                                         | Provides a clear, auditable path from raw input to committed <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entities</code>.                        |
| **Load Step (Topic Coming Soon)**            | A configured stage that writes data to a <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.object</code>.                            | Applies matching rules to find or create <code class="expression">space.vars.entities</code>, then applies mapping rules to write field values. Multiple load steps run sequentially within a single <code class="expression">space.vars.smartconnector</code>. | Target multiple <code class="expression">space.vars.objects</code> or apply different write logic to different subsets of data within one <code class="expression">space.vars.smartconnector</code> run. |
| **Matching Rules (Topic Coming Soon)**       | Logic that determines how an incoming row is matched to an existing <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entity</code>. | Rules are evaluated in order. No match → create new; one match → update; multiple matches → row is skipped. Archived <code class="expression">space.vars.entity</code> handling is configurable.                                                                | Prevent duplicate <code class="expression">space.vars.entities</code> and control exactly how the <code class="expression">space.vars.smartconnector</code> resolves ambiguous or missing matches.       |
| **Mapping Rules (Topic Coming Soon)**        | Logic that controls how execution variable values are written to <code class="expression">space.vars.entity</code> fields.                                                             | Applied after a <code class="expression">space.vars.entity</code> is matched or created. Options include Only Update Blank, Overwrite (Clear Field if Blank), Overwrite (But Skip if Blank)                                                                     | Fine-tune write behavior field by field. For example, never overwrite a value that already exists, or always apply the latest file value.                                                                |
| **Diff Check (Topic Coming Soon)**           | A row-level deduplication feature based on hashed execution variable values.                                                                                                           | Compares each row against the hash from the last successful execution. Unchanged rows are skipped automatically.                                                                                                                                                | Avoid redundant processing when running a complete dataset file repeatedly — only changed rows consume processing time.                                                                                  |

***

## SmartConnector Types

<code class="expression">space.vars.smartconnectors</code> support three <code class="expression">space.vars.smartconnector</code> types, each with a different trigger mechanism and data intake behavior. All three share identical <code class="expression">space.vars.workflow</code> behavior from the variable mapping step onward. Once data has been shaped into execution variables, the <code class="expression">space.vars.smartconnector</code> type no longer matters.

The three <code class="expression">space.vars.smartconnector</code> types are:

* Spreadsheet
* Webhook
* Scheduler

{% hint style="info" %}
**Note:** For more details, see [SmartConnector Types](/docs/concepts/smartconnectors/smartconnector-types.md).
{% endhint %}

***

## SmartConnector Settings

Each <code class="expression">space.vars.smartconnector</code> has a set of configurable settings that control its identity, execution behavior, and notification handling.&#x20;

The configurable settings are as follows:

* Description&#x20;
* Concurrent Executions&#x20;
* Notification Emails
* Execution Ended Webhook&#x20;

For more information, see SmartConnector Settings **(Topic Coming Soon)**.

{% hint style="info" %}
**Note:** A <code class="expression">space.vars.smartconnector</code> API Name is defined via original <code class="expression">space.vars.smartconnector</code> name and cannot be changed once initially created.
{% endhint %}

***

## Guiding Principles

These are the behavioral rules that govern how <code class="expression">space.vars.smartconnector</code>s operate. Understand these before configuring anything.

* **Batch-oriented:** <code class="expression">space.vars.smartconnector</code>s are not intended for real-time or single-<code class="expression">space.vars.entity</code> operations. Use <code class="expression">space.vars.automations</code> for single-<code class="expression">space.vars.entity</code> <code class="expression">space.vars.workflows</code>.
* **Execution variables enforce type validity at the row level:** A failed type conversion is treated as blank; if the variable is required, the row is skipped. Partial success is a valid execution outcome, and individual rows may be skipped while the rest of the run completes.
* **Diff checking operates on a hash of execution variable values per row:** Unchanged rows are skipped automatically with no additional configuration required beyond enabling the feature.
* **Canceling a run does not roll back already-processed data:** Any <code class="expression">space.vars.entities</code> written before cancellation remain committed in <code class="expression">space.vars.Kizen\_company\_name</code>.
* **Load steps always execute sequentially:** Ordering matters when one <code class="expression">space.vars.object</code> depends on another. You can create parent <code class="expression">space.vars.entities</code> before child <code class="expression">space.vars.entities</code>.
* **Dry run mode produces a full XLS report without writing anything to Kizen:** Always validate configuration with a dry run before executing live.
* **SmartConnectors must be activated before a live run can execute:** Activation triggers full configuration validation; a <code class="expression">space.vars.smartconnector</code> is automatically deactivated when its SQL is changed and not yet re-validated.
* **Agentic Workflows do not fire automatically on Records created or updated by a SmartConnector run** unless explicitly configured in the load step. Default trigger suppression is available as a load step option.
* **Every SmartConnector type is fundamentally file-oriented:** Non-spreadsheet <code class="expression">space.vars.smartconnectors</code> generate a file internally and pass it through the same <code class="expression">space.vars.workflow</code>. All <code class="expression">space.vars.smartconnector</code> types share identical behavior from the variable mapping step onward. This generated input file is available for review from the three-dot menu on any execution; just select **Download Input File**.

***

## What's Next

The next step is [SmartConnector Types](/docs/concepts/smartconnectors/smartconnector-types.md). That topic covers each of the trigger mechanisms in detail: what distinguishes its data intake behavior, when to use it, and what it produces as input to the <code class="expression">space.vars.smartconnector</code> <code class="expression">space.vars.workflow</code>.

<details>

<summary>Related Topics</summary>

* [SmartConnectors](/docs/concepts/smartconnectors.md)
* [SmartConnector Types](/docs/concepts/smartconnectors/smartconnector-types.md)
* [SmartConnector Diff Checking](/docs/concepts/smartconnectors/smartconnector-diff-checking.md)
* [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md)

</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-core-concepts.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.