# SmartConnector Execution Variables {% hint style="success" %} **Audience:** Administrators, Integrators, Developers **Purpose:** Understand what execution variables are, how they are typed and validated, and how they flow through the space.vars.smartconnector space.vars.workflow. {% endhint %} ## Overview Execution variables are how SQL results get passed into the rest of a space.vars.smartconnector. Any column from your SQL output that you want to use in matching rules, mapping rules, or load steps needs to be declared as an execution variable, and you need to tell space.vars.Kizen\_company\_name what type of data it holds. ### What Are Execution Variables? Execution variables are typed, named values drawn from SQL output columns or defined statically in the space.vars.smartconnector configuration. Any column needed downstream must be declared as an execution variable with an explicit type before it can be used in a matching rule, mapping rule, or load step. Once declared, execution variables persist in the space.vars.smartconnector configuration and are available to all downstream steps in the flow. Variable type compatibility matters beyond the initial declaration. The UI filters the options available in matching and mapping rule dropdowns based on whether the variable type is compatible with the destination field type on the target space.vars.object. If an expected variable is missing from a dropdown, the most likely cause is a type mismatch. Check that the variable type matches the field type on the space.vars.object you are mapping to before troubleshooting anything else. *** ## Variable Types Seven variable types are supported. Each type defines how incoming data is parsed, how it is represented downstream, whether arrays are accepted, and any special runtime rules that apply. {% tabs %} {% tab title="Boolean" %} ### Boolean **Behavior:** The input format is autodetected from the column data. **Input formats** * `True/False` (default) * `Yes/No` * `On/Off` * `1/0` * `t/f` **Output formats** * `True/False` (default) * `Yes/No` * `On/Off` **Arrays accepted:** No {% endtab %} {% tab title="Date" %} ### Date **Behavior** * The input format is autodetected. When a value is ambiguous, the output falls back to `MM/DD/YYYY`. * If a datetime value is uploaded to a Date variable, the time component is stripped. **Input formats** * `YYYY-MM-DD` (default) * `MM/DD/YYYY`, `MM-DD-YYYY`, `MM.DD.YYYY` * `DD/MM/YYYY`, `DD-MM-YYYY`, `DD.MM.YYYY` * `YYYY/MM/DD`, `YYYY.MM.DD` * Excel Epoch Time * UNIX Epoch Time **Output formats** * `MM/DD/YYYY` (default) * `MM-DD-YYYY`, `MM.DD.YYYY` * `DD/MM/YYYY`, `DD-MM-YYYY`, `DD.MM.YYYY` * `YYYY/MM/DD`, `YYYY-MM-DD`, `YYYY.MM.DD` * `D MMM YYYY` **Arrays accepted**: No **Format key** | Token | Meaning | | ------------ | ---------------------------- | | `YYYY` | 4-digit year | | `MM` | 2-digit month | | `MMM` | Abbreviated month (e.g. Apr) | | `DD` | 2-digit day | | `D` | Day of month | | {% endtab %} | | {% tab title="DateTime" %} ### DateTime **Behavior** * The input format is autodetected. * Any precision beyond minutes (seconds, milliseconds) is ignored. * Timezones are dropped if present on the input. * Date-only inputs (`yyyy-MM-dd`, `MM/dd/yyyy`, `yyyyMMdd`) are treated as midnight in the business timezone. **Input formats** * `yyyy-MM-dd HH:mm` (default) * `MM/dd/yyyy HH:mm` * `MM/dd/yyyy h:mm a` * `MM/dd/yyyy h:mm:ss a` * `yyyy-MM-dd'T'HH:mm` * `yyyyMMddHHmm` * `yyyy-MM-dd`, `MM/dd/yyyy`, `yyyyMMdd` * UNIX Epoch Time **Output formats** * `MM-dd-yyyy h:mm a` (default) * `yyyy-MM-dd HH:mm` * `MM/dd/yyyy HH:mm` * `MM/dd/yyyy h:mm a` * `yyyy-MM-dd'T'HH:mm` * `d MMM yyyy h:mm a` * `MM.dd.yyyy h:mm a` **Arrays accepted**: No **Format key** | Token | Meaning | | ------------ | ---------------------------- | | `yyyy` | 4-digit year | | `MM` | 2-digit month | | `MMM` | Abbreviated month (e.g. Apr) | | `dd` | 2-digit day | | `d` | Day of month | | `HH` | Hour, 24-hour (00–23) | | `h` | Hour, 12-hour (1–12) | | `mm` | Minutes | | `ss` | Seconds | | `a` | AM/PM marker | | {% endtab %} | | {% tab title="Number" %} ### Number **Behavior** * Values with or without comma separators are accepted automatically. * Currency symbols are stripped on input. * Decimal precision matches the saved value and is not padded. **Input formats** * Numbers with comma separators (e.g., `1,250.50`) * Numbers without comma separators (e.g., `1250.50`) **Output formats** * With commas (e.g., `1,250.50`) * Without commas (e.g., `1250.50`) **Arrays accepted:** No {% endtab %} {% tab title="Phone Number (E164)" %} ### Phone Number (E164) **Behavior** * A column is autodetected as a phone number when at least 80% of its values can be parsed into E164 **Input formats** * Any string containing a recognizable phone number. Values are normalized using the business's configured default phone country. **Output format** * E164 (e.g., `+14155551234`) **Arrays accepted:** No {% endtab %} {% tab title="String" %} ### String **Behavior** * When no other type classification succeeds, the variable defaults to String. **Input formats** * Any character content. **Output formats** * Any character content. **Arrays accepted:** Yes {% endtab %} {% tab title="UUID" %} ### UUID **Behavior** * When all values match either UUID format, the type is set automatically without prompting for an input format. **Input formats** * Hyphenated: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` * Unhyphenated: `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` **Output format** * Hyphenated: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` (default) **Arrays accepted:** Yes {% endtab %} {% endtabs %} *** ## Type Validation Behavior Type validation occurs when execution variables are resolved, so after the SQL processor runs and before the load step begins. The entire execution variable file is processed at once before any load step chunk work begins. How validation failures are handled depends on whether the variable is required or optional: * **Required variable:** If a required variable has an invalid or blank value for a given row, that row fails. The row is skipped and the failure is logged in the output report. The run continues for all other rows. * **Optional variable:** If an optional variable has an invalid value, it is treated as blank. The row is not failed. Failed rows appear in the errors and warnings column of the load step tab in the execution report. A run where some rows pass and others fail is reported as a partial success. ### Auto-Detect Unmapped Columns The **Auto-detect unmapped columns** button scans all SQL output columns and automatically creates an execution variable for any column that has not yet been mapped. This is most useful when the SQL output has changed. For example, when a new CSV file is uploaded to an existing space.vars.smartconnector and introduces new columns or data. After completing test execution and publishing the updated space.vars.smartconnector live, revisit the Initialize Variables step and click **Auto-detect unmapped columns** to add execution variables for the new columns without defining each one manually. ### Additional Variables Additional variables are statically defined values that are available across all scopes in the space.vars.smartconnector flow. Unlike execution variables derived from SQL output, additional variables do not require SQL and are defined directly on the space.vars.smartconnector configuration and injected into the flow at runtime. Additional variables are useful for constants that need to be available throughout a run, such as a source system identifier or a fixed reference value. Because they are static, their values do not change between rows or between runs unless the space.vars.smartconnector configuration is updated. ### Variable Scopes Execution variables are scoped to the space.vars.smartconnector execution and are not shared between runs. Each run produces its own isolated set of resolved variable values. When SQL processing produces multiple output tables, each output table generates its own scope of execution variables. Variables declared against one output table are not automatically available in the scope of another. Load steps are configured against a specific scope, so variable declarations must be present in the correct scope for a given load step to use them. Additional variables are available across all scopes within a single execution. *** ## What's Next With execution variables declared and typed, the next step is configuring your [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md); where those variables are used to match existing space.vars.entities, map values into fields, and write data into space.vars.Kizen\_company\_name space.vars.objects.
Related Topics * [SmartConnector SQL Processing](/docs/concepts/smartconnectors/smartconnector-sql-processing.md) * [SmartConnector External Data Sources](/docs/concepts/smartconnectors/smartconnector-external-data-sources.md) * [SmartConnector Load Steps](/docs/concepts/smartconnectors/smartconnector-load-steps.md) * [SmartConnector Diff Checking](/docs/concepts/smartconnectors/smartconnector-diff-checking.md)
--- # 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-execution-variables.md?ask= ``` 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.