> 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-design-best-practices/smartconnector-execution-variable-design-best-practices.md).

# SmartConnector Execution Variable Design Best Practices

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

**Purpose:** Explains how to declare and type execution variables correctly so that SQL output columns map cleanly to Kizen field types and row-level validation catches missing or malformed data before it reaches a load step.
{% endhint %}

## Overview

Execution variables are the typed interface between your SQL output and Kizen field types. The type you assign to each output column determines whether that variable appears as a mapping option in a load step, and whether the value casts correctly when written to a Kizen field. This is most important for data that Kizen needs to interpret in a specific format, including lists, datetimes (for example `dd/mm/yyyy` vs. `dd-mm-yyyy`), and booleans (`Yes`/`No` vs. `true`/`false`).

### Declare All Output Columns as Execution Variables

Before using a SQL output column in a load step, declare it as an execution variable. Columns that are not declared cannot be used in matching rules or mapping rules.

When you add columns to your SQL output, use the Auto-detect unmapped columns feature to create variables for any columns that have not yet been mapped. Auto-detect infers a data type for each new column based on a sample of rows from the output table. Always review the inferred types before saving and correct any that were assigned incorrectly as inferred types are a starting point, not a guarantee.

For the full list of supported variable types and their behavior, see, see [SmartConnector Execution Variables](/docs/concepts/smartconnectors/smartconnector-execution-variables.md).

### Use Required Variables to Enforce Row-Level Integrity

Mark an execution variable as required when a missing or null value for that column should prevent a row from being processed. Required variable validation happens at the row level. A row that fails the check is skipped without affecting the rest of the run.

Use required variables to enforce that critical identifiers and relationship field values are always present. SQL execution will complete successfully even when a column produces null values, so required variables are the right place to catch and handle missing data before it reaches the load step.

For more information on required variable behavior, see [SmartConnector Execution Variables](/docs/concepts/smartconnectors/smartconnector-execution-variables.md).

***

## What's Next

Continue to [SmartConnector Load Step Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-load-step-design-best-practices.md) to learn how to sequence and structure load steps correctly. Because load steps consume execution variables directly, the variable types and required settings you configure on this page determine what is available to match and map in the next step.

<details>

<summary>Related Topics</summary>

* [SmartConnector SQL Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-sql-design-best-practices.md)
* [SmartConnector Running and Testing Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-running-and-testing-design-best-practices.md)
* [SmartConnector Design Best Practices](/docs/concepts/smartconnectors/smartconnector-design-best-practices.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, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-design-best-practices/smartconnector-execution-variable-design-best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.