SmartConnector Execution Variables
Audience: Administrators, Integrators, Developers
Purpose: Explains what execution variables are, how they are typed and validated, and how they flow through the SmartConnector Workflow.
Overview
Execution variables are how SQL results get passed into the rest of a 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 Kizen 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 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 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 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 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.
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.YYYYDD/MM/YYYY,DD-MM-YYYY,DD.MM.YYYYYYYY/MM/DD,YYYY.MM.DDExcel Epoch Time
UNIX Epoch Time
Output formats
MM/DD/YYYY(default)MM-DD-YYYY,MM.DD.YYYYDD/MM/YYYY,DD-MM-YYYY,DD.MM.YYYYYYYY/MM/DD,YYYY-MM-DD,YYYY.MM.DDD MMM YYYY
Arrays accepted: No
Format key
YYYY
4-digit year
MM
2-digit month
MMM
Abbreviated month (e.g. Apr)
DD
2-digit day
D
Day of month
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:mmMM/dd/yyyy h:mm aMM/dd/yyyy h:mm:ss ayyyy-MM-dd'T'HH:mmyyyyMMddHHmmyyyy-MM-dd,MM/dd/yyyy,yyyyMMddUNIX Epoch Time
Output formats
MM-dd-yyyy h:mm a(default)yyyy-MM-dd HH:mmMM/dd/yyyy HH:mmMM/dd/yyyy h:mm ayyyy-MM-dd'T'HH:mmd MMM yyyy h:mm aMM.dd.yyyy h:mm a
Arrays accepted: No
Format key
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
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
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
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-XXXXXXXXXXXXUnhyphenated:
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Output format
Hyphenated:
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX(default)
Arrays accepted: Yes
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 SmartConnector and introduces new columns or data.
After completing test execution and publishing the updated 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 SmartConnector flow. Unlike execution variables derived from SQL output, additional variables do not require SQL and are defined directly on the 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 SmartConnector configuration is updated.
Variable Scopes
Execution variables are scoped to the 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; where those variables are used to match existing Records, map values into fields, and write data into Kizen Objects.
Last updated
Was this helpful?