Create readers in bulk

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

Bulk import/update overview

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)

Download a template CSV

First, download a sample CSV file to use as a template for your bulk import:

1. Go to Account > Readers. The Readers page opens to the Readers tab.
2. Select + Import Readers from Spreadsheet.
   Select + Import Readers from Spreadsheet
   
   The Upload Readers modal opens.
3. In the modal, select the link to Download Example CSV. This downloads the sample CSV file to your computer.

Add data to your CSV

Whether you use our template or your own CSV file, as you fill out the CSV, 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), first name, 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.).

Here's more information on each field:

• 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're using admin-managed passwords for readers. Refer to What's the difference between admin managed and self-administered reader passwords? for more information. Most authors don't need to enter anything here.
• Groups (optional): You only need to use this field if you want to assign different readers in this CSV to different groups. (Ignore this field if you don't use reader groups, or don't want to assign any readers to groups, or are assigning all readers in this CSV to the same 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).
  No new groups
  You must reference existing groups. Any new group names will be ignored in the import.
• Help Sites (optional): If you have multiple knowledge bases and want to assign readers in this spreadsheet to different knowledge bases, use this column. (Ignore this field if you only have one knowledge base or you're assigning all readers in this spreadsheet to the same knowledge base(s)) The knowledge base name entered here must match what you see in the Knowledge base name field in KB 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 (in Readers > Settings). Match the Custom Field heading to the custom field(s) you're using, and enter appropriate values. Refer to Add custom fields to the reader signup form for more information on working with custom fields.

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

Email / Username (login),First Name,Last Name,Password (leave blank for self-administered passwords),Groups (optional),Help Sites (optional),Organization
linus@knowledgeowl.com,Linus,Owl,,Support,"Support KB,KO Blog",KnowledgeOwl
owlpacino@knowledgeowl.com,Owl,Pacino,,"Developers,Support","Support KB,KO API Docs",KnowledgeOwl
owlbert@knowledgeowl.com,Owlbert,Einstein,,,Support KB,KnowledgeOwl
jimmy@knowledgeowl.com,Jimmy,Talon,,Developers,KO API Docs,KnowledgeOwl
owlbus@owlette.com,Owlbus,Dumbledore,,Partners,Support KB,Owlette
owlcapone@owlette.com,Owl,Capone,,Partners,Support KB,Owlette

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 Support KB 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 Support KB 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 Support KB knowledge base. Our custom Organization field marks this reader as being part of KnowledgeOwl.
• Jimmy Talon 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 Support KB knowledge base. Our custom Organization field marks both readers as belonging to Owlette.

Upload your CSV

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

1. Go to Account > Readers. The Readers page opens to the Readers tab.
2. Select + Import Readers from Spreadsheet.
   Select + Import Readers from Spreadsheet
   
   The Upload Readers modal opens.
3. In the modal, select Choose File to select your CSV file for import. A file browsing window opens.
4. Navigate to the CSV file you've saved, select it, and select Open.
   
5. The Upload Readers modal updates to display the name of the CSV file you uploaded. Confirm that the CSV file name displayed is the one you meant to upload. If it's incorrect, select Choose File and repeat the previous step. Once it's correct, select Next. The Import Options page opens.
6. 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. Follow the instructions in the next section.

Choose your import options

1. The top section sets 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. Choose the option that best suits you:
     • Skip importing readers that already exist: The importer will ignore any email address in the CSV that already exists in your account.
     • Update existing readers with import data: The importer will update the details for any email addresses in the CSV that already exist in your account. This will overwrite any existing groups, knowledge base access, and so on for that reader.
     • Delete all current readers before importing from CSV: The importer will delete all existing readers and use the CSV to create all reader accounts fresh. Use this option if you want only the readers in the CSV to exist in your account.

       Not for SSO accounts
       The Duplicate Reader Action ignores SSO-created and -maintained reader accounts. If you're using SSO accounts, don't try to update or import them using this tool.

   • CSV Header Row: Check the My CSV includes a header row box if you've used our sample CSV or created your own with headers. This option tells the importer to ignore the first row of data.
2. Use the Map Reader Fields section to 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. We recommend reviewing all of these fields to be sure they're importing to the correct fields.
   
   • Email (Username): Map this field to the column containing your reader's email addresses
   • First Name: Map this field to the column containing your reader's first name
   • Last Name: Map this field to the column containing your reader's last name.
   • Password: If you use self-administered passwords, you can't make a selection here. If you use admin-managed passwords, you'll have a dropdown to map this field to the password field in your CSV. Refer to What's the difference between admin managed and self-administered reader passwords? for more information.
   • Groups: You can choose whether to pull group information from the CSV or whether to assign all readers in the CSV to specific 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're assigning all readers in this CSV to the same group(s), use the Give all uploaded readers access to the following groups option and select the groups you want to assign these readers to.
   • Knowledge Base Access: You can choose whether to pull knowledge base access from the CSV or whether to assign all readers in the CSV to the same knowledge base(s):
     • 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, 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.
3. Once you've finished your field mappings, select Import Readers to complete your import. While the import processes, the Importing Readers page displays a progress bar.
4. Once the import completes, a confirmation message displays:
   
5. Select Return to readers page to return to the Readers page and view 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.

Troubleshoot 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:

The following usernames appear in your CSV file multiple times:
[list of duplicate reader usernames]
If you continue, we will only import the first instance of each reader.
Continue Import     Cancel Import

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

If you select Cancel Import, it will cancel the import. 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 just skips that group.