Create and run an Importer

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.
  • 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, which can only be implemented by your CSM. 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.

Add 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.


Find Imports in the Dashboard

  • To open Imports, click Imports in the Dashboard’s navigation bar. The page opens to 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

  • 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

🚨 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.

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

Set up data source

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

Step 2: Configure table

Select importer

  • 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 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.

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.


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

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.

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

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

Have any questions?

Please reach out to your Customer Success Manager or Solutions Engineer to for additional support when configuring your data import.