rt/docs/customizing/approvals.pod

   1 =head1 RT Approvals
   2
   3 Some types of change requests processed through RT can
   4 require an approval before being fulfilled. You can configure
   5 RT to set up such an approval workflow for tickets in
   6 queues you select.
   7
   8 This document walks through the steps to set up a
   9 "Change requests" queue with approvals. You should try
  10 this in a test instance first. If you don't have a test RT
  11 instance, you should read through the entire document first,
  12 change the details as needed for your approval scenario, and then
  13 set up approvals.
  14
  15 =head2 Overview
  16
  17 The approvals solution in RT involves using a special queue,
  18 called ___Approvals, to hold approval requests. Scrips and
  19 templates automatically create the necessary tickets
  20 and process the approval or rejection.
  21
  22 =head2 Change Management Queue
  23
  24 Since this example will use a change management queue as the
  25 queue where tickets need approval, first we'll set up the queue.
  26
  27 Login into UI as the 'root' user. Go to Tools -> Configuration ->
  28 Queues and create a new 'Change requests' queue.
  29
  30 When you set up this queue, do not select the "approvals" Lifecycle.
  31 That selection is for the ___Approvals queue itself, not for queues that
  32 need tickets approved.
  33
  34 =head3 Change Management Template
  35
  36 Once the Change Management queue is created, select Templates
  37 -> Create in the queue configuration menu. Enter the Name 'create approval',
  38 leave the default Type as Perl and in the content area enter the following:
  39
  40     ===Create-Ticket: Manager approval
  41     Subject: Manager Approval for {$Tickets{TOP}->Id} - {$Tickets{TOP}->Subject}
  42     Depended-On-By: TOP
  43     Queue: ___Approvals
  44     Owner: root
  45     Requestors: {$Tickets{TOP}->RequestorAddresses}
  46     Type: approval
  47     Content-Type: text/plain
  48     Due: {time + 3*24*60*60}
  49     Content: Please approve me.
  50
  51     Thanks.
  52     ENDOFCONTENT
  53
  54 All of the text should be against the left side of the textarea
  55 with no spaces.
  56
  57 Click create.
  58
  59 You'll now use this template when you create the scrip.
  60
  61 =head3 Change Management Scrip
  62
  63 Now you need a scrip. On the queue configuration page, select
  64 Scrips -> Create. For the Description, enter 'Create an approval
  65 on ticket create', select the 'On Create' condition, 'Create Tickets'
  66 action, and select the template you just created. Click create.
  67
  68 =head3 Testing
  69
  70 You can already test your first workflow with approvals. Create
  71 a ticket in your new 'Change requests' queue. You're logged in as
  72 'root' and the owner of the approval is root (based on the template),
  73 so it's your job to approve or deny the request. Select Tools -> Approvals
  74 in the RT main menu. You should see your first approval request.
  75
  76 Select the 'Deny' radio button, write 'too expensive' in the notes area
  77 and click Go! You just rejected the approval request. If you open the ticket
  78 you created for testing then you will see that it's rejected
  79 as well and has the correspondence:
  80
  81     Greetings,
  82
  83     Your ticket has been rejected by root.
  84
  85     Approver's notes: too expensive
  86
  87 You may need to search for the ticket since the rejected state means
  88 it's no longer 'active'.
  89
  90 Where did this message come from? From templates in the ___Approvals
  91 queue.
  92
  93 =head2 ___Approvals queue
  94
  95 ___Approvals is a special queue where all approvals are created. The queue
  96 is disabled and is not shown in until you search for it.
  97 Go to Tools -> Configuration -> Queues, leave "Name is" in the search
  98 area and enter ___Approvals into the search
  99 field. Check 'Include disabled queues in listing.' and click Go!
 100 You should now see the ___Approvals queue configuration page.
 101
 102 You may want to change the name of the ___Approvals queue, but parts of RT
 103 expect it not to change.  The name normally isn't shown to users, however, so
 104 it will be largely invisible.
 105
 106 =head2 Approvals' templates
 107
 108 From the ___Approvals queue configuration page, click 'Templates' in the
 109 page menu. You should see templates that are used after actions
 110 on approvals. For example if you click on the 'Approval Rejected'
 111 template in the list, you will see the template that generates
 112 the correspondence mentioned above.
 113
 114 =over 4
 115
 116 =item * New Pending Approval
 117
 118 Owners of new approval requests get this message.
 119
 120 =item * Approval Passed
 121
 122 Recorded as correspondence on the ticket when it's approved by an
 123 approver, but still requires more people to approve.
 124
 125 =item * All Approvals Passed
 126
 127 Recorded when no more approvals are required.
 128
 129 =item * Approval Rejected
 130
 131 Recorded when the approval request is rejected (denied).
 132
 133 =item * Approval Ready for Owner
 134
 135 Sent to the Owner of the ticket when it's approved and no more approvals
 136 are required.
 137
 138 =back
 139
 140 You can customize these templates to meet your needs. However,
 141 note that there is just one ___Approvals queue for the system,
 142 so make sure changes work with all queues that use approvals.
 143
 144 =head2 Approvers
 145
 146 Navigate back to the template used to create approvals. It has
 147 the following line:
 148
 149     Owner: root
 150
 151 With this code you set the owner of the approval request to root.
 152 Approvals, as well as tickets, have Ccs, AdminCcs and Requestors. For
 153 example the following line copies requestors from the Tickets
 154 to the approval request:
 155
 156     Requestors: {$Tickets{TOP}->RequestorAddresses}
 157
 158 Let's create a group 'Change Approvers' and let any user of
 159 this group approve 'Change Requests'. Create the group, and add root
 160 as a member. Open the 'create an approval' template, and replace
 161 the 'Owner:...' line with the following:
 162
 163     AdminCcGroup: Change Approvers
 164
 165 Note that this line only works in RT 4.0.5 and newer.
 166
 167 Create another test ticket, and you as root still should be able to see
 168 the newly created approval, but now because of the group membership.
 169 You can accept or deny it.
 170
 171 Any member of the group can accept/deny without consulting
 172 the other members, which is useful with more complex
 173 multistep workflows.
 174
 175 =head2 Approvers' Rights
 176
 177 Since the ___Approvals queue is a regular RT queue, you need
 178 to grant rights to allow your approvers to operate on approval
 179 requests. As root, you have super user rights and haven't needed
 180 specific rights for this example.
 181
 182 It's wise to grant rights via roles as there
 183 is only one queue for all approvals in the system.
 184
 185 To grant rights to your Change Approvers group, go to the queue
 186 configuration page for the ___Approvals queue. Click on Group Rights
 187 in the page menu. Grant ShowTicket and ModifyTicket rights to the
 188 Owner and AdminCc roles. This should be enough for most cases.
 189
 190 Now members of the 'Change Approvers' group can act on approvals
 191 even if they have no SuperUser rights.