Chapter 5. Roles

The Rational Unified Process (RUP) defines a role as “an abstract definition of a set of activities performed and artifacts owned. Roles are typically realized by an individual, or a set of individuals, working together as a team. Roles are not individuals; instead, they describe how individuals behave in the business and what responsibilities these individuals have.”

In the RUP the use of roles in a process is a key concept, but there is no specific role object in ClearQuest. ClearQuest schema designers use roles in their schema implementations without a defined methodology.

Some designers have used the ClearQuest group concept as a method for implementing roles, but ClearQuest groups are designed to implement permissions. In this chapter we shall propose other implementation methods for roles.

Roles are used mainly in the following areas:

• Setting the action’s access control, thus verifying if the logged-in user is allowed to perform the action selected (this subject is quite obvious and we shall cover it only briefly)

• Automating some actions within the ClearQuest application process

• Manipulating assignment choices or pick lists based on roles

• Notifying users based on their roles

In the following sections we describe typical problems that occur when roles are not implemented in the change management system. We define basic terms related to roles in the change process. We then propose several solutions that the ClearQuest schema designer can use, each one with a different degree of complexity. We describe how roles are implemented in the ClearQuest ALM schema. In section 5.6, “Roles in Jazz,” we describe roles in the default Jazz process template. The last section includes code examples for the solutions proposed.

5.1. Understanding Typical Problems

As your successful software project grows, it is inevitable that there will be new releases for different customers, organizational changes, architectural changes, or new technologies adopted. These changes will likely increase the number of people involved in the project and introduce new stakeholders. These changes force the project to change the business process that was previously adopted successfully and are likely to cause changes in the roles that individuals take on and what their responsibilities may be. These changes also affect the processing of work items or change requests. As the number of people on the project grows or changes, it is not always clear who should perform a specific task. As the number of stakeholders increases, the volume of work items increases very quickly, and the amount of time involved in determining who should handle each work item may overwhelm the team.

Let us consider some examples of problems faced when creating the work item workflow in ClearQuest.

5.1.1. Enforcing Security Control

Every ClearQuest action is secured by an Access_Control hook that prevents unauthorized users from performing the action. By default, access is given to all users. Access control is set either according to the user’s groups or with a hook (Perl or BASIC scripting).

If roles are not managed, it is harder to enforce security for actions. To overcome this security issue, some ClearQuest administrators hard-code in the Access_Control hook script the names of the allowed users or groups. This method is definitely not good from a maintenance point of view, because each change in a role requires changes in the ClearQuest schema (i.e., schema checkout, modify, test, check-in, backup, and upgrade).

5.1.2. Unassigned Change

In the built-in schemas (defect tracking, UCM, and enterprise), after the Submit action the defect (or the enhancement request) has no owner. Furthermore, after the Resolve action the owner is the developer. That is literally not correct, unless we mean something else by the term owner. A work item that is Resolved should be owned by the tester who verified the solution. When a work item is unassigned, nobody is working on it and probably nobody is responsible for delivering the work. For this reason we introduce a new term, Responsible; see section 5.2.1, “Basic Definitions.”

5.1.3. Assigning the Wrong Person

Because a change request has to be owned by a user, ownership is given by a manager (project or product manager), group leader, or even the submitter. We have witnessed cases where ownership is given to the wrong person. In some organizations ownership is taken and not given, in many cases by the wrong person.

In one of the organizations in which we have implemented a defect-tracking system, assignment was dependent on the following factors: project, subproject, product, and application. There were many dozens of options, far too many for manual assignment without making mistakes.

Reasons for such mistakes are

• Lack of knowledge of the organization

• Lack of understanding of the process

• Misunderstanding the roles within the process

Also, the higher the turnover in the company/project, the more difficult it is to know the right person to assign.

So the outcome is that the next owner of the change request is set by assumptions, which often cause errors.

5.1.4. Blocking Assignment

Blocking assignment means that a change request is assigned to a person who can’t perform the next step in the process.

For example, the UCM methodology defines the owner as the solution provider. In most cases the solution provider is a developer, but what about other parts of the workflow? Who is responsible for the work item when it is not owned by someone in the development group (R&D)?

As previously mentioned, there is no owner before the Assigned state. After the action Resolve the owner is no longer responsible for the work item; it should be handled by the testing group. This can create confusion among users.

The result is loss of time until the next action occurs, because someone has to assign a person to the change request in order for work to begin on it, and that takes time. Also, each time the wrong person is assigned, time is spent on reassigning.

The rest of this chapter introduces examples of implementing roles in a ClearQuest schema so that a change request is assigned to the right person automatically throughout the change request lifecycle, and so that the automation of that assignment is robust in the face of changes: new projects, changes in personnel, or changes in the role to which a person is assigned on a given project. The result will be that every change request has a valid owner, and that the team can process change requests accurately and quickly. We shall also give examples of how to use roles to efficiently set the action’s access control.

5.2. Understanding Terms and Concepts

Before diving into techniques and solutions, we need to define some basic terms, the types of roles, and their relationship to user groups.

5.2.1. Basic Definitions

We are using new ideas and solution techniques, so first we have to define the terms used to set a common baseline.

• Owner: the user who currently has ownership of the work item

It is important to note that the owner does not own the work item for the entire lifecycle. For example, in the Rational Unified Change Management method (UCM) the solution provider is the owner of the change request only in the states Assigned and Opened, or in UCM terms in the states of type Ready and Active.

• Responsible: the user who has general responsibility for the work item

The responsible user should follow up on work item status, in some cases triage responsibly, and resolve ownership issues. The responsible user may or may not be the owner.

• Role: a set of activities to be performed by one or more users

For our purposes we are implementing only one aspect of the RUP roles that can be automated while processing a work item in ClearQuest.

• Area: the organizational domain or product domain that characterizes the work item

Every domain that users belong to (or work for) can be defined as an area. Some examples are software product, project, component, and module. In the ClearQuest ALM schema the area is defined in the Category Type field.

5.2.2. Role Type (Cardinality)

We can define two types of roles:

• Single: Only one user can have this role in a specific area.

Project Manager, for example, is a role of type Single. There is typically only one project manager for any project.

• Multiple (Many): Multiple users can have the same role in a specific area.

For example, Developer is a role of type Multiple. There are typically several developers for a given project.

5.2.3. Roles, Areas, and Groups

A user may have different roles in different areas. A user may have several roles in one or more areas, and the role of a user may change over time.

The fact that different users can fulfill the same role does not mean that the role is a Multiple role. Only if there is more than one user who can fulfill a role in a specific area is the role of type Multiple.

For example, if several users have the role Component Leader, but only one user is the leader of the component Messaging, the role is of type Single.

Roles of type Single and areas can be pictured in a two-dimensional matrix: for each role and area couple there is only one user.

5.2.4. Key Roles in the Change Request Process

The following are key roles in the defect and change management process:

• Customers are persons who actually use the product or service.

They report defects and have requests for changes in the product they use. The success of the product or service depends upon how these requests are managed. When customers have access to the change management system, extra attention should be given to security.

• The Software Change Control Board (SCCB) reviews the incoming change requests and determines how each individual request will be handled.

The board sets the priority and assigns the work item to a solution provider or team leader.

• The solution provider gets the assigned change requests from the SCCB and develops the proper solutions to resolve them.

• The tester evaluates the resolution when a change request has been declared Fixed or Resolved.

It is the tester’s responsibility to ensure that resolved claims provide satisfactory answers to a change request.

• A stakeholder is affected by the outcome of the process.

A customer is a stakeholder, but a stakeholder is not always a customer. Frequently, stakeholders prefer to participate directly in the process to influence decision-making or evaluation methods.

In complex processes more roles will be introduced, for example, Product Manager, Component Owner or Manager, Group Leader, R&D Moderator, QA Manager, Test Leader, QA Moderator, and Analyst.

5.3. Possible Solutions

This section describes some solutions for implementing roles in various ClearQuest applications. The solutions are based on different methods, and each method has its advantages, limitations, and disadvantages.

The level of complexity of each solution is different; we present the solutions from the less complex and thus the easiest to implement to the more complex, which requires more effort. The value to the organization does not necessarily match the level of complexity.

5.3.1. Implementing Roles with ClearQuest Groups

One way of implementing roles is by creating a group for each role. But because roles are relevant in the context of a specific area (such as project roles), such roles must be created for each area. Here is an example: For a project called Andromeda we can create groups such as Andromeda_developers, Andromeda_testers, and so on. We must do the same for each and every area. The advantage of such an implementation is that we do not have to script the Access_Control hooks, and we can just select the group or groups. The disadvantages are that for large organizations a huge number of groups have to be created and maintained, and for strict security scripting will be needed anyway. So the group solution is good for relatively small organizations, and for projects that are isolated from one another or for schemas that are designed for a single project.

A better solution is to create two types of groups:

• Groups for roles (Project Manager, Developer, Tester, Leader, etc.)

• Groups that include members of each area (Project_A, Project_B, Component_A, Component_B, etc.)

So how do we achieve this? If a user is a member of both the Project_A group and the Leaders group, then he or she has the Leader role in Project_A. Determining the exact role that a user fulfills in a particular area is done by a query in a script.

We can create a query that returns the users having the role Tester in the project Andromeda (users who are members of the group Tester AND in the group Andromeda). Such a query is presented and explained in section 5.7.1, “SQL Command for Group Method.”

The ClearQuest Access_Control hook contains a call to a global script to verify that the logged-in user has the specified role in the specified area, for example:

HasRole("UserName" "AreaName", "RoleName")

The code in Listing 5.1 is a simple example of a Defect_AccessControl BASIC script.

Listing 5.1. ClearQuest Access Control BASIC Script

---

Function Defect_AccessControl(actionname, actiontype, username)
REM - Allow action if user is leader or developer in the selected project
  project = GetFieldStringValue("Project")
    If (HasRole(username, project, "Developer")
      OR HasRole(username, project, "Leader") )
  Then
          Defect_AccessControl = TRUE
    Else
        Defect_AccessControl = FALSE
    End If

---

A significant disadvantage of this solution is that setting up a new role or changing roles requires administrator changes in the IBM Rational ClearQuest User Administration tool. Usually very few people have the privileges to use this tool, so the project team must have the ClearQuest administrator perform changes in roles. Also, the ClearQuest User Administration tool is not available from the Web, which poses an additional limitation.

5.3.2. Implementing Roles Implicitly

To handle multiple projects running concurrently, a more data-driven solution would be to define fields that indicate a role for a particular area (project, component, or module). This is more practical because we are using the project structure to capture the different roles, and we do not have to create as many groups as in the previous example (5.3.1), which reduces the maintenance effort.

Figure 5.1 displays the relationships between the Area objects and the users. The role fields of type Reference build the relationship by linking the objects. Think about each box as a database table and the arrows as links. Using ClearQuest terms, each table is a record type and each arrow is a reference or a reference list.

Figure 5.1. Roles implemented as fields in project and module

What we have are two stateless record types for Area A (for example, Project) and for Area B (for example, Module). They are linked with a field (here called Sub_Area) of type Reference_List, which means that each project contains several modules.

Each Area record type has fields for roles:

• A field representing a role of type Single is of type Reference to the Users stateless record type (represented as a one-to-one relationship in Figure 5.1).

• A field representing a role of type Multiple is of type Reference_List to the Users stateless record type (represented as a one-to-n relationship in Figure 5.1).

See section 5.7.2, “Hook to Automatically Set Responsible Based on Role of Type Single,” for a hook that demonstrates how to automatically set the Responsible field according to the role Leader related to the module (an area) previously selected by the user. Because the Leader is a role of type Single, we can automatically assign the change request to the user having this role.

A somewhat more complicated example is when the role is of type Multiple. We cannot assign the change request automatically because there are several choices, so what we shall do is populate the choice list with all the users having the required role for the selected area.

See section 5.7.3, “Hook to Automatically Set Choices Based on Role of Type Multiple,” for a hook that demonstrates how to set the Responsible choice list field according to the role Moderator related to the project (an area) previously selected by the user.

Figure 5.2 shows a project record with the Roles tab. Three roles are defined: manager, qa_manger, and developers. The ClearQuest administrator or the project manager can add or remove users from the developers role. It is a significant advantage that the area team can maintain their roles, and they do not require the ClearQuest administrator to do that work for them; as teams change, people move from one role to another or from one team to another.

Figure 5.2. Roles defined in the Project record

In a similar way the roles of the area SubSystem are defined and maintained in the SubSystem record. Figure 5.3 shows the SubSystem record and the lead role.

Figure 5.3. Roles defined in the SubSystem record

Figure 5.4 shows the Defect record. When the user selects the Project field, the Subsystem choice list is populated. When the user selects the Subsystem field, now two things happen: the Value_Changed hook is fired and fills the value of the Owner field with the value of Lead Role, and the choice list is populated with the subsystem team users. The user can change the default value that was set by the hook and select another user from the list that was auto-populated; Figure 5.4 shows this operation.

Figures 5.2, 5.3, and 5.4 demonstrate the relationship between the work item (of type Defect in this example) and the Areas record types (Defect > Project > SubSystem) and the relationship between the owner of the defect and the role area (SubSystem Leader). Note that the Defect form includes fields that reference the Project stateless record (an area) and the SubSystem stateless record (an area).

In the Project record there are three role fields (Project Manager, QA Manager, and Developers); each one references the Users record.

In the SubSystem record there are two role fields (Leader and Developer Team Member) that reference the Users record.

Note also that the Project record has three tabs; the SubSystems tab includes a field of type Reference_List that links the project and the related subsystems.

Figure 5.4. Selecting the owner based on the Subsystem role

5.3.3. Using Roles Stateless Record Type (with Static Roles)

In this section we shall demonstrate a more general but somewhat more complicated solution. The method is to define a role object, a stateless record type that defines the relationship between the different areas and the roles.

We recently used this method with a customer that captures both hardware and software change requests with a single record type. Assignment was complicated and correct assignment was important.

Table 5.1 gives definitions of fields in the Roles record type. The example is tied to a specific customer configuration. The ClearQuest designer will design this record type to meet the organization’s configuration and roles.

Table 5.1. Fields in the Roles Stateless Record Type

Roles other than the ones delineated in Table 5.1 are possible.

For each combination of project, product, and component there may be one Leader user, several Testers and Developers, and possibly more fields for other roles.

See section 5.7.4, “Hook to Automatically Set Responsible Based on Role Object,” for an example of an action validation hook that demonstrates how to automatically set the Responsible field based on the Roles record type for a dynamic workflow.

5.3.4. User-Defined Roles

In the previous examples the roles were predefined in the schema. In many cases this is sufficient, as the roles are defined in the organization’s process and are not subject to frequent changes. The area structure (project, product, and component) was also predefined, which is relevant to many organizations but not all of them.

Adding a new component requires creating a new role record, but if the company starts managing new types of changes such as hardware they may include new areas like Board or Firmware that will require changing the schema. Our aim is to create such a schema so that many of the maintenance changes are performed on the client side rather than in the schema.

In large enterprises we find that different projects have different roles. For those organizations the previous example is not good enough.

To ease the customization process and to componentize it, we have created a role stateless record type. In this solution the area owner creates a record for each role in his or her area. This means that you can identify exactly if a user has specific role. The role record may include the allowed actions for each record type. With a list of allowed actions (or denied actions) you can dynamically and easily determine the user’s Access_Control for each action performed.

Table 5.2. Suggested Fields for Stateless Record Type Roles (User-Defined Roles)

There are advantages to using the user-defined roles method:

• It reduces the schema customization and the level of maintenance.

• It reduces the amount of repeated work, especially when new products are introduced or after organizational changes.

• The previous methods used predefined roles such as Project Manager, QA, Developers, Testers. An organization/project may want to define its specific roles such as Technical Writer, Controller, or Integrator.

• When roles are not defined as a general object, it is hard to write a single global script to perform a general function with regard to roles, such as security, automatic assignment, or notification.

• Enterprises usually have many projects and many products. Roles may differ from one project to another. This method allows each project manager (not the ClearQuest designer!) to define the roles for the areas in his or her project.

Figure 5.5 shows an example of a role record; the authorized user defined the roles and the allowed actions for that role. This record defines the Product Manager role for the product Alfa and the actions allowed on the Defect and BaseCMActivity record types. The role is of type Single and the user having that role is bashansh.

Figure 5.5. Example of roles stateless record with user-defined roles

See section 5.7.5, “Hooks for User-Defined Roles,” for a hook example that shows how to populate the allowed actions.

5.4. Security and Roles

We shall discuss security in detail in Chapter 9, “Metrics and Governance,” but because security is often related to roles, we will make a few remarks here. If you implement security with the ClearQuest Security Context feature, you probably know that visibility to records is set by groups, and currently there is no other option. Therefore, when you design roles, think about the groups that you already have. We have specified that one of the disadvantages of implementing roles using groups is the difficulty of managing groups with the ClearQuest User Administration. This may be an advantage if groups are already managed for the purpose of security.

In all our examples for roles of type Multiple, we have used the Reference_List field to the Users record type. If all of those users are already grouped in users’ groups, it is advisable to use a field of type Reference that points to the Groups record type. This will save time and reduce errors.

5.5. Roles in the ClearQuest ALM Schema

The Application Lifecycle Management (ALM) schema includes roles as an integral part. The ALM role is similar to the user-defined roles previously described in section 5.3.4, “User-Defined Roles,” but in a somewhat more general way.

Roles are realized with two stateless record types:

• ALMRoleLabel

• ALMRole

To use roles in the ALM schema an ALMRoleLabel must first be created. A role label is a stateless record type that includes the role name, description, and the actions allowed to this role (represented as a pair list of recordtypename::actionname).

The ALMRole record type includes two fields that reference the ALMProject and ALMRoleLabel records; these fields are the record’s unique key fields. The members having this role can be specified as a list of users and/or groups of users.

The ALMRole does not have a type (Single or Multiple) but has a field Primary that references a user. That allows automation via auto-assignment, similar to what we explain in section 5.7.2, “Hook to Automatically Set Responsible Based on Role of Type Single.”

Because a role is related to a project which is related to a category, the same role can have different attributes in each project.

When a user performs an action (in either an ALMRequest, ALMTask, or ALMActivity), the ClearQuest system uses the members list and the ApprovedActions list to verify the access control.

To understand the details see the code in the global subroutine IsUserApproved()in the ALMAuthorization script.

Figures 5.6, 5.7, and 5.8 are snapshots of an ALMRole record and display the various tabs and fields. The Role tab in Figure 5.6 includes the Project and the Role Label fields which are the combined record unique key.

Figure 5.6. The ALMRole record

Figure 5.7 shows the Members tab. You can select individual members and/or groups. At least one of these two fields must be filled in. The primary field is also mandatory and is used to auto-assign the user depending on the record role.

Figure 5.7. Member in the ALMRole record

Figure 5.8 shows the list of actions that the members of this role are allowed to perform in each record type.

Figure 5.8. The ALMRole approved actions for each record type

5.6. Roles in Jazz

In the Jazz server roles identify the functions of team members. Permissions for specific operations can be assigned to roles at the project level or within a team area. This is realized in three elements:

• Roles for the project area

• Members of roles

• Permitted actions for roles

The following examples include screen shots from a Jazz project area. Roles are identical in Rational Team Concert and Rational Quality Manager projects.

The first stage is to define the roles for the project area. Figure 5.9 shows an example of roles definition. Note that a role has an identifier (which is the role name or label; in Figure 5.9 the role label is GroupLead), a description, and cardinality (in this case Many).

Figure 5.9. Roles definition in a Jazz project area

The second stage is to assign each project member to one or more roles. This is done in the Overview tab of the project area, in the Members section. Figure 5.10 demonstrates the members and their Process Roles.

Figure 5.10. Assigning roles to team members in a Jazz project area

The third stage is to define the permitted actions for each role. This can be done in the Project Configuration or the Team Configuration section of the project area; click on Permission to open the Permission definition section. Figure 5.11 demonstrates permitted actions for the testlead role.

Figure 5.11. Setting the permitted actions for each role

5.7. Code Examples

The following ClearQuest code examples demonstrate how to use the techniques explained in this chapter for

• Access control hook

• Auto-assign

• Choice list population

5.7.1. SQL Command for Group Method

The query in Listing 5.2 returns the list of users who are members of the ProjectLeads group and are also members of the Andromeda group. As you see, the query is quite complex but will do the job. The query in Listing 5.2 is related to section 5.3.1, “Implementing Roles with ClearQuest Groups.”

Listing 5.2. Identifying the User Role with a SQL Query

---

select distinct T1.dbid,T1.login_name
from ((( ( users T1 LEFT OUTER JOIN
   [select * from parent_child_links ]. AS T4mm
    ON T1.dbid = T4mm.parent_dbid  )
    LEFT OUTER JOIN groups T4 ON T4mm.child_dbid = T4.dbid  )
    LEFT OUTER JOIN [select * from parent_child_links ]. AS T5mm
    ON T1.dbid = T5mm.parent_dbid  )
    LEFT OUTER JOIN groups T5 ON T5mm.child_dbid = T5.dbid  )
where T1.dbid <> 0
 and (T5.name =  'ProjectLeads' )
 and  T1.dbid <> 0
 and ((T4.name = 'Andromeda'))

---

In the query example the groups are hard-coded; a more practical solution would be to insert the groups as parameters.

This query can be used in a Choice_List hook by using the session method BuildSQLQuery and passing the query string as parameter; see the following examples in Perl and BASIC:

$session->BuildSQLQuery(SQL_string);
session.BuildSQLQuery(SQL_string)

In the previous query we used hard-coded names (ProjectLeads and Andromeda). This is not a good practice; the hard-coded names should be changed to variables when coding the hooks.

For example, instead of using a hard-coded project name, get the project value:

ProjVal = GetFieldStringValue ("project")

When including a variable in a query, you must wrap it as follows:

BASIC: '"&ProjVal&"'
Perl:  '$ProjVal'

For a full example of a script that uses BuildSQLQuery, see the code in section 5.7.4, “Hook to Automatically Set Responsible Based on Role Object.”

5.7.2. Hook to Automatically Set Responsible Based on Role of Type Single

The hook in Listing 5.3 demonstrates how to automatically set the Responsible field according to the role Leader related to the module (an area) previously selected by the user.

In this case the Leader is a role of type Single, so we can automatically assign the work item to the user having this role.

If you are not using the Responsible field, replace it with the field Owner.

Listing 5.3. Automatic Assignment

---

Function Defect_Validation(actionname, actiontype(
  ' actionname As String
  ' actiontype As Long
  ' Defect_Validation As String
  ' action is Assign_owner
  ' record type name is Defect

'  --- This hook sets the responsible field based on the selected module.
'  --- It is a Base action hook, so that responsible will be set
 '     for all types of actions.
'  --- The Module field should be mandatory so the role field can be read.

Dim moduleObj, sessionObj
'  ---Check if module value was changed (or selected)
originalValue = GetFieldOriginalValue("module").GetValue
currentValue = GetFieldValue("module").GetValue
If currentValue <> originalValue AND currentValue <> "" Then
 ' ---Look for the Group Leader of this Module
 set sessionObj = GetSession
 set moduleObj = sessionObj.GetEntity("Module",currentValue(
 lead = moduleObj.GetFieldValue("leader").GetValue
 SetFieldValue "responsible", lead
End If

End Function

---

5.7.3. Hook to Automatically Set Choices Based on Role of Type Multiple

Now let us see an example where the role is of type Multiple. We cannot assign Responsible automatically because there are several choices, so what we shall do is populate the choice list with all the users having the required role area.

The hook in Listing 5.4 demonstrates how to set the Responsible choice list field according to the role Moderator related to the project (an area) previously selected by the user. Again, in this case the Moderator role is of type Multiple, so we cannot automatically assign Responsible. Instead, we set the choice list of the field Responsible to all the users having this role, in this case through reference to a group.

If you are not using the Responsible field, replace it with the field Owner.

Listing 5.4. Populating a Choice List Based on Role

---

Sub responsible_ChoiceList(fieldname, choices)
  ' fieldname As String
  ' choices As Object
  ' record type name is Defect
  ' field name is responsible

  Dim actionname
    Dim oCQSession, oProj
    Dim oCQQuery, oCQFilter,oCQResultSet

actionname = GetActionName
originalValue = GetFieldValue("module").GetValue
originalState = GetFieldValue("State").GetValue
if (actionname = "Assign" OR originalState = "Submitted" ) _
                                AND originalValue = "" then
'  ---No module selected put all leaders in choice list
    Set oCQSession = GetSession()
    proj = GetFieldValue("project").GetValue
    set oProj = oCQSession.GetEntity("project" , proj (
    moderators_group = oProj.GetFieldValue("Moderators").GetValue
' ---Query the users database
    Set oCQQuery = oCQSession.BuildQuery("users")
    oCQQuery.BuildField ("login_name")
    Set oCQFilter = oCQQuery.BuildFilterOperator(AD_BOOL_OP_AND)
'  ---Return only those members of moderator (read from Project)
    oCQFilter.BuildFilter "groups", AD_COMP_OP_EQ, moderators_group
    Set oCQResultSet = oCQSession.BuildResultSet(oCQQuery)
    oCQResultSet.Execute

    Do While oCQResultSet.MoveNext = AD_SUCCESS
        choices.AddItem oCQResultSet.GetColumnValue(1(
    Loop
End If

End Sub

---

5.7.4. Hook to Automatically Set Responsible Based on Role Object

The Defect_Validation hook in Listing 5.5 is related to section 5.3.3, “Using Roles Stateless Record Type (with Static Roles).”

The hooks first read the data in the Defect record that uniquely defines the role area (i.e., project, subproject, and component). The next step is to create an SQL query (using the session method BuildSQLQuery) to retrieve the user who is the responsible user (using the ResultSet object).

In this script rules for setting the responsible/owner are also based on the defect state which is done in the last part of the script.

If you are not using the Responsible field, replace it with the field Owner.

Listing 5.5. Populating a Choice List Using Role Object

---

Function Defect_Validation(actionname, actiontype)
  ' actionname As String
  ' actiontype As Long
  ' Defect_Validation As String
  ' action is Update
  ' record type name is Defect

        Dim manager, fullname
Dim sessionObj, my_proj
    Dim NonBase_action
Dim proj, subproj, compon
    Dim qry , resultset

    set sessionObj = GetSession

Rem ---  Get the areas values
    proj = GetFieldValue("Project").GetValue()
    subproj = GetFieldValue("SubProject").GetValue()
    compon = GetFieldValue("Component").GetValue()


Rem --- Build the query to retrieve user having the application
Rem     responsible role
Rem --- Note the triple wrapping ('"&) around the variables within
Rem     the SQL command

qry = "select T9.login_name
       from Roles T1,users T9,Project T5, subproject T6, components T7
       where T1.responsible = T9.dbid and T1.project = T5.dbid and
             T1.subproject = T6.dbid and T1.component = T7.dbid and
             (T5.name = '"&proj&"' and T6.name = '"&subproj&"' and
              T7.name = '"&compon&"') "

    set resultset = sessionObj.BuildSQLQuery(qry)

Rem --- Run the query and get the result
    resultset.Execute
    stat = resultset.MoveNext
  If stat = AD_SUCCESS then
        manager = resultset.GetColumnValue(1)
  Else
Rem --- If no value retrieved from the roles record-type set
Rem     the project manager
      set my_proj = sessionObj.GetEntity("Project" , proj)
      manager = my_proj.GetFieldValue("manager").GetValue()
  End if

Rem ---   Set the Owner/Owner_Display based on action and role

            NonBase_action = GetActionName
    select case NonBase_action
        case "Submit"
           fullname = GetUserDisplayName(manager)
          SetFieldValue "Owner_Display" , fullname



       Rem   -- Deal with some other action cases
. . .
. . .
. . .

    case "Resolve"
             fullname = GetFieldValue("Resolver_Display").GetValue()
             SetFieldValue "Owner_Display" , fullname

    case "Verify"
             fullname = GetFieldValue("Verifier_DIsplay").GetValue()
             SetFieldValue "Owner_Display" , fullname
        case else
    end select
'
Rem ---  The Owner_full_name is set , Now set the Owner too

    login = GetUserLoginFromFullName(fullname)
    SetFieldValue "Owner", login


End Function

---

5.7.5. Hooks for User-Defined Roles

The allowedactions_ChoiceList hook in Listing 5.6 is related to section 5.3.4, “User-Defined Roles.”

This choice list hook builds a list of pairs RecordType::ActionName. This list can be used in Access_Control hooks to find out whether the user is allowed to perform the action.

Listing 5.6. Allowed Actions List

---

sub allowedactions_ChoiceList {
    my($fieldname) = @_;
    my @choices;
    # $fieldname as string scalar
    # @choices as string array
    # record type name is Roles
    # field name is AllowedActions
    # Start User Code
  my $entityDefObj, $value;
  my $nameList, $value;
  my $sessionObj = $entity->GetSession();
  my $entityDefNames = $sessionObj->GetEntityDefNames();

  # Iterate over all the record types
  foreach $EntityName (@$entityDefNames){

    #  Check if the entity is statebased (REQ_ENTITY)
    $entityDefObj = $sessionObj->GetEntityDef($EntityName);
    if ($entityDefObj->GetType() == $CQPerlExt::CQ_REQ_ENTITY) {
        $nameList = $entityDefObj->GetActionDefNames();
        foreach $actionName(@$nameList)  {
                $value = $EntityName . "::" . $actionName;
                push( @choices, $value);
           } # foreach action
      } # endif statebased
} # foreach entity
    # End User Code
    return @choices;
}

---

5.8. Summary

In this chapter we explained some of the problems that may arise during the process of change without having a proper methodology. We demonstrated several methods to solve those problems by using roles within a ClearQuest schema. The ClearQuest schema designer will have to analyze the organization’s structure, the product structure, and the process requirements before selecting the preferred method to define roles as described in this chapter. The method described in section 5.3.4, “User-Defined Roles,” will probably fit many large organizations but can also be applied in small organizations. In section 5.7, “Code Examples,” we included several code examples that will help you implement the required method for your organization.

The ClearQuest ALM schema roles implementation includes two special record types, the ALMRoleLabel, which is general, and the ALMRole, which is specific to a project; this allows the definition of roles for each project.

We described how roles are defined in the Jazz-based products, how roles are assigned to users, and how permissions are set by roles in each project area.

Whenever possible we strongly suggest using automatic assignment. If this is not possible, limit the choice list to only those users having the required role; this will minimize errors, save time, and improve the user experience.