SmartConnector Data Model
Audience: Developers and Solution Architects
Purpose: Explains the structural data model behind SmartConnectors, describing how configurations, executions, and output artifacts are represented and how they relate to each other, and prepares readers to work with SmartConnectors programmatically via the SmartConnector APIs.
Overview
SmartConnectors are backed by three distinct resources: the SmartConnector configuration, the execution (flow run), and the execution output report. A foundational understanding of SmartConnector 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
SmartConnectors are built around three core resources:
SmartConnector Configuration: The configuration represents the SmartConnector definition. It stores everything that describes how the SmartConnector is built and how it behaves: the SmartConnector 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 SmartConnector against a specific input. Each execution is linked to the version of the SmartConnector configuration that was active at the time the run was initiated. Changes made to the SmartConnector 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.
A single SmartConnector configuration can have many executions. Each execution has exactly one output report. Executions are always associated with the SmartConnector 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 SmartConnector configuration at the time of the run. Edits to the SmartConnector 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.
Statuses
SmartConnectors have four statuses:
Setup in Progress
Operational
Operational (Needs Attention)
Inactive
Statuses reflect the activation state of the SmartConnector and the outcome of its most recent live run. For a full description of each, see Running a SmartConnector.
Status Transitions
Two actions can change a SmartConnector's status:
Toggling the Active flag moves the SmartConnector to either Operational or Inactive depending on its prior run history and the result of pre-activation checks.
A live run completing moves the SmartConnector to either Operational or Operational (Needs Attention) depending on whether the run succeeded or completed with errors.
Note: Dry runs do not affect SmartConnector status. Only live runs trigger status transitions.
Mapping to APIs
SmartConnector resources map to API-accessible resources as follows:
SmartConnector configuration maps to a resource that can be retrieved and referenced via the API. Each SmartConnector 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 SmartConnector. 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 SmartConnector 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.
Note: API Names for SmartConnectors follow the same derivation pattern used by other Kizen resources. The API Name is auto-generated from the SmartConnector name and is displayed in the SmartConnector settings. For more on how API names work across Kizen, see Object API Names.
What's Next
With the data model in place, the next step is putting it to work. Continue to SmartConnector APIs to learn how to trigger runs, monitor execution status, and cancel executions in progress using the available API endpoints.
Last updated
Was this helpful?