Ibm Rational Clearquest Administration

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 Browser

RWP

E-mail Server

CQ Web

CQ E-mail

ClearQuest Windows Installation

Tier 1

Clear Quest

CQ Designer

CQ Maint. CQ Tool Export

CQ Import

COM

Tier 2

Tier 3

E-mail Client

ClearQuest Core Application logic and Business Rules ODBC

RDBMS Microsoft Access, SQL Anywhere, SQL Server,Oracle, DB2

COM

ClearQuest Databases Schema Repository #1

User Database #1

Database Set #1 User Database #2

User Login

User Database #3

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 Field Field behavior Form Record Data type Record type family State State type Action

•

Hook, Script

Table (in RDBMS) Column definition Input attribute of the column Layout for submit/display Row entry Acceptable data format Provides ability to query across record types Indicates user record status in its lifecycle Categorizes the states for rule enforcement Represents the available activities on a user record 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

postpone

Action: assign

Submitted State

Action:

State

Action:

close

Action:

Assigned Action:

State

assign

reject

Opened Action:

State

Closed

Resolved Action:

open

State

resolve

Action: duplicate Action: duplicate

Action:

postpone

Action: unduplicate

Duplicated State

• State is a placeholder • Action institutes rules such as state transition

Action: validate

State

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: statebased 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: 2. 2. Data: Data:

States, States, Actions, Actions, Behaviors Behaviors 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 container that specifies the configuration of one ClearQuest application.

• Process model specifications • 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 Permission Value_Changed Validation Choice_List

Access_Control Initialization Validation Commit 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

Entity

EntityDef

QueryDef ResultSet

FieldInfo

Link

QueryFilterNode

Entity-related objects

Attachmentrelated objects

Query-related objects

Historyrelated objects

OleMailMsg

HookChoices

EventObject

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.

ClearQuest Database Row ____ ____ ____ ____

Entity

logon

Session

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