SmartConnector Types
Audience: Administrators, Developers, Integrators, Solution Architects
Purpose: Explains each SmartConnector type, when to use it, and what distinguishes its trigger and data intake behavior from other types.
Overview
Every SmartConnector type is fundamentally file-oriented. Non-spreadsheet SmartConnectors encode their input data as a CSV file internally, and from that point forward the data passes through the same Workflow as an uploaded file. This means all SmartConnector types share identical behavior from the variable mapping step onward. Trigger type only affects how the input file is produced, not how it is processed.
It also means any SmartConnector's input file can be downloaded, modified, and re-uploaded to reprocess a specific batch of data, regardless of how that data originally arrived. Whether a run is triggered by a file upload, an inbound webhook batch, or a scheduled timer, the input file is always accessible from the execution Timeline and can be reused.
SmartConnector Types
Kizen currently supports three SmartConnector types. Each type has a different trigger mechanism and data intake behavior, but all three share identical Workflow behavior from the variable mapping step onward:
Trigger
Manual file upload. Capped at 500MB
Inbound HTTP request
Configured schedule
Accepted input
CSV, XLSX, .zip
JSON body, query strings
System-generated timestamp CSV
SQL processing
Optional
Required (auto-enabled)
Optional
Primary use case
Recurring batch imports from external files
Batching high-volume inbound event data
Scheduled logic against reference or external data
Input file reprocessing
Yes
Yes
Yes
Max payload/file size
No enforced limit
Body: 256 KB, Query string: ~4 KB
N/A
Spreadsheet
Spreadsheet (File Upload) is the most common SmartConnector type. It is triggered manually by uploading a file and is the right choice for recurring batch imports where a human or external system provides a data file on a regular basis.
Accepted formats
Spreadsheet SmartConnectors accept the following file formats:
CSV (.csv)
Tab-separated values (.tsv, .dat)
Microsoft Excel (.xls, .xlsx, .xlsm, .xlsb)
OpenDocument Spreadsheet (.ods)
ZIP archives (.zip) containing CSVs
The file schema must be compatible with the SmartConnector's configured SQL or variable mapping. Columns that don't correspond to a declared variable or SQL input will be ignored.
UTF-8 Encoding
When a text-based file (CSV, TSV, or DAT) is uploaded without explicit encoding information, the system assumes UTF-8 and displays a warning. This is not an error. It is a notification that the system is making an assumption about the file's encoding. If uploaded characters decode incorrectly (for example, accented characters appear as garbled text), the source file likely uses a non-UTF-8 encoding and should be re-exported with UTF-8 encoding before uploading. This warning does not apply to Excel or ODS formats, which encode character data differently.
Sample File
The system generates a sample file for every Spreadsheet SmartConnector. This file is a blank CSV with one column per field on the destination Object, populated with dummy values. It can be downloaded from the SmartConnector's build tab and modified freely before upload. It is intended as a starting point for building and testing your SQL or variable mapping, not as a fixed template.
Webhook
The Webhook SmartConnector type accepts inbound HTTP requests and batches them for processing on a configured schedule. Instead of processing each webhook individually as it arrives, the SmartConnector queues incoming requests and processes them in a batch at regular intervals, making it significantly more efficient than handling high-volume webhook traffic one event at a time.
Processing Cadence
When creating a Webhook SmartConnector, you configure how often queued webhooks are processed using the Process new webhooks every setting. This cadence determines how frequently the batch runs, not how quickly individual webhooks are accepted. Incoming requests are queued immediately regardless of the cadence.
Webhook URL
The webhook URL is displayed in the SmartConnector's connection trigger configuration. You can reference the SmartConnector using either its UUID or its API Name. The API Name is auto-generated from the original SmartConnector name and cannot be changed, making it a stable identifier for use in webhook URLs and integrations.
Accepted Payload Formats
Webhook SmartConnectors accept a POST body (recommended), query string parameters (max ~4 KB), or other body formats, with a max of 256 KB on all content types. JSON is recommended because ClickHouse SQL can access JSON body values directly using dot notation, making extraction seamless.
SQL Processing
SQL processing is required for Webhook SmartConnectors and is automatically enabled. It cannot be disabled. Webhook payloads arrive as structured data (JSON, query strings, or other formats) and must be parsed into named output tables before variable mapping can occur.
Your SQL must produce at least one output table using the output. prefix (for example, output.my_table). This is required for the SQL processing step to pass validation checks.
Example POST body:
{"table": 7, "order": {"item": "fries", "toppings": ["cheese", "ketchup"]}}
Example SmartConnector SQL:
Output:
7
fries
cheese, ketchup
The SQL environment provides two input tables for accessing the incoming webhook data:
input.webhooks (recommended for most use cases) provides a typed, structured view of the incoming webhook data with the following fixed columns:
timestamp
DateTime64
The time the webhook was received
employee_id
UUID
The identifier of the employee associated with the request
querystring
String
The raw query string from the webhook URL
body
JSON
The request body, accessible using dot notation (e.g., body.name or body.address.city)
input.webhooks_raw provides the same data as input.webhooks but with simpler, less strictly typed columns. Use this table when you need to parse the payload manually or when the typed columns in input.webhooks do not suit your use case.
Development Workflow
While the SmartConnector is inactive, incoming webhooks are queued but not processed. This behavior is intentional and useful during development. You can send sample requests to the webhook URL, download the queued execution's input file from the executions list, and use it as your SQL test input. Cancel the queued execution before activating the SmartConnector so it is not processed against live data.
A previous execution's input file can also be downloaded and re-uploaded to reprocess that exact batch of webhooks, which is useful for retrying a failed execution with the original payload data without needing to re-send the original requests.
For full configuration detail, SQL access patterns, and worked examples, see Webhook SmartConnectors (Topic Coming Soon).
Scheduler
The Scheduler SmartConnector type triggers on a configured schedule without requiring a file upload. When the schedule fires, the SmartConnector generates a simple CSV containing only a timestamp and passes it through the pipeline as the input file. The timestamp is available in SQL and can be used to scope queries or filter reference data.
Scheduler SmartConnectors are typically used when the data source is already inside Kizen, for example when querying reference data or running calculations against existing Records using SQL, or when connecting to an external data source such as an S3 bucket or external database that is read on a schedule rather than triggered by an event.
Scheduling Options
The standard scheduling UI supports recurring schedules defined by interval and start time, for example every 24 hours starting at 2:00 AM. If you need more complex scheduling patterns that the standard UI cannot express, such as "the third Thursday of November" or "every weekday in Q1," Kizen offers an advanced scheduling entitlement that unlocks a raw iCal RRULE text input.
Contact your Kizen representative to enable this entitlement.
What's Next
Continue to SQL Processing (Topic Coming Soon) to learn how to transform your input data using ClickHouse SQL before it reaches the variable mapping and load step stages. SQL processing is optional for Spreadsheet and Scheduler SmartConnectors but required for Webhook SmartConnectors, so understanding how it works is essential before configuring variables and load steps.
Last updated
Was this helpful?