Difference between revisions of "ApprovalCreation"

From Request Tracker Wiki
Jump to navigation Jump to search
(No difference)

Revision as of 12:12, 2 December 2010

Creating Approvals In RT

Using the CreateTicket action

The key to creating an Approval is the CreateTicket event. To make a queue use the approval system, you need to create a Scrip to be triggered when the ticket is created. This scrip will cause a CreateTicket action to occur, using data from a custom template.

Expected Results of using the Approvals queues.

The book says that approvals do 3 things automatically:

  • A ticket cannot be closed until all of its approvals are resolved.
  • If rejected, its original ticket (and all other approvals) are rejected.
  • When an approval-ticket is resolved/rejected comments are attached to the original ticket.

Defining the template

All the juice behind an Approval is stored in a template. Create a new custom template local to your queue, and define the new template to look something like this :

===Create-Ticket: codereview Subject: Code review for {$Tickets{'TOP'}->Subject} Depended-On-By: {$Tickets{'TOP'}->Id} Queue: Approvals Type: approval Content: Someone has created a ticket. you should review and approve it, so they can finish their work ENDOFCONTENT

_NOTE:_ There is an error in the documentation for RT3. This caused me a good bit of trouble. The Depended-On-By line in the documentation example is incorrect. The value on this line must be "TOP" (as shown here) and not "{$Tickets{'TOP'}->Id}" as the docs show.

_2nd NOTE:_ In RT 3.2.0 this is fixed and you must use "{$Tickets{'TOP'}->Id}" because just using "TOP" does not properly build the link. Also in template your template you need "Queue: Queuename" or RT will tell you it can't assign the ticket to a queue.

_3rd NOTE:_ In RT 3.4.0rc1 you must use "TOP". Also default Approvals queue name is ___Appovals that you have to enable first and rename it to just "Approvals" or the above template will not work.

_4th NOTE:_ In RT 3.6.0 I had to use the following 2 lines in the template, {$Tickets{'TOP'}->Id()} and Refers-To: {$Tickets{'TOP'}->Id()}. Another thing that has not been mentioned is the permissions. I had to give the person who will be approving the tickets the following grants: [=ModifyTicket], [=OwnTicket], [=ShowTicket].

_5th NOTE:_ In the book "RT Essentials" this topic is described on page 94. The sample scripts there show the Depended-On-By: and Depends-On: commands within the Content area, which does not work. Moving them above the Content: area works correctly. [This has bitten me twice and I hope putting it here will prevent me from suffering a third time :)]

The dependencies between the tickets will force the Approval ticket to be closed before the original ticket can be written off.

Approvals Notification And Permissions

If you want different groups of people to have access to different sets of approvals, you will need to set up a few new Queues. No Ticket of type "Approval" will appear in the normal ticket lists, but tickets of this type from any Queue will be shown on the Approvals page. By managing your permissions, you can set up Approval systems for various organisational departments.

Note that if you're using the default ___Approvals Queue for your approvals, you'll need to give the people who are to approve things permissions to see tickets in this queue (which you can only do by granting Global permissions.) You'll want to grant ShowTicket to AdminCC's (which ever role your template attaches the approving group to the approval ticket as). If the approval link isn't showing you may need to set Configuration > Global > Group Rights > $mygroup > ShowApprovalsTab.

Example using PO Requisition Approvals

Create a PO-Req queue for PO Requisitions.. this is where the tickets get created which need approval. Enable this queue and add users who are allowed to submit PO Requisitions to this queue with necessary permissions.

Create the following template named "Create Approval":

===Create-Ticket: poreq
 Subject: Approve purchase order for {$Tickets{'TOP'}->Subject}
 Depended-On-By: TOP
 Queue: Approvals-PO
 Type: approval
 Owner: username-of-owner   #note this is so that notifications work properly
 Content: Someone has created a purchase requisition.  Please review and approve it, so they can spend some money.
 ENDOFCONTENT
 
 

If you want multiple approvals, just add more "===Create-Ticket:" sections

and the following Scrip:

Description: Create PO Req approval
Condition: On Create
Action: Create Tickets
Template: Create Approval
Stage: TransactionCreate

Create queue Approvals-PO, and copy the templates and scrips from the [__]Approvals queue. (Leave the [__]Approvals queue disabled and its templates unaltered for future reference). If you want an easy way to copy these templates/scrips.. I have none.. it was copy/paste.

You could do this in Mysql with commands such as:

insert into Scrips (Queue, Description, ScripCondition, ScripAction, ConditionRules, ActionRules, CustomIsApplicableCode,
CustomPrepareCode, CustomCommitCode, Stage, Template, Creator, Created, LastUpdatedBy, LastUpdated) select NEWQUEUENUM,
Description, ScripCondition, ScripAction, ConditionRules, ActionRules, CustomIsApplicableCode, CustomPrepareCode,
CustomCommitCode, Stage, Template, Creator, Created, LastUpdatedBy, LastUpdated from Scrips where Queue=2;

insert into Templates (Queue, Name, Description, Type, Language, TranslationOf, Content, LastUpdated, LastUpdatedBy, Creator,
Created) select NEWQUEUENUM, Name, Description, Type, Language, TranslationOf, Content, LastUpdated, LastUpdatedBy, Creator,
Created from Templates where Queue=2;

Set the Reply Address and Comment Address to the email address of the "PO-Req" queue. This just makes sense.

Enable this queue and add as AdminCCs the user(s) you wish to be the Approver(s).

In the scrip for "When an approval ticket is created..." change the following condition from User Defined to "On Create".

The "Approval Passed" Template says "Ticket Rejected" in the subject.. please change to "Ticket Approved". The "All Approvals Passed" Template says "Ticket Rejected" in the subject.. please change to "Ticket Approved".

There you have it. Hope this helps.

Group Approvals

Sometimes you want to create tickets so that any one person from a group can approve it. One way to do that is as follows:

Create a group that contains the list of users that can approve. In the Approval template, add an AdminCC field. This will contain the group, but you cannot just list the group name, unfortunately; that would just create an unprivileged user with the same name as the group. You have to list the group's Principal ID. I suppose you could find out what that is manually and enter it directly, but that's not very manageable. Instead, put some Perl code in the field as follows:

 AdminCC: {
   my $group_name  = 'Group Name';
   my $groups      = RT::Groups->new( $RT::SystemUser );

   $groups->LimitToUserDefinedGroups();
   $groups->Limit(
         'FIELD'    => 'Name',
         'OPERATOR' => '=',
         'VALUE'    => $group_name );
   $groups->First->Id;
}

This inserts the ID of the group named "Group Name" in the AdminCC field. Be sure to replace the group named "Group Name" with the appropriate name of your group.

Now you need to modify permissions for the Queue that contains the Approval so that the AdminCC role can approve it.

Now when you create a ticket with approvals, the approval will show the group name and all of its members in the AdminCC field, and anyone listed there can approve that ticket. If the user that approves it also takes it, then you can easily see in the original ticket's "Depends On" section who approved it. You can automate this via another scrip. Create the following scrip on the Approval queue:

Condition: On Resolve
Action: User Defined
Template: Global Template: Blank
Stage: Transaction Create
Custom Action Preparation Code:
  my $Actor = $self->TransactionObj->CreatorObj->Id;
  if( $Actor != $self->TicketObj->OwnerObj->Id ) {
    $RT::Logger->info("Auto assign ticket #". $self->TicketObj->id ." to user #". $Actor );

    my ($status, $msg) = $self->TicketObj->SetOwner( $Actor );
    unless( $status ) {
      die "Error: $msg";
    }
  }
  return( 1 );

One of the features of doing it this way is that you can continue to have a single Approval queue and different people can approve different tickets since the rights are based on the AdminCC role and not a specific user or group.