Table of Contents

Manage Roles & Permissions

Danielle Kellogg Updated by Danielle Kellogg

What are Roles & Permissions?

Knack enables you to use roles and permissions to define different types of users who can access your Live App and the different ways they can use it.

It starts with your user roles in the Schema section of the Builder. When you create a role for each type of user you have, you open up a host of possibilities for personalizing and simplifying their experience of using your Live App.

The user roles can be used to enable permissions in the Pages section of Builder via logins. Each user role gets its own pages where the users in that role can only see, edit, and delete the data that you define.

Those are the two key pieces required to enforce permissions in your Live App: user roles and login views restricted a specific user role.

Let's take a look at how roles and permissions are used in our Customer Portal app template. The Customer Portal has two user roles - Customers and Managers. In order to give Customers and Managers access to only the data and functions they need, there is a different page in the app for each role. These two pages are each protected by a login view with permission restricted to their respective user role.

The Customers' page allows them to do three things:

  • Add a new service request
  • View current and past service requests
  • Pay invoices

The Managers' page has much more functionality. They can:

  • View and edit all customers
  • See their related service requests and invoices
  • Add new records - customers, invoices

They need access to all the data in the database to manage the customer side of the business.

When planning your roles, it's important to think about who will be using your app and how they will be using it. They're not necessarily based on title, but function.

Activate User Roles

Before you can use user records with your app, you must first enable Users. You can read more about Users and how to activate them here.

Manage User Roles & Permissions

Add User Roles

User roles are key for creating permissions. Add a user role for each type of user who will access your Live App.

To add new user roles, select the green "+" button next to the "User Roles" text. This will walk you through creating a new user role.

Add Permissions

Now that you have your user roles, you can set up permissions on your pages! To do this, you'll need to add login views and limit login access to specific user roles.

Adding login permissions to a new page

Enabling logins during the page creation processes allows you to add views displaying records connected to the logged-in user upfront.

Click the green "+" button located above the page list and select "Login Page" from the options in the dropdown menu.

This will open a guide or "wizard" explaining how to create the login settings of your choice.

In the role selection box, choose the role for which you want to permit access to this page:

This is the final step for enabling page level permissions in your app. Only the users who are assigned to the role you add here will be able to access this page.

From here, you can customize your page based on what user role you have given access to this page. For example, if you have restricted access to the Customer user role, you can choose to display the Invoices connected to the logged-in Customer.

The option to add views displaying records connected to the logged-in user only appears if you have restricted access to a single user role. You won't have these options if you restrict access to multiple user roles.

From here, you can continue choosing the views you want on the page and naming the page. See this article for a detailed walk-through of the rest of this process.

Adding logins to an existing page

First, select the page from the left sidebar, click the "..." more options icon, and choose "Require Login" from the dropdown.

Follow the prompts and choose to limit the login to a specific user role. See the above section (Adding login permissions to a new page) for step by step instructions.

After you add the login, the page will now have a new parent page, or top level login page. This login page contains the login view, where you control access to that page.

Edit User Roles

To edit user roles, either select the "..." more options icon next to the user role name and then select the "Settings" option from the dropdown when viewing the user role.

In the user role settings, you can edit the following options:

  • Object Name: this is the name of the user role.
  • Display Field: this is the field which will be displayed to represent the record in connection fields.
  • Sort Order: this is the default order records will sort in within the user role.
  • Approval Template: this is the editable email template used to notify users have been approved.
  • Account Info Template: this is the editable email template used email users their account details.

Edit Permissions

To edit login permissions, select the page and choose the login view you want to edit. This will open the login view settings in the left toolbox where you can edit the permissions.

Allow access to all users

To allow access to all users leave the "Limit permissions to specific user roles" unchecked. This means every user can access this page, regardless of which user role they are assigned to.

This option is good for ensuring that only registered users can access your app. It works well on a home page. With this option, you cannot add any views to the protected page that show records specific to the logged-in user.

Limit access to specific user roles

To limit which user roles have access to login, enable the checkbox for "Limit permissions to specific user roles" under the "Permissions" section.

Only the selected user roles added under the "Which roles have permission?" will be able to access this page. This option is appropriate for most permissions circumstances where you want only a single subset of users to have access to the data and functions on the page. This is also the option you need to use in order to create views displaying records specific to the logged-in user.

You can edit login views to change what roles have access to your pages, but have caution when removing user roles from a login view. You will corrupt any views based upon the logged-in user. See Notes & Troubleshooting below for more details.

Delete User Roles

To delete a user role, click on the settings icon next to the user role name. Then choose the "Delete" option. This will delete the user role but will not delete the user records in that role. They will remain in the main Accounts object without that role.

When you delete a user role that is used in login views, the role will be removed from that login view. Remember to update any login views after deleting a user role. It will also corrupt any views based on that user role.

Delete Permissions

There are two ways to delete permissions from your Live App.

  1. You can delete the login view entirely, which opens up that page in your app to be accessed by anyone.
  2. You can also change the permissions on the login view to open the page up to a broader audience.

To delete a login view, navigate to the login page with the view on it. Click on the trash icon for the login view. This will remove the login from that page in your app.

To alter the permissions of your login view and open the page up to a different subset of users, see the "Edit Permissions" section above.

As with deleting a user role, deleting a login could also corrupt any views protected by that login that are based on the logged-in user (as users will no longer log in).

Using Roles & Permissions in your Live App

Here are a few other examples of apps where roles and permissions can be used to create a application that can be used across your business. Each of the user roles in these apps have their own pages, protected by logins restricted to their own role, with views that give them the functionality described below.

  • Project Management:
    • Admins can create projects, assign managers, and have full read/write privileges.
    • Project Managers manage one or more projects and assign tasks to employees.
    • Employees login to receive project tasks and track hours and costs.
  • Employee Hours:
    • Supervisors manage employees and view hourly totals and reports.
    • Employees login and submit hours.
  • Warehouse Manager:
    • Admins have access to view and perform all warehouse operations.
    • Warehouse staff can log in to ship recent orders or order more inventory.

Using Logins to Allow Users to See Only Their Records

One of the powerful configurations available in Knack is the ability to create pages that show each user only their own records.

By creating a page protected by a login and restricted to a single user role, you can add views to that page that show:

  • Records connected directly to the logged-in user.
  • Records connected to a company or group the logged-in user is also connected to.

Let's use the example of a Project Management app to show how these views can be used.

Records connected directly to the logged-in user.

Within a project management app, you can set up a Projects page for the Project Managers. Each Project Manager will log in and see all the Projects records they are connected to. In other words, the Project Manager logs in to see their Projects.

For instructions on setting up this kind of view, see this guide.

Records connected to a company or group the logged-in user is also connected to.

Taking it a step further than the example above, maybe you want an easier way for Project Managers to see all the tasks for their Projects at a glance. This can be helpful for the Project Managers to see who their project's Tasks are assigned to and the status of those tasks all in one place. You can set up a page that displays Tasks connected to the logged-in user's Projects.

For instructions on setting up this kind of view, see this guide.

Each of these scenarios require that the login has user role access restricted to only a single role (including the Accounts role). If the login view allows access to all user or more than one role, these options are no longer available.

Using Page Rules with Logins to Manage Permissions

Manage Permissions on Pages with Multiple User Role Access

We already covered most of the basics about using user roles with login views to control permissions in your Live App. The above section talks about some special views you can set up when you restrict login access to a single user role.

What about when you have multiple user roles who can access a single page but want to further manage permissions on a view level? That's where page rules come in.

Page rules are a great tool for simplifying your app. If you have a few different user roles that need access to mostly the same content, with the exception of a view or two, you can use page rules to show/hide certain views based on the user role.

For example, an internal company event calendar may be accessible to all the user roles in the company - HR, Managers, Employees, Directors - but only the HR users can add new events. You can set up a page rule to only show the form to add a new event if the logged-in user is in the HR user role.

Show/Hide Views Based on a User's Status

Similar to the example above, you can also use page rules to show or hide certain views based on a logged-in user's status. For example, you may have a member directory with multiple Member tiers. Basic and Premium Members can all view the Members list, but only Premium members can send a message to other Members.

Using page rules, you can choose to only show the form view to add a new message if the Member's status is Premium.

For more details on using page rules within your app, see this guide.

Notes & Troubleshooting

Removing user roles from your app and from a login view

Be cautious when removing user roles from a login view or when deleting them from your app altogether. If you have any views on the pages protected by the login that are reliant upon the logged-in user, they will be corrupted.

For example, if you have a page that shows Invoices for the logged-in Customer and you remove the Customer user roles from the login view, the Invoices view will be broken. The same principle applies when user roles are deleted.

When there is no option to add views showing records connected to the logged-in user

The option to add views displaying records connected to the logged-in user only appears if you have restricted access to a single user role. You won't have these options if you restrict access to multiple user roles.

The object of the records you want to display must be connected directly to the user role that has access to the page. For example, you may have a Notes object connected to Accounts, allowing all users of all roles to submit notes. To display the connected Notes records, you must restrict login access to the Accounts role directly, since that's the role connected to Notes.

How-To Guides

Here are some guides for functionality you can add to your Knack app with roles and permissions enabled:

How did we do?

Users and the Page Menu

Single Sign-On with Google, Facebook, Twitter, and Custom