Reader management

Users are people who can create, edit, and manage your knowledge base content. They have access to the backend of the application, and you pay for the users on your account. There are two main types of users:

• Admin Users: Account administrators have access to everything in your account.
• Non-admin users: Non-admins are granted permissions by the admins on a per knowledge base level. For each knowledge base, a user can be an editor, a writer, or have no access.
  • Editors have access to all settings on a knowledge base, including settings, security, and styles.
  • Writers can only create and edit content (categories and articles).
  • Users with no access will not be able to view a knowledge base in the backend.
  • Non-admin users can be given access to Readers.

Readers are people who can view your knowledge base. They only have access to the frontend (the knowledge base). You can have an unlimited number of readers on your account. 

Readers are users that can log in and view your knowledge base. Sites can be set up to allow readers to log in to view additional content or only allow readers with logins to access the site.

Readers can be assigned to groups that have access to specified content. All categories and articles can be viewable by all readers or only by specific reader groups, which can be set up under Your Account > Readers.

To create a reader...

1. Go to Your Account > Readers.
   
   
2. Click on Add a Single Reader.
   
   
3. Specify a Login/Username. If you are using admin managed passwords, you will set up a  Password  too. If you are using self-administered passwords, the system will automatically send a welcome email with a temporary password. Password types and emails can be customized under Readers > Settings.
   
   
4. (Optional) Assign the reader to the appropriate groups. Click Add Group to create a new group for the reader.
5. Specify your Group Name.
   
   
6. Click Create Group. The new group will be pre-selected as the Reader Group. 
7. Select which Help Sites (knowledge bases) the reader will be able to access.
8. Click Save to create the new reader.

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. Go to Your Account > Readers.
2. When the Readers page opens, click the Import Readers from Spreadsheet button at the top.
   
   Sample Readers screen, calling out the Import Readers from Spreadsheet button
3. This will open a pop-up where you an upload your CSV file. Click the link on the lower left to Download Example CSV.
   
4. 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): REQUIRED. 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: REQUIRED. The reader's first name.
• Last Name: REQUIRED. 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 Your Account > Readers, clicking on the Settings tab, 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).
  Note: 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 Your Account > 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 Your Account > Readers to upload it and create your new reader accounts.

1. Click on the + Import Readers from Spreadsheet button.
   
2. In the Upload Readers pop-up, click the Choose File button.
   
3. 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.)
   
4. 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.
   
5. 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.
6. 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.
7. 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
      
8. Once you have finished your field mappings, click Import Readers to complete your import.
   

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.)

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 account will be created and assigned to KO Product Docs, but it won't be assigned to any reader groups.

You can create groups to restrict access to content.  

To create groups...

1. Go to Your Account > Readers.
2. Click on Groups.
3. Click on Add Group.
4. Specify the Group Name.
5. Click Create Group.

From this screen you can also...

• Rename a group by clicking on the little wrench icon to the right
• Delete a group using the red x icon, and 
• Reorder the way groups appear in the editor using the up arrow icon.

Your groups will appear in the editor for categories and articles, allowing you to restrict the content to this groups.

Even in public knowledge bases, you can restrict some content so that it is only visible to specific readers. To do so, create a reader group or groups and then restrict the category or individual articles to that group.

How does restricted content work?

Readers must be logged in to see content that is restricted. When content is restricted:

• Only readers who belong to the restricted group(s) will be able to see the content in the Table of Contents
• Only readers who belong to the restricted group(s) will see the content in Search Results
• Readers who do not belong to the restricted group will get a "You don't have access to view this" page if they enter the direct URL for the content

Restrictions can be set:

• At the category level: restrictions set here will automatically cascade to all articles or sub-categories as long as those sub-categories and articles have "None / Inherit" selected.
• At the article level: restrictions set here apply only to the individual article and don't impact other articles or categories in any way 

Restrict access based on Reader Groups

1. If you do not have your reader groups set up, you will need to set them up by following these instructions. 
2. Create a new category or article (or edit an existing one by clicking on the wrench icon to the right of any content) inside Knowledge Base > Articles.
3. In the edit view for the category or article, select the Reader Groups should be able to view this content under Restrict to Groups in the right-hand column:
   
4. Click Save.

If more than one group is selected, does a reader need to belong to all or only one of the groups?

This depends on your knowledge base's settings. Two Reader Group Logic options are supported:

• Inclusive: Readers can see content when they belong to at least one designated group (multiple groups are treated like an "or")
  • Example: An article is restricted to groups "Apples" and "Bananas". The article can be viewed by any reader in groups "Apples" OR "Bananas".
• Exclusive: Readers must belong to all designated groups (multiple groups are treated like an "and")
  • Example: An article is restricted to groups "Apples" and "Bananas". The article can only be viewed by a reader in groups "Apples" AND "Bananas".

By default, all knowledge bases are set to Inclusive Reader Group Logic. You can check or update this by going to Settings > Security and checking the Reader Options section:

When logged into the knowledge base as a user, you will be able to simulate what the site looks like for different groups by click on Change Reader Groups. If you want to actually test the readers, follow these instructions:

1. Go to your knowledge base home page. The URL should end in "/help", "/home", or "/docs".
2. Append "/readerlogout" to the end of the URL. The URL should now end in "/help/readerlogout", "/home/readerlogout", or "/docs/readerlogout"
3. Hit enter (or return) to go to this new URL.
4. Log in to your help site with the reader you wish to test.

1. Go to Settings > Basic.
2. Select the option to "Add a reader login / logout link".
3. Click Save.
4. Click View KB.
5. Click on Login in the top navigation bar to log in as the reader you wish to test.*

*The login button will not automatically appear if the Body HTML under Settings > Style has been modified. The Login and Logout buttons can be added by using the following merge code: [template ("login")]. If you do not wish to add these buttons, you can follow the first set of instructions to Test access based on Reader Roles, which allows you to log in and log out by altering the URL.

1. Go to Your Account > Readers > Settings.
2. Password Management: Choose whether you want to manage reader passwords or have them manage their own. We recommend self-administered passwords because few people have time to deal with forgotten password issues. This is an account-wide setting but can be overwritten on individual knowledge bases for accounts with multiple knowledge bases under Settings > Security.
3. Password Attempts: Choose whether or not you want to allow unlimited password attempts. By default, reader accounts are locked for 20 minutes following 3 unsuccessful attempts.
4. User Logins: Choose whether to allow KnowledgeOwl users to log in as readers (recommended and on by default).
5. Restricted IP Protection: Optionally restrict reader logins to a specific IP address or list of IPs as a form of two-factor authentication (password AND IP address).
6. Case insensitive Logins: If using admin managed passwords, choose whether or not you want the usernames to be case-sensitive.
7. Save.

1. Go to Your Account > Readers > Settings. Make sure "Allow readers to administer their own passwords" is selected for Password Management to be able to see the Self-Administered Reader Options.
2. Password Expiration Interval: Specify at what interval reader passwords will expire, forcing the reader to choose a new password. The options are:
   • Never (default)
   • Every Month
   • Every 2 Months
   • Every 3 Months
   • Every 6 Months
   • Every Year
3. Repeat Password Limitations: Choose whether and how to limit password reuse when resetting passwords. The options are:
   • None (default)
   • Cannot use previous password
   • Cannot use previous 2 passwords
   • Cannot use previous 3 passwords
   • Cannot use previous 4 passwords
   • Cannot use previous 5 passwords
4. Custom Validation Rule: Create your own password validation using RegEx. You can find prewritten validation rules using your favorite search engine. Check out this Regular Expression Libraryfor some examples.
5. Custom Validation Description: This message will be displayed on the password reset screen if you have a custom validation rule. Use it to tell your reader about the rule so they can create a password that works.
6. Auto-assign Group Rules: If you are using group rules to automatically assign your readers to groups, use this setting to ensure that reader groups will update based on the rules each time a reader logs in. This allows you to create new rules and have it automatically applied to existing readers, but it will override any  groups you might have set manually. Do not choose this option if you are manually setting reader groups.
7. Reader Signups: Add a reader signup link to your login page so you reader can sign up own their own. By default, new readers will be added and a welcome email sent with a temporary password. You can optionally choose to require an admin approval before the welcome email is sent, and you can set up notification email to inform you are new reader signups or signup requests.
8. Signup Notification Recipients: Specify which emails or list of emails to send notifications when a new reader signs up or requests access.
9. Save.

Password management for readers can be set up under Your Account > Readers > Settings and allows you to choose how reader passwords are set. There are two options for reader password management:

• Managed Passwords: Passwords can only be managed by KnowledgeOwl admins (default)
• Self-administered Passwords: Allow readers to administer their own passwords by email

Allowing readers to administer their own password also enables reader welcome emails,  password reset emails, and reader signups. Emails are not sent for managed passwords.

Managed passwords

Managed passwords can only be set and reset by a KnowledgeOwl admin (user with reader admin permissions). When using managed passwords, you will need to give the reader his or her username and password through your own system. If the reader forgets his or her password, they will need to contact you to retrieve or reset it. No welcome or password reset emails are sent for managed passwords; all reader communication occurs outside of the KnowledgeOwl application.

When creating readers with managed passwords, you will need to set the password in the Admin Managed Password field when adding a single reader or have a column with the passwords when creating readers from a spreadsheet.

Self-administered passwords

Self-administered passwords are set and reset by reader via email. When using self-administered passwords, readers are sent a welcome email containing a temporary password and will be asked to update their password when they first log in.  

If a reader forgets or wants to reset his or her password, there is a "Reset Password" option on the login page. Clicking "Reset Password" allows a reader send a temporary password to his or her email address to create a new password. For this reason, usernames should be an email address for self-administered passwords to work properly. 

KnowledgeOwl admins can reset self-administered passwords either by sending a new temporary password or manually setting a temporary passwords; readers will be asked to update their password when they use the temporary one.

Reader welcome and password reset emails can be customized under Your Account > Readers > Settings.  Reader emails are account-wide so the same email is sent for all knowledge bases in an account.

When creating readers with self-administered passwords, readers will automatically be sent a welcome email with their temporary password when you add a single reader or create readers from a spreadsheet.  If you do not want the welcome email sent when creating new readers, you can temporarily choose Managed Passwords, create the readers with an admin password, and switch back to Self-Administered Passwords.  The admin password will then be used as a temporary password; readers will be asked to update them when they log in.

Account-wide password management

Reader settings are account-wide so the password management option will apply to all knowledge bases on an account by default. Managed Passwords are the default option for password management. You can switch to self-administered passwords under Your Account > Readers > Settings.

Different password management for different kbs

You can choose to override the default account-wide password management option for individual knowledge bases under Settings > Security. By default, reader passwords will be set to "Use the account wide password management setting (default)". 

You can choose to use the default or override the default for a particular knowledge bases. There are three options:

• Use the account wide password management setting (default)
• Managed Passwords: Passwords  can only be managed by KnowledgeOwl admins
• Self-administered Passwords: Allow readers to administer their own passwords by email

Specifying the type of password management will override the default setting under Your Account > Readers > Settings.

You can allow your readers to sign up for access to your reader login restricted knowledge base. On your login page, this will add a link for those without an account to sign up for access.

Set Up Reader Signups

1. Go to Your Account > Readers > Settings.
2. Make sure that Password Management is set to "Allow readers to administer their own passwords".
   
3. Scroll down to Reader Signups under Self-Administered Reader Options to choose "Allow people to sign up to become a reader".
4. You can also choose to  set up notifications emails if you want to be alerted when new readers sign up. Notifications are especially helpful if you want to manually add the reader to groups to give them access to restricted content or you require approval before the new reader can access the site.
5.  If you want to require approval, choose "Require a KnowledgeOwl admin to approve new reader access" and be sure to set up notification emails so you are alerted when a new reader has requested access.
   
6. Save.

Add custom fields to the reader signup form

By default, the reader signup form requires an email, first name, and last name. You can choose to include up to 5 additional fields that will be mapped to reader custom fields 1-5. 

Reader signup custom fields

To add custom fields to the signup form...

1. Go to Your Account > Readers > Settings.
2. Scroll down to Reader Signup Custom Fields.
3. Add labels and check the box to enable the fields you want to collect. You can also choose to require the field.
4. Save.

The custom fields will be added to your signup and will also be included in your notification emails.

Reader signup form with custom fields

Automatic approval versus admin approval

The default behavior is to send new reader signups a welcome email with a temporary password immediately after they sign up. This allows new readers to sign up and gain access to your site without any approval process. 

You can choose the option to "Require a KnowledgeOwl admin to approve new reader access" to wait to send the welcome email and password pending approval. When a new reader signs up, they are requesting approval for access and will only get access after an admin user  approves them in KnowledgeOwl. 

Approve New Reader Signups

When a new reader sign ups, they will be added to Your Account > Readers in pending approval. You will see an alert on top of the Readers list if you have new readers awaiting approval, and you can filter the readers list to only view those pending approval by searching for "pending".

To approve the reader, click on the blue Pending icon (or edit the reader) and click on the link to "approve them here".

Here you can choose to give them access to the requested knowledge base and sent them the welcome email with a temporary password.

Manually Set Groups versus Auto-Assign Groups By Email Rules

New reader sign ups are not assigned to any reader group by default. Admin users can add new readers to groups manually after receiving a sign up notification or approval request, or you can create Email Groups to automatically assign readers to groups based on their email domain. 

To set up Email Rules...

1. Go to Your Account > Readers > Groups.
2. Click on Add Rule.
3. Set up your rule by specify a name, domain, and what groups the domain should get.
   
4. Click Save Rule. 

Note: Rules will only be applied when a new reader first signs up. To run the rules on  subsequent logins and allow rules to affect existing readers, choose "Override reader groups based on rule logic on each login" under Your Account > Readers  > Settings. 

If you have reader sign-ups enabled, you can create rules to automatically assign readers to groups based on their email domain. 

A common use case is to assign all readers with internal email addresses to an internal reader group. For example, Linus likes having a rule that will assign all readers with a knowledgeowl.com email address to the Support reader group, which gives them access to all content restricted to our Support group.

If you're using reader sign-up, this can help guarantee that new readers get access to the content they need without a KnowledgeOwl admin having to manually review and assign them to the appropriate groups.

Set up Email Rules

1. Go to Your Account > Readers > Groups.
2. Click on Add Rule.
   
3. This will open a pop-up where you can define the auto-assign rule.
   Auto-Assign Groups Rule pop-up
   
4. Set up your rule by specifying a Rule Name, the Email Domain it applies to, and assigning which groups the domain should get. Here, you can see the rule Linus has set up for assigning all knowledgeowl.com readers to our Support group:
   Sample rule, assigning all @knowledgeowl.com readers to the Support group
   
5. Click Save Rule. 

Note: Rules will only be applied when a new reader first signs up. To run the rules on  subsequent logins and allow rules to affect existing readers, choose "Override reader groups based on rule logic on each login" under Your Account > Readers  > Settings. 

You can allow readers to sign up for and log in to your knowledge base with their Google account.

To set up Google log in for readers:

1. Open up Settings > Security in KnowledgeOwl and Google  APIs and Services.
   Go to Settings > Security and scroll down to Reader Sign Ins Using Google. Click on Google credentials settings to create a new project using Google APIs. 
2. Set up your OAuth consent screen.
   Click OAuth consent screen and complete the set up. You must provide an email address and product name.
3. Create OAuth client ID credentials and insert your KnowledgeOwl redirect URIs.
   Click Create credentials > OAuth client id and choose Web application. Enter "KnowledgeOwl" as the name, and copy the Google Login Redirect URL and the Google Signup Redirect URL from KnowledgeOwl into the Authorized redirect URIs fields.
4. Set up your client ID and secret in KnowledgeOwl.
   Click create to get your client ID and client secret. Copy and paste your client ID and client secret into the corresponding fields in KnowledgeOwl. Save.
5. Turn on Google log in for readers in KnowledgeOwl.
   Go to Your Account > Readers > Settings and check "Allow readers to log in using their Google account" next to Allow Google Sign In. To allow readers to sign up using Google, check "Allow people to sign up to become a reader" as well. Save.