Roles

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
• Email

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

1. Log in to the administration interface.
2. Select the Roles tool.
3. Select New.
4. Name the role.
5. (Optional) Provide a description of the role, if necessary.
6. Under the System permissions tab, tick relevant permissions to add them to the role.
7. 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.
8. Repeat step 7 for any additional asset types.
9. 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.
10. 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.
11. 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.

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.