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