> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/kizen-basics/kizen-in-action/upload-records-with-a-csv-file-or-kizen-basics.md).

# Upload Records with a CSV File | Kizen Basics

## Overview

{% hint style="warning" %}
**Caution:** This setup reflects Kizen's default configuration. Your administrator may have customized your layout, so columns or navigation may appear differently. Trial accounts may have limited features.
{% endhint %}

Adding <code class="expression">space.vars.entities</code> one at a time works well for a handful of entries, but it doesn't scale when you need to import many <code class="expression">space.vars.entities</code> at once. A <code class="expression">space.vars.smartconnector</code> lets you upload a spreadsheet, such as a CSV file, and create or update many <code class="expression">space.vars.entities</code> in a single run instead of repeating the same manual steps.

A Spreadsheet Upload <code class="expression">space.vars.smartconnector</code>, the most common type, reads the rows in your file, maps each column to a field on the destination Object, and writes a Record for every row.

Let's return to our sample scenario. At one of <code class="expression">space.vars.Theme\_park\_name</code>'s concession stands, Marcus grabs some nachos, Sofia gets a snow cone, Caleb picks a churro, and Elena orders a lemonade. Rather than creating four separate Concession <code class="expression">space.vars.entities</code>, you'll upload all four purchases in a single run using a CSV file we provide. <code class="expression">space.vars.smartconnectors</code> are designed for this kind of batch work. You will:

* Create a Spreadsheet <code class="expression">space.vars.smartconnector</code> for the Concessions <code class="expression">space.vars.object</code>
* Map CSV columns to Concessions fields
* Validate your upload with a Dry Run before writing any data
* Run a Live Run to create the Records

These same steps apply to any <code class="expression">space.vars.object</code> when you need to add or update many <code class="expression">space.vars.entities</code> at once.

### Why This Matters

* **Efficiency**: One upload handles many rows, keeping bulk changes fast as data grows.
* **Accuracy**: A Dry Run checks your file first, catching bad values before anything is written.
* **Consistency**: Every row follows the same mapping, so <code class="expression">space.vars.entities</code> stay consistent at any volume.
* **Repeatability**: Reuse a configured <code class="expression">space.vars.smartconnector</code> for any future file in the same format.

***

## Before You Begin

To complete this task, you must:

* Have permission to create and run <code class="expression">space.vars.smartconnectors</code>
* Have completed:
  * [Create Your First Object](/docs/kizen-basics/kizen-in-action/create-your-first-object-or-kizen-basics.md)
  * [Create Your First Contact Record](/docs/kizen-basics/kizen-in-action/create-your-first-contact-record-or-kizen-basics.md)
  * [Create Your First Record](/docs/kizen-basics/kizen-in-action/create-your-first-record-or-kizen-basics.md)
* Have already created the Concessions <code class="expression">space.vars.object</code>
* Have <code class="expression">space.vars.contact</code> <code class="expression">space.vars.entities</code> for all four Reyes family members, including Elena Reyes

{% stepper %}
{% step %}

#### Download the sample CSV file

Download `flywheel-concessions-upload.csv` below. It contains four new concession purchases for the Reyes family, one per row, with a column for each Concessions field you'll map in the next step.

{% hint style="warning" %}
**Caution:** This sample file is pre-populated with the Reyes family's concession data for this walkthrough. It's not a blank template, so build a new CSV file when you're ready to upload your own records.
{% endhint %}

{% file src="/files/o5BD6QqzdN7Iou0qOUTs" %}
{% endstep %}

{% step %}

#### Create a new SmartConnector

In the top navigation, select **Data** > **SmartConnectors**.

Select **NEW SMARTCONNECTOR**.

Name it **Concessions CSV Upload**, choose **Spreadsheet Upload** as the Connector Type, and set **Concessions** as the Primary Object. Select **SAVE**.&#x20;

Saving takes you to the <code class="expression">space.vars.smartconnector</code>'s **Settings** tab.
{% endstep %}

{% step %}

#### Add a description

Provide a **Description**: "Runs a bulk upload of concession purchase records from a CSV file"

Leave the other settings as they are.&#x20;

Navigate to the **Build** tab.
{% endstep %}

{% step %}

#### Configure the Connection Trigger

On the canvas, find **Connection Trigger** and select the pencil icon to edit it.

Confirm the content on the **General Settings** tab, then select **SAVE & CONTINUE** to navigate to the **Configure Connection** tab.&#x20;

To upload the sample file, select **Choose File** and upload the `flywheel-concessions-upload.csv` file.

Select **SAVE & CONTINUE** to navigate to the **Initialize Variables** tab.&#x20;
{% endstep %}

{% step %}

#### Initialize the variables

You'll see that <code class="expression">space.vars.Kizen\_company\_name</code> reads the CSV file and attempts to map the columns to variable names. Confirm the content and set all five columns to **Required**.&#x20;

Select **SAVE & FINALIZE**.
{% endstep %}

{% step %}

#### Match the identifiers

On the canvas, find **Upload Concessions**, select the three-dot menu, and choose **Edit**.

On the **Unique Identifier(s) Matching** tab, align the <code class="expression">space.vars.Kizen\_company\_name</code> fields and the variables, starting with Concession Name → concession\_name. You can leave the defaults for the Upload Functions.

Select to **ADD FIELD MATCH RULE** and align the remaining fields and variables:

* Concession Value → concession\_value
* Primary Contact Record → primary\_contact\_record
* Quantity → quantity
* Purchase Date → purchase\_date. For this one, change the value for **If Multiple Matches Found** to **Do Not Upload Row**.

Select **SAVE & CONTINUE**.
{% endstep %}

{% step %}

#### Configure the Mapping Rules

On the **Mapping Rules** tab, set the <code class="expression">space.vars.Kizen\_company\_name</code> Field Name for Concession Name to concession\_name.&#x20;

For the view, leave the default: Mapped Fields.

For the unmapped variables, match each Data Source Variable to its <code class="expression">space.vars.Kizen\_company\_name</code> Field. As you do, new rows appear as fields for updating.&#x20;

Select **SAVE**.
{% endstep %}

{% step %}

#### Configure the Finalize Settings

On the **Finalize Settings & Preview** tab, leave Variable Name to Assign Output Record (Created or Matched) blank. This upload has only one load step, so there's no later step that needs to reference the matched or created Concessions record.

Leave Variable Type set to UUID (Kizen ID), and leave both of the following blank:

* **Agentic Workflow(s) to Start on Newly Created Records**
* **Agentic Workflow(s) to Start on Other Matched Records**

Leave **Agentic Workflow Trigger Suppression** set to **All Triggers Fire**, so the four new Concessions records can trigger any <code class="expression">space.vars.automations</code> configured on the <code class="expression">space.vars.object</code>, just as <code class="expression">space.vars.entities</code> do when created one at a time.

Select **SAVE & CLOSE**.
{% endstep %}

{% step %}

#### Do a Dry Run

Back on the canvas for the <code class="expression">space.vars.smartconnector</code>, select the play button to open the Executions page.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fst9MSfgMjdlV9oHJWa5a%2Fkizen-executions-button.jpg?alt=media&amp;token=908aea43-eaa1-40ba-8caa-3e7e6729e7e9" alt="SmartConnector canvas toolbar with the Play button selected, showing the Executions tooltip." width="267"><figcaption></figcaption></figure></div>

Select **START DRY RUN** and in the new modal, upload the `flywheel-concessions-upload.csv` file.

Select **START**. <code class="expression">space.vars.Kizen\_company\_name</code> initiates the run and sends you an email when the run completes. From the email, you can quickly see the starting and end times, as well as a link to a full report.&#x20;

Confirm all four rows passed with no errors. A Dry Run does not create, update, or modify any <code class="expression">space.vars.entities</code>, so it's safe to run as many times as you need.
{% endstep %}

{% step %}

#### Activate and Run a Live Run

{% hint style="warning" %}
**Caution:** Canceling a Live Run doesn't undo Records it's already written.
{% endhint %}

Once your Dry Run report looks correct, activate the SmartConnector from the canvas then select **SAVE**:

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FWOGHiVbznSOj7G4Nam0D%2Fkizen-active-button.jpg?alt=media&amp;token=9285c138-7111-4dbc-a965-482837b236a6" alt="SmartConnector settings panel with the Active toggle switched on and the Save button visible." width="280"><figcaption></figcaption></figure></div>

Still on the canvas, select the play button to open the Executions page, then choose **START RUN**. In the modal, upload the `flywheel-concessions-upload.csv` file again. This time, <code class="expression">space.vars.Kizen\_company\_name</code> writes the four <code class="expression">space.vars.entities</code> to the Concessions <code class="expression">space.vars.object</code>.

<code class="expression">space.vars.Kizen\_company\_name</code> emails you a report.

### What the finished setup looks like

After completing these steps, the Concessions <code class="expression">space.vars.object</code> shows 5 <code class="expression">space.vars.entities</code>: Popcorn from earlier, plus Nachos, Snow Cone, Churro, and Lemonade from your upload, each with the Primary <code class="expression">space.vars.contact</code> <code class="expression">space.vars.entity</code>, Quantity, and Purchase Date from your file.

***

## How Bulk Uploads Support Growing Operations

As <code class="expression">space.vars.Theme\_park\_name</code> gets busier, more <code class="expression">space.vars.entities</code> need to exist faster than any one person can create them by hand. <code class="expression">space.vars.smartconnectors</code> keep pace with that growth:

* **Agentic Workflows:** Bulk-created <code class="expression">space.vars.entities</code> can trigger the same automations as manually created ones, so a busy night doesn't mean falling behind on guest follow-up.
* **Reporting:** Dashboards reflect the full day's activity as soon as the Live Run finishes, not just what staff had time to enter by hand.
* **Data quality:** Field mapping applies the same rules to every row, so a rushed evening doesn't introduce inconsistent data.

Other <code class="expression">space.vars.smartconnector</code> types bring in data automatically, with no file upload. A Scheduler <code class="expression">space.vars.smartconnector</code> can pull data from an external source, such as a database or S3 bucket, on a recurring schedule. A Webhook <code class="expression">space.vars.smartconnector</code> collects data that external systems send by webhook and processes it in batches. For more information, see [SmartConnectors](/docs/concepts/smartconnectors.md).

***

{% endstep %}
{% endstepper %}

## What's Next

Now that you can add Records individually or in bulk, the next step is controlling who can see and edit them. In [Configure Your First Permission Groups](/docs/kizen-basics/kizen-in-action/configure-your-first-permission-groups-or-kizen-basics.md), you'll create a permission group for <code class="expression">space.vars.Theme\_park\_name</code>'s staff.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/kizen-basics/kizen-in-action/upload-records-with-a-csv-file-or-kizen-basics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.