When To Use It
Use Imports to put entire lists of supporters into Salsa in one go from an outside database or spreadsheet. Imports are a powerful, flexible feature. They feature heavily in the setup of most new Salsa accounts, but are also frequently useful for a variety of ongoing data management needs.
How To Get There
Imports begin outside of Salsa, with a data source of some kind that will need to be saved into a delimited file for import. (We'll discuss more on how to do that below.) Once there's an import-ready delimited file, navigate to the Import Supporters tool in the Supporter Package.
Here's a short training video with an overview of the import process. Full feature documentation is found below.
Preparing Your Data for Import
The first step to importing happens outside Salsa altogether: you'll need to ready your data for import by getting it into a Salsa-friendly format.
Formatting Your Import File
An import file should comprise data that can be held in a single worksheet of Excel or a similar spreadsheet application.
That spreadsheet should hold:
- One horizontal row per supporter (or other record) to create in Salsa
- One vertical column per field whose data will be filled in each of those records
You probably have a lot more information than just email: first names, last names, addresses, phone numbers, and so forth. There is no maximum or minimum "width" to your import spreadsheet.
A Note About Preventing Duplicate Records
By default, Salsa deduplicates based up the Email field. This means that Salsa takes the Email field from your import and searches your existing supporter records for any identical email address. When it finds a match, it knows to update an existing record (rather than creating a new one). For this reason, you should always include Email as one of the columns in your source file.
If you want even more assurance against duplicate records, you can add additional columns for these data points. The Salsa Import Tool seeks a data match using these three fields, in this order, if any of them are provided in the import file:
1. supporter_KEY - A distinct ID number assigned by Salsa
2. uid - An optional unique ID field that you can fill with values generated from an outside database
No matter how much (or how little) you're importing, every column in an import spreadsheet should contain only one single piece of information. For example, First Names and Last Names need to be in two distinct columns. The same goes for addresses, which must be broken up into separate columns for Street, City, State and Zip.
We have a template tab-delimited text file that you can download to see how best to format your data for import into Salsa.
Wary? If you're new to the imports feature or unsure how Salsa will render the data in your file, a good way to start might be to make a test import file comprising just the first three or four lines of your potential import. Import that test, then eyeball the resulting data before proceeding with the full file import.
Saving Your Import File
The last step in prepping your data is saving it to a usable format. Because Salsa cannot import directly from an Excel or OpenOffice spreadsheet, you'll need to save your data in a tab-delimited text format. Also, be sure not to include any special characters in your filename. This process will work for most files, but if you have international characters, please use the alternate process noted below.
1) Open your correctly formatted Excel file
2) In the File menu, click Save As
3) Select the Format drop down list and select Tab Delimited Text. Click .
4) When prompted with the scary message that some features may be removed, click to convert the file anyway. This is just Excel being proprietary.
Salsa can readily handle data sets that contain non-English characters. Usually, you'll just need to do one quick preparatory loop before import.
1. Saving Your Import File with International Data
Ensure the source import file is saved with a compatible character encoding, ideally UTF-8. Follow these steps:
For instance, the process for generating a compatible import file for Excel is typically:
- Save-as a tab-delimited text file as described above.
- Close and then reopen the newly-saved tab-delimited text file in a plain-text application such as Notepad.
- Select File > and set the value to UTF-8.
Basic Supporter Import
Your import file is ready, and Salsa is ready. Now, let's do what you came to do - Import a list of supporters!
The import tool is located in the Supporter Management tab. Click the Supporter Management tab, then click "Import Supporters" in the sub-navigation menu:
It's just a two-step process.
Step 1: Choose your data source
When you've opened Salsa's import feature, you'll immediately see the first step to run an import: selecting the data file that you'll be importing.
- Option 1: Click the "Browse" button next to the Filename field to import a file (you'll usually use this option). This option is illustrated below.
- Option 2: Simply paste the data into the text area at the bottom of the page if it's a really small amount of data. This option is not recommended.
Other step one options
For most everyday supporter imports, choosing a file and its appropriate delimiter is all you need to do on step one. You can freely ignore the other options in this step unless you have specific reason to use them.
- Write-In Table enables advanced users to import to Salsa data objects other than the Supporter table. (Advanced users desiring more information about each field and data type, please see here.)
- Similar Uploads may help shortcut the second import step if you regularly import data files that look pretty similar to one another.
- Character Encoding is important only when importing non-English data characters.
Click to upload the file and move on to step 2.
Step 2: Match your spreadsheet columns to Salsa's field names
In the second step of the import process, you tell Salsa to insert Tab A into Slot B.
You should now see a two columns:
- A list of fields matching the top row of data in your import file; and,
- A parallel column of pull-down menus full of Salsa fields.
Your task is simple, but incredibly important. You must match your column headers (on the left) with Salsa's field names (on the right). This ensures that your data gets stored in the correct place. You also have the option to set any column to "Ignore" to have the importer disregard it. A complete list of of the fields in Salsa's supporter table is here.
If the second step shows you garbled data, or all your data in a single field, the importer didn't understand your file. Return to step one and try again. The most common cause of this is choosing the wrong field delimiter (e.g. tab instead of comma) in step one.
Supporter Groups and Tags
To add all supporters in this source file to be added to a particular group (which must exist prior to the upload), or given a particular tag, you can specify them here.
If you want to add some supporters in this source file to one or more groups and tags, read more information about formatting groups and tags for import.
NOTE: You may only import existing supporters against groups that they are not already assigned to.
Most regular imports can just ignore these steps.
- Skip Lines enables you to put a number of rows in the import spreadsheet that you'd like Salsa to skip over. Often, the first line of a file will have the column names in it, instead of actual values, and it can be helpful (though not essential) to skip that one line in order to avoid create a supporter whose first name is "First Name."
- Deduplication overrides Salsa's default deduplication logic by keying it to any supporter field -- or turning it off deduplication entirely for the current upload.
- Overwrite Options modify Salsa's behavior when the import's deduplicator does match an incoming row to a record already in Salsa. Absent any of these settings, such a match will result in Salsa
- Overwriting existing data with the data for a corresponding field in the import. (e.g., if the pre-existing supporter record has a First Name of "Joe" and the import has a First Name of "Joseph", "Joseph" will be the First Name in the record post-import); and
- Ignoring null or empty values in import fields. (e.g., if the pre-existing supporter record has a First Name of "Joe" and the import has a blank value for First Name, "Joe" will be the First Name in the record post- import).
When you're ready with field matching and any additional settings, hit the button!
A note about e-mail subscriptions
Salsa's baseline behavior is to assume that it's managing a list of (actual or potential) recipients of mass email blasts. If you're importing a list of people who should not receive email, include a column in your import file with the value of 0 for every row in the import. Have the importer write that column to Salsa's Receive Email field.
What if there's a problem?
It's easier to prevent problems than to fix them. If you're unsure of your import, take these precautionary steps first:
- Use the Query/Export tool to run a query of your entire supporter list and export that data to Excel. This creates a backup of data stored on the supporter table.
- After you finish formatting your source file, make a copy of it and delete all except a few rows in the copy. Import this copy first and spot check the data. After you've verified the data in this "mini-import," go back and import the complete file.
Despite all of those precautions, mistakes can still happen. To help you sort out the data should this occur, Salsa automatically creates two system-generated tags for every import (where XXXXX is the unique ID number of the import):
- import:createdXXXXX - New records were created by the import
- import:updatedXXXXX - Pre-existing records which were "touched" by the import.
Running a query on these two tags will help you identify every record which was affected by this import. If there is a problem, this list of supporter records gives you a place to start restoring your data (and a place for our support team to start helping).