# Importers Overview

> Create an Importer to insert or update Accounts and Transactions from CSV, S3, Snowflake, or other data sources, then map columns and fix run errors.

Source: https://help.withpersona.com/articles/2fpD7Bwb7OrzAS4g7XWoMG/
Section: Imports > Introduction > Key Concepts

An **Importer** is a tool for inserting or updating external information in Persona. Importers work by taking information from a third-party data source (e.g. Amazon S3 Bucket, CSV, Snowflake) to update or create Persona objects (e.g. Accounts, Transactions).

## Key terms for Importers

- **Data source:** The system that houses the external data that you want to import into Persona. A data source is required to run an Importer.
- **Importer:** The process that imports the external data. Each Importer has a configurations that specify its data source and how the data should be imported, including the **Destination**, **Write mode**, and **Write frequency** (available for select data source types).
  - **Destination:** The destination object that an Importer writes to
  - **Write mode:** The logic by which Persona inserts external data into Graph
    - **The default write method** is `upsert` (update a row if a reference ID exists or insert a row if there is no reference ID), which means that if no account or transaction already exists with the reference ID listed, Persona **creates** a new account or transaction.
    - The alternative write method is `create`. With this method, if there is a reference ID in a row, Persona does not update the row, leaving the existing information for that given field untouched. If there is no matching reference ID in a row, Persona creates/inserts that row into Graph. Only new accounts or transactions are imported into Persona.
  - **Write frequency:** How often an Importer run occurs over a particular period of time
- **Importer run:** The specific instance of an importer reading data from a data source and attempting to write to destination objects in Persona.

## Adding a data source

To use Importers, you must connect to at least one external data source from which Persona can extract data and map onto Persona’s data schema. This section teaches you how to add a data source.

### Exploring options for data sources

- Navigate to **Imports** in the Dashboard’s navigation bar. The page opens the **Data sources** tab.
- The Imports page has two tabs: **Data Sources** and **Importers**. The first step in getting started with **Importers** is to set up a data source and grant Persona access to the data you’re looking to import.
- To add a data source, click **\+ Add new data source** in the top right corner of the Imports page.

  ![importsPage](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/importspage.png '1476x705')

- In the modal that opens up, choose the type of data source: CSV, Google Sheets, MySQL, S3, or Snowflake.
- Under **Name**, provide a name for the data source—this is how Persona refers to the data source within Graph.

  ![new data source modal](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/new-data-source-modal.png '2880x2048')

ℹ️

Some data source types may require you to provide a set of credentials in order for Persona to
retrieve your data. Because CSVs are simple file uploads, you don’t need to provide credentials to
add a CSV as a data source.

- After entering your credentials to authorize connection to the desired data source, click Create to finish adding it data source to Persona.

### Additional data source-specific guides

Creating a data source is the first step in being able to utilize an Importer to import data. For more robust information specific to data source, you can refer to the following articles:

- [Add Amazon S3 as a data source for Importers](/articles/2tjvJNnvYACPdFMa30TtN/ 'Add Amazon S3 as a data source for Importers')
- [Add Snowflake as a data source for Importers](/articles/57noRkQv9y6gz8Mn12ZXZ2/ 'Add Snowflake as a data source for Importers')

## Create an Importer

Now that you have created a data source, click **\+ Add new importer** to tell Persona how you want to map the external data.

### Step 1: Set up importer

![Importers Step 1](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/step-2-set-up-data-source-updated-2.png '1440x1024')

- In the **Name** field, name the new Importer.
- Select the database type: S3, CSV, Google Sheets, MySQL, or Snowflake.

### Step 2: Configure table

![Importers Step 2](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/step-1-select-importer-updated-3.png '1440x1024')

- Open the dropdown under **Select a data source** and select a data source from which to import information. All external data sources that have been added to your Persona dashboard will be listed in the dropdown.

  (In the example above, we use a CSV called “test-importer-run” that we previously uploaded as a data source.)

- Check that the table beneath the selected data source accurately displays the type of data source under **Name** and the columns found in this data source, listed by name, under **Columns**.

### Step 3: Set destination

![Set importer destination](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/screenshot-2024-05-16-at-11-54-44-pm.png '2886x1278')

To tell Persona where to import information,

- Using the **Destination** dropdown, select a destination object onto which the Importer will insert information. Currently, we support two destination object types: Accounts and Transactions.
- Using the **Destination Type** dropdown, specify the type of object: business, courier, UBO (Ultimate Beneficial Ownership), or User.
- - You can choose whether to create new records, updating existing records, or allow both.
- If the destination type has array fields, you can specify array update behavior.

### Finish creating the Importer.

Click **Create** to complete the importer setup process and move onto data mapping.

## Map your data onto Persona

In this section, you will learn how to map data from the data source and to write it into Persona’s data schema.

---

### Navigation bar

In the top right corner of the page, you will see the name of your Importer, the current status (e.g. Initialized, Done, Archived). On the top right, you will see any actions you can take (Activate & Run, Archive, and Save).

## Importer run details

The first section in the page displays five fields:

- **Data Source:** The name of the data source to be imported
- **Destination:** The part of Persona’s data schema onto which Persona will write information from the selected data source
- **Destination Type:** This was selected on the previous screen
- **Created at:** The time at which this importer was created
- **Importer ID:** The unique identifier for this importer

## Importer table section

This section displays the table you want to import.

If your data source has multiple tables, select the table for the Importer to read from.

If your data source has only one table, as in the example below, it displays the data source type as the first column in the table, followed by the names of the other columns that Persona is extracting from the data source.

## Column mapping section

In the Column mapping section, you can preview the data from your data source and you can select fields to write into.

### Query box

You can create data previews that only display a select number of columns by entering mySQL queries in the **Query box**. This is an optional feature—you can use Importers without it.

Click **Run** to run a **data** **preview**.

ℹ️

Note that no data is be imported at the point in time at which you click "Run," despite
appearing on the screen.

![Column mapping](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/column-mapping.png '1440x1189')

### Columns table

You can map the source columns onto Persona objects and their respective fields using the **Columns table**. From left to right, the Columns table shows the following information:

- **Source column** displays the data source column that you are mapping onto a Persona object.
- **Data preview** shows a real data sample for each column, taken from the same row of the data source
- **Accepted type** describes the accepted datatype for each column
- **Persona field** shows a dropdown that you can use to select the Persona field onto which the Importer maps the source data

ℹ️

To prevent importers from overwriting fields, each destination field can only be selected once,
and reference_id must be present for both Accounts and Transactions.

### Array type columns

For mapping to array type Persona fields from a CSV and other import types that use CSV files, you should provide JSON strings with some slight modifications.

- The JSON string has to be wrapped in double quotes.
- Any double quotes within the JSON string (to specify keys or strings, for example) must be replaced with double double quotes.

Examples of valid array column values:

```jsx
"[{\"identification_number\": \"3820\", \"issuing_country\": \"US\"}, {\"identification_number\":\"0134\", \"issuing_country\":\"CAN\"}]"
```

## Run the importer

In order to run the Importer, click **Save**. Then, click **Activate & Run**.

## Check the import run

Once the import run is complete, we recommend checking the Activity tab to view its status and confirm that all the data was imported successfully.

---

### Troubleshoot import run errors

In the example below, four objects were created successfully, but two rows errored. The errors are both labeled as “Reference ID not specified.”

![Review errors in Importer runs](https://assets.withpersona.com/f_auto,q_auto/help-center/articles/other-platform-products/review-errors-in-importer-runs.png '1650x768')

Our explorer will aggregate the rows that errored and provide information about why they errored. For an example like this, we recommend troubleshooting with the following steps:

- Download the errored rows as a CSV
- Enter the Account ID for the rows that are missing values and save the CSV file
- Add the updated CSV file as a new data source
- Run a new Importer with the new data source