Kavi Help CenterKavi® Members Help
| Appendix F. Sample User Data Files for the Upload Data Tool | ||
|---|---|---|
 |
Part X. Appendix | 
|
Table of Contents
The samples presented here appear in tables to reflect the way the data file would appear in a spreadsheet. To see how a CSV file would appear in a text editor, see Text editor view of CSV data file.
A 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.
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'.
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, 'status' of all users added through this sample data file would be set to '1' (i.e., '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.
You always want to set the 'primary_email' 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.
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.
If you are populating a database for an individual-based or mixed organization, you probably want to upload individual memberships as you add users. For an example of a data file used to add preexisting and new memberships as users are added, see the sample Data file to add new users and memberships.
It is extremely useful to designate Primary Contacts if this is a company-based or mixed organization. To add a Primary Contact, 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'. On the other hand, you may not need to specify 'member_types' (i.e., User Types) because User Types are usually assigned automatically through membership, or are highly privileged types assigned selectively to staff or administrators through Admin tools.
Sample file description:
The first row contains the column headings and the second and subsequent rows contain records of users being added to the database.
The first new user is legal staff and belongs to a company with the purpose of 'Staff and Administration'. This user has been assigned the 'Company Admin' Company Administration and Contact Type, which gives the user access to tools that can be used to manage company data in the Company Area.
The second is a representative of a nonmember company. This organization manages registered nonmembers rather like members, but with fewer privileges. This user is the company's designated Primary Contact.
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 '1' (i.e., active), the user won't be able to access protected areas of the Web site at this time because their company is inactive and they don't have any roles that confer access privileges. If the company membership passes the billing and moderation steps and is approved, this user will inherit the 'member' role that grants basic Members Area access through Company Types assigned to their company when the membership goes current. 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 F.1. Sample data file for adding users
| upload_action | signup_date | first_name | last_name | primary_email | purpose | company_name | company_contact_types |
|---|---|---|---|---|---|---|---|
| add | Daniel | Webster | dan@legal.kavi.com | Staff or Administration | Legal Co. | Company Admin | |
| add | 2000/01/01 | Techla | Techie | techie@adopter.kavi.com | Company Representative | Existing Nonmember, LLC. | Primary Contact |
| add | New | Bie | new.bie@new.net | Company Representative | Applicant Company, Inc. | Primary Contact |
If you are adding memberships for individuals, your data file will look something like this. For simplicity's sake, this example includes only the fields that the Upload Data tool requires when adding company memberships plus the 'signup_date' field. When this file is uploaded, other fields required by the database (i.e., 'purpose', 'display_publicly', 'receive_email', 'status', 'member_type' and 'company_contact_type') will be set to the default values. Every user must be assigned a 'company_contact_type' (i.e., Company Administration and Contact Type), so even though these users are individual members, this will be set to 'Employee' or a default value specific to the site. Values for the 'member_types' field will be set automatically if a default has been set for the site and others will be assigned through membership as the membership passes through the membership workflow.
Sample file description:
The first row contains the column headings and the second and subsequent rows contain records of companies being added to the database.
The first record belongs to an applicant whose new membership will go through the normal membership workflow. Depending on the way the membership type is configured, the membership may be subject to billing or moderation steps or may automatically pass these steps and be approved. The start and end dates will be added when the membership is approved.
The second record belongs to a member who joined the organization the year before the database was created and renewed, so they already have a current membership for this year. If adding memberships that are already current but the membership type has billing or moderation steps, the memberships won't go current until the memberships are moderated and any membership bills are paid. Organization Admins can use the Individual Membership Applications tool to moderate these memberships in bulk. When viewing the CSV file through a text editor, the series should be encased in doublequotes like this: "Historical Individual Member, Current Individual Member","2005/01/01,2006/01/01","2006/01/01,2007/01/01".
The third record belongs to a founding member who has participated in the organization for two years prior to the creation of the database. The start date has been specified so that the actual date that this individual became involved with the organization will be available in the database. No end date is specified but since this is a lifetime membership, the end date value will be set as the membership moves through the workflow.
Table F.2. Sample data file for adding users
| upload_action | signup_date | first_name | last_name | primary_email | purpose | company_name | membership_types | membership_start_dates | membership_end_dates |
|---|---|---|---|---|---|---|---|---|---|
| add | 2006/04/14 | Sole | Mio | solo@individual.kavi.com | Individual Member | Individual Members Group | Current Individual Member | ||
| add | 2006/04/14 | Preexisting | Personage | preexisting@research.example.com | Individual Member | Example Co. | Historical Individual Member, Current Individual Member | 2005/01/01,2006/01/01 | 2006/01/01,2007/01/01 |
| add | 2006/04/14 | Preexisting | Founder | founder@hq.example.com | Individual Member | Example Co. | Individual Founding Member | 2004/04/14 |
If you need to edit a large percentage of the records in the database you might choose to download the 'person.csv' file through the Upload Data tool. If you were only going to edit a small percentage of records in the database, you might choose to run a report such as the Person Data Report and use search criteria to narrow the set of records retrieved through the search.
It's also possible to upload a data file where some records are edited and others are deleted or added. For an example, see Preparing a mixed-action data file.
Sample file description:
Imagine an organization has decided to change Kavi Members configuration to enforce accepted domains, so the Super Admin is adding or editing the records of users whose primary address doesn't contain an accepted domain. The Super Admin will have collected a list of accepted domains and user email addresses for each member company. The company records will have been updated in a separate data file upload.
The required 'upload_action' column will already contain the value 'edit' if the file was downloaded through the Upload Data tool, otherwise the column and values will have to be added.
The 'item_key' column is also required. These values must never be edited. If you accidentally edit this value, you will not be able to upload this record without correcting it.
The 'company_name', 'first_name' and 'last_name' columns aren't required by the Upload Data tool, but the Super Admin uses this information to determine which company the user belongs to and which user the record belongs to. The data file should probably be sorted by company name to make it easier for the Super Admin to check the 'primary_email' values against the list of allowed domains.
The Super Admin will check the 'primary_email' field for each user to see whether the address uses an accepted domain. If the record already contains a primary email address with an accepted domain, the row containing the record will be removed from the data file to streamline the upload process. If the primary email addresses uses some other domain, the Super Admin will edit the value by inserting the correct address for that user.
The first row contains the column headings and the second and subsequent rows contain user records retrieved from the database.
The rows containing records would contain records that did need to be changed. These rows are for users from the same company.
Table F.3. Sample data file for editing users
| upload_action | item_key | first_name | last_name | primary_email | company_name |
|---|---|---|---|---|---|
| edit | abb1234 | New | Bie | new.bie@example.com | Example Co. |
| edit | arz4567 | Old | Timer | old.timer@example.com | Example Co. |
Most users are added to the database when they apply for individual memberships or signup as representatives of member companies, but this isn't always the case. Organizations may create startup Web sites without the membership feature, then enable this feature later when their membership structure has been formally defined. Users may also be added without memberships when populating the database as part of the setup process, then memberships are added in a separate upload. Organizations that track nonmembers may convert some nonmembers to members by resetting the user's purpose and adding memberships.
If you are adding memberships by editing companies that are already in the database, begin by downloading data through the Upload Data tool person.csv' data file link or through a report such as the Person Data Report. If you use a report, you might set the search criteria so that only users with the 'Individual Member' purpose are returned if you are adding memberships as a separate step when populating the database, or 'Nonmember' if the organization has been tracking potential members who have now decided to join the organization. Be sure the 'item_key' field is included in the report results. If you downloaded the 'person.csv' data file through the Upload Data tool, you could sort the results by the 'purpose' column heading and remove companies that don't have the appropriate purpose. Remove any other records you don't want edited and any unnecessary columns, then add the memberships.
Sample file description:
This sample includes the 'upload_action' and 'item_key' columns, which are required by upload data and must contain valid values. It also contains the three columns used to add memberships. These columns are all required, but only the 'membership_types' column requires a valid value. Values are specified for the two date columns, 'membership_start_dates' and 'membership_end_dates', only if the values that would be set by default during the normal membership workflow are inappropriate under the circumstances. The 'purpose' field has been included so that it can be reset for any individuals with incompatible purposes.
The first row contains the column headings and the second and subsequent rows contain records of individual memberships being added to the database.
The first record shows a single membership being added for an individual. The 'membership_start_dates' and 'membership_end_dates' fields have been left blank. These values will be set as the membership passes through the regular membership workflow.
The second record shows a single membership being added for an individual who is a founding member of the organization. This individual's membership predates the creation of the database, so the start date is in the past. A 'Founding' membership is a lifetime membership, so the value in the 'membership_end_dates' field is set to 'Lifetime'. This field could also have been left blank.
Table F.4. Sample data file for editing users to add memberships
| upload_action | item_key | first_name | last_name | purpose | membership_types | membership_start_dates | membership_end_dates |
|---|---|---|---|---|---|---|---|
| edit | 55e555 | Neu | Welle | Individual Member | Individual Sponsor | ||
| edit | 55ln66 | August | Founderi | Individual Member | Individual Founder | 2005/03/27 | Lifetime |
The delete action is very simple. It is also very permanent. If you want to delete users who belong to a former member or staff company that is no longer associated with the organization, just delete the company and all users who belong to that company will be automatically deleted. This doesn't apply to individual members, who belong to companies created specifically to group individuals (i.e., "companies" with the purpose of 'Company for Individuals'). These companies cannot be deleted, and these users must be removed by deleting their individual records.
For information on deleting companies, see Preparing a data file retrieved through report tools for hints on using company reports to prepare company records for deletion. For information on preparing files where you want to delete some records while adding or editing others, see Preparing a mixed-action data file.
Sample file description:
You might want to remove former individual members from your database who haven't participated in the organization for several years to reduce the database footprint. The criteria you'll use to identify companies that should be deleted is that the company will be inactive and have a database record that hasn't been updated in three years. You could begin by running a report and searching for inactive companies only to minimize the number of files in the report results, then download the results as CSV data file. Now you'll sort the results by the 'company_last_modified' date and remove those where this date is less than three years old, leaving only the records you want to delete.
This sample shows a set of records for inactive users who have been selected for deletion. When performing a delete action, the only columns you really need are 'upload_action' and 'item_key'.
This example includes the 'status' and user name information which have been left in the file for reference by the person preparing the data file. The first row of the data file contains the column headings and the second and subsequent rows contain records of companies retrieved from the database.
Table F.5. Sample data file for deleting users
| upload_action | item_key | status | first_name | last_name |
|---|---|---|---|---|
| delete | fs12358132134 | active | Boorish | Spammer |
| delete | uv1618033989 | inactive | Recreating | Retiree |
|
|
 |
|
| Appendix E. Sample Company Data Files for the Upload Data Tool |  |
Appendix G. Kavi Members Email Template Variables |