10 tips and tricks to secure versions of your data on a Jazz server

Leveraging the security features of the Configuration Management application

The Jazz-based Configuration Management application can be used to protect multiple versions of data. This article gives examples of how data can be organized into configurations, describes default security settings and how they can be configured, explains the benefits of team areas, and offers troubleshooting tips.

Wayne Diu, Advisory Software Developer, IBM Canada

Wayne DiuWayne Diu is an advisory software developer at IBM Rational. He has worked on designing and implementing UML modeling features for the Rational Modeling Platform, and he was one of the developers responsible for creating the metamodel integration framework. He has been involved with a diverse collection of other features, such as printing, validation marker enhancements, and refactoring support. Wayne was also one of the developers of the Design Management product; he is currently working on the Configuration Management application.



17 December 2013

The Configuration Management application is a Jazz application that enables the versioning of resources of consuming Jazz product applications, such as Design Management and Requirements Management. The default settings of the Configuration Management application can be customized to protect these resources.

Consuming applications that use the Configuration Management application typically create a default configuration when a project area is created. However, from the Configuration Management application, you can create additional snapshots and workspaces. Both snapshots and workspaces are types of configurations: a snapshot is a configuration that contains a fixed set of resources at a particular point in time (much like a picture that cannot be changed), and you can add, remove, and modify resources that are contained in a workspace. A configuration is useless by itself; its primary purpose is to keep track of resources and their individual versions for the given configuration.

Typically you create additional snapshots and workspaces using either the Configuration Explorer, which is accessible from https://servername:port/vvc, or the Current Configuration Context menu. The Current Configuration menu is found in the banner bar and displays the name of the current configuration, as shown in Figure 1:

Figure 1. The Current Configuration Context menu
The Create Workspace menu item is highlighted.

Click to see larger image

Figure 1. The Current Configuration Context menu

The Create Workspace menu item is highlighted.

Like other Jazz applications, the Configuration Management application also allows security permissions to be specified, and these permissions are complementary to those defined in the consuming applications. These 10 tips and tricks show you how to leverage the security permissions in the Configuration Management application to protect the integrity of the resources on the server.

Tip 1. Understand the correspondence between configurations, configuration spaces, and project areas

In a Jazz-based consuming application, data can be organized into separate project areas so that there is one project area per logical group of information.

Figure 2 shows two project areas: Reservation System (Designs) and Scheduling System (Designs). Each contains the design resources (such as documents, sketches, and models) relevant to the particular project:

Figure 2. Project areas that the user has access to in the Design Management application
The My Projects tab is selected

Click to see larger image

Figure 2. Project areas that the user has access to in the Design Management application

The My Projects tab is selected

In the Configuration Management application, there is exactly one project area per configuration space. These project areas are specific to the Configuration Management application and are not to be confused with the project areas from the consuming application (as shown in Figure 2). The existence of the Configuration Management application project areas allows you to use the standard Jazz project area management user interface (UI) for administering project area specific properties (such as permissions, roles, team areas, and users) to control the security access rules of a configuration space.

A configuration space is associated with every project area in a consuming application that the Configuration Management application manages. Each time you create a configuration space for a new project area in a consuming application, a corresponding project area in the Configuration Management application is created automatically. This corresponding project area is used to manage the access rules of the new configuration space and any resources that it governs.

Keep in mind that you could use the same configuration space across multiple consuming applications. Because configurations (such as snapshots and workspaces) are contained within configuration spaces, you can also use the same configuration across multiple consuming applications. For example:

  • One configuration could track both designs and requirements for the reservation system, and another configuration could track both designs and requirements for the scheduling system (see Figure 3). This would be beneficial if the systems were to be released at different times.
  • One configuration could track both designs and requirements for the reservation system, as well as both designs and requirements for the scheduling system (see Figure 4).
Figure 3. Separate configurations are used for the reservation and scheduling systems
Project areas grouped into two configurations.
Figure 4. The same configuration is used for the reservation and scheduling system
Project areas grouped into one configuration.

Tip 2. Understand the differences between permissions from different applications

In general, you can set permissions for operations in every Jazz application by using the project area details administration pages. This is also the case for the Configuration Management application, where permissions are defined using the Roles or Permissions tabs of the project area details page for the Configuration Management application.

However, project areas in the consuming application and the Configuration Management application can have the same name. Don't confuse the two project areas. Be sure to pay attention to the page header, which contains either Application Administration – Configuration Management (/vvc) or Application Administration – Name of Consuming Application (/<application_root>)

The Configuration Management application's permissions are complementary to the consuming application's permissions. While the Configuration Management application manages access rules for workspaces and snapshots in general, the consuming application manages access to application-specific operations and resources (such as Design Management's Create a design resource permission or Requirements Management's Create an artifact permission). This architecture allows the consuming application to be configured, for example, to indicate whether a certain user can create resources. The Configuration Management application further allows specifying which workspaces the user can modify and thereby controls where those resources can be created. Properly securing the application requires setting the appropriate permissions in both the consuming application and the Configuration Management application.


Tip 3. Understand the Configuration Management application’s permissions and default roles

The Default Access process template (ID: vvc.default.access) that is installed with the Configuration Management application provides six predefined roles: Editor, Configuration Lead, Snapshot Creator, Product Lead, Change Set Administrator, and Change Set Collaborator.

Users are assigned zero or more roles, and each role contains a set of permissions, as you can see in the following tables.

Even when users aren't explicitly assigned any roles, they are always implicitly assigned the Everyone (default) role, for which all permissions are enabled, and therefore, all operations are permitted. As explained in the next tip, you need to revoke permissions for operations from the Everyone (default) role to restrict permissions properly.

Users who are assigned the Editor role can make changes to a workspace configuration by creating, editing, and deleting resources (as defined by the consuming application, such as design documents or requirements) that are part of the workspace configuration.

The Configuration Lead role is an administrative role typically assigned to someone who can work with the workspaces and snapshots. The Snapshot Creator role is for users who can only create snapshots, which provide the ability to capture a configuration and the versions of resources that it references at a specific time. The Product Lead role is used to give permissions for modifying dimensions.

Two roles pertain to change sets: Change Set Administrator and Change Set Collaborator. Typically, with only the Update (update which resources are part of this configuration) permission, the user can modify a change set that he or she has created. The Change Set Administrator role allows you to work with other people's change sets as if those change sets were your own. This permission includes the ability to complete, share, and even discard change sets. This role could be helpful when the administrator wishes to archive a workspace but cannot do so because of change sets in progress. If the consuming application has the permission concerning the ability to unlock other people's resources (for example, the Force the unlock of a design resource permission in Design Management), it would be helpful to give the administrative user that permission also.

The Change Set Collaborator role is typically assigned to people who work together on creating change sets. This role allows participants to modify the change sets of others, without giving the ability to share or discard someone else's change set.

You can locate change sets in two ways:

  1. From a project area within the consuming application, locate the configuration context banner button. Then, from that drop-down menu, choose the Explore Change Sets… menu item.
  2. Navigate to the Configuration Explorer, locate the workspace configuration that contains the change sets, and click on the configuration name. Then, click the Change Sets tab.
Figure 5. The "Change Sets" tab of a workspace configuration
Two change sets in the v2 workspace configuration.

Click to see larger image

Figure 5. The "Change Sets" tab of a workspace configuration

Two change sets in the v2 workspace configuration.

In both cases, a list of change sets that you created is displayed. To see others' change sets, click the Switch between current user mode and all users mode icon.

Table 1. Default predefined roles for configurations
Everyone (default)EditorConfiguration LeadSnapshot CreatorProduct LeadChange Set AdministratorChange Set Collaborator
Add, update, or remove dependencies X X
Archive or restore X X
Assign Team Ownership X X
Complete, share, modify, or discard other team members' change sets X X X
Create or modify (rename) snapshots X X X
Create or modify (rename) workspaces X X
Merge (accept, rebase, or deliver) X X
Modify or complete other team members' change sets X X X
Update (update which resources are part of this configuration) X X X X
Table 2. Default predefined roles for dimensions
Everyone (default)EditorConfiguration LeadSnapshot CreatorProduct LeadChange Set AdministratorChange Set Collaborator
Create or modify X X

Tip 4. Get ready to define permissions

By default, the Everyone role has all permissions. Since the Everyone role is implicitly applied to all users, this means that all users will have permissions to do anything, regardless of any additional roles that have been defined. So, the first thing to do if you are managing additional access controls is to revoke permissions granted in the Everyone role. You can do this from the project area details page for the desired project area in the Configuration Management application:

  1. Click the Permissions link on the menu at the left to go to the Permissions tab.
  2. Select the Everyone (default) role in the Roles box
  3. Click the Revoke permissions for all operations icon.

I suggest revoking all permissions from the Everyone role, but if some particular operations do not need to be restricted, you can also revoke permissions individually.

After revoking the permissions for the Everyone (default) role, you are now ready to assign permissions to users.

  1. Click the Overview link on the menu at the left to go to the Overview tab.
  2. In the Members section, click the Add… link.
  3. Type in the username of the user you wish to add, or press the Show All link.
  4. Select the username you wish to add and then click the right arrow button (you can multiselect by pressing the Shift or Ctrl keys when clicking).
  5. Repeat steps 3 and 4 as necessary.
  6. Select the roles and then click the right arrow button (again, you can multiselect by pressing the Shift or Ctrl keys when clicking).
  7. Click Finish.

The permissions in roles are cumulative, so assigning the default Editor (that is, only the update permission) and Configuration Lead (all permissions except the update permission) roles to a user would result in the user having all permissions. Similarly, assigning the Snapshot Creator role to a user who already has the Configuration Lead role will have no effect, because the Configuration Lead role already includes the permission to Create or modify (rename) snapshots.

Note:
By default, individual members of the consuming application's project are not added to the Configuration Management application's project area's Members and Administrators sections.


Tip 5. Keep the configuration space name in sync with the project area name

Since there is a 1:1 correspondence between configuration spaces and Configuration Management application project areas, it's helpful to keep them named similarly. To rename both the project area and the configuration space, first go to the project area details page for the desired project area in the Configuration Management application. Then:

  1. Type in the new name of the project area.
  2. Click the Configuration Space link on the menu at the left to go to the Configuration Space page.
  3. Check the Update the configuration space name to the name of the project area checkbox.
  4. Click Save.

Now the configuration space name will be the same as the name of the project area.

Figure 6. Synchronize the name of the configuration space with the name of the project area
The Configuration Space page

Click to see larger image

Figure 6. Synchronize the name of the configuration space with the name of the project area

The Configuration Space page

Tip 6. Define customized roles

You are free to make your own process template and import it by clicking the Templates link in the menu section at the top of the Configuration Management application administration page. (For full details on how to make a process template, see Resources.) The default ID for the Configuration Management's process template is vvc.default.access, so you can overwrite the existing process template by reusing this name for your customized template. Doing so enables all new project areas created with the default template to contain your customizations automatically. (Previously created project areas remain unchanged.)

However, to make quick customizations to existing individual project areas, you can modify the permissions of predefined roles, add your own roles, or delete existing roles.

To modify the permissions of predefined roles, first go to the project area details page for the desired project area in the Configuration Management application. Then:

  1. Click the Permissions link on the menu at the left to go to the Permissions tab.
  2. Click on one of the roles in the Select a role: box.
  3. Expand the items under Configuration Management in the Permissions for Editor: box.
  4. In the Actions column of the Permissions for Editor: box, click the green checkmark or red bar to enable or disable that particular permission.
  5. Repeat Step 4 as desired for each of the permissions.

Note:
If you change the permissions of roles in a project area, the change affects only the permissions of the roles in that particular project area.

To add a role, first go to the project area details page. Then:

  1. Click the Roles link on the menu at the left to go to the Roles tab.
  2. Click the Create Role icon next to the Defined Roles header.
  3. Type in an Identifier in the Identifier: box and Name in the Name: box. Click Save.
  4. Follow the previous steps that describe how to modify the permissions of a role.

To delete a role, first go to the project area details page. Then:

  1. Click the Roles link on the menu at the left to go to the Roles tab.
  2. Click the Delete Role icon next to the Defined Roles header.

Note:
If you delete a role that has been assigned to a user, that user no longer has that role (and its permissions). Also, if you add or delete a role in a project area, it affects only that particular project area.


Tip 7. Understand default security settings for configurations

When a space is initialized and its root configuration is created, by default, the configuration's owning area is set to the Configuration Management application project area that corresponds to the space (and not to team areas, which are typically created later).

When you create a child configuration, by default, it appears to take on the same security permissions as its parent configuration. In reality, for workspaces, the parent's owning area is assigned as the child workspace's owning area. Because of this structure, you can independently change the parent's or the child's owning project or team area.

For snapshots, you can't set the owning project or team area because by definition, a snapshot (except its name or description) can't be modified. So, the parent's security settings are considered instead. This functionality means that when the snapshot's parent's owning area is changed, the snapshot's implicit owning area is changed as well.

Note:
You don't need to be concerned about the defaults for change set configurations. For change sets, security is based on whether or not you created the change set or whether you have one of the two permissions to modify the change sets of others.


Tip 8. Use team areas for further granularity

By default, the project area corresponding to the space is the owning area of a root configuration.

However, you might want finer control over child configurations. For example, 10 people in total may work on the Reservation System project:

  • Five people (Abby, Alicia, Amanda, Amy, and Andrea) work on maintenance for version one.
  • Five people (Barry, Bart, Brent, Brian, and Bob) work on the new version two.

Work is rarely divided as neatly as that, so let's complicate our example: In version two, Barry and Bart work on the core components, while Brent, Brian, and Bob work on the UI. Sometimes Abby contributes to the core components in version two while Andrea contributes to the UI in version two.

Figure 7. Users can belong to multiple team areas
The users contained in each team area.

To replicate an example like this one, create team areas in a project area. Each team area can then be set as the owner of a configuration. First, navigate to the project area details page for the desired project area in the Configuration Management application. Then:

  1. Click the Create Team… icon in the Team Area Hierarchy section.
  2. In the team area details page, type in the name of the team (such as v1 Team).
  3. In the Members section, click the Add… link.
  4. Type in the username of the user you wish to add, or press the Show All link.
  5. Select the username you wish to add and then click the right arrow button (you can multiselect by pressing the Shift or Ctrl keys when clicking).
  6. Repeat steps 4 and 5 as necessary.
  7. Click Save to enable the Roles and Permissions links in the menu at the left.
  8. Follow the instructions above in the "Get ready to define permissions" section of this article to add roles and permissions to team members.

In team areas, by default, permissions for roles are inherited from the project area. This is indicated by the Inherited from parent scope icon in the permissions table that appears for the selected role in the Permissions tab. You can override this functionality by clicking the Customize button in the Actions column and clicking the Grant Access or Revoke Access icons.

Figure 8. The "Customize Permissions" dialog invoked by clicking the "Customize" icon in the "Actions" column
The Customize Permissions dialog on the Team Area page.

Click to see larger image

Figure 8. The "Customize Permissions" dialog invoked by clicking the "Customize" icon in the "Actions" column

The Customize Permissions dialog on the Team Area page.

In team areas, you might notice that the roles box in the Roles tab is empty by default. This is again because roles are inherited from the parent project area. It doesn't mean the roles are unavailable to be used. In fact, you can assign roles to users as normal as described in the "Get ready to define permissions" section of this article. Furthermore, you can add roles by clicking the Create Role icon in the Defined Roles header (and customize roles from the Permissions tab as explained above).

Miscellaneous tips when working with team areas:

  • Team areas control only write access. Read access is controlled at the project area level.
  • You can navigate to the parent project area or team areas by clicking the name of the project area or team area right above the box containing the team area's name.
  • You can navigate to the parent project area or team areas from the Overview tab of the team area editor by clicking the name of the project area or team area in the Team Area Hierarchy box.
  • When you navigate away from a team area, even back to the parent project area, you must press Save or you'll lose your changes.
  • You can override permissions of roles and add additional roles, but you can't delete roles defined in parent areas.
  • Pay attention to which area you are in before customizing a role. The permissions of roles can be defined differently at different levels of the project and team area hierarchy. When you customize a role, the same role from another hierarchy isn't affected. In the example above, customizing the Configuration Lead role in v2 will not affect that same role in v1 (because it's in a different hierarchy), nor will it affect Reservation System (because it's the parent), but it will affect Core and UI (because they're children of v2). (That's why creating a new role with a unique name can help avoid confusion.)
  • A user can belong to multiple project and team areas, each time with different roles assigned.
  • A user can belong to a team area without belonging to the containing project area. (That's why any users that you may have added to the project area in the consuming application are not added to the project area in the Configuration Management application by default when the space is initially created.)
  • Above all, the key point to remember is that security settings in team areas are inherited from the parent.

After defining the team areas, you can assign them as owners of configurations. This restricts access to the configuration (and hence the versions of resources that are referenced by that configuration). You can set the team ownership to the project area associated with the configuration space or any team area defined within that project area. You can't change the team ownership to a project area or its contained team areas from a different configuration space. Also, you need the Assign team ownership permission for both the current owning area and the new owning area to change the owning team area or project area successfully.

To set the owning area, use the Specify an Area to Control Access to the Configuration dialog from the Configuration Explorer:

  1. Navigate to the Configuration Explorer.
  2. Locate the desired workspace configuration.
  3. Click the Assign Team Ownership icon.
  4. Select a new team area or project area.
  5. Click OK.

Now, the owning team has been set for the configuration.

Figure 9. The "Assign Team Ownership" icon in the Actions column of the Reservation System configuration
Highlighted configuration.

Click to see larger image

Figure 9. The "Assign Team Ownership" icon in the Actions column of the Reservation System configuration

Highlighted configuration.

Tip 9. Determine the controlling area

A configuration's security settings are governed by its owning project or team area.

You can determine a configuration's owning area in three ways.

The first way is by using the Specify an Area to Control Access to the Configuration dialog from the Configuration Explorer:

  1. Navigate to the Configuration Explorer.
  2. Locate the desired workspace configuration. If you are trying to determine a snapshot configuration's owning area, locate its parent workspace's configuration.
  3. Click the Assign Team Ownership button.
  4. Observe the highlighted project area or team area: this is the configuration's owning area.
Figure 10. The configuration's owning area is highlighted in the "Specify an Area to Control Access to the Configuration" dialog
Highlighted team area in dialog.

The second way to determine a configuration's owning area is by using the Workspace Editor or Snapshot Editor directly:

  1. Navigate to the Configuration Explorer.
  2. Click on the title of a workspace or snapshot configuration.
  3. In the Workspace Editor or Snapshot Editor, you will see the Controlling Area as a clickable hyperlink to the appropriate project area details page or team area details page for the corresponding area in the Configuration Management application.

Alternative steps:

  1. From the configuration context menu from within a consuming application, click the Open Current Configuration menu item.
Figure 11. The workspace editor shows the controlling process area as a hyperlink to the project area or team area
Workspace configuration editor.

Click to see larger image

Figure 11. The workspace editor shows the controlling process area as a hyperlink to the project area or team area

Workspace configuration editor.

Finally, the third way to determine a configuration's owning area is to hover over greyed-out items in the Configuration Management application UI. Greyed-out icons typically have an explanation that indicates the controlling area.


Tip 10. Troubleshoot permissions problems

You'll want to troubleshoot permissions problems differently depending on whether you're in a test environment or a production environment.

If a user in a test environment can't perform an operation in a project area and you're unsure whether it's related to the security settings, follow these steps:

  1. Go to the project area details page for the corresponding project area in the Configuration Management application.
  2. Create a new role called troubleshooting.
  3. Assign all of the Configuration Management permissions to that role.
  4. Assign the role to the user who's having problems.

Repeat the above steps for the corresponding project area in the consuming application:

  1. Go to the project area details page for the corresponding project area in the consuming application.
  2. Create a new role called troubleshooting.
  3. Assign it all of the consuming application's permissions.
  4. Assign the role to the user who's having problems.

If the user can now perform the operation, then the issue was indeed related to the security settings. Individually revoke permissions from the troubleshooting roles until you determine which permission is causing the operation to be denied.

In a production environment, you might not wish to change the roles and permissions. To determine the cause of an error in this case, examine the Configuration Management application's log file for errors that relate to permissions:

  1. Navigate to https://servername:port/jts/admin using your web browser, where jts is the Jazz Team Server root directory.
  2. Click on Diagnostics in the menu at the left.
  3. Click the Export Results link at the top right of the page and save the file to your computer.
  4. Extract the log files within the zip file and open the vvc.log file in a text editor.
  5. Look for errors relating to permissions (code 403). The most recent errors are at the bottom of the file.
Figure 12. The "Export Results" link is located at the top right corner of the Diagnostics page
The Diagnostics Server Administration page.

Click to see larger image

Figure 12. The "Export Results" link is located at the top right corner of the Diagnostics page

The Diagnostics Server Administration page.

Conclusion

This article described tips and tricks for getting the most out of the security settings provided by the Configuration Management application. By using these tips, you can set up applications that use the Configuration Management application with security permissions that appropriately protect the resources on the server.


Acknowledgements

The author expresses his gratitude to Daniel Leroux, Dusko Misic, Adam Neal, and Catherine Radatus for reviewing this article and to Kay Keppler for editing.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=957387
ArticleTitle=10 tips and tricks to secure versions of your data on a Jazz server
publish-date=12172013