Running a SmartConnector
Audience: Administrators, Developers, Integrators, Solution Architects
Purpose: Explains the full SmartConnector execution lifecycle, from activation through dry run, live run, and reviewing results.
Overview
To use SmartConnector reliably and avoid unintended consequences, you need to understand how activation works, when to use a dry run, and how to read the output report.
Activation
Before a SmartConnector can execute a live run, it must be activated. Validations are performed continuously as you configure the SmartConnector, so any configuration errors should already be surfaced before you reach activation. At activation, the system performs one additional check for queued executions.
A few important behaviors to understand around activation:
If configuration steps are incomplete, the system displays a warning before allowing even a dry run to proceed
An inactive SmartConnector will queue incoming data but will not process it. This is intentional and useful during development. For example, you can keep a Webhook SmartConnector inactive while sending sample payloads to capture them for testing, without triggering a live run
Toggling a SmartConnector inactive stops all processing immediately
Toggling it back to active does not retroactively process data that arrived while it was inactive. However, any executions that were queued during the inactive period will begin processing on reactivation (assuming max concurrency is greater than zero). Before reactivating, the UI prompts you with the list of queued executions so you can cancel them if needed.
Dry Run
A dry run executes the full SmartConnector flow, including SQL processing, variable resolution, matching, and mapping, without writing anything to Kizen. It is the safest way to validate your configuration before committing to a live run.
Key behaviors of a dry run:
Accepts any compatible input file, not just the reference or sample file used during setup
Produces the same XLS output report as a live run, so you can inspect exactly what would have happened
Does not create, update, or modify any Records in Kizen
Record IDs in the output are not populated since no Records get created.
We recommend you do a dry run before executing a live run on a new or modified SmartConnector. The output report will surface any configuration issues, type mismatches, or unexpected row failures before they affect live data.
Live Run
A live run processes the input file and writes matched and created Records to Kizen.
Key behaviors of a live run:
Records are created or updated in Kizen as the SmartConnector processes each chunk of information
Caution: Canceling a live run does not undo already-processed data. Chunks of information that have been committed to Kizen before cancellation remain in place. If you need to reverse the results of a run, that must be handled manually or through a separate process.
Run Outputs
Every run, whether dry or live, generates artifacts you can use to review and troubleshoot what happened. Each execution has two downloadable artifacts: the XLS Output Report and the SQL Output (ZIP). These can be downloaded using the three-dot menu of any execution listed on the Executions Tab.
XLS Output Report
The XLS Output Report is a spreadsheet that captures the full results of the run. It is sent to the user who initiated the run and is available from the three-dot menu on any execution in the Executions tab.
The report contains the following tabs:
SQL Output: one tab per output table (scope), showing the data produced by the SQL processor. Output tables with names ending in
errorsare not passed through to variable mapping.Execution Variable Resolution: one tab per scope, showing how each variable was parsed and typed for every row.
Load Step: one tab per load step, showing per-row results including created, updated, skipped, errored, and any warnings.
The Load Step tabs are the most useful for troubleshooting. Each row shows exactly what the SmartConnector attempted to do and what the outcome was. Rows that failed validation, could not be matched, or produced warnings are all visible here.
In a dry run, the report reflects what would have happened if the run had been live. Record IDs are not populated in the load step tabs since no Records were actually created.
SQL Output (ZIP)
The SQL Output is a zip of CSV files, one per output table produced by the SQL execution. It contains the same SQL output data shown in the SQL Output tabs of the XLS report, in a format that's easier to open, diff, or load into other tools. It is available from the three-dot menu on any execution in the Executions tab.
The SQL Output becomes available as soon as the SQL execution completes, which means you can inspect SQL results while the Load Steps are still running. This is useful for catching issues in the SQL output early, without waiting for the full run to finish.
Execution Statuses
A SmartConnector can be in one of four statuses at any given time:
Setup in Progress: The SmartConnector has been created but has never been activated. Activation requires at least a sample file and one load step.
Operational: The SmartConnector is active. If a live run has completed, the most recent one completed without errors.
Operational (Needs Attention): The SmartConnector is active but the last live run completed with errors. The SmartConnector will continue to accept and process runs. If the next live run completes successfully, the status changes to Operational automatically.
Inactive: The SmartConnector has been deactivated and will not process any runs until reactivated.
Canceling a Run
A run can be canceled at any time from the executions list.
Caution: Canceling a run does not roll back already-processed data. Any Record written to Kizen before the cancellation are committed and remain in place. Cancellation stops further processing but does not undo what has already been done.
What's Next
Continue to SmartConnector Settings to learn how to configure the operational settings that govern how your SmartConnector behaves in production. SmartConnector Settings covers concurrent executions, notification emails, and the execution ended webhook, all of which are important for running SmartConnectors reliably at scale.
Last updated
Was this helpful?