Using 'Scheme Tools' to 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

  In JIRA Enterprise, a project administrator (that is, someone who has the 'Administer Project' permission, but not neceessarily 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.

1. Log in as a user with the 'JIRA Administrators' global permission.

2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

3. On the panel on the left, under the title "Schemes", click the link labelled "Scheme Tools".

   

4. This will display the "Scheme Tools" page. Click the "Group to Project Role Mapping Tool" link.

   

5. This will display the "Map Groups to Project Roles: Select Schemes" page:

   
   • 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.
   • Then click the "Map Groups to Roles" button.

6. This will display the "Map Groups to Project Roles: Select Mappings" page:

   

   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.

7. You will now see the "Map Groups to Project Roles: Preview Transformation for Schemes" page:

   

   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.

8. You will now see confirmation of the above changes on the "Map Groups to Project Roles: Results of Transformation for Schemes" page:

   

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 permissions schemes and notification schemes can make your JIRA system easier to manage. To identify and remove unnecessary schemes, follow the steps below:

1. Log in as a user with the 'JIRA Administrators' global permission.

2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

3. On the panel on the left, under the title "Schemes", click the link labelled "Scheme Tools".

   

4. This will display the "Scheme Tools" page. Click the "Scheme Comparison Tool" link.

   
   • 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).

5. This will display the "Scheme Comparison: Select Schemes" page:

   
   • 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.
   • Then click the "Compare Schemes" button.

6. This will display the "Scheme Comparison: View Scheme Differences" page:

   
   • 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 ("ABC Project Permission Scheme" and "XYZ Project Permission Scheme") are identical.

7. 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 "XYZ Project Permission Scheme" if she is a member of the "Administrators" project role for the XYZ project.

8. Then repeat the steps above, and verify that you have achieved a batch of 2 or more identical permission schemes, eg:

   
9. Click the "Merge Duplicate Schemes Tool" link. (Note: this link is also available from the "Scheme Tools" page shown in step 4.)

10. You will now see the "Merge Schemes: Choose Schemes to Merge" page:

    

    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.

11. You will now see the "Merge Schemes: Preview Results" page:

    

    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
    • unassociate 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 step 15).

12. You will now see confirmation of the above changes on the "Merge Schemes: Results" page:

    

13. Click the "Bulk Delete Schemes Tool" link. (Note: this link is also available from the "Scheme Tools" page shown in step 4.)

14. You will now see the "Bulk Delete Schemes: Select Schemes" page:

    

    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.

15. You will now see the "Bulk Delete Schemes: Confirm Schemes to Delete" page:

    

    If you are satisfied that the information shown on this page is correct, click the "Delete Schemes" button.

16. You will now see the "Bulk Delete Schemes: Results" page, confirming that the unused schemes have been deleted: