# Name: RTsubmit
# Author: Shawn Doyle,
# Company: ReleaseTeam, Inc.
# Description: A script to add a record to ClearQuest then allow the 
#		user to assign that record to themselves.
# 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
my ($headline) = ""; # Flag for the -h option
my ($priority) = 0 ; # Flag for the -p option
my ($severity) = 0;  # Flag for the -s option
my ($assign) = 0;    # Flag for the -A option
my ($open) = 0;      # Flag for the -O option

######################
# Start main execution
######################
GetOptions ("help|?" => \$help,
            "h=s" => \$headline, 
            "p=i" => \$priority,
            "s=i" => \$severity,
            "A" => \$assign,
            "O" => \$open) ||
  pod2usage ({ -exitval => 2, -verbose => 0 });

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

if ($headline eq "" || $severity == 0) {
  print ("ERROR: Required parameters missing. Exiting.\n");
  pod2usage ({ -exitval => 1, -verbose => 0 });
}

if (($assign || $open) && !$priority) {
  print ("ERROR: -p option required when using -A or -O. Exiting\n");
  pod2usage ({ -exitval => 1, -verbose => 0 });
}

&fixParms();

&openSession();

&createRecord();

&moveAssigned () if ($assign);

if ($open) {
  # If the user added the -O option but not the -A option, move the
  # record to the Assigned state prior to moving to the Opened state.
  &moveAssigned () if (!$assign);
  &moveOpened();
}

&closeSession ();

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

#######################################################################
# Subroutine: fixParms ()
# Description: Changes the value of the priority and severity fields
#              to a format expected by the base defect record. The user
#              only needs to type 1-5 on the command line.
# Input: None
# Output: None
sub fixParms {
  if ($priority < 1 || $priority > 4) {
    print ("ERROR: Invalid priority level specified. Valid levels " .
           "are 1 to 4. Exiting.\n");
    exit (1);
  }

  $priority = "1-Resolve Immediately" if ($priority == 1);
  $priority = "2-Give High Attention" if ($priority == 2); 
  $priority = "3-Normal Queue" if ($priority == 3);
  $priority = "4-Low Priority" if ($priority == 4);

  if ($severity < 1 || $severity > 5) {
    print ("ERROR: Invalid severity level specified. Valid levels " .
           "are 1 to 5. Exiting.\n");
    exit (1);
  }

  $severity = "1-Critical" if ($severity == 1);
  $severity = "2-Major" if ($severity == 2);
  $severity = "3-Average" if ($severity == 3);
  $severity = "4-Minor" if ($severity == 4);
  $severity = "5-Enhancement" if ($severity == 5);
}

#######################################################################
# 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: createRecord ()
# Description: Creates the record in ClearQuest.
# Input: None
# Output: None
sub createRecord {
  eval ("\$newRecord = \$CQSession->BuildEntity(\"defect\");");
  &CQ_error ("BuildEntity") if ($@);

  # Set the fields specified from the commandline.
  # Future version to use a GUI prompt.
  eval ("\$newRecord->SetFieldValue (\"headline\",\"\$headline\");");
  &CQ_error ("SetFieldValue") if ($@);
  eval ("\$newRecord->SetFieldValue(\"Severity\",\"\$severity\");");
  &CQ_error ("SetFieldValue") if ($@);

  eval ("\$uniqueKey = \$newRecord->GetDisplayName();");
  &CQ_error ("GetDisplayName") if ($@);

  # Commit the defect record to the database.
  eval ("\$newRecord->Validate ();");
  &CQ_error ("Validate") if ($@);
  eval ("\$newRecord->Commit ();");
  &CQ_error ("Commit") if ($@);
  print ("$uniqueKey added to $dbname user database.\n");
}


#######################################################################
# Subroutine: moveAssigned ()
# Description: Moves the newly created record to the "Assigned" state.
# Input: None
# Output: None
sub moveAssigned {
  # Assign the record to the current user
  eval ("\$assignRecord = \$CQSession->GetEntity (\$recordtype, " .
        "\$uniqueKey);");
  &CQ_error ("GetEntity") if ($@);
  
  eval ("\$CQSession->EditEntity (\$assignRecord, \"assign\");");
  &CQ_error ("EditEntity") if ($@);
  
  eval ("\$assignRecord->SetFieldValue (\"Priority\", \"\$priority\");");
  &CQ_error ("SetFieldValue-Priority") if ($@);
  eval ("\$assignRecord->SetFieldValue (\"Owner\", \"\$CQ_user\");");
  &CQ_error ("SetFieldValue-Owner") if ($@);
  
  # Commit the defect record to the database.
  eval ("\$assignRecord->Validate ();");
  &CQ_error ("Validate") if ($@);
  eval ("\$assignRecord->Commit ();");
  &CQ_error ("Commit") if ($@);
  print ("$uniqueKey moved from Submitted to Assigned\n");
}

#######################################################################
# Subroutine: moveOpened ()
# Description: Moves the Assigned record to the Opened state.
# Input: None
# Output: None
sub moveOpened {
  # Move the defect record to the "Opened" state. 
  eval ("\$openRecord = \$CQSession->GetEntity (\$recordtype, " .
        "\$uniqueKey);");
  &CQ_error ("GetEntity") if ($@);
  eval ("\$CQSession->EditEntity (\$openRecord, \"open\");");
  &CQ_error ("EditEntity") if ($@);
  
  # Commit the defect record to the database.
  eval ("\$openRecord->Validate ();");
  &CQ_error ("Validate") if ($@);
  eval ("\$openRecord->Commit ();");
  &CQ_error ("Commit") if ($@);
  print ("$uniqueKey moved from Assigned to Opened\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__

=head1 NAME

RTSubmit - add a Record to ClearQuest, with the option of moving it to
           the Assigned state and even onto the Opened state. Not
           specifying a state option will leave the record in the
           Submitted state with only the Headline and Severity fields
           set. 

=head1 SYNOPSIS

RTSubmit [--help | -?] -h "headline" -s severity [-p priority -A -O]

=head1 OPTIONS

=over 8

=item B<--help | -?>

Display online documentation

=item B<-h "headline">

The headline for the new defect record. Should be enclosed in quotes.

=item B<-s severity>

The severity of the defect. The user is only required to type the
number corresponding to the desired severity, 1 - 5. The number entered
is then mapped to the correct severity string for the base defect
record type.
1 = 1-Critical
2 = 2-Major
3 = 3-Average
4 = 4-Minor
5 = 5-Enhancement

=item B<-p priority>

The priority of the defect for the user. The user is only required to
type the number corresponding to the desired priority, 1 - 4. The
number entered is then mapped to the correct priority string for the
base defect record type. The -p option is only required if you want to
move the new record to the Assigned or Opened states.
1 = 1-Resolve Immediately
2 = 2-Give High Attention
3 = 3-Normal Queue
4 = 4-Low Priority

=item B<-A>

Move the new record to the Assigned state. 

=item B<-O>

Move the new record to the Opened state. Specifying only the -O option
will automatically move the record to the Assigned state, then to the
Opened state.

=back

=head1 DESCRIPTION

The RTsubmit utility is a simple way to create a 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 uses the -O option, the record is assigned to the current
user and opened for them.  As is, the script works for the default
defect tracking schema, using the defect record type. Any modifications
to the schema may effect this script and will require customizations.

=head1 Examples

Creates a new defect record but leaves it in the Submitted state. The
headline is "Headline for bug" and the severity is 1.

	RTsubmit -h "Headline for bug" -s 1

Creates a new defect record and moves it to the Assigned state. The
headline is "Headline for bug", severity is 2, and priority is 1.

	RTsubmit -h "Headline for bug" -s 2 -p 1 -A

Creates a new defect record and moves it to the Opened state. The
headline is "Headline for bug", severity is 3, and priority is 2.
	RTsubmit -h "Headline for bug" -s 3 -p 2 -O

=cut