ibm rational clearquest administration
TRANSCRIPT
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
Tier 2
Tier 3
Tier 1CQE-mail
ClearQuest Core Application logic and Business Rules
RDBMSMicrosoft Access, SQL Anywhere, SQL Server,Oracle, DB2
COM
ClearQuest
CQDesigner
CQ Web
Web Browser
COM
RWP
CQExport
CQ Maint.Tool
CQImport
E-mail Client
E-mail Server
ClearQuest Windows Installation
ODBC
ClearQuest DatabasesSchema Repository #1 User Database #1
User Database #2
User Database #3User Login
Schema Repository #2
User Database #4
User Database #5
Database Set #1
Database Set #2
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 ClientHands-On Lab
• ClearQuest Windows Client Capabilities– Navigating the CQ User Interface– Creating Queries & Charts– Creating Reports
ClearQuest DesignerSchema Elements & Terminology
• Record type• Field• Field behavior• Form• Record• Data type• Record type family• State• State type• Action
• Hook, Script
Table (in RDBMS)Column definitionInput attribute of the columnLayout for submit/displayRow entryAcceptable data formatProvides ability to query across record typesIndicates user record status in its lifecycleCategorizes the states for rule enforcementRepresents the available activities on a user record Provides ability to enhance or automate a specific function
ClearQuest Term Major 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
AssignedAction:assign
Action:open
Action:resolve
Action:validate
Submitted Opened
Duplicated
Resolved Closed
Action:duplicate
StateState
State
State State
• State is a placeholder• Action institutes rules such as state transition
State
Action:unduplicate
Action:postpone
Action:close
Action:reject
Action:assign
State
Action:duplicate
Action:postpone
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 DesignerFour Areas of ClearQuest Customization
1. Process: States, Actions, Behaviors1. Process: States, Actions, Behaviors
2. Data: Record Types, Fields2. Data: Record Types, Fields
3. Presentation of data: Forms3. Presentation of data: Forms
4. Analysis of data: Queries, Charts, Reports4. Analysis of data: Queries, Charts, Reports
ClearQuest DesignerSchemas & Packages
• Process model specifications
• Field definitions and behavior
• Form design
• Hook code
A ClearQuest schema is a container that specifies the configuration of one ClearQuest application.
ClearQuest DesignerSchemas & Packages
• Certain process specifications
• Some field definitions and behavior
• Some form design
• Special hook code
• Queries, charts & reports
A ClearQuest package is a bundle of the system configuration and customization for one feature or function.
ClearQuest DesignerHands-On Lab
• Using pre-defined schemas and packages– Choose an “out of the box” schema– Build capabilities using packages
ClearQuest User AdministrationPrivileges
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 AdministrationPrivileges
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 DesignerHands-On Lab
• User Administration– Creating Users and Groups– Setting Privileges
Remember to “Upgrade” your databases after changing user/group information!
ClearQuest DesignerCustomization
• 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 DesignerCustomization
• 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 DesignerCustomizable 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 DesignerTypical 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 DesignerHands-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 DesignerWhat 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 DesignerField Hooks and Action Hooks
Field Hook Types• Default_Value• Permission• Value_Changed • Validation• Choice_List
Action Hook Types• Access_Control• Initialization• Validation• Commit• Notification• Record Script
ClearQuest DesignerCustomizing Field Hooks
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.
Field Hook Types
ClearQuest DesignerCustomizing Action Hooks
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.
Action Hook Types
ClearQuest DesignerRecord 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 DesignerExecution 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 APIImplementation
• 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 APICapabilities
• 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 APIKey Objects in the ClearQuest API
Attachment-relatedobjects
History- relatedobjects
OleMailMsg HookChoices EventObject
DatabaseDesc
ResultSet
EntityEntityDef QueryDef
Entity-related objects Query-related objects
Logon
QueryFilterNode
FieldInfoLink
Session
ClearQuest DesignerSession 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.
Row________________
SessionClearQuest Database logon
Entity
ClearQuest APIEntity 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 APICommonly 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.
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 APISome 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_fa
mily/cq_pdf/cq_api.all.pdf
ClearQuest APIAn 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).