How to create a role to assign permissions

Roles serve two primary functions:

  • Grant permissions to a specific user.  For example, this can be for an entire apps or to limit users to specific aspects of an app (dashboards, views/records, forms).
  •  Set preferences for a user, including Administrators.  The order of Dashboards, and which Form is used to create new records or view existing records is set through the Role.  Note: this applies to Super Admins as well.

Creating a Role

Navigate to the Admin icon and click "New Role" from the Roles drop-down menu. You should now be viewing the Role Settings page.

Rename the Role
The first step is to give the role a name by clicking the text, 'New Role', in the top left corner of the page. Role name is required and cannot be duplicated.

Role Type
Before assigning dashboards, forms and views to the role, you will want to select the Type of role you are creating. There are two options: Limited and App Admin.

  • The App Admin user type will automatically be granted permission to view and edit all resources in the app. The sections below are only used to set an Admin's preference for which dashboards appear on their home page and for which forms appear by default when creating records and opening records from a view. When a user is assigned as an app Admin, they will see the "Admin" icon in the header of the account. This allows them to access the 'App Overview' page for any app where they have been added to an Admin role. The App Admin role consists of 4 sections: Users, Dashboards, Flows, Resources.
  • The Limited user type requires the assignment of specific resources that have been created within the app in order for them to access anything in the app. The Limited User role consists of 5 sections Users, Global Permissions, Dashboards, Flows, Resources. See the sections below for an explanation of the resources that can be granted.

Global Permissions

This section is only available to Limited User Roles. Here you can designate a limited user's app wide permissions. 

Dashboards


This section is where you can give a role permission to view a Dashboard and to set a Dashboard as a home page. Click the 'ADD/REMOVE' button to open a dialog for selecting which dashboard is appropriate for this role. This window contains each dashboard in the app. You can assign multiple dashboards to a role, if needed.

When you select a dashboard, its elements (Views and Forms) are automatically added to the Resources section. When you assign a dashboard to a role and an element on the dashboard has not yet been explicitly granted permission to it, the system will require you to select an edit form for this new resource. If you click the Done button without granting access to all of a dashboard's elements, you will see a warning icon next to it to remind you.

When multiple Dashboards are assigned to a Role, you can drag and drop each Dashboard to position them in a specific order. The first Dashboard in the list will be the home page for the users in that Role. The order of the Dashboards determines the order of the links at the top of the page (from left to right) when a user is viewing a Dashboard. You can display four or five links across the top of a dashboard, with the rest of the links under the More drop-down menu.

The ability to filter resources by dashboard is also available. Click the Filter icon on the right of a dashboard to show only the forms and views that apply to this dashboard in the Resources section.

Notice the filter icon is now circled (until you navigate away from this section) and the Filter button in the Resources section is highlighted.

Flows

The Flows section works similarly to the Dashboards section. When you add a flow, the TrackVia app will automatically crawl the flow and add associated top level resources to the Resources section below where the admin can review and update permissions as needed.

In addition to adding flow, you can also filter the resources for a flow. Click the Filter icon on the right of a flow to show only the forms and views that apply to it in the Resources section (more on this below).

Notice the filter icon is now circled (until you navigate away from this section) and the Filter button in the Resources section is highlighted.

Resources

This is the most powerful and complex section of the Role Builder page.  

The Resources section lets you:

  • add Views & Forms
  • assign Read, Write, Delete record permissions
  • configure Offline, Print, Share & Notification, Export & Hide Add Record preferences
  • set the create form to be used when a user clicks the Add icon on a view  
  • set more than 1 create form for a role
  • filter resources by dashboard
  • filter resources by flow


Tables
Tables are listed in alphabetical order.  

Tables with assigned resources use dark text and will appear at the top in alphabetical order. Those without assigned resources will appear below in gray text.

Tables shared with other applications are designated with the ‘Cross App’ icon.

Resource Count
Immediately upon looking at the Resources section, you’ll notice several elements.

Each table has ‘at a glance’ information if at least one resource has been assigned. These ‘hero data pills’ display the number of assigned views (orange) and forms (green) for each table, as well as an indicator of the create form for the Add button ("Create New Records Using"). A blue pill with a name will identify the form or the pill will be gray if none has been assigned.

These counts automatically update as resources are added and removed. 

Search
Search for any resource (Table, View or Form) in the app.  

If no resources have been assigned, the search will bring back only table names.

If resources have been assigned, the search will bring back tables, views and forms which match, highlighted in yellow.

For example, “mat” has been entered in the search bar below. The list of available resources displays after typing the third and consequent letters in a ‘type-ahead’ style..

Press Enter after typing a search term and matching resources are highlighted in yellow.


Filter

Use the Filter button to filter resources already assigned through a dashboard or flow, giving you a convenient way to see the components of a dashboard or flow and manage the permissions appropriately.  

Click the Filter button and choose Dashboard or Flow. Then select the specific dashboard or flow which has been assigned and click "Apply" (or click Clear to clear the filter).

The Resources section will update to show only the elements associated with that dashboard or flow. In this example, you’ll see the Active Job Management dashboard name highlighted in blue and only those resources associated with the dashboard.  

Click the "Clear Filter" button to remove the filter.

Recall the Filter icon in the Dashboards and Flows sections. Using that automatically applies the filter to the Resources section.  

For example, clicking the Filter icon beside ‘Active Job Management’ in the Dashboards section activates the filter in the Resources section.

Expanding a Table

Click the arrow on the left of a table name to expand that section and see assigned views and forms.

Creating New Records

"Create Forms" are specifically identified forms that allow users in a role to add records to a specific table. You can assign multiple forms for creation, however there is only one primary add form per table.  The user will only be able to add data into the fields that are included on the form assigned here (unless the field is marked as read only on the form).
Note:
Sometimes these forms are simpler than their counterparts, so that whomever is adding the record can do so with minimal effort.

A user who is allowed to create new records will see a stylized + button on a view. This button invokes the form specified in the "Create New Records Using" dropdown list.

In the example below, the create form has not been assigned. Notice the blank selection in the “Create New Records Using:” dropdown. This is also identified by the “No Create Form” gray pill.

Once a form has been selected, the admin will see a blue pill with the name of the form

As mentioned above, a role can have more than one Create Form for a table.



In the above example, [Jobs] Default Form has been designated as the primary create form for the + Add button on a view. This information shows up as the blue pill and in the Assigned Forms section with Create Permission toggled on (green).

For the Jobs Details form, an admin can also toggle on Create Permission to designate another create form.

Use one or more additional create forms in these situations:

  • Set up a flow using different create forms for ‘Add’ steps

  • Place the form on a dashboard

  • Use the form for a dashboard shortcut

Reminder: when adding a record to a view using the ‘Add New Record’ or ‘Save and Add New’ button, the primary create form is used.



Assigned Views - Add/Remove Views

Click the ‘Add/Remove Views’ button to open a modal showing the list of views. Check one or multiple views and click "Done" to add to the role. Conversely, uncheck from the list and click "Done" to remove from the role.

Click "Cancel" or the X in the upper right corner to close the modal window without changes.

View Permissions

Permissions vary based on the role. Admin roles will have full permissions, as expected, with an option to set a view to be available offline.

For a limited user role, the admin can grant View Permissions, choose an Edit Form and configure Edit Permissions for the record as before. Hover over the icons to see what each represents.

Remember, settings in the Global Permissions section can govern the view permissions too.

Click the X in the Add/Remove column to remove this view from the role.

Views & Record Editing


This section allows you to grant limited users access to specific views in a table in the app.  When you grant access to a view, you are giving the limited user permission to every record in that view.  Next, you will want to choose the form the role is going to use to view or update these records when a single record is opened. The limited user will only be able to update the fields that are included on the form assigned here (unless the field is marked as read only on the form).  For a limited role, in the next drop-down menu, you will be able to choose one of three options for the records in the view: 'Read, Update & Delete', 'Read & Update', or 'Read only'.  ***The Form Permissions set here will apply to all views that have been assigned the same form.
Note: Limited users will only be able to in-cell edit the fields on a view if that view's form has given the user permission to edit it. 

Before you finish, let's add some users to this role!

Don't forget to click 'save' before leaving the page!


Feedback and Knowledge Base