> 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/smartconnector-data-model.md).

# SmartConnector Data Model

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

**Purpose:** Documents the structural data model behind <code class="expression">space.vars.smartconnectors</code>, describing how <code class="expression">space.vars.smartconnector</code> configurations, executions, and output artifacts are represented and how they relate to each other. Prepares readers to work with <code class="expression">space.vars.smartconnectors</code> programmatically via the <code class="expression">space.vars.smartconnector</code> APIs.
{% endhint %}

## Overview

<code class="expression">space.vars.smartconnectors</code> are backed by three distinct resources: the <code class="expression">space.vars.smartconnector</code> configuration, the execution (flow run), and the execution output report. A foundational understanding of <code class="expression">space.vars.smartconnector</code> structure and interrelationships is required to interact with them programmatically, interpret execution history, and reference them reliably in API calls and webhook URLs.

***

## SmartConnector Data Model Foundations

<code class="expression">space.vars.smartconnectors</code> are built around three core resources:

* **SmartConnector Configuration:** The configuration represents the <code class="expression">space.vars.smartconnector</code> definition. It stores everything that describes how the <code class="expression">space.vars.smartconnector</code> is built and how it behaves: the <code class="expression">space.vars.smartconnector</code> type, the published SQL script, execution variable declarations, load step configuration, and operational settings such as concurrent executions, notification emails, and the execution ended webhook. The configuration is what you create, edit, activate, and reference by name or API Name.
* **Execution (Flow Run):** The execution, also called a flow run, represents a single run of a <code class="expression">space.vars.smartconnector</code> against a specific input. Each execution is linked to the version of the <code class="expression">space.vars.smartconnector</code> configuration that was active at the time the run was initiated. Changes made to the <code class="expression">space.vars.smartconnector</code> configuration after a run has started do not affect that run.
* **Execution Output (XLS Report):** When a SQL script completes execution, a structured XLS report is produced for that run. If the SQL script fails with a terminating error (like a throwIf() assertion being triggered), no report is produced for that execution. For details on accessing and interpreting the report, see [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md).

A single <code class="expression">space.vars.smartconnector</code> configuration can have many executions. Each execution has exactly one output report. Executions are always associated with the <code class="expression">space.vars.smartconnector</code> configuration that produced them.

***

## Execution

Each execution captures the full context of a single run:

* **Configuration version:** The execution is linked to the state of the <code class="expression">space.vars.smartconnector</code> configuration at the time of the run. Edits to the <code class="expression">space.vars.smartconnector</code> after a run starts do not affect that run.
* **Input and output references:** The execution stores a reference to the input file used for the run and the location of the generated XLS output report.
* **Status tracking:** The execution tracks run state from initialization through completion, cancellation, or failure.

For a full description of the execution lifecycle, including dry runs, live runs, chunked processing, cancellation behavior, and output interpretation, see [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md).

***

## Statuses

<code class="expression">space.vars.smartconnectors</code> have four statuses:&#x20;

* **Setup in Progress**
* **Operational**
* **Operational (Needs Attention)**
* &#x20;**Inactive**

Statuses reflect the activation state of the <code class="expression">space.vars.smartconnector</code> and the outcome of its most recent live run. For a full description of each, see [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md).

### Status Transitions

Two actions can change a <code class="expression">space.vars.smartconnector</code>'s status:

* **Toggling the Active flag** moves the <code class="expression">space.vars.smartconnector</code> to either **Operational** or **Inactive** depending on its prior run history and the result of pre-activation checks.
* **A live run completing** moves the <code class="expression">space.vars.smartconnector</code> to either **Operational** or **Operational (Needs Attention)** depending on whether the run succeeded or completed with errors.

{% hint style="info" %}
**Note:** Dry runs do not affect <code class="expression">space.vars.smartconnector</code> status. Only live runs trigger status transitions.
{% endhint %}

***

## Mapping to APIs

<code class="expression">space.vars.smartconnector</code> resources map to API-accessible resources as follows:

* **SmartConnector configuration** maps to a resource that can be retrieved and referenced via the API. Each <code class="expression">space.vars.smartconnector</code> has a UUID that serves as its unique system identifier and an API Name that serves as a stable, human-readable identifier.
* **Executions** are accessible as child resources of the <code class="expression">space.vars.smartconnector</code>. You can retrieve the status of an execution, monitor its progress, and cancel it via API using the execution ID returned when a run is initiated.
* **API Name** is the recommended way to reference a <code class="expression">space.vars.smartconnector</code> programmatically. Unlike the UUID, the API Name is human-readable and is designed to remain stable across environments. It is used as a path segment in webhook URLs and as an identifier in API calls that trigger or reference a connector by name.

{% hint style="info" %}
**Note:** API Names for <code class="expression">space.vars.smartconnectors</code> follow the same derivation pattern used by other <code class="expression">space.vars.Kizen\_company\_name</code> resources. The API Name is auto-generated from the <code class="expression">space.vars.smartconnector</code> name and is displayed in the <code class="expression">space.vars.smartconnector</code> settings. For more on how API names work across <code class="expression">space.vars.Kizen\_company\_name</code>, see [Object API Names](/docs/concepts/objects/object-apis/object-api-names.md).
{% endhint %}

***

## What's Next

With the data model in place, the next step is putting it to work. Continue to [SmartConnector APIs](/docs/concepts/smartconnectors/smartconnector-apis.md) to learn how to trigger runs, monitor execution status, and cancel executions in progress using the available API endpoints.

<details>

<summary>Related Topics</summary>

* [Running a SmartConnector](/docs/concepts/smartconnectors/running-a-smartconnector.md)
* [SmartConnector Settings](/docs/concepts/smartconnectors/smartconnector-settings.md)
* [SmartConnector Export, Import, and Duplication](/docs/concepts/smartconnectors/smartconnector-export-import-and-duplication.md)
* [SmartConnector APIs](/docs/concepts/smartconnectors/smartconnector-apis.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/smartconnector-data-model.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.