NAME REST.pm

Clearquest REST client - Provide access to Clearquest via the REST interface

VERSION

Author: Andrew DeFaria <Andrew@DeFaria.com>
Revision: $Revision: 2.16 $
Created: Wed May 30 11:43:41 PDT 2011
Modified: 2013/03/26 02:24:01

SYNOPSIS

Provides a RESTful interface to Clearquest

DESCRIPTION

This module implements a simple interface to Clearquest. The backend uses REST however this module hides all of the ugly details of the REST implementation. Since REST is used, however, this module can be used by any normal Perl. See Perl Modules below of a list of Perl modules required.

This module is object oriented so you need to instantiate an object. Be careful to make sure that you properly disconect from this object (See disconnect method).

The methods exported are simple: add, delete, get, modify... In most cases you simply need to supply the table name and a hash of name value pairs to perform actions. Record hashes representing name/value parts for the fields in the records are returned to you.

Here's an example of use:

use Clearquest;

my $cq;

END {
  $cq->disconnect if $cq;
} # END

$cq = Clearquest->new (CQ_MODULE => 'rest');

$cq->connect;

my %record = $cq->get ('Project', 'Athena');

my %update = (
  Deprecated => 1,
  Projects   => 'Island', '21331', 'Hera' ],
);

$cq->modify ('VersionInfo', '1.0', 'Modify', \%update);

if ($cq->error) {
  die "Unable to modify record\n" . $cq->errmsg;
}

NOTES

Multiline text strings are limited to only 2000 characters by default. In order to expand this you need to change the cqrest.properties file in:

C:\Program Files (x86)\IBM\RationalSDLC\common\CM\profiles\cmprofile\installedApps\dfltCell\TeamEAR.ear\cqweb.war\WEB-INF\classes

on the web server. Multiline text strings can theoretically grow to 2 gig, however when set even as small as 10 meg REST messes up!

METHODS

The following methods are available:

Options

Options are keep in the cq.conf file in the etc directory. They specify the default options listed below. Or you can export the option name to the env(1) to override the defaults in cq.conf. Finally you can programmatically set the options when you call new by passing in a %parms hash. The items below are the key values for the hash.

CQ_SERVER: The web host to contact with leading http://
CQ_USERNAME: User name to connect as (Default: From cq.conf)
CQ_PASSWORD: Password for CQ_USERNAME
CQ_DATABASE: Name of database to connect to (Default: From cq.conf)
CQ_DBSET: Database Set name (Default: From cq.conf)

add ($table, %record)

Adds a %record to $table.

Parameters:

$table

Table to add a record to (e.g. 'Defect')

$values

Hash reference of name/value pairs for the insertion

@ordering

Array containing field names that need to be processed in order. Not all fields mentioned in the $values hash need be mentioned here. If you have fields that must be set in a particular order you can mention them here. So, if you're adding the Defect record, but you need Project set before Platform, you need only pass in an @ordering of qw(Project Platform). They will be done first, then all of the rest of the fields in the $values hash. If you have no ordering dependencies then you can simply omit @ordering.

Note that the best way to determine if you have an ordering dependency try using a Clearquest client and note the order that you set fields in. If at anytime setting one field negates another field via action hook code then you have just figured out that this field needs to be set before the file that just got negated.

Returns:

$errmsg: Error message (if any)

connect (;$$$$)

This method doesn't really connect but is included to be similar to the Clearquest::connect method. It does set any of the username, password, database and/or dbset members

Parameters:

$username: Username to use to connect to the database
$password: Password to use to connect to the database
$database: Clearquest database to connect to
$dbset: Database set to connect to (Default: Connect to the default dbset)

Returns:

connected ()

Returns 1 if we are currently connected to Clearquest

Parameters:

none

Returns:

1 if logged in - 0 if not

database

Returns the current database (or the database that would be used)

Parameters:

none

Returns:

database

dbset

Returns the current dbset (or the dbset that would be used)

Parameters:

none

Returns:

dbset

delete ($table, $key)

Deletes a %record from $table.

Parameters:

$table: Table from which to delete a record from (e.g. 'Defect')
$key: Key of the record to delete

Returns:

$errmsg: Error message (if any)

disconnect ()

Disconnects from REST. Note you should take care to call disconnect or use undef to undefine your instantiated Clearquest::REST object. If your script dies or exits without disconnecting you may cause web sessions to remain. You might try something like:

use Clearquest::REST;

my $cq = Clearquest::REST->new;

 END {
   $cq->disconnect if $cq;
 } # END

Parameters:

nothing

Returns:

$error: Error number (if any)

errmsg ($errmsg)

Returns the last error message. Optionally sets the error message if specified.

Parameters:

$errmsg: Error message to set

Returns:

$errmsg: Last error message

error ($error)

Returns the last error number. Optional set the error number if specified

Parameters:

$error: Error number to set

Returns:

$error: Last error

fields ($table)

Returns an array of the fields in a table

Parameters:

$table: Table to return field info from.

Returns:

@fields: Array of the fields names for $table

fieldType ($table, $fieldname)

Returns the field type for the $table, $fieldname combination.

Parameters:

$table: Table to return field type from.
$fieldname: Fieldname to return the field type from.

Returns:

$fieldType: Fieldtype enum

fieldReference ($table, $fieldname)

Returns the name of the table this reference or reference list field references or undef if this is not a reference or reference list field.

Parameters:

$table: Table to return field reference from.
$fieldname: Fieldname to return the field type from.

Returns:

$fieldType: Name of table this reference or reference list field references or undef if this is not a reference or reference list field.

find ($;$@)

Find records in $table. You can specify a $condition and which fields you wish to retrieve. Specifying a smaller set of fields means less data transfered and quicker retrieval so only retrieve the fields you really need.

Parameters:

$table: Name of the table to search
$condition: Condition to use. If you want all records then pass in undef. Only simple conditions are supported. You can specify compound conditions (e.g. field1 == 'foo' and field1 == 'bar' or field2 is not null). No parenthesizing is supported (yet).
@fields: An array of fieldnames to retrieve

Returns:

$result or ($result, $nbrRecs): Internal structure to be used with getNext. If in an array context then $nbrRecs is also returned.

get ($table, $key, @fields)

Retrieve records from $table matching $key. Note $key can be a condition (e.g. Project = 'Athena'). Return back @fields. If @fields is not specified then all fields are returned.

Warning: Some Clearquest records are large. It's always better and faster to return only the fields that you need.

Parameters:

$table: Table to get records from (e.g. 'Defect')
$key: Key to use to get the record. Key is the field that is designated to be the key for the record.
@fields: An array of field names to return. It's usually better to specify only those fields that you need.

Returns:

%record: An hash representing the qualifying record.

get ($table, $key, @fields)

Retrieve records from $table matching $key. Note $key can be a condition (e.g. Project = 'Athena'). Return back @fields. If @fields is not specified then all fields are returned.

Warning: Some Clearquest records are large. It's always better and faster to return only the fields that you need.

Parameters:

$table: Table to get records from (e.g. 'Defect')
$key: Key to use to get the record. Key is the field that is designated to be the key for the record.
@fields: An array of field names to return. It's usually better to specify only those fields that you need.

Returns:

%record: An hash representing the qualifying record.

getNext ($)

Return the next record that qualifies from a preceeding call to the find method.

Parameters:

$result: The $result returned from find.

Returns:

%record: Hash of name/value pairs for the @fields specified to find.

key ($$)

Return the key of the record given a $dbid

NOTE: Not supported in REST implementation.

Parameters:

$table: Name of the table to lookup
$dbid: Database ID of the record to retrieve

Returns:

key

modify ($table, $key, $action, $values, @ordering)

Updates records from $table matching $key.

Parameters:

$table

Table to modify records (e.g. 'Defect')

$key

The $key of the record to modify.

$action

Action to use for modification (Default: Modify). You can use this to change state for stateful records.

$values

Hash reference containing name/value that have the new values for the fields

@ordering

Array containing field names that need to be processed in order. Not all fields mentioned in the $values hash need be mentioned here. If you have fields that must be set in a particular order you can mention them here. So, if you're modifying the Defect record, but you need Project set before Platform, you need only pass in an @ordering of qw(Project Platform). They will be done first, then all of the rest of the fields in the $values hash. If you have no ordering dependencies then you can simply omit @ordering.

Returns:

$errmsg: Error message (if any)

modifyDBID ($table, $dbid, $action, %update)

Updates records from $table matching $dbid.

Parameters:

$table

Table to modify records (e.g. 'Defect')

$dbid

The $dbid of the record to modify.

$action

Action to use for modification (Default: Modify). You can use this to change state for stateful records.

$values

Hash reference containing name/value that have the new values for the fields

@ordering

Array containing field names that need to be processed in order. Not all fields mentioned in the $values hash need be mentioned here. If you have fields that must be set in a particular order you can mention them here. So, if you're modifying the Defect record, but you need Project set before Platform, you need only pass in an @ordering of qw(Project Platform). They will be done first, then all of the rest of the fields in the $values hash. If you have no ordering dependencies then you can simply omit @ordering.

Returns:

$errmsg: Error message (if any)

new (%parms)

Instantiate a new REST object. You can override the standard options by passing them in as a hash in %parms.

Parameters:

%parms: Hash of overriding options

Returns:

REST object

records ()

Returns a hash of all records and their record numbers

Parameters:

nothing

Returns:

%records: Hash of records and their record numbers

response ()

Returns the response content

Parameters:

nothing

Returns:

$respondContent: Response content from the last REST call

username

Returns the current username (or the username that would be used)

Parameters:

none

Returns:

username

CONFIGURATION AND ENVIRONMENT

DEBUG: If set then $debug is set to this level.

VERBOSE: If set then $verbose is set to this level.

TRACE: If set then $trace is set to this level.

DEPENDENCIES

Perl Modules

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Andrew DeFaria <Andrew@DeFaria.com>.

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone else, you are strictly prohibited from removing any copyright notice from that Modified Version.

Copyright Holder makes no, and expressly disclaims any, representation or warranty, should the Package be used for any purpose. The liability of the Copyright Holder is limited to the maximum extent permitted by law.

To install Clearquest, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Clearquest

CPAN shell

perl -MCPAN -e shell
install Clearquest

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME REST.pm

VERSION

SYNOPSIS

DESCRIPTION

NOTES

METHODS

Options

add ($table, %record)

connect (;$$$$)

connected ()

database

dbset

delete ($table, $key)

disconnect ()

errmsg ($errmsg)

error ($error)

fields ($table)

fieldType ($table, $fieldname)

fieldReference ($table, $fieldname)

find ($;$@)

get ($table, $key, @fields)

get ($table, $key, @fields)

getNext ($)

key ($$)

modify ($table, $key, $action, $values, @ordering)

modifyDBID ($table, $dbid, $action, %update)

new (%parms)

records ()

response ()

username

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

Perl Modules

BUGS AND LIMITATIONS

LICENSE AND COPYRIGHT

Module Install Instructions