A role is a collection of permissions that determines how people with that role will use your Teamworks AMS site. This article contains important information about:
- Managing roles
- Configuring roles
- Steps to create a new role
- Examples of different roles
- System permissions
- Data permissions
Managing roles
The Roles tool is used to manage how people can use your AMS site. This tool allows you to see a complete list of all roles on your AMS site including the Name and Description of the role. You can sort the roles using the Sort button or filter roles by Name, Description, System permissions or Data permissions.
To edit a role, search for and select it from the list. Alternatively, hover over the role to reveal the more options menu and select Edit, Delete or Duplicate. Deleting a role will delete the role itself but not the user accounts for the people who have access to the role. However, if those people do not have access to any other roles, they will not be able to log into the AMS site. Duplicating a role creates a new role with the same system and data permissions as the original. Other components of the role, such as people, are not included in the duplicate.
System roles are predefined roles that bundle existing permissions on the platform. They are managed by our developers and cannot be edited. Here are two examples of system roles you may see on your AMS site:
- SYSTEM_ROLE_API_USER (primarily used for integration connections)
- SYSTEM_ROLE_TEST (basic permissions primarily used by Teamworks developers for testing)
We do not recommend assigning users to these roles, but accidentally doing so will not pose a security risk.
Roles cannot be linked between sites on an enterprise server.
Configuring roles
Assigning permissions to a role
There are two types of permissions:
- System permissions: these are generic permissions that are common to every AMS site. There are important system permissions that govern a person's ability to enter data, view or edit their account details, see the sidebar, access their inbox, view their performance history and make use of tools such as reports, training blocks, scheduling and appointments.
- Data permissions: these are permissions specific to the content of your AMS site. Each time you create a category, build a form or set up a dashboard, AMS provides data permissions so that you can control which people are able to interact with that part of your site and how they're able to interact with it.
Some system permissions provide access to advanced administrator and builder features. These permissions are reserved for tools that require careful management, and therefore should not be accessible without the proper understanding of the tool's function. For this reason, these permissions can only be added to a role by the site owner or a SuperAdmin. These permissions must be added individually to a role via the search box; they are not available in the multi-selection window. Users must also be configured as a builder or administrator to interact with any advanced tools or functions they have access to.
Data permissions are specific to the content on your AMS site. Forms have different types of permissions according to whether they are event, profile, database or related entity forms. These are Linked, Calendar, Read, Write and Delete permissions, with the former two only applying to event and profile forms. Permissions for forms are somewhat hierarchical in the sense that having the Write permission automatically allows a form to be read, and having the Delete permission allows the form to be read and written. When assigning Write or Delete permission to a form, the inherent permissions will automatically be selected.
In the screenshot below, the Coach role has been assigned Write access to the Big Five Inventory Test and Army Combat Fitness Test event forms. Since the Read permission is inherently included in Write, the boxes have been automatically ticked and grayed out.
Categories and dashboards each have a single data permission associated with them, which enables the person to view the category contents or the dashboard. In the screenshot above, the Coach role has access to the Team Wellness Summary dashboard.
Note that having permission for a dashboard doesn't include the permissions for any data which is displayed in a dashboard; you need to add these data permissions separately. If a role does not include a minimum of Read data permissions for a data source within the dashboard, data will not be shown in any widgets referencing the data source.
Assigning users to a role
Roles must be assigned cautiously. Each role has different levels of access to sensitive data, including medical records and personal information. It is important that people are assigned to roles that match their authorized level of access to the data.
To assign users to a role, go to the Assigned to tab for the role and select Add. Use the search box in the sidebar to search for users and check the box next to their account name to select them.
To confirm the selection, select the Add selected button in the sidebar.
If we wanted to add two people (Jack Smith and Jamie Anderson, shown in the example below) to the role, we could search for Jack, select his account, then search for "Jamie." Selections will be retained, even if the filtering conditions are changed.
Enable multi-factor authentication for a role
As an administrator, you can enable multi-factor authentication (MFA) for specific roles. For example, MFA may be required for a medical role, but not an athlete role. If MFA is enabled, people must verify their identity on each device or browser they use to access AMS.
To enable MFA for a role, go to the Settings tab and tick the box to indicate that MFA is required. Next, select the communication method for people within a role to receive their authentication codes. This setting will become available after you've enabled MFA for the role and saved the changes to the role. The options are:
- Authentication App
- SMS
Depending on the site-wide MFA settings, you may not have the option to choose all three of these when setting up MFA for a role.
These options work in a hierarchy:
- If you select Email in the role settings, anyone with this role could elect to receive their codes via email, SMS or an Authentication app.
- If you select SMS, people with the role can only choose to receive their codes via SMS or an Authentication app.
- If you select the Authentication App, people will only have the option to receive codes via this method. You may not have the option to choose all three of these when setting up your role, depending on site-wide settings.
If you are restricting to authentication via an Authentication app only, people will need to have first logged in and located their MFA key. If people cannot log in and locate their key, they won’t be able to set up their Authentication app with it. The key can only be accessed by the individual who the user account belongs to (not by an administrator or coach).
You can specify a shorter time until accounts with this role require re-authentication by enabling Override system timeout. This is the duration, in months, after which someone must re-authenticate.
- An expiry period of 0 or a negative value means that the person will need to authenticate every time they log in, as the authentication expires immediately.
- An expiry period of >0 means that the person will need to re-authenticate their device when this number of months passed since their most recent authentication (e.g. if the expiry period is 6, the person will need to re-authenticate their device in 6 months).
If a new expiry period is set in the future, expiry will occur from the most recent date of authentication. If MFA is enabled site-wide and for a role where each has a different expiry period, the shorter expiry period will be adhered to.
Other login settings for a role
If single sign-on (SSO) is configured for your AMS site, you can enable SSO for a specific role in the Settings tab.
You can also override the system timeout set in the Application detail. In instances where different timeout periods are set at both the site- and role-level, users with that role will be required to re-authenticate their account after the shortest timeout period.
Team administrators
A user can have limited administration access to users with certain roles by being granted group admin access in the Settings tab. These group admins can assign users to the role through the administration interface. For more information, see our article on Team administrators.
In some instances, it may not be appropriate for a team administrator to edit user accounts within the role. For example, a team administrator may have access to coach or site administrator user accounts through their roles and groups. In the Settings tab, use the tickbox to prevent group admins from editing users within the role.
Steps to create a new role
- Log in to the administration interface.
- Select the Roles tool.
- Select New.
- Name the role.
- (Optional) Provide a description of the role, if necessary.
- Under the System permissions tab, tick relevant permissions to add them to the role.
- Under the Data permissions tab, choose the asset type (e.g. Event forms, Database forms, Dashboards), then select + Add.
- Search for and select the asset(s) to add to the role. You can select multiple assets but they should be from the same asset category (e.g. all event forms, or all dashboards).
- For forms, select the type of permission from the dropdown (Linked, Read, Write, Delete, Calendar).
- Click Add selected.
- You can further customize permission types in the matrix table.
- Repeat step 7 for any additional asset types.
- Under the Assigned to tab, select Add to search for and add users to the role. You can select one or multiple users. Click Add selected.
- To remove a user from a role, hover over the user, select the More option and select Remove.
- To remove multiple users from a role, search for and tick relevant users, then select Remove.
- Use the Settings tab to apply any additional settings.
- Enable Multi-factor authentication for people with this role.
- Enable Single sign on for people with this role.
- Enable a system timeout override for roles that require MFA.
- Enable Group administrators for the role, or prevent group administrators from editing users with this role.
- View or enable other administrative features such as:
- Page layouts
- System messages
- Terms documents
- Password policies
- Restriction policies
Examples of roles
Below are some examples of how you might configure roles for certain types of people.
Athlete
In this scenario, an athlete uses AMS to enter information about their daily wellness and training sessions. They also need access to a profile form with their emergency contact details and a dashboard summarizing their wellness and training data.
The system permissions that might be applicable to the athlete’s role are:
- Account write to update their account details.
- Athlete history to view their previous records.
- Dashboards read to view dashboards.
- Enter data to create and edit records.
- Profile data to create and edit profile records.
The data permissions that might be applicable to the athlete’s role are:
- Write access to the daily wellness form.
- Write access to the training data form.
- Write access to the emergency contacts profile form.
- Access to the summary dashboard.
Coach
In this scenario, a coach uses AMS to review the daily wellness and training session data that their athletes enter into AMS, as well as GPS data syncing via an integration. The coach needs to visualize this information on a dashboard to make decisions about upcoming training sessions and games.
The system permissions that might be applicable to the coach’s role are:
- Account write to update their account details.
- Dashboards read to view dashboards.
- Groups to view the different groups that they have access to.
- Reports to view tabular summaries of the data they have access to.
- Sidebar to view and navigate to athletes' data from the sidebar.
The data permissions that might be applicable to the coach’s role are:
- Read access to the daily wellness form.
- Read access to the training data form.
- Read access to the GPS data form.
- Access to the summary dashboard.
Medical practitioner
In this scenario, a medical practitioner uses AMS to enter and review medical consultation notes and run injury surveillance statistics to present to the board at quarterly meetings. They should also be able to see a summary form which has information linked from the wellness, training and emergency contact forms to provide them with additional context during medical consultations.
The system permissions that might be applicable to the practitioner’s role are:
- Account write to update their account details.
- Dashboards read to view dashboards.
- Enter data to create and edit records.
- Groups to view the different groups that they have access to.
- Reports to view tabular summaries of the data they have access to.
- Sidebar to view and navigate to athletes' data from the sidebar.
The data permissions that might be applicable to the practitioner’s role are:
- Write access to the medical consultation notes form.
- Read access to the summary form.
- Linked access to the daily wellness form.
- Linked access to the training data form.
- Linked access to the GPS data form.
- Linked access to the emergency contact details profile form.
- Access to an injury surveillance dashboard.
System permissions
This section briefly describes each system permission which may be added to a role. System permissions marked with an asterisk can only be assigned to a role by the site owner or a SuperAdmin.
Some important considerations for roles with advanced system permissions:
- Administrators who are not the site owner or do not have the Assign SuperAdmin-only permissions system permission in their own role are unable to edit roles that contain any advanced system permissions.
- Administrators who are not the site owner or do not have the Assign SuperAdmin-only permissions system permission in their own role are unable to assign roles that contain any advanced system permissions to user accounts.
- Users that register for an account will not be given access to any roles that contain advanced system permissions even if they are part of a Default role.
- Password policies and Terms documents cannot be removed from any roles that contain advanced system permissions.
Data entry permissions
Enter data
A front page tool (Enter data) that allows the person to fill out event forms they have Write data permission for. This system permission must be enabled for people to fill out event forms, regardless of any Write data permissions they have.
Enter data for group
A front page tool (Enter data for group) that allows professional users to enter data for event forms they have Write data permission for using group entry mode. If this system permission is assigned to non-professional users, the front page tool will not appear. The event form must also be enabled for group entry mode in the advanced form properties.
Edit athlete fields
Allows the person to tag other people in the event form using the Single athlete, Coach or Multiple athletes fields.
Import data
A front page tool (Import data) that allows people to import historical data for an event form using the web version of AMS. Users need Write data permission for individual forms.
Profile data
A front page tool (Profile data) that allows people to fill out profile forms they have Write permission for. This system permission must be enabled for people to fill out and view profile forms, regardless of any Read or Write data permissions they have for profile forms. This system permission is also required for the person's contact information, such the phone number or email address associated with their account, to be displayed beneath their profile image.
Import profile data
A front page tool (Import profile data) that allows people to import data for a profile form using the web version of AMS. People need Write data permission for individual forms and Profile data system permission to view profile forms.
Reporting permissions
Athlete history
A front page tool (History) that takes the person to their performance history and allows professional users to view the performance history of other people. Also enables the History button in the profile section of the athlete sidebar and the Activity screen for athletes on the mobile app.
Dashboards read
This system permission gives people the ability to access the dashboard tool for the purposes of viewing custom dashboards and dashboards created using the Dashboard builder. For each dashboard created using the Dashboard builder, there is a corresponding data permission that must be included in a person’s role for them to access that dashboard. To view custom dashboards, people must have the data permission for the relevant dashboard’s category in their role.
Dashboards write
This system permission is scheduled for removal and relates to an obsolete dashboards front page tool.
Recent entries
A front page tool (Recent entries) that allows people to view all event forms in chronological order from most to least recent. Professional users can choose to view the recent entries by group member or by group. Also enables the Activity screen for athletes on the mobile app.
Excel reports write
Ability for people to create Excel reports about themselves. Professional users can create Excel reports about other people.
Excel reports read
A front page tool (Excel reports) that allows people to download Excel reports about themselves that have been shared with them. Professional users can download Excel reports about other people that have been shared with them.
Reports
A front page tool (Reports) that allows people to create reports using forms they have Read data permission for. Professional users can choose to create reports using one or more members of the currently-loaded group.
Reports - export
Ability to use the Excel button to export data as a CSV from the Reports and Performance history tools, if the role includes access to those tools.
Reports - send to front page
Ability to use the Send to front page button in the Reports tool. For the report to be visible, the Front page reports button must be part of the person's page layout and the Reports system permission must be included in the role.
Reports - send to users front page
Ability to use the Send to front page of users button in the Reports tool. For the report to be visible, the Front page reports button must be part of the person's page layout and the Reports system permission must be included in the role.
Reports - PDF
Ability to use the PDF and PDF (Form) buttons to export data as a PDF from the Reports and Performance history tools, if the role includes access to those tools.
Reports - send to users
Ability to use the Save copy to users button in the Reports tool, if the role includes access to that tool.
Reports - send email
Ability to email a copy to selected people of exported reports created using the Excel, PDF or PDF (Form) buttons in the Reports and Performance history tools. Additional tools are required to access these tools and export features.
Scheduling and appointments
Enter scheduled data
A front page tool (Enter scheduled data) that allows the person to fill out scheduling forms. People need Write data permission to individual scheduling forms.
Enter appointment
A front page tool (Enter appointment) that allows the person to fill out appointment forms. People need Write data permission to individual appointment forms.
Training blocks write
This gives people the ability to duplicate and edit training blocks that have been shared with them, create new training blocks and share training blocks with other people. This requires Read data permission for individual forms.
Calendar
Front page tool (Calendar) that takes the person to a calendar containing their events (if set up to appear in calendar); allows a professional user to view the calendar of another person.
Preview schedule
A front page tool (Preview schedule) that allows people to view scheduled events for related entities. Requires Read data permission for individual related entity and scheduled event forms.
Related entity calendar
A front page tool (Related entity calendar) that allows people to view a calendar view of events for all related entities for which they have Read data permission.
Publish scheduled events
Ability to use the Publish and Publish with iCals buttons in the Preview schedule tool. Requires the Preview schedule system permission.
Schedule page
A front page tool (Schedule) which allows people to view event forms from a selected date for a specified number of days. Professional users can view the schedule of all members of the current group.
Training blocks read
A front page tool (Training blocks) that allows people to see and apply training blocks that have been shared with them. This requires Read data permission for individual forms. Professional users are able to apply training blocks to multiple members of the currently-loaded group.
Site layout
Sidebar
This gives people the ability to view and interact with the left sidebar, which displays the event form categories, event forms, a link to enter new event form records and the event form performance history if enabled.
Athlete sidebar
This gives people the ability to view and interact with the right sidebar, which displays the selected person's photo (if available), critical information and links to their profile (if the Profile data system permission is assigned), internal messages (if the Messaging system permission is enabled), performance history (if the Athlete history system permission is assigned) and new favorite event records. Note that the athlete sidebar will always be available when the Sidebar system permission is enabled - that permission encompasses this permission.
Resources
Resources
A front page tool (Resources) which allows people to access content uploaded as a resource. Category data permission must be enabled for the person to access content in individual categories.
Resources - upload
Ability to use Manage resources button in the Resources tool to upload and edit content in categories that the person has data permissions for.
Groups and notifications
Groups
Ability for people to change between groups they are members of or have access to.
Messaging
This gives people the ability to access messaging buttons, including the inbox link if included in the page layout. Non-professional users can send messages to the professional users with access to their current group. Professional users can send messages to other professionals with access to the current group or to members of the group. Messages can be sent from the inbox or from different parts of the system, for example, the reports tool.
Performance alerts read
A front page tool (Performance alerts) that allows people to view and edit performance alerts where they are the owner of the alert. They can also view and action any activated alerts. Any performance alerts of which they are a Notified user are listed, along with any notification criteria and the alert message.
Performance alerts write
This gives people the ability to create performance alerts. People can only create performance alerts with themselves as the monitored and notified user. Anyone with coach access to a group can create performance alerts with anyone in the group they are viewing (or the entire group) as the monitored group and with anyone in the current group or another professional user as the notified user/s. Note that only the person who creates a performance alert is able to edit it. For site administrators, this permission allows them to create new performance alerts using the Performance alert management tool in the administrator interface.
Personal groups read
A front page tool (Personal groups) that allows a professional user to create personal groups from members of the current group. Only useful to professional users.
Personal groups write
This system permission is obsolete and scheduled for removal.
Accounts
Account read
This gives people the ability to view their account details, such as username, first name, last name, password field (the password itself is never visible in plain text), email and contact information. People can view but cannot edit account information unless they also have the Account write system permission.
Account write
This gives people the ability to edit their account details, such as username, first name, last name, password field (the password itself is never visible in plain text), email and contact information. It not necessary to also have the Account read permission if you have the Account write permission. See also: Edit athlete account – partial.
Edit athlete accounts
Allows professional users to edit some account information for other people without needing access to the administration site. This is done via the Athlete profiles button or the profile section of the right sidebar (requires Athlete sidebar system permission).
Edit athlete accounts - partial
Allows professional users partial ability to edit account details for other people without needing access to the administration site via the Athlete profiles button or the profile section of the right sidebar (requires Athlete sidebar system permission). This is limited to making changes to the following fields:
- Known as
- Date of birth
- Sex
- Account picture
- Addresses
- Phone numbers
- Language
- Favorite events
- Favorite dashboards
- MFA code communication preference
This system permission can be assigned in place of Edit athlete accounts (for professional users). To edit your own account details (as a professional or non-professional user), refer to the Account write system permission.
User onboarding
A tool that can be used to assist in onboarding people to AMS via QR codes.
Advanced
Delete all
A button in reports and performance history that allows the person to delete all records when using the Reports or Performance history tools. Professional users can use this to delete multiple records for multiple people. This system permission should not be enabled in most roles and is best only assigned to site builders and administrators. Records can only be deleted if the person also has the relevant data permission to Delete records for the event form.
The Delete all system permission should not be enabled in most roles. It is best to only assign the permission to site builders and administrators.
*Assign SuperAdmin-only permissions
This permission enables an administrator to assign advanced system permissions to other roles and to manage roles that include this permission.
*Assign builder/admin permissions
This permission enables an administrator to assign builder and administration access to other accounts via the Accounts tool.
Other
Yearly plans read
A front page tool (Yearly plans) that allows people to view yearly plans created by professional users of the currently-loaded group and/or a yearly plan that has been applied to them. Requires Read data permission for individual forms.
Yearly plans write
This gives people the ability to duplicate and edit yearly plans that have been shared with them, create new yearly plans and share yearly plans with other people. This requires Read data permission for individual forms. Professional users are able to apply yearly plans to members of the currently loaded group.
Schedule calendar
Ability to view a schedule as a calendar when using a mobile device. Requires Schedule page system permission to be enabled.
*Administrate Smart flows
This permission enables an administrator to view, edit, duplicate and delete Smart flows.
*Administrate Smart saves
This permission enables an administrator to view, edit, duplicate and delete Smart saves.
*Set custom passwords
This permission enables an administrator to assign a custom password to an account. Without this permission, the administrator can only activate a password reset email, which the person can then access to update their password.
*Manage object ownership
This permission enables an administrator to find and edit the owner of a data structure (object) in the builder interface.
*Manage password policies
If an AMS site's Application details has been set to allow multiple password policies, this permission enables an administrator to create, edit and delete items in the Password policy management tool.
*Manage security whitelists
This permission enables an administrator to create, edit and delete items in the Security whitelist tool.
*Allow site creation
This permission enables a builder to create new AMS sites on the server via the Create new application tool of an existing application.
*Set system overrides on restriction policies
This permission allows an administrator to enable system overrides on restriction policies. This is configured in the Restriction policies tool and is only used for certain bespoke workflows.
*Manage event data conflicts
This permission enables an administrator to view and manage data conflicts in the Data conflict management tool.
*Edit application details
This permission enables a builder to use the Application details tool.
*Merge users
This permission enables an administrator to merge user accounts within the Accounts tool.
Download all files
This permission gives people the ability to download a ZIP file containing multiple files associated with records shown in a report or performance history. This permission is only available when the feature is enabled in the site’s Application details.
Allow site switching
This permission allows people to easily switch between child sites from the user, builder and administration interfaces if they’re part of an enterprise system (multiple, linked sites on the same server). This permission is only available on sites within an enterprise configuration.
Manage shared sites
This permission enables an administrator to manage site sharing configurations for forms, data, categories and users if they're part of an AMS enterprise system (i.e. multiple, linked sites on the same server). This permission is only available on sites within an enterprise configuration.
*Administrate Integrations Manager
This permission will enable a future feature regarding integrations.
Data permissions
Data permissions are permissions specific to the content of your AMS site. Categories and dashboards each have a single data permission associated with them, which enables the person to view the category contents or the dashboard. Note that having permission for a dashboard doesn't include the permissions for any data which is displayed in a dashboard; you need to add these data permissions separately. If a role does not include a minimum of Read data permissions for a data source within the dashboard, data will not be shown in any widgets referencing the data source.
Forms have different types of permissions according to whether they are event, profile, database or related entity forms. These are Linked, Calendar, Read, Write and Delete permissions, with the former two only applying to event and profile forms. Permissions for forms are somewhat hierarchical in the sense that having the Write permission automatically allows a form to be read, and having the Delete permission also allows the form to be read and written. This means that you can give people a single data permission for a form which reflects the maximum level of interaction they can have with the data. The list below describes each type of data permission in order from most to least restricted.
Linked
Gives people the ability to see data from this form in other forms. This data permission means you don't have to give people full Read access to a form. Instead they can see selected information which is linked into forms they have Read access to.
Related entity and database forms do not have the Linked data permission.
Calendar
Gives people the ability to see this form in the calendar if it has been enabled to appear in the calendar. With this permission, someone can see that a record exists and when it was recorded but can only see data that has been set up to appear in the calendar summary.
Related entity and database forms do not have the calendar data permission.
Read
Gives people the ability to view data entered into a saved record for this form. This data permission makes the Linked and Calendar data permissions unnecessary. Forms which the person has Read access to will appear in dashboards, the sidebar, performance history, reports and other parts of AMS. They will not appear in the data entry process.
Write
Gives people the ability to create and edit records for this form. This data permission makes the Read permission unnecessary. Forms which the person has Write access to will appear in the data entry process, the sidebar, performance history, reports and other parts of AMS.
Delete
Gives people the ability to delete a record created using this form (exception: related entity records cannot be deleted by a user and must be deleted by a builder). This data permission makes the Write permission unnecessary. Forms which the person has Delete access to will appear in the data entry process, the sidebar, performance history, reports and other parts of AMS.
Deleting a record will permanently delete the record from AMS. This data permission should only be assigned to people who are authorized to delete records.