In this article, we will guide you through the process of managing user roles and permissions when using views and pages in your Knack app.
In order to assist you in quickly finding the information you require, this article covers the following topics:
How To Guides
What are roles and permissions?
With Knack, you have the ability to utilize roles and permissions to define various user types that can access your Live App and determine how they can interact with it.
To begin, navigate to the Data section of the Builder and define user roles for each type of user. This will unlock a multitude of possibilities for customizing and streamlining their experience with your Live App.
User roles can be utilized to enable permissions in the Pages section of Builder through logins. Each user role has its own pages where users in that role can only view, edit, and delete the data that you define.
These are the two essential components needed to enforce permissions in your Live App: user roles and login views restricted to a specific user role.
Let's take a look at how roles and permissions are used in our Customer Portal sample app.
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 provides customers with the ability to perform three actions:
Add a new service request
View current and past service requests
The Managers' page has much more functionality. Managers are able to:
View and edit all customers
See their related service requests and invoices
Add new records - customers, invoices
To effectively manage the customer side of the business, it is necessary for managers to have access to all the data in the database.
Note: When considering your roles, it is essential to consider the individuals who will be utilizing your application and how they will be utilizing it. The roles are not necessarily determined by job titles but rather by their specific functions and responsibilities.
Activating User Roles
Before you can use user records with your app, you must first enable users. You can learn more about users and how to activate them here.
Managing User Roles & Permissions
Adding User Roles
User roles play a vital role in establishing permissions. Make sure to add a user role for every user type that will access your Live App.
To create new user roles, simply click on the "+" button next to the "User Roles" text. This option will guide you through the process of setting up a new user role.
Once you have established your user roles, you can easily configure permissions for your pages. To accomplish this, simply add login views and restrict access to specific user roles.
Adding Login Permissions to a New Page
By enabling logins during the page creation process, you can conveniently include views that showcase records connected to the logged-in user right from the start.
Click on the "+" button above the page list and choose "Login Page" from the options in the dropdown menu.
This will open a helpful guide or "wizard" that will walk you through the process of creating the login settings according to your preferences.
In the role selection box, choose the role for which you want to permit access to this page:
Note: 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.
Based on the user role you have assigned to this page, you can now personalize it to meet their specific needs. For instance, if access is limited to the "Customer" user role, you can opt to display the Invoices associated with 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 walk-through of the rest of the process.
Adding Logins to an Existing Page
To add a login to an existing page, there are two options available. The first option is to select the desired page from the page tree.
Then, you can click on the arrow button next to the page name and choose the "Require Login" option. Alternatively, you can click on the lock icon in the top page navigation and select "Require Login".
Simply follow the prompts to select whether you would like to restrict the login to a specific user role.
Once you have added the login, the page will have a new parent page, or top-level login page, as indicated by the "lock" icon. This login page will provide you with settings to control the access to that particular page.
Editing User Roles
To edit user roles, either select the dropdown arrow icon next to the user role name and then select the "Settings" option.
In the user role settings, you can edit the following options:
Table Name: This represents the name of the user role.
Display Field: This field represents the record that will be displayed in connection fields.
Sort Order: This represents the default order in which records will be sorted within the user role.
Approval Template: This is the customizable email template used to notify users that they have been approved.
Account Info Template: This is the customizable email template used to send users their account details.
To modify login permissions, simply select the desired page and choose the login view that you wish to edit. Alternatively, you can click on the lock icon located in the top page navigation.
This action will open up the login view settings in the left toolbox, allowing you to easily make changes to the permissions.
Allowing Access to All Users
To give access to all users, simply leave the "Limit permissions to specific user roles" unchecked. This way, every user will be able to access this page, regardless of their assigned user role.
This option is great for ensuring that only registered users can access your app. It is particularly suitable for a home page.
However, please note that with this option, you won't be able to include any views on the protected page that display records specific to the logged-in user.
Limiting Access to Specific User Roles
To restrict access to login for specific user roles, simply check the box for "Limit permissions to specific user roles" in 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.
Caution: When modifying login views to adjust the roles with access to your pages, it is important to exercise caution when removing user roles from a login view. Doing so may cause any views that rely on the logged-in user to become corrupted.
See the Notes & Troubleshooting section below for more details.
Deleting User Roles
To remove a user role, simply click on the settings icon next to the name of the user role. Then, select the "Delete" option. This action will remove the user role, but it will not delete the user records associated with that role.
The user records will still be retained in the main Accounts table, but without the assigned role.
Caution: If you delete a user role that is being used in login views, the role will be removed from those login views. Make sure to update any login views after deleting a user role to avoid any issues.
Additionally, deleting a user role can corrupt any views that are based on that user role.
There are a couple of ways you can 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, simply navigate to the login page where the view is located. Next, click on the trash icon for the login view.
This action will remove the login from that specific page in your app.
Tip: To alter the permissions of your login view and open the page up to a different subset of users, see the Editing Permissions section above.
Caution: 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 (users will no longer log in to view the page).
Using Roles & Permissions in Your Live App
Here are a few other examples of apps that demonstrate how roles and permissions can be utilized to create an application that can benefit your entire business. Each user role in these apps has its own dedicated pages, which are protected by logins restricted to their respective roles.
These pages include views that offer the functionality described below.
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.
Supervisors manage employees and view hourly totals and reports.
Employees login and submit hours.
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 amazing features in Knack is the capability to design pages that display each user's individual 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.
Now, let's take a look at a Project Management app and see how these views can be utilized.
Records Connected Directly to the Logged-In User
In a Project Management app, you have the ability to create a Projects page specifically for Project Managers. When they log in, each Project Manager will be able to view all the Projects records that they are associated with.
Essentially, the Project Manager logs in to access their own Projects.
Tip: 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
To enhance the functionality for Project Managers, you can provide them with an easier way to view all the tasks associated with their projects in one place. This feature allows Project Managers to quickly see which tasks are assigned to their projects and the status of those tasks.
You can set up a page that displays "Tasks connected to the same Projects connected to the logged-in Project Manager".
Tip: For instructions on setting up this kind of view, see this guide.
Note: 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 users or more than one role, these options will no longer be available.
Using Page Rules with Logins to Manage Permissions
Manage Permissions on Pages with Multiple User Role Access
We have already discussed the fundamental concepts of using user roles with login views to manage permissions in your Live App. The previous section provides information on specific views that you can create when restricting login access to a single user role.
What if you have multiple user roles that can access a single page but need to manage permissions on a view level? This is where page rules come into play.
Page rules are an excellent tool for streamlining your app. If you have multiple user roles that require access to mostly the same content, with just a view or two that differs, you can utilize page rules to selectively display or hide specific 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. Only the HR users can add new events.
You could set up a page rule to only show the form to add a new event if the logged-in user is assigned 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.
Tip: 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
Please exercise caution when removing user roles from a login view or deleting them from your app. If there are any views on the pages protected by the login that rely on the logged-in user, they may become corrupted.
For instance, if you have a page displaying Invoices for the logged-in Customer and you remove the Customer user roles from the login view, the Invoices view will no longer function properly. The same concept applies when user roles are deleted.
When There is No Option to Add Views Showing Records Connected to the Logged-In User
If you limit access to a single user role, you will be able to add views that display records connected to the logged-in user. However, if you restrict access to multiple user roles, you won't have these options available.
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.
Below are some helpful guides that will assist you in adding functionality to your Knack app with roles and permissions enabled.
- Show Records Connected to the Logged-in User
- Show Records Connected To The Logged-in User's Company Or Other Group
- Create an Admin User Role to View All Records
- Add Read-Only Access For Users
- Track Which User Last Updated a Record