Kavi Help CenterKavi® Members Help
| Chapter 23. How to Add Records through Upload Data | ||
|---|---|---|
 |
Part I. Kavi Members Concepts and How-tos | 
|
Table of Contents
The Upload Data tool can be used to add large numbers of new companies or users. First time memberships can be added simultaneously. This can be done during site setup or any time the organization needs to add new records in bulk, such as after a membership drive. This document walks Super Admins through the data file preparation process.
The Upload Data tool tests the data for validity before accepting it for upload, but since it is designed to upload records in bulk, it can't check each record individually in the same way that other Kavi Members Admin and User tools can. Errors introduced into the database through the Upload Data tool have the potential to affect multiple records, so there is no substitute for careful file preparation. This requires a great deal of knowledge and careful attention to detail on the part of the Super Admin. You'll get better results if you read and follow these instructions each step of the way, then study the results file before committing the changes to the database.
Back to topThere are a couple of rules you need to know before you begin.
Every user has to be assigned to a valid company during the data upload process, so new companies must be added to the database before you can add users who belong to those companies. Companies and users are added separately, so if you need to upload both companies and users, you'll have to prepare separate data files.
-
You can only upload first time memberships or historical memberships. Once a company or user has a membership, subsequent memberships need to be added through tools expressly designed to support membership renewal or replacement so that the system can maintain the membership history accurately.
If you are adding new members, you don't have to add memberships at the same time that you add the member. If you do add the memberships later, you'll actually do it by editing the member's records to add the memberships.
Instructions for adding memberships are provided in a separate document: How to Add Memberships through Upload Data. If you want to add memberships while adding new members, go ahead and prepare the member records first and when you're done with basic data file preparation, you can follow the instructions for adding the membership information. Or you can prepare a member record first, then add the membership information on a row-by-row basis since adding memberships isn't as complex as adding a company or user record. Or you can add the member records now, then edit the records to add the memberships during a separate upload process. Whatever works best for you.
Because the data upload process is complex, there is quite a lot of documentation available.
There are four guides that provide detailed information about all the default data fields, including whether the field is required or not, what value will be inserted in the record if the value isn't specified and tips on how to format the data for best results. You probably want to work with one or more of these guides open in a browser window for handy reference. The data guides are divided into sections on Company Data Fields, Membership Data Fields and User Data Fields.
If you haven't prepared data for this tool before or would like some tips on working with comma-separated values, see Preparing CSV Files for Upload.
When your files are prepared and you are ready to proceed with the upload, consult the Upload Data page help for instructions.
Be sure all other Kavi Members configurations steps are complete before you begin to upload data—particularly membership renewal configuration and the addition of custom fields—as database structure and validation rules are determined by configuration. When you download the company.csv and person.csv templates, the column headings will reflect site configuration and all default and custom fields that exist in the database will be present.
Your organization needs to have some custom types defined in order to classify companies or users. If membership is enabled, a Company Type or User Type is commonly created for each membership type, so companies and users are classified according to the type of membership they hold. But if your organization grants accounts to nonmembers, consider adding one or more Company Types or Users Types to classify companies or users independently of membership and provide basic website access. These types can be assigned during the data upload process, then immediately used to sort users into directories, retrieve them through searches, etc. These types may be persistent or may be replaced with other types as site setup progresses or the organization formalizes its membership categories, etc.
Company and user data files must be uploaded separately. Since Kavi Members requires every user to be assigned to to a company, company data must be uploaded first. Follow the Add Companies instructions. You may add current and historical memberships for these companies during the initial upload or as a separate upload operation as described in How to Add Memberships through Upload Data.
Next, follow the instructions for Adding Users. You may also add current and historical memberships for these individuals, as described in How to Add Memberships through Upload Data.
The 'upload_action' column is required and must contain the value 'add'.
Values provided in the data file will be assigned if the value is valid. Fields are validated during Upload Data's validation step and invalid values raise errors.
Required fields without values (i.e., empty fields) are set to default values. These are often configuration-dependent, as described in the following tables and in the data field guides.
To begin the data preparation process, download the person.csv template through the link provided through the Upload Data tool and open it in a spreadsheet application or text editor. If you open it in a spreadsheet, it's easy to see the column headings and table structure. The rows below the column headings will contain the data records, with one record for each row.
Table 23.1. Fields Required by Upload Data Add Operations
| Column name | Instructions |
|---|---|
| upload_action | This should be the first column in the data file. Enter 'add' for every record in this column. |
| name | Add the company name. This name must be unique, so if you haven't yet checked your data for duplicates as described in Preparing CSV Files for Upload, this would be a good time to do it. |
| purpose | Add the company purpose. |
Table 23.2. Other Fields Required for Add Operations
| Column name | Instructions |
|---|---|
| accepted_domains | If accepted domains are enforced for this site, this column will appear in the template. Be sure to add a comma-delimited list of accepted domains for each company or the company will NOT be available on the Company Representative Signup form. |
| company_type | Assign one or more Company Types to each company. Multiple types must be comma-delimited. If this field is empty, whatever Company Types are designated as default for companies of this purpose will be assigned automatically. |
| display_publicly | Set this to '1' if the company's information should appear in the directory. Set this value to '0' (zero) if the company wants its information hidden. Defaults to '1' if not specified. |
| show_on_signup_form | Set this to '1' if this company should be listed on the Company Representative Signup Form. Set to '0' for all other companies, especially if the company purpose is 'Staff Company' or 'Company for Individuals'. Defaults to '1' if not specified. |
| status | If this is set to 'active', users who belong to the company will have website access. If this is set to 'inactive', users who belong to the company will NOT have website access and the company will be hidden from directories and signup forms. Defaults to 'active' if not specified. |
| signup_date | This is the date the company became involved with the organization as a member, prospective member, staff company, registered nonmember, etc. (in YYYY/MM/DD format). This is important historical information, so be sure to set this value if the data is available. If you are adding this company as part of site setup, the signup_date probably predates the creation of the website. If you don't specify a date, this defaults to the current date. |
A data file used to add companies when populating the database for the first time should look something like this. Since companies must be added before users can be added, these companies include a staff company, a company created to group individual members, a nonmember company from the adopter community and a member company whose membership will be added later.
This example only includes required fields. In reality, you'd want to add all available information for each company, so your data file would have many more columns. It might also contain custom fields that aren't described in any of the help documentation.
Description:
The first company added to the database is added to group the organization's staff. This "company" is added because the staff can then be managed like any other company in the database, assigned types created specifically for them to confer roles they need to access special staff-only areas and mailing lists, etc.
Since this organization offers individual memberships, the second "company" is added to group individual members so they can be managed effectively.
The third company is a nonmember company that is classified as an adopter by assigning an 'Adopter' Company Type. This nonmember company has been associated with the organization for some time, so the 'signup_date' is set to the actual date that this event occurred.
The fourth record belongs to an active member company that wishes to remain hidden from directories and the Company Representative Signup form. In this example, the company membership is going to be added in a separate data upload.
Table 23.3. Sample data file for adding companies
| upload_action | name | purpose | display_publicly | show_on_signup_form | status | signup_date | company_type |
|---|---|---|---|---|---|---|---|
| add | Organization Staff | Staff Company | 0 | 0 | active | ||
| add | Individual Sponsors | Company for Individual Members | 1 | 1 | active | ||
| add | Existing Nonmember, LLC. | Nonmember Company | 0 | 0 | active | 2000/01/01 | Adopter |
| add | Hidden Member Co. | Member Company | 0 | 0 | active |
Since Kavi Members requires users to be assigned to companies, you can't add a user to the database unless the company already exists in the database. Upload company records first or add companies manually through Kavi Members Admin Tools.
Download the person.csv template through the link provided through the Upload Data tool and open it in a spreadsheet application or text editor. Follow the data preparation instructions outlined below. To view an example of how your data file might look, see Sample data file for adding users.
If you want to add new memberships for individuals, follow the additional file preparation instructions in How to Add Memberships through Upload Data.
Important
When you add new users to a live site, enable email so that the new user welcome email is sent out. This scheduled email includes a login link so new users can log in, set their private passwords and begin to enjoy their website privileges.
- User Purpose and Company Purpose
User Purpose is a required field, and the sample includes users with different kids of purposes. Some of these users belong to companies that don't exist in the real world, but were added to Kavi Members to group users so they can be managed more effectively. These companies have a purpose of 'Company for Individuals', and users who belong to these companies have a purpose of 'Individual Members' or 'Individual Nonmembers'. There is a correlation between User Purpose and Company Purpose. The 'Company Representative' User Purpose is compatible with 'Member Company' or 'Nonmember Company' Company Purpose. The User Purposes of 'Individual Member' or 'Individual Nonmember' are compatible with the 'Company for Individuals' Company Purpose. The 'Staffperson' User Purpose is compatible only with the 'Staff Company' Company Purpose.
- primary_email
You always want to enter the 'primary_email' address if available. Users who are added to the database without a primary email address won't be sent login links via the regularly scheduled email templates, so extra steps are required to get these users set up to login.
- individual memberships
If you are adding users for an organization that offers individual memberships, you probably want to upload memberships as you add users. See How to Add Memberships through Upload Data for instructions.
- primary_contact
If this is a company-based or mixed organization, it is extremely useful to designate one user as a Primary Contact for each company. To do this, set the user 'purpose' to 'Company Representative', add the value 'Primary Contact' to the 'company_contact_types' field and be sure to add a 'primary_email'
- signup_date
When populating a database you may want to specify the 'signup_date' to create a historic record of the user's membership in the organization. If not specified, the 'signup_date' is set to the current date.
| Column name | Instructions |
|---|---|
| upload_action | This usually appears as the first column in the data file. Enter 'add' for every record in this column. |
| first_name | This individual's first name (i.e., given name). |
| last_name | This individual's last name (i.e., family name). |
| company_name | The name of the company to which this user belongs. This must be an exact match to an existing company name. If you enter a name that doesn't match the name of a company in the database, you will have to add or edit the company before adding users who belong to this company. |
| purpose | Add the appropriate purpose for each user. It is very important to assign the correct purpose, as the purpose you assign determines how this user is managed in the system. |
| Column name | Instructions |
|---|---|
| company_contact_types | Every user must be assigned at least one Contact Type to establish their relationship to their company. These types can also be assigned to designate special kinds of company representatives such as 'Primary Contact', 'Billing Contact', etc. This field will be set to the designated default type(s) if not specified when uploading new users whose purpose is 'Company Representative'. If you are populating the database during site setup and do not want to use the 'Employee' type that is installed by Kavi Members, you must add types through the Manage Contact Types tool before populating the database. It is extremely useful to have a Primary Contact designated for every company in the database, so be sure to assign the 'Primary Contact' type to any user who is to act as their company's Primary Contact. |
| company_purpose | An organization that offers memberships to both companies and individuals may have two records for the same company in the database, where one company's purpose is 'Member Company' and the other is 'Company for Individuals'. When this is the case, you must add the company_purpose to be sure the user gets assigned to the right company. |
| display_publicly | If this is set to '1', the user's information will appear on the roster. If your organization offers a privacy opt out, you may set this to '0' (zero) to have user information hidden on the roster to protect user privacy. Defaults to '1' if not specified. |
| member_types | This field actually containsUser Types. You may optionally assign one or more User Types. User Types assigned only through membership should not be assigned during an upload. |
| primary_email | If a primary email address is available, be sure to include it in the data file so the user can receive login links by email. Each email address must be unique. If accepted domains are enforced, the Upload Results will include a warning if a user's primary email address doesn't use an accepted domain. |
| receive_email | This is one of the privacy options that users can set if the site is configured to allow this. Set this field to '1' if this user should receive general announcements and email from the Members list or '0' if this user should NOT. Defaults to '1' if not specified when adding users. If a user has indicated they don't want to receive announcements or this type of user isn't to be sent announcements under organization policy, set this to '0'. |
| signup_date | Set this to the date this individual became associated with the organization or leave it empty to have it set to the current date (in YYYY/MM/DD format). |
| status | Set this to 'active' if the user should be allowed to login, or 'inactive' if not. |
| username | This column is ordinarily omitted from the data file when uploading, but if you do upload a username it must be unique. |
A person.csv data file used to add users when populating the database for the first time should look something like this. Companies must be added before users can be added and every user record must include the name of the company to which the user belongs.
This example only includes a partial set of required fields, including all fields required by the Upload Data tool but a subset of the fields required by the database. Fields required by the database but not included in the data file will be automatically set to the default values. For example, the Status of all users added through this sample data file would be set to 'active'. In reality, you'd want to add all the information that was available for these users, so your data file would have many more columns. It might also contain custom fields that aren't described in any of the help documentation.
Description:
The first new user belongs to a "company" that represents organization staff as a group. To give this staffer access to organization data and Admin Area tools, the default User Type 'Organization Admin' is assigned in the 'member_types' field. The Contact Type 'Employee' is assigned in the 'company_contact_types' field, because this user is an employee of the organization.
The second user is a representative of a nonmember Adopter company. This organization offers formal memberships, but also allows nonmembers to hold accounts. This user is designated 'Primary Contact' in the 'company_contact_types' field. This user isn't a staffperson so it wouldn't be good to assign any privileged User Types, but she is assigned a general User Type that classifies her as an Adopter.
The third record belongs to a user from a company that has just been added to the database as a potential member. Even though the user's Status will be 'active', the user won't be able to access protected areas of the website at this time because their company doesn't yet have membership. If the company membership is approved, this user will inherit the 'member' role from their company. If the company membership isn't approved, the company will be deleted and all users who belong to the company will be deleted simultaneously.
Table 23.4. Sample data file for adding users
| upload_action | signup_date | first_name | last_name | primary_email | purpose | company_name | company_contact_types | member_types |
|---|---|---|---|---|---|---|---|---|
| add | Daniel | Webster | dan@staff.kavi.com | Staff Company | Organization Staff | Employee | Organization Admin | |
| add | 2000/01/01 | Techla | Techie | techie@adopter.kavi.com | Company Representative | Existing Nonmember, LLC. | Primary Contact | Adopter |
| add | New | Bie | new.bie@example.net | Company Representative | Applicant Company, Inc. | Primary Contact |
|
|
 |
|
| Chapter 22. Using Website Tools to Send Email Manually |  |
Chapter 24. How to Edit and Delete Records through Upload Data |