IBM Rational ClearQuest

Administration
NAGESHWAR REDDY MARELLA
 Agenda
• Day 1 - ClearQuest Administration Topics
• Day 2 - Roundtable Discussion
• Environment-specific issues
• Implementing security policies in CQ
• Discussion of “Best Practices” derived from first day
ClearQuest Administration
• ClearQuest Architecture
• ClearQuest Databases
• ClearQuest Client
– Comparing the CQ Client interfaces
– CQ Client capabilities
• ClearQuest Designer
– Schemas and Packages
– User Administration
– ClearQuest Customization
– Hooks and the ClearQuest API
 ClearQuest Architecture Web E-mail
Browser Client

RWP E-mail
Server
ClearQuest Windows Installation

Clear CQ CQ Maint. CQ CQ CQ CQ
Quest Designer Tool Export Import Web E-mail
Tier 1

COM COM

Tier 2
ClearQuest Core
Application logic and Business Rules
ODBC

Tier 3 RDBMS
Microsoft Access, SQL Anywhere, SQL Server,Oracle, DB2
 ClearQuest Databases
Schema
Repository #1 User Database #1

Database Set #1
User Database #2

User User Database #3

Login

Schema
Repository #2
User Database #4

Database Set #2

User Database #5
ClearQuest Client Capabilities
• Windows client
– Full-featured client interface
• Web client
– Integrations (i.e., UCM) not supported
– Cannot create report formats or charts
• Drill-down capability on charts not supported
• Restricted Access Web client
– Uses a separate URL
– Submit records
– Run a single, pre-defined query
– Does NOT consume a license!
ClearQuest Client
Hands-On Lab

• ClearQuest Windows Client Capabilities

– Navigating the CQ User Interface
– Creating Queries & Charts
– Creating Reports
ClearQuest Designer
Schema Elements & Terminology

ClearQuest Term Major Function

• Record type Table (in RDBMS)
• Field Column definition
• Field behavior Input attribute of the column
• Form Layout for submit/display
• Record Row entry
• Data type Acceptable data format
• Record type family Provides ability to query across record types
• State Indicates user record status in its lifecycle
• State type Categorizes the states for rule enforcement
• Action Represents the available activities on a user
record
• Hook, Script Provides ability to enhance or automate a
specific function
The Change Request Lifecycle
 The lifecycle of a change request defines the process
of resolving the request.
 To resolve a request, a number of actions can take
place.
 To track the progress of the change request, a set of
common states are chosen to indicate the current
status of the change request.
 The set of available actions for a change request
differ given the state of the request.
 The correlation between change request states and
actions represent the lifecycle of a change request.
 Sample Process Model
Postponed Action:
Action: State
postpone close
Action:
assign Action: Action:
postpone reject
Submitted Assigned Opened Resolved Closed
State State State State State
Action: Action: Action: Action:
assign open resolve validate

Action:
Action:
duplicate
unduplicate
Action:
duplicate
Duplicated
State

• State is a placeholder
• Action institutes rules such as state transition
Record Types in ClearQuest
• Record type in ClearQuest is similar to Table in
relational database management systems.
• There are two different kinds of record types: state-
based and stateless.
• Each state-based record type has its own process
model.
• For stateless record types, there is neither state
transition nor lifecycle tracking.
• The relationship between different record types is
referencing.
ClearQuest Forms
• ClearQuest uses forms for data entry and
display.
• For each record type, you can have two active
forms: Submit form and Record form.
– You submit change requests with the Submit form.
– You display change request records in ClearQuest
database with the Record form.
– If there is only one form for a record type, then the
form is both the Submit form and the Record form.
ClearQuest Designer
Four Areas of ClearQuest Customization

1.
1. Process:
Process: States,
States, Actions,
Actions, Behaviors
Behaviors

2.
2. Data:
Data: Record
Record Types,
Types, Fields
Fields

3.
3. Presentation
Presentation of
of data:
data: Forms
Forms

4.
4. Analysis
Analysis of
of data:
data:Queries,
Queries, Charts,
Charts, Reports
Reports
ClearQuest Designer
Schemas & Packages

A ClearQuest schema is a
• Process model
container that specifies the specifications
configuration of one
ClearQuest application. • Field definitions and
behavior
• Form design
• Hook code
ClearQuest Designer
Schemas & Packages
A ClearQuest package is a
bundle of the system
configuration and customization
for one feature or function.
• Certain process
specifications
• Some field definitions
and behavior
• Some form design
• Special hook code
• Queries, charts &
reports
ClearQuest Designer
Hands-On Lab

• Using pre-defined schemas and packages

– Choose an “out of the box” schema
– Build capabilities using packages
ClearQuest User Administration
Privileges

Active User
• Has ClearQuest logon privileges.
• Can change your own password, name, e-mail and phone number.
• Cannot change group or subscription information.
• Can view schema and database information.
Schema Designer
• Can change schemas and upgrade databases.
• Cannot create or delete databases.
• Cannot edit other users’ information.
User Administrator
• Can add or edit users’ and groups’ subscription information.
• Can grant or revoke user permissions.
Super User
• Has all ClearQuest permissions.
• Can create and delete schemas and user databases.
ClearQuest User Administration
Privileges

Public Folder Administrator

• Full control of the content of the Public Queries folder.
Dynamic Choice List Administrator
• Full control of the content of dynamic choice lists.

SQL Editor
• Can edit the SQL code generated by ClearQuest queries.
Security Administrator
• Can manage the visibility of records based on ClearQuest groups. Users
with this privilege can determine which groups have access to which
records.
All Users/Groups Visible
• Allows ClearQuest users to view information about other users and
groups. Without this privilege, ClearQuest users cannot access information
on other users or groups. This privilege is granted for all new users by
default so that they can access information about other users or groups.
 ClearQuest Designer
Hands-On Lab

• User Administration
– Creating Users and Groups
– Setting Privileges

Remember to “Upgrade” your databases after changing user/group information!

 ClearQuest Designer
Customization

• What you can do:

–You can create a new schema based
upon an existing schema version.
–You can modify an existing schema
version to add, change or delete functions.
–You can apply a package revision to add
functionality to a schema version.
ClearQuest Designer
Customization

• What you cannot do:

– After upgrading user databases, you cannot roll back to a
previous schema version
– If a schema version is associated with one or more user
databases, you cannot delete the schema version without
first deleting the associated databases
– You cannot remove the application of a package without
deleting all schema versions where the package exists.
ClearQuest Designer
Customizable Elements for Schema Design

• To customize the schema functionality, you can:

– Apply package(s)
– Define record type(s)
– Construct the process model, including states, state
types, and actions
– Define fields and their behaviors
– Design forms
– Develop hook code and scripts to enhance or
automate functions
– Build record type families
ClearQuest Designer
Typical Customization Steps

1. Check out a schema and create a new schema

version.
2. Carry out modifications. For example, add a new
field, or change the form layout to include the new
field.
3. Examine your modified functionality in the test
database. (You do have a test database, right?)
4. Check the new schema version into the schema
repository.
5. Upgrade the user database(s) to make the
modifications available to users.
ClearQuest Designer
Hands-On Lab

• ClearQuest Customization
– Process:
• Modifying States, Actions, and Behaviors
– Data:
• Record Types, Fields, and Record Type Families
– Presentation of Data:
• Using the Forms Designer
– Analysis of Data:
• Queries, Charts, Reports managed in the client…
ClearQuest Designer
What Are ClearQuest Hooks?

• Hooks are pieces of code that extend

functionality.
• Hooks customize the behavior of the
associated ClearQuest objects.
• VBScript and Perl are the available
scripting languages for writing ClearQuest
hooks.
• Hooks use the ClearQuest Application
Programming Interface (API).
ClearQuest Designer
Field Hooks and Action Hooks

Field Hook Types Action Hook Types

• Default_Value • Access_Control
• Permission • Initialization
• Value_Changed • Validation
• Validation • Commit
• Choice_List • Notification
• Record Script
ClearQuest Designer
Customizing Field Hooks
Field Hook Types

In this example, the selection

for the Default_Value hook of
the Submit_Date field is
SCRIPTS. The display of
BASIC,PERL indicates scripts
in both languages are
available.
ClearQuest Designer
Customizing Action Hooks
Action Hook Types

To work on an action hook:

• Double click on Actions to bring up
the Actions grid.
• Click the appropriate action hook
column to display the available
options.
ClearQuest Designer
Record Scripts and Global Scripts

• Record scripts are scripts that can be executed within

the context of one record type.
– Can be called upon in field hooks, action hooks and other
record scripts of the same record type.
– Usually triggered by a form control to perform specific tasks at
runtime.
• Global scripts allow you to define a library of routines
that can be called upon by all record types in the same
schema.
– Must be invoked from other field hooks, action hooks, record
scripts or global scripts. There is no mechanism to execute a
global script alone.
ClearQuest Designer
Execution Order for Field and Action Hooks

When a user tries to carry out an action, hooks fire in

this order:
•Access Control action hook
•Permission field hooks (for each field)
•Initialization action hook
•Default Value field hooks (for SUBMIT & IMPORT only)
•Value Changed field hooks (for each field)
•Validation field hooks (for each field)
•Choice List field hooks (for each choice list field)
•Validation action hook
•Commit action hook
•Notification action hook
ClearQuest API
Implementation
• The ClearQuest API is implemented as:
– A COM (Component Object Model) library
– A Perl package, CQPerlExt
• For calling ClearQuest API functions in ClearQuest
hooks and scripts:
– UNIX platform - Use Perl as the scripting language
– Windows platforms – select either VBScript or Perl
• For calling ClearQuest API functions in external
applications:
– The environment must either support OLE automation or be able
to embed Perl
ClearQuest API
Capabilities

• By calling ClearQuest API functions, you can:

– Logon to either the schema repository or the user
database
– Create a new record, or view and edit the content of
an existing record
– Create a new query, run an existing query, and
retrieve query results
– Generate charts and reports
– View and update users, groups, and database
information for the user database
ClearQuest API
Key Objects in the ClearQuest API

Session
DatabaseDesc
Logon

EntityDef Entity QueryDef

ResultSet
FieldInfo
Link QueryFilterNode

Entity-related objects
Query-related objects

Attachment- History-
related related OleMailMsg HookChoices EventObject
objects objects
ClearQuest Designer
Session and Entity Objects

For external applications to access the ClearQuest

database, you must:
• Get the Session object.
• Use its Logon method to Log onto the ClearQuest db.
• Use the Entity object to connect to a row of the table, which is a record in
ClearQuest user database.

logon
ClearQuest Database Session
Row
____
____ Entity
____
____
ClearQuest API
Entity and EntityDef Objects

– The structure of an Entity object is defined by the

corresponding EntityDef object (the record type).
– An EntityDef object can be either state-based or
stateless.
– Each Entity object contains the values for all of the fields
of a single data record.
– Get the information about the structure of a record from
its EntityDef object, including the properties of fields,
actions, and hooks for that record type.
ClearQuest API
Commonly Used Methods
GetSession Gets a specified session as the current
Session object.
GetUserLoginName Returns the name that was used to log
in for this session.
GetEntity Gets a specified record as the current
Entity object.
SetFieldValue Places the specified value in the named
field.
AddItem Adds a new item to the list of choices
created by a CHOICE_LIST hook.
GetFieldValue Returns a FieldInfo object for the
specified field.
GetValue Returns a FieldInfo object's value as a
single string.
ClearQuest API
Some Light Reading…

• The ClearQuest API Reference

– Installed with the CQ client
• c:\Program Files\Rational\ClearQuest\doc\books\cq_api.pdf
– Available via the web:
• ftp://ftp.software.ibm.com/software/rational/docs/v2003/cc_family/c
ClearQuest API
An Example…
my $platform;
$platform = ($entity->GetFieldValue($fieldname))->GetValue();
if ($platform eq "Windows XP") {
push(@choices, “Professional", “Home");
} else {
if ($platform eq "Windows NT 4.0") {
push(@choices, “Server", “Workstation");
} else {
if ($platform eq "Windows 98") {
push(@choices, "Win98");
} else {
push(@choices, " ");
}
}
}

What is this code is doing?

Is this likely a field hook or an action hook?
Which “hook type” do you suspect this is?
ClearQuest Best Practices / Notes
• Pros/Cons of Choice List implementations
– Static CHOICE_LIST
– Dynamic Lists (i.e., Named Lists)
– Stateless Record Types
• Hooks/Scripts
– Plan ahead when you decide to write hooks and scripts for ClearQuest schema
customization
– Pick appropriate types of hooks and scripts
– Remember to debug
• dbwin32, OutputDebugString()
– Re-use existing code in the developerWorks CQ Hooks Index
• http://www-128.ibm.com/developerworks/rational/library/4236.html
– If ClearQuest Web client will be used, plan to test the customization on the Web
browser to ensure they work as expected in the Web context.
• SQL Queries
– Once you modify the SQL generated by ClearQuest for a particular query or chart, you
can’t go back and graphically view or manipulate the modified query.
• Using Global Variables
– Use global variables to hold relatively static but frequently accessed data
ClearQuest Best Practices / Notes
• Security Context Fields – restrict who can SEE records based on group
− Create user groups.
− Designate a Reference type field in the target record type as the security context field.
− The referenced record type used to store customer, department, or project team info.
− ClearQuest automatically adds Ratl_Security tab to forms of the referenced record type.
− Check-in new schema version and upgrade user database.
− Login to ClearQuest client with Super User or Security Administrator privileges.
− Query the referenced record type for all instances.
− For each instance, populate the Ratl_Security tab list view with the appropriate user
group(s).