Kavi® Members Help
Use the Upload Data tool to perform batch uploads of company, user or membership data when setting up a new site, migrating records from legacy databases or whenever you need to add, edit or delete records as a batch. Upload Data is a powerful tool designed for experienced Super Admins who are familiar with Kavi Members database fields and this specific website's configuration. If you have just a few files to upload or have not yet acquired this degree of expertise, standard Kavi Members Admin Tools may suit your purposes better since they provide extensive data filtering and validation based on site-specific configuration and rules.
This document provides general instructions for the Upload Data tool. The Upload Data tool itself is actually easy to use—preparing the data file is the complex, time-consuming part. For a list of instructions that can help guide you through the process of preparing your data file, see the Related Topics at the end of this document.
Data migration tends to be a painstaking, time-consuming task and changes committed to the database are permanent, so a wise Super Admin invests the time and effort needed for proper data preparation, knowing it will pay off in smoother data uploads and minimal need for cleanup. Although the Upload Data tool checks file structure and validity of data fields and values (including both default and custom fields) and enforces many system rules, a poorly prepared data file can introduce errors that aren't detectable by the software, so the Super Admin is ultimately responsible for the results of the upload process. In a worse case scenario, a bad data upload can corrupt information in the database so severely that the only remedy is to revert to a backup version of the database. When this happens, any new data introduced between the time the backup was created and the time the database was corrupted will be lost.
Populate the Kavi Members database for website setup.
Add multiple new companies or users to the database.
Edit multiple companies or users simultaneously.
Add historical and current memberships for site setup.
Permanently delete a batch of company or user records from the database.
Perform a mix of actions on company or user records: adding, editing and deleting multiple records in a single upload process.
Change user or company purposes. This is particularly risky, so be sure to read the instructions first.
Properly prepared data files are a prerequisite for the upload process. Begin by clicking one of the links at the top of the Upload Data tool to download a data file or template in CSV format. If you haven't worked with CSV files before, read Preparing CSV Files for Upload Data.
Now follow the instructions for your data type (e.g., Company or User) and action in How to Add Records through Upload Data or How to Edit and Delete Records through Upload Data.
Download your CSV Template or Data File:
- To Add New Users
Click the 'CSV template for adding new users' link to download the person.csv template. The template contains column headings but no data. This template should not be used to edit or delete existing users.
- To Edit or Delete User Records
Click the 'CSV data for editing existing users' link to download the person.csv data file. You are taken to a search page where you can set parameters to selectively retrieve the records you want to edit or delete. The narrower the set of records retrieved from the database, the fewer that you'll have to weed out of the data file by hand.
- To Add New Companies
Click the 'CSV template for adding new companies' link to download the company.csv template. The template contains column headings but no data. This template should not be used to edit or delete existing companies.
- To Edit or Delete Company Records
Click the 'CSV data for editing existing companies' link to download the company.csv data file. You are taken to a search page where you can set parameters to selectively retrieve the records you want to edit or delete. The narrower the set of records retrieved from the database, the fewer that you'll have to weed out of the data file by hand.
Now that you have your carefully prepared CSV data file ready, you may begin the upload process by performing a test run to check file structure and perform some basic validity tests on required and custom fields before preforming the actual upload. If you skipped the instructions on file preparation in hopes that the tool would automagically detect any errors you might possibly introduce, you may want to go back and read the instructions before proceeding, since you are responsible for the results of your data upload.
The Test Run option allows you to preview the changes that will be made to the database before permanently committing the changes. Whether you select the Test Run option or not, the Upload Data tool may detect errors that need to be fixed before the upload process can be completed. If you are notified of any errors in your data file, click the Back button to return to the first step, correct your CSV data file, then repeat this step. The Upload Data tool retains all your option settings, so you don't have to reset these fields each time you repeat a test run. You don't even have to browse for the data file again unless you save it under a new name or in a different location.
- CSV File
Browse for the CSV data file on your hard drive and select it for upload.
- Data Type
Select 'Company' if you are uploading a company data file, or 'User' if you are uploading a user data file.
- Send Email
- Do NOT send any email.
The Send Email option is set to 'Do NOT send any email.' by default so that email that is normally scheduled to go out when records are added or edited is suppressed. Super Admins rarely change this setting, since most prefer to perform the upload quietly and generate any required email notifications manually through the template blast tools. This option doesn't affect or suppress the Upload Results Email that is mailed to you or other administrators as the upload process completes.
Select this option except on those rare occasions where you do want scheduled email to be sent. For example, if you add new users to a live site, you probably want the new member welcome email to go out. This option won't suppress the Upload Results Email. You will have an opportunity to notify companies or users who have been affected by data changes after the upload operation has been performed.
- Send all scheduled email.
This is rarely used, except when you add new users to a live site, in which case you want the new member welcome email to go out.
- Test Run
The Test Run feature checks your data file and identifies errors that need to be corrected before you commit your changes to the database. It also allows you to preview the kinds of changes that the upload will make in the database before performing the actual upload. When you perform a test run on a data file, the validation results will notify you of any errors encountered during the test run. Make whatever corrections are necessary and repeat the test-run-and-correction cycle until your data file passes the test run without any validation errors.
To perform a test run, set the 'Test Run' option to 'Do a test run.' Be sure to add the email address where you want your test results sent in the 'Email Results To' text box. Give the process a few minutes to complete before you check your email in-box for the 'Validation Results' email.
The results are presented as a) a total number of rows, b) the number of 'good rows' and c) the number of 'bad rows'. The first row of the data file contains column headings, so the number of 'good rows' should equal the total number of rows minus one, since 'good rows' refers only to the rows that contain actual data.
Review the results email. If you are satisfied with the changes that will be made to the database, your file is ready for upload. Press Upload Another File to return to the Option step, set the 'Test Run' option to 'Do NOT do a test run. Do the real upload.' and follow the steps to commit your changes to the database.
- Email Results To
Enter the email address that you are currently monitoring so you can check the results easily. When you perform the actual upload, you may add the addresses of any other users who should receive the results.
Validation Results are displayed for you to review. This may include a list of errors encountered during the upload process, followed by a list of all successfully uploaded rows. The results describes the type of error and the row in which it was found. If your data file contains validation errors, click the Back button to return to the Options step, correct the errors, save and retest the file as described previously.
If the file passes the validation check, click the Upload Data button. If you are using the Upload Data tool in test run mode, no changes are committed to the database. If you completed the test run process and are performing a real upload, your changes will be committed to the database.
The Upload Data tool provides the Super Admin with a lot of information about errors in the data files. Hopefully you have only a few errors in your data file and the information provided at the validation step or in the results file is enough to help you remedy any errors. If you have a lot of errors, you may want to go back and reread the instructions while checking your file thoroughly to be sure that it is properly structured, all appropriate fields are present and all values adhere to the expected formats. If your data appears to be complete and accurate and you are still receiving error messages, here are a couple of errors with obscure causes.
- Company or user does not exist error
If the Upload Data tool rejects a row because a company (or user) does not exist and you're quite certain that it does, there may be a typo in one version of the name. To retrieve the record from the database, enter some part of the name that doesn't include any white space and let Kavi Members search for partial matches.
If the name in the retrieved record mysteriously appears to be an exact match for the name in the data file, it's possible that the there is a hidden character in the white space. Double spaces, tabs or carriage returns display as a single space when viewed through a browser, so copy the name into a text editor or word processor to see if there are any discrepancies between the name in the Kavi Members database and the name in your upload file.
- Special characters
You may encounter problems uploading files with special characters, even if the character is in the ISO8859-1 character set and the data file was saved in this format. Special characters (e.g., curly quotes, non-English characters, etc.) are problematic and are not supported as standard input to the Upload Data tool.
- Characters added or removed by spreadsheet software
Spreadsheet software is designed to intelligently anticipate user needs, so it can helpfully but stupidly remove leading zeros, convert long strings of numerals into scientific notation rounded off to two decimal places, add newline characters and otherwise wreck annoying havoc on your data files. Many people prefer to work in CSV files for this reason, but it is easier to view and maniplate data in a spreadsheet. If you use a spreadsheet, you might want to store an extra version of any data file you download from the database until you are positive that your data has uploaded properly. The only way to prevent much of this behavior is to prepare the spreadsheet in advance by setting all the cell formats to 'plain text' before opening any files with problematic number-like fields such as zip or postal codes, credit card numbers, etc. Have fun and good luck.
Your data has been uploaded and the Upload Results Email has been sent to the specified email addresses. Always examine the results email to see if there were any errors that weren't detected during the basic data validation check. Some errors that aren't truly validation errors can only be detected by a person who is familiar with the data (i.e., yourself). If the results meet with your approval, the data file is ready for upload. Click Upload Another File, reset the 'Test Run' option to 'Do NOT do a test run. Do the real upload.' and run back through the steps to perform an actual upload. If you have any concerns or questions, contact Kavi support before proceeding with the actual upload.
Instructions and Reference Documents: