# SmartConnector Types

{% hint style="success" %}
**Audience:** Administrators, Developers, Integrators, Solution Architects

**Purpose:** Explains each <code class="expression">space.vars.smartconnector</code> type, when to use it, and what distinguishes its trigger and data intake behavior from other types.
{% endhint %}

## Overview

Every <code class="expression">space.vars.smartconnector</code> type is fundamentally file-oriented. Non-spreadsheet <code class="expression">space.vars.smartconnectors</code> encode their input data as a CSV file internally, and from that point forward the data passes through the same <code class="expression">space.vars.workflow</code> as an uploaded file. This means all <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnector</code>'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 <code class="expression">space.vars.timeline</code> and can be reused.

***

## SmartConnector Types

<code class="expression">space.vars.Kizen\_company\_name</code> currently supports three <code class="expression">space.vars.smartconnector</code> types. Each type has a different trigger mechanism and data intake behavior, but all three share identical <code class="expression">space.vars.workflow</code> behavior from the variable mapping step onward:

|                             | Spreadsheet                                 | Webhook                                 | Scheduler                                          |
| --------------------------- | ------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
| **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 <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnectors</code> 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 <code class="expression">space.vars.smartconnector</code>'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 <code class="expression">space.vars.smartconnector</code>. This file is a blank CSV with one column per field on the destination <code class="expression">space.vars.object</code>, populated with dummy values. It can be downloaded from the <code class="expression">space.vars.smartconnector</code>'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 <code class="expression">space.vars.smartconnector</code> type accepts inbound HTTP requests and batches them for processing on a configured schedule. Instead of processing each webhook individually as it arrives, the <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnector</code>, 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 <code class="expression">space.vars.smartconnector</code>'s connection trigger configuration. You can reference the <code class="expression">space.vars.smartconnector</code> using either its UUID or its API Name. The API Name is auto-generated from the original <code class="expression">space.vars.smartconnector</code> name and cannot be changed, making it a stable identifier for use in webhook URLs and integrations.

**Accepted Payload Formats**

Webhook <code class="expression">space.vars.smartconnectors</code> 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 <code class="expression">space.vars.smartconnectors</code> 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 <code class="expression">space.vars.smartconnector</code> SQL:

```sql
create table output.food_orders engine Log() as
select
  body.table::String as table_number
  , body.order.item::String as order_item
  , arrayStringConcat(body.order.toppings::Array(String), ', ') as topping_list
FROM
	input.webhooks;
```

Output:

| table\_number | order\_item | topping\_list   |
| ------------- | ----------- | --------------- |
| 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:

| Column        | Type       | Description                                                                                |
| ------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `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 <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnector</code> type triggers on a configured schedule without requiring a file upload. When the schedule fires, the <code class="expression">space.vars.smartconnector</code> 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 <code class="expression">space.vars.smartconnectors</code> are typically used when the data source is already inside <code class="expression">space.vars.Kizen\_company\_name</code>, for example when querying reference data or running calculations against existing <code class="expression">space.vars.entities</code> 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," <code class="expression">space.vars.Kizen\_company\_name</code> offers an advanced scheduling entitlement that unlocks a raw iCal [RRULE](/docs/concepts/agentic-workflows/automation-code-steps/recurrence-rules-rrule.md) text input.&#x20;

Contact your <code class="expression">space.vars.Kizen\_company\_name</code> representative to enable this entitlement.

***

## What's Next

Continue to [SmartConnector SQL Processing](/docs/concepts/smartconnectors/smartconnector-sql-processing.md) 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 <code class="expression">space.vars.smartconnectors</code> but required for Webhook <code class="expression">space.vars.smartconnectors</code>, so understanding how it works is essential before configuring variables and load steps.

<details>

<summary><strong>Related Topics</strong></summary>

* [SmartConnector SQL Processing](/docs/concepts/smartconnectors/smartconnector-sql-processing.md)
* Webhook SmartConnectors **(Topic Coming Soon)**
* [SmartConnector Core Concepts](/docs/concepts/smartconnectors/smartconnector-core-concepts.md)

</details>


---

# 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-types.md?ask=<question>
```

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.