Create readers in bulk

You can create and/or update multiple reader accounts at once by uploading a CSV spreadsheet.

Bulk import/update overview

You'll upload a .csv file containing all of the readers you want to import or update. The importer can:

• Delete all existing readers (this will remove all current accounts and replace them with the accounts in the spreadsheet)
• Skip existing readers
• Update existing readers (if it matches the email address to a current reader account, it will update all the additional information for the reader with what's in the spreadsheet, but leave their password and email address untouched)

Getting a template CSV

You can download a sample CSV file to use as a template for your bulk import:

1. Click on your profile icon/name in the upper right.
2. Select Readers from the dropdown to access the Readers area of your account.
3. Click the Import Readers from Spreadsheet button at the top.
   
   Sample Readers screen, calling out the Import Readers from Spreadsheet button
4. This will open a pop-up where you an upload your CSV file. Click the link on the lower left to Download Example CSV.
   
5. This will start a download of a sample CSV file (it will also include custom fields):
   

Adding data to your CSV

Whether you use our template or your own CSV file, as you fill out the CSV, you'll enter one row for each reader account you wish to create. For each reader, you'll assign an email (to be used as their username), and first and last name. You can assign all readers in a CSV to the same set of groups and knowledge bases in the import options for the upload, or you can assign specific readers to different groups and knowledge bases using separate fields in your CSV.

Use comma-separated lists (with no spaces after the comma) for fields where you want to assign the reader to more than one option (such as Groups, Help Sites, etc.).

See more detail in the following list of CSV fields and the sample import below:

• Email / Username (login): This is the email address the reader will use to login. It needs to be unique. Their welcome email will be sent to this address once the upload is complete.
• First Name: The reader's first name.
• Last Name: The reader's last name.
• Password (optional): You should only use this field if you are using admin-managed passwords for readers. (You can confirm this by going to Readers > Settings and reviewing the Password Management option selected. If "Passwords can only be managed by KnowledgeOwl admins" is selected, use this field. Otherwise, ignore it.)
  
  If this option is selected, use the Password field in your CSV. Otherwise, ignore this column.
• Groups (optional): You only need to use this field if you are assigning different readers in this CSV to different groups. (If you do not use reader groups, or don't want to assign any readers to groups, or are assigning all readers in this CSV to the same group(s), you can ignore this field.) If you are assigning individual readers in the CSV to one or more reader groups, use a comma-separated list of group names with no spaces after the commas (example: Administration,Support will assign the reader to both the Administration and Support reader groups).
  You cannot create new groups here; you must reference existing groups.
• Help Sites (optional): If you have multiple knowledge bases and want to assign readers in this spreadsheet to different knowledge bases, use this column.  (If you only have one knowledge base, or you are assigning all readers in this spreadsheet to the same knowledge base(s), you can ignore this column.) The knowledge base name entered here must match what you see in the Knowledge base name field in Settings > Basic. To assign a single reader to multiple knowledge bases, use a comma-separated list with no spaces after the commas (example: "KO Product Docs,KO Blog" will assign the reader to the KO Product Docs knowledge base and the KO Blog knowledge base).
• Custom Field 1-5 (optional): Use these fields only if you have Custom Fields in your Reader Signup form (visible in Readers > Settings). Match the Custom Field heading to the custom field(s) you're using, and enter appropriate values.
  
  Reader Signup Custom Fields

Here's a sample of a saved CSV ready for upload:

Sample reader CSV, ready for import This will create 6 new readers:

• Linus Owl: will receive a randomly-generated password, be assigned to the Support group, and will gain access to the KO Product Docs and KO Blog knowledge bases. Our custom Organization field marks this reader as being part of KnowledgeOwl.
• Owl Pacino: will receive a randomly-generated password, be assigned to the Developers and Support groups, and will gain access to the KO Product Docs and KO API Docs knowledge bases. Our custom Organization field marks this reader as being part of KnowledgeOwl.
• Owlbert Einstein: will receive a randomly-generated password, not be assigned to any groups, and will gain access to only the KO Product Docs knowledge base. Our custom Organization field marks this reader as being part of KnowledgeOwl.
• Jimmy Tallon: will receive a randomly-generated password, be assigned to the Developers group, and will gain access to only the KO API Docs knowledge base. Our custom Organization field marks this reader as being part of KnowledgeOwl.
• Owlbus Dumbledore and Owl Capone: will receive a randomly-generated password, be assigned to the Partners group, and will gain access to only the KO Product Docs knowledge base. Our custom Organization field marks both readers as belonging to Owlette.

Uploading your CSV

Once you have your CSV created, return to the Readers page to upload it and create your new reader accounts.

1. Click on your profile icon/name in the upper right.
2. Select Readers from the dropdown to access the Readers area of your account.
3. Click on the + Import Readers from Spreadsheet button.
   
4. In the Upload Readers pop-up, click the Choose File button.
   
5. This will open a file browsing window; navigate to the CSV file you've saved, select it, and click Open. (Note: your screen may look different depending on your browser, operating system, and display settings.)
   
6. Confirm that the CSV file name displayed is the one you meant to upload. If it's incorrect, click Choose File and repeat the previous step. Once it's correct, click Next.
   
7. This will take you to the reader Import Options screen. Here, you'll decide what to do if your spreadsheet contains readers who already exist, map the columns in your CSV to the appropriate fields in KnowledgeOwl, and/or assign the same groups or knowledge bases to all readers in the CSV.
8. The top two options set the overall way the import will be handled.
   
   • Duplicate Reader Action: As part of the import, we'll check to be sure that the email address you're adding doesn't already exist. If it does already exist, this setting tells us what to do with it. The options are:
     • Skip importing readers that already exist: Any email address in the CSV that already exists in your account will be ignored completely.
     • Update existing readers with import data: For email addresses found in the CSV that already exist in your account, all related fields will be updated. This will overwrite any existing groups, knowledge base access, and so on for that reader.
     • Delete all current readers before importing from CSV: This will delete all existing readers and use the CSV to create all reader accounts fresh. Only use this option if you want only the readers in the CSV to exist in your account.
       
       Note: This Duplicate Reader Action ignores SSO-created and -maintained reader accounts. If you're using SSO accounts, do not try to update or import them using this tool.
   • CSV Header Row: If you've used our sample CSV or created your own using your own headers, be sure this box is checked so the importer ignores the header row.
9. The Map Reader Fields section will let you map the fields in your CSV file to the corresponding fields in KnowledgeOwl using the provided dropdowns. It will auto-select titles that match exactly, but we recommend reviewing all of these fields to be sure they're importing to the correct fields.
   
   • Email (Username): map this to the column containing your reader's email addresses
   • First Name: map this to the column containing your reader's first name
   • Last Name: map this to the column containing your reader's last name.
   • Password: this option will be unselectable if you don't have admin-managed passwords. If you do use admin-managed passwords, you'll have a dropdown to map this field to the password field in your CSV.
   • Groups: If you have a column designating readers' groups, use the Assign groups using spreadsheet column setting and the dropdown below it to map that field.
     
     Map readers to groups using the Groups field in the CSV
     
     If you didn't need the Groups column in your CSV because you are assigning all readers in this CSV to specific groups, use the Give all uploaded readers access to the following groups option and select the groups you want to assign these readers to.
     
     This will assign all readers in the CSV to the Support group
   • Knowledge Base Access: If you have a column designating reader's knowledge base access (the Help Sites column in our template), use the Assign access using spreadsheet column setting and the dropdown below it to map that field.
     
     Assign knowledge base access using the column called Help Sites in the CSV
     If you want to assign all readers in the CSV to the same knowledge base(s), use the Give all uploaded readers access to the following knowledge bases option and select the knowledge bases you want to assign these readers to.
   • Custom Fields 1-5: If you use custom reader signup fields, be sure to map the custom fields in your spreadsheet to these custom fields. If you don't use custom fields at all, you can ignore this section. In our example, we had a custom field for "Organization" but no other custom fields, so that would look like this:
     
     Sample custom field mapping
      
10. Once you have finished your field mappings, click Import Readers to complete your import.
    
11. While the import processes, you'll be taken to the Import Readers screen, which will display a progress bar.
12. Once the import completes, you'll see a confirmation message:
    
13. Click the Return to readers page link to return to the readers page and see your new readers.

As soon as the import completes, your readers will receive a welcome email. Existing readers that were skipped will not receive an email. Readers whose accounts were updated will only receive a welcome email if they were given access to a knowledge base they haven't accessed before.

Troubleshooting reader imports

The Reader Import Options settings will handle when an existing reader matches the username you've included in your reader import file. But if the CSV file you're trying to import contains the same username more than once, you'll see an error as the import is being processed. It will look something like this, and will include a list of each duplicate username:
Sample warning when the CSV file contains duplicate usernames

If you get this warning and you click Continue Import, it will use the data from the first time the duplicate username appears in the spreadsheet.

If you click Cancel Import, it will cancel the import and you can open your CSV, remove the duplicate, re-save the file, and begin the import again.

Does capitalization matter in usernames/email addresses?

The bulk reader import tool strips out capitalization in the username/email address, for consistency. (Individually-created readers' usernames will also be set to lower case.)

Do I need to worry about trailing spaces at the end of email addresses or names?

No. The bulk importer will automatically trim trailing spaces from email addresses, first name, and last name. (For email addresses, it will trim them before it does the check for duplicate/existing readers.)

Will the bulk import tool check for invalid email addresses?

No. It will import the email address/username as you have it in the CSV. Be sure to review your CSV to be sure the email addresses you're using are correct and valid.

What if I use a group name that doesn't exist?

The bulk import tool will not throw an error if you reference groups that don't exist. It will just skip that group.

For example, let's say one of the rows in my spreadsheet looks like this:

If the group called "Partners" doesn't exist, this reader will be created and assigned to KO Product Docs, but they won't be assigned to any reader groups.