Kavi Help CenterKavi® Members Help
| Appendix H. Upload Data Instructions for Add, Edit and Delete Actions | ||
|---|---|---|
 |
Part X. Appendix | |
Table of Contents
The 'upload_action' column is required for all actions because the value in this column instructs the tool what action to perform on that row of data. These values are 'add', 'edit' or 'delete'.
If you haven't prepared data for this tool before, see Preparing CSV Files for Upload. If you need more information about a specific field, see Guide to Predefined Data Fields. The instructions for each action include links to Sample Company Data Files for the Upload Data Tool or Sample User Data Files for the Upload Data Tool. These samples should help give you some idea of how your data should look, but they have been kept simple by design. Your data files will almost always contain more columns than those shown in the samples.
It's generally easiest to prepare data files by downloading files available through the Upload Data tool, especially if the organization is fairly new so there aren't a lot of records in the database yet or you need to edit a high percentage of the records. If there are a lot of records in the database or you need to edit only a small number of records, it may be easiest to begin by downloading a Company Data Report, User Data or other available report. If you do this, be sure to include the item key ('item_key' field) when you run the report, then add an 'upload_action' column to the data file.
Back to topValues provided in the data file are assigned to the company, user or membership if the value is valid.
Values for required fields are validated and invalid values will 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.
The 'add' action is used when populating the database for Web site setup, so this section provides instructions that apply only when populating the database, then refers you to general instructions for adding companies and users. Another set of instructions describe how to add memberships at the same time.
When populating the database:
Be sure all other Kavi Members configurations steps have been completed before you begin to upload data—particularly membership renewal configuration and custom fields—as database structure and validation rules are determined by site configuration. When you download the CSV templates, the column headings will reflect site configuration: all required fields and custom fields will be present and any unused fields will be omitted.
You must upload company and user data separately. Since Kavi Members requires every user to be assigned to to a company, company data must be uploaded first.
Follow the instructions to Add Companies. You may add memberships for these companies during this upload or as a separate upload, follow the Add new memberships instructions.
Follow the instructions for adding users. You may add memberships for these individuals during this upload, follow the Add new memberships instructions.
Download the company.csv template through the link provided on the Upload Data page and open it in a spreadsheet application or text editor. Follow these data preparation instructions. To view an example of how your data file might look, see Company data file to populate the database.
If you want to add new memberships for companies, follow the additional file preparation instructions in Add new memberships.
You may perform other actions such as 'edit' or 'delete' during the same data file upload. Download the records you want to edit or delete and merge these records with the records you are adding. Leave the 'item_key' field blank in records that are being added.
Begin by preparing fields required by the Upload Data tool.
Table H.1. Fields required by Upload Data
| Column name | Instructions |
|---|---|
| upload_action | This usually appears as the first column in the data file. Enter 'add' for every record in this column. |
| name | Add a name for each company. This name must be unique, so if you haven't checked the data file for duplicates yet as described in Preparing CSV Files for Upload, this would be a good time to do it. |
| purpose | Add a purpose for each company. |
Table H.2. Other required fields
| Column name | Instructions |
|---|---|
| accepted_domains |
If accepted domains are enforced for this site, 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. To see whether accepted domains are enforced, view the settings for the 'Check Accepted Domains' option in the Configure Company Representative Signup Options tool. If this is set to any option except 'Never check domains', then this site enforces accepted domains on signup. |
| company_type | One or more Company Types assigned to this company. Multiple types must be comma-delimited (separated by commas but no spaces). If this field is empty, any Company Types designated as default will be assigned. |
| display_publicly | Set the field to '0' (zero) for any members that should be hidden to protect user privacy. Companies that do wish to appear on the roster should be set to '1'. Defaults to '1' if not specified when adding a company. |
| show_on_signup_form | Set this field to '1' if this is a member company that should be listed on the Company Representative Signup Application. Set this field to '0' for all other companies. Defaults to '1' if not specified when adding a company. |
| status | Set the status to 'active' if you want users who belong to the company to have Web site access. Set the status of companies whose user's shouldn't have Web site access to 'inactive'. Defaults to 'active' if not specified when adding a company. |
| 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). |
Since Kavi Members requires users to be assigned to companies, you can't add a user to the database if their company doesn't yet exist in the database. Upload company records first or add them 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 Add new memberships.
You may perform other actions such as 'edit' or 'delete' during the same data file upload. Download the records you want to edit or delete and merge these records with the records you are adding. Leave the 'item_key' field blank in records that are being added.
Table H.3. Fields required by Upload Data
| 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 individual. It is very important to assign the correct purpose, as the purpose you assign determine how this individual will be managed in the system. |
Table H.4. Other required fields
| Column name | Instructions |
|---|---|
| company_contact_types | Every user must be assigned at least one Company Administration and 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 or Company Admin. 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 Company Administration and 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. |
| display_publicly | Set this field to '1' to display the user's information on the roster or '0' (zero) to have the user's information left off the roster protect user privacy. Defaults to '1' if not specified when adding a user. |
| member_types | These are actually User Types. You may optionally assign one or more valid User Types. Types designated as being 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 '1' (active) if the user should be allowed to login, or '0' (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. |
New memberships can be uploaded through add actions when populating the Members database during site setup or when adding new members in bulk. New memberships can be added for companies or users who already exist in the database through 'edit' actions.
New memberships are memberships for companies or users that don't yet have a membership in the database. These include new and historic memberships that are added when the database is populated for the first time as part of the site setup process, as well as memberships for new members.
To edit, delete, replace or renew existing memberships, you must use Manage a Company or Manage a User tools. To manage pending memberships use the tools listed under 'Manage and Moderate Applications' on the Admin Tools page.
When preparing a data file to add memberships, just prepare the data file according to the preceding instructions, then add the fields used to add memberships through the Upload Data tool: 'membership_types', 'membership_start_dates' and 'membership_end_dates'. If adding a membership as part of an 'edit' action you must also add these fields, but the 'upload_action' will be 'edit'. Be sure to remove any other membership-related fields when preparing a data file for upload (except 'member_types', which is actually a user data field containing User Types).
Once a membership has been uploaded, it passes through the normal membership workflow and Kavi Members automatically sets the rest of the fields in the membership record.
Upload Data enforces most membership rules. For example, you won't be able to add a membership for a company or user with an incompatible purpose such as 'Staff and Administration'.
Table H.5. How to prepare membership fields
To prepare data files for upload, download the company.csv or person.csv templates through the links provided on the Upload Data page. If the database contains a large number of records or you want to edit only a small percentage of the records in the database, it might be easiest to acquire the data you need by running a Company Data Report or User Data Report. You must prepare company and user data in separate data files. Be sure the item key (i.e., 'item_key' field) is included in the downloaded results. When you are ready to upload your data, the company data file should be uploaded unless this is an individual-based organization and you only need to edit user data.
If you downloaded a csv file through the Upload Data tool, the 'upload_action' column will be prefilled with the 'edit' value. If you have acquired your data through another source, such as the Company Data Report or User Data Report, you will have to add the 'upload_action' column and set the value to 'edit' for all records (i.e., rows) that you want to edit.
To edit a company or user through the Upload Data tool, the record for that company or user must have a valid item key (i.e., a unique ID generated by Kavi Members) in the 'item_key' column.
If a field in the database contains a value and no value is specified in the data file, the field value in the database will be retained.
Values provided in the data file will be assigned to the company, user or membership as long as the value is valid. If a value already exists in the data file it will be overwritten if a valid value is uploaded. If the value in the uploaded file is invalid, the value in the database will be retained.
Required fields without values (i.e., empty fields) are set to default values. These are often configuration dependent, as described below.
Any edits performed on company data have the potential to affect users who belong to that company, particularly if the company's purpose, status or types change.
If you want to add new memberships for companies that already exist in the database, follow the additional file preparation instructions in Add new memberships.
Table H.6. Fields required by Upload Data
| Column name | Instructions |
|---|---|
| upload_action |
This usually appears as the first column in the data file. The value of this field must be set to 'edit' for every record you wish to edit. If you downloaded the csv data file through the Upload Data tool, the value 'edit' will have been prefilled for every record in this column. You should remove any records (i.e., rows) that you do not want edited in order to streamline the upload process and prevent the accidental introduction of errors into these rows. You may delete records in this same data file upload. Follow the instructions in Delete companies. |
| item_key | This field must contain a valid item key generated by Kavi Members. |
Table H.7. Fields required by Upload Data
| Column name | Instructions |
|---|---|
| display_publicly | Set the field to '0' (zero) for any members that should be hidden in order to protect user privacy. Companies that want to be included in the roster should be set to '1'. |
| show_on_signup_form | Set this field to '1' if this is a member company that should be listed on the Company Representative Signup Application. Set this field to '0' for all other companies. |
| status | Set the status to 'active' if you want users who belong to the company to have Web site access. Set the status of companies whose user's shouldn't have Web site access to 'inactive'. |
| 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). Once the start date has been assigned it shouldn't be overwritten because it is part of the historic record of this company's relationship with the organization, so this column should be omitted from the data file unless you are adding records. |
| company_type | You may edit the Company Types assigned to a company but care must be taken to assure the company has all appropriate types when the upload completes. Multiple types appear as a comma-delimited series (separated by commas but no spaces). You add or delete types by adding or removing types from this series. Types assigned through membership should be edited by editing the membership, which automatically adds or revokes appropriate types. |
Since Kavi Members handles some user management tasks through the company to which they are assigned, it's always a good idea to edit company data before editing user data, so that changes to the company that affect its users will have been propagated to the user records before your edits are introduced.
If you want to add new memberships for individuals who already exist in the database, follow the additional file preparation instructions in Add new memberships.
Table H.8. Fields required by Upload Data
| Column name | Instructions |
|---|---|
| upload_action |
This is usually the first column in the data file. If you download the 'person.csv' data file from the link on the Upload Data tool it will already be present and the value 'edit' will have been prefilled for every record in this column. If you download a User Data Report, you will have to add this column. For every record (i.e., row) you wish to edit, set the value of the 'upload_action' field to 'edit'. Remember to remove any rows that you do not want to edit in order to streamline the upload process and prevent the accidental introduction of errors into these records. You may delete records in this same data file upload. Follow the instructions in Delete companies. |
| item_key | This field must contain a valid item key generated by Kavi Members. |
Table H.9. Other required fields
| Column name | Instructions |
|---|---|
| company_contact_types | Every user must be assigned at least one Company Administration and Contact Type to establish their relationship to their company. You may edit the Company Administration and Contact Types assigned to a company representative, but care must be taken to assure the user has all appropriate types when the upload completes. Multiple types appear as a comma-delimited series (separated by commas but no spaces). You assign or revoke types by adding or removing types from this series. |
| company_name | The 'company_name' 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. |
| display_publicly | Set this field to '1' to display the user's information on the roster or '0' (zero) to have the user's information left off the roster protect user privacy. |
| member_types | These are actually User Types. You may edit the User Types assigned to a user, but care must be taken to assure the user has all appropriate types when the upload completes. Multiple types appear as a comma-delimited series (separated by commas but no spaces). You assign or revoke types by adding or removing types from this series. Types designated as being assigned only through membership are not ordinarily assigned or revoked 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 Email will contain 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. If a user has indicated they don't want to receive announcements or organization policy specifies this type of user should not be sent announcements, set this to '0'. |
| signup_date | This column is ordinarily omitted from the data file when performing 'edit' actions to avoid overwriting the signup date. |
| status | Set this to '1' (active) if the user should be allowed to login, or '0' (inactive) if not. |
| username | Omit this column from the data file when performing 'edit' actions to avoid overwriting usernames. |
Since every user must belong to a company, deleting a company will delete all users assigned to that company. Deletion is permanent. If you merely want to hide the record, set the user or company status to 'inactive'.
Your file must include the 'upload_action' column. This is usually the first column in the data file. If you download the 'person.csv' data file from the link on the Upload Data tool it will already be present and the value 'edit' will have been prefilled for every record in this column, so you will have to change the value to 'delete' for every record (i.e., row) you want to delete. If you download a Company Data Report, you will have to add this column. For every record (i.e., row) you wish to delete, set the value of the 'upload_action' field to 'delete'. You may perform other actions on company data such as 'edit' or add' in the same upload. There must be a value in this column for every record in the data file, either 'add', 'edit' or 'delete'. Any rows that you do not want changed in the data file should be removed prior to upload in order to streamline the upload process and prevent the accidental introduction of errors into these records.
To delete a company through the Upload Data tool, the record for that company must have a valid item key (i.e., a unique ID generated by Kavi Members) in the 'item_key' column. If you are downloading a report, be sure this field is included in the downloaded results.
Since every user must belong to a company, deleting a company will delete all users assigned to that company. Deletion is permanent. If you merely want to hide the record, set the user or company status to 'inactive' or archive the membership.
Delete actions only require the 'upload_action' and 'item_key' columns, but you may want to include the company name ('name') and other fields so you can see whether you're deleting the right companies.
Table H.10. Other required fields
| Column name | Instructions |
|---|---|
| upload_action | Set this field to 'delete' for every record (i.e., row) you want to remove from the database. |
| item_key | Each record must have a valid item key (i.e., a unique ID generated by Kavi Members) in the 'item_key' field. |
Since every user must belong to a company, edit company data before editing user data. Deleting a company will delete all users assigned to that company. Deletion is permanent. If you merely want to hide the record, set the user or company status to 'inactive' or archive the membership.
Delete actions only require the 'upload_action' and 'item_key' columns, but you may want to include the company name ('name') and other fields so you can see whether you're deleting the right companies.
Table H.11. Other required fields
| Column name | Instructions |
|---|---|
| upload_action | Set this field to 'delete' for every record (i.e., row) you want to remove from the database. |
| item_key | Each record must have a valid item key (i.e., a unique ID generated by Kavi Members) in the 'item_key' field. |
|
|
 |
|
| Appendix G. Kavi Members Email Template Variables |  |