Table of Contents
Manage Roles & Permissions
Updated
by Lesley
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 Data 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.
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:
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.
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
There are two options to add a login to an existing page. The first is to select the page from the page tree. Then click on the “...” next to the page name and choose the “Require Login” option. You can also click the lock icon in the top page navigation and choose "Require Login":
Follow the prompts to choose if you want to limit the login to a specific user role.
After you add the login the page will now have a new parent page, or top level login page (as indicated by the “lock” icon). This login page will have settings for controlling the access to that page.
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:
- Table 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 or click the lock icon in the top page navigation. This will open the login view settings in the left toolbox where you can edit the permissions.
The second is to click directly on the login view or click the edit “pencil” icon to open the login options:
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.
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 table without that role.
Delete Permissions
There are two ways to delete permissions from your Live App.
- You can delete the login view entirely, which opens up that page in your app to be accessed by anyone.
- 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.
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.
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 table 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 table 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:
