# Name: RTnote
# Author: Shawn Doyle
# Company: ReleaseTeam, Inc.
# Description: A simple script that adds a note to a ClearQuest defect
#              record.
# Support: If you have any problems or would like to see additional
#          functionality, send an email to support@releaseteam.com
#######################################################################

########################
# USER DEFINED VARIABLES
########################

# Name of the ClearQuest database
$dbname = "";

# Username with access to the above database
$CQ_user = "";

# Password for the above user
$CQ_password = "";

# Type of ClearQuest record
$recordtype = "defect";

###########################################
# NO USER DEFINED VARIABLES BELOW THIS LINE
###########################################
use CQPerlExt;
use Getopt::Long;
use Pod::Usage;

require 5.6.0; # CQPerlExt module requires at least Perl version 5.6.0

my ($help) = 0; # Flag for the -help and -? options

#vars for CQ queries
my ($querydef);
my ($rsltset);      #  This is a ResultSet object 
my ($status);
my ($column);
my ($num_columns);
my ($num_records);

$bugfilename = "c:\\temp\\bug.txt";
$choicefilename = "c:\\temp\\choice.txt";
$notefilename = "c:\\temp\\note.txt";

######################
# Start main execution
######################
GetOptions ("help|?" => \$help) ||
  pod2usage ({ -exitval => 2, -verbose => 0 });

pod2usage ({ -exitval => 0, -verbose => 2 }) if ($help);

if ($ENV{CQCC_DEFECT}) {
  my ($prompt_string) = "Add Note to $ENV{CQCC_DEFECT}?";
  my ($cmd) = "CLEARPROMPT yes_no -type ok -default yes " .
              "-mask yes,no -prompt  \"$prompt_string\"";
  $result = system ($cmd);
  if ($result) {
    if (@ARGV == 0) {
      die ("ERROR: Defect record not specified. Exiting!\n");
    } else {
      $defect = $ARGV[0];
      chomp ($defect);
    }
  } else {
    $defect = $ENV{CQCC_DEFECT};
  }
} else {
  if (@ARGV == 0) {
    die ("ERROR: Defect record not specified. Exiting!\n");
  } else {
    $defect = $ARGV[0];
    chomp ($defect);
  }
}

&openSession();

&promptNote();

&addNote();

&closeSession ();

exit (0);
####################
# End main execution
####################

#######################################################################
# Subroutine: openSession ()
# Description: Creates the Session object required for communication
#              with ClearQuest.
# Input: None
# Output: None
sub openSession {
  eval ("\$CQSession = CQPerlExt::CQSession_Build();");
  &CQ_error ("CQSession_Build") if ($@);
  eval ("\$CQSession->UserLogon(\$CQ_user, \$CQ_password, \$dbname, \"\");");
  &CQ_error ("UserLogon") if ($@);
}

#######################################################################
# Subroutine: promptNote ()
# Description: Ask the user for the note s/he would like to add to the
#              record.
# Input: None
# Output: None
sub promptNote {
  $prompt_string = "Enter Note to add to defect.";
  my ($cmd) = "CLEARPROMPT text -multi_line -outfile $notefilename -prompt \"$prompt_string\"";
  my ($result) = system ($cmd);
  open (NOTE_FILE, "$notefilename");
  while (<NOTE_FILE>) {
    chomp();
    $note = $note."  ".$_;     	
  }
  close (NOTE_FILE);
}

#######################################################################
# Subroutine: addNote ()
# Description: Adds the note to the record and validates that addition.
# Input: None
# Output: None
sub addNote {
  eval ("\$entityaddnote = \$CQSession->GetEntity(\$recordtype, " .
        "\$defect);");
  &CQ_error ("GetEntity") if ($@);
  eval ("\$CQSession->EditEntity(\$entityaddnote, \"modify\");");
  &CQ_error ("EditEntity") if ($@);

  # Set the Notes field
  eval ("\$entityaddnote->SetFieldValue(\"Note_Entry\", \$note);");
  &CQ_error ("SetFieldValue") if ($@);

  # Close the record
  eval ("\$entityaddnote->Validate();");
  &CQ_error ("Validate") if ($@);
  eval ("\$entityaddnote->Commit();");
  &CQ_error ("Commit") if ($@);
  print ("Note added successfully to record: $defect\n");
}


#######################################################################
# Subroutine: closeSession ()
# Description: Destroys Session object.
# Input: None
# Output: None
sub closeSession {
  eval ("CQSession::Unbuild (\$CQSession);");
  &CQ_error ("Unbuild") if ($@);
}

#######################################################################
# Subroutine: CQ_error ()
# Description: Displays the error given by a failed ClearQuest API
#              command.
# Input: $method - Name of the ClearQuest API method that failed
# Output: None
sub CQ_error {
  my ($method) = @_;
  print ("ERROR: $method failed with the following message:\n$@\n");
  exit (1);
}

END {
  unlink ($notefilename);
}

__END__

=head1 NAME

RTnote - add a note to a ClearQuest record

=head1 SYNOPSIS

RTnote [-help | -?] [record]

=head1 OPTIONS

=over 8

=item B<-help | -?>

Display online documentation

=back

=head1 DESCRIPTION

The RTnote utility is a simple way to add a note to an existing
Rational ClearQuest record without the hassle of opening the ClearQuest
client and logging in. The user simply needs to set the user defined
variables at the top of the script once to use this script.

If the user happens to have the CQCC_DEFECT environment variable set
to a valid ClearQuest record, the script will ask the user whether they
would like to update that record or another that is specified on the
command line.

=cutupdate that record or another that is specified on the
command line.

=cut