Migrating User Groups to Project Roles

Project roles are a flexible way of associating particular users and groups with a particular project.

Why migrate to Project Roles?

  • Ease of management — JIRA versions prior to 3.7 did not have project roles. If you previously used JIRA 3.6.x (or earlier), your system may contain multiple, project-specific groups, permission schemes and notification schemes. By implementing project roles, you may be able to reduce the number of groups, permission schemes and notification schemes in your JIRA system. This can make your system easier to manage.
  • Delegated administration — A project administrator (that is, someone who has the 'Administer Project' permission, but not necessarily the global 'JIRA Administrator' permission) can assign users and groups to project roles for their project. If their project's permission scheme and notification scheme are using project roles, the project administrator can control who may access their project and who receives email notifications.

The instructions on this page will help you use Scheme Tools to:

  • update your permission schemes and notification schemes so that they use project roles instead of groups; then
  • minimise the number of permission schemes and notification schemes in your JIRA system.

On this page:

Updating Permission Schemes and Notification Schemes to use Project Roles instead of Groups

Before you begin: Back up your existing JIRA data.

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Choose > System. Select Advanced > Scheme Tools to open the Scheme Tools page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'scheme tools'
  3. Click the 'Group to Project Role Mapping Tool' link.
    Screenshot 1: 'Scheme Tools'
  4. This will display the 'Map Groups to Project Roles: Select Schemes' page:
    Screenshot 2: 'Map Groups to Project Roles: Select Schemes'

    • Note that schemes that are not associated with any projects need not usually be included in this process; but if you wish to select from all schemes in your system (including unused schemes), click 'All'.
    • Under 'Step 1: Select a scheme type', select whether you want to update permission schemes or notification schemes. (You can only do one type of scheme at a time, but you can easily come back and do the other type later).
    • Under 'Step 2: Select the schemes to work with', select the schemes you want to update to use project roles instead of groups. You can use the 'Ctrl' key to select multiple schemes.
    • Click the 'Map Groups to Roles' button.
  5. This will display the 'Map Groups to Project Roles: Select Mappings' page:
    Screenshot 3: 'Map Groups to Project Roles: Select Mappings'

    For each group, select the project role that will replace it; or, for any groups that you do not want to migrate, choose the 'Do not map group' option. Then click the 'Preview Mappings' button.
    • For ease of maintenance, it is recommended that you do not migrate any groups to which JIRA users are automatically added (that is, groups which have the 'JIRA Users' global permission). If you migrate these groups to project roles, and you still want all new users to have access to particular projects, you will need to manually add new users to the relevant project role for each project.
  6. You will now see the 'Map Groups to Project Roles: Preview Transformation for Schemes' page:
    Screenshot 4: 'Map Groups to Project Roles: Preview Transformation for Schemes'

    If you are satisfied that the information shown on this page is correct, click the 'Save' button to:
    • create a backup of the scheme(s) that you selected in step 5 (you can later delete this backup scheme by using the 'Bulk Delete Schemes Tool', available from the 'Scheme Tools' page shown in step 4). This backup scheme will not be associated with any projects.
    • update the scheme(s) that you selected in step 5 to use the role (left of the blue arrow) instead of the group (right of the blue arrow)
    • add the users (in the right column of the table) to the project role (in the left column of the table) for each project that uses the scheme. This ensures that all users will continue to have the same permissions and notifications.
  7. You will now see confirmation of the above changes on the 'Map Groups to Project Roles: Results of Transformation for Schemes' page:
    Screenshot 5: 'Map Groups to Project Roles: Results of Transformation for Schemes'

After updating your permission schemes and notification schemes to use project roles instead of groups, you may find that many of your schemes are now very similar. To identify such schemes, merge them, and delete any redundant ones, please see Minimising the number of Permission Schemes and Notification Schemes (below).

You may also find that some groups are no longer required. You can use the Group Browser to identify and delete groups that are not used by any permission schemes or notification schemes.

Minimising the number of Permission Schemes and Notification Schemes

Minimising the number of permissions schemes and notification schemes can make your JIRA system easier to manage. To identify and remove unnecessary schemes, follow the steps below:

Before you begin, please perform a full backup.

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Choose > System. Select Advanced > Scheme Tools to open the Scheme Tools page.
    (tick) Keyboard shortcut: 'g' + 'g' + start typing 'scheme tools'
  3. Click the 'Scheme Comparison Tool' link.
    Screenshot 6: 'Scheme Tools'

    • The Scheme Comparison Tool assists you in identifying similar schemes, and if appropriate, making them identical.
    • Identical schemes can later be merged using the Merge Duplicate Schemes Tool (see step 9 below).
  4. This will display the 'Scheme Comparison: Select Scheme' page:
    Screenshot 7: 'Scheme Comparison: Select Scheme'

    • Note that schemes which are not associated with any projects need not usually be included in this process; but if you wish to select from all schemes in your system (including unused schemes), click 'All'.
    • Under 'Step 1: Select a scheme type', select whether you want to compare permission schemes or notification schemes. (You can only do one type of scheme at a time, but you can easily come back and do the other type later.)
    • Under Step 2: Select the schemes to work with, select the schemes you want to compare. Select at least 2 (and no more than 5) schemes, using the 'Ctrl' key to select multiple schemes.
    • Click the 'Compare Schemes' button.
  5. This will display the 'Scheme Comparison: View Scheme Differences' page:
    Screenshot 8: 'Scheme Comparison: View Scheme Differences'

    • Only the differences between the selected schemes are displayed. For example, in the screenshot above, only the "Administer Projects" permission is displayed; this means that all the other permissions in these two permission schemes ("Angry Nerds Permission Scheme" and "Angry Molluscs Permission Scheme") are identical.
  6. If you decide it is appropriate to edit a scheme to make it the same as another one, you can edit the scheme by clicking the scheme name. For example, it may be appropriate to delete Single User (marym) from the "Angry Nerds Permission Scheme" if she is a member of the "Administrators" project role for the Angry Nerds project.
  7. Then repeat the steps above, and verify that you have achieved a batch of 2 or more identical permission schemes, e.g.
    Screenshot 9: 'Scheme Comparison: View Scheme Differences' (showing identical schemes)
  8. Click the 'Merge Duplicate Schemes Tool' link. (Note: this link is also available from the 'Scheme Tools' page shown above).
  9. You will now see the 'Merge Schemes: Choose Schemes to Merge' page:
    Screenshot 10: 'Merge Schemes: Choose Schemes to Merge'

    If you decide it is appropriate to merge the displayed schemes:
    • Check the box next to the scheme names.
    • Type a name for the new scheme in the 'New Scheme Name' box.
    • Click the 'Preview Changes' button.
  10. You will now see the 'Merge Schemes: Preview Results' page:
    Screenshot 11: 'Merge Schemes: Preview Results'

    If you are satisfied that the information shown on this page is correct, click the 'Submit Changes' button to:
    • create the new scheme whose name is shown in bold.
    • associate the projects (in the right column of the table) with the new scheme.
    • disassociate the existing schemes (in the left column of the table) from the projects. These schemes can then be deleted using the 'Bulk Delete Schemes Tool' (see below).
  11. You will now see confirmation of the above changes on the 'Merge Schemes: Results' page:
    Screenshot 12: 'Merge Schemes: Results'
  12. Click the 'Bulk Delete Schemes Tool' link. (Note: this link is also available from the 'Scheme Tools' page shown above).
  13. You will now see the 'Bulk Delete Schemes: Select Schemes' page:
    Screenshot 13: 'Bulk Delete Schemes: Select Schemes'

    If you decide it is appropriate to delete the displayed schemes:
    • Check the box next to the scheme names.
    • Type a name for the new scheme in the "New Scheme Name" box.
    • Click the '"Preview' button. Note that deleting these schemes will not affect any projects, as this page only displays schemes that are not associated with projects.
  14. You will now see the 'Bulk Delete Schemes: Confirm Schemes to Delete' page:
    Screenshot 14: 'Bulk Delete Schemes: Confirm Schemes to Delete'

    If you are satisfied that the information shown on this page is correct, click the 'Delete Schemes' button.
  15. You will now see the 'Bulk Delete Schemes: Results' page, confirming that the unused schemes have been deleted:
    Screenshot 15: 'Bulk Delete Schemes: Results'
Last modified on Nov 12, 2012

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.