summaryrefslogtreecommitdiff
path: root/doc/rt-liberation.texinfo
blob: 168e68c8fa79d9ed6d08c629b7a27c9121fbbe70 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename rt-liberation.info
@settitle The rt-liberation Manual
@c %**end of header

@c History: This manual was started on the 6th of April 2009.

@dircategory Emacs
@direntry
* rt-liberation: (rt-liber).           rt-liberation
@end direntry


@copying
 @copyright{} 2009
   Yoni Rabkin yonirabkin@@member.fsf.org
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying


@c For printed material
@titlepage
@title The rt-liberation Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@c END For printed material


@ifnottex
@node Top, Introduction, (dir), (dir)
@top The rt-liberation Manual

This is the Manual for the rt-liberation system

@insertcopying

@menu
* Introduction::                Introduction to rt-liberation.
* Dependencies::                Before you can use rt-liberation.
* Installation::                Setup rt-liberation to work on the system.

Using rt-liberation
* Queries::                     Retrieve particular tickets from the server.
* Ticket Browser::              Browse the query results.
* Ticket Viewer::               Interface to query results.

Extensions
* Gnus Integration::            Sending email to the RT server via Gnus.
* Tracking Updates::            Keeping up to date with ticket changes.
* Batch Operations::            Performing operations on batches of tickets.
* Local Storage::               Associate arbitrary data with tickets.

Copying and license
* Copying::                     The GNU General Public License gives you
                                permission to redistribute rt-liberation
                                on certain terms; it also explains that
                                there is no warranty.

* The GNU FDL::                 The license for this documentation.

Indices
* Concept Index::
* Function Index::
* Variable Index::
* Keybinding Index::

@detailmenu
 --- The Detailed Node Listing ---

Queries

* Query Compiler::              Compiling Emacs Lisp to TicketSQL.
* Query Language::              A description of the Sexp-based language.

Ticket Browser

* Ticket Browser Display::      How tickets are displayed in the browser.
* Ticket Browser Sorting::      How tickets are sorted in the browser.
* Ticket Browser Filtering::    How to filter tickets out of the browser.
* Multiple Ticket Browsers::    More than one ticket browser buffer.

@end detailmenu
@end menu

@end ifnottex





@c --------------------------------------------------

@node Introduction
@chapter Introduction

@cindex introduction

rt-liberation is a GNU/Emacs package for working with the Request
Tracker (henceforth abbreviated as just ``RT'') software from Best
Practical Solutions. RT has a Web interface and a command line
interface (the ``RT CLI''). rt-liberation uses the RT CLI as a backend
to communicate to the server.

rt-liberation allows sending search queries to the RT server, browsing
the resulting tickets, viewing the tickets' contents and performing
operations on the ticket.





@c --------------------------------------------------

@node Dependencies
@chapter Dependencies

@cindex dependencies

rt-liberation has been tested exclusively on GNU/Emacs.

rt-liberation uses the RT command line interface (RT CLI) as a back-end
to communicate with the RT server. rt-liberation will need a local
copy of the RT software on the machine running rt-liberation. RT is
available at @uref{http://bestpractical.com/rt/download.html}

@menu
* RT CLI Setup::        Getting the RT Command Line Interface to work
@end menu




@node RT CLI Setup
@section RT CLI Setup

The following is a short description of how to get the RT CLI setup on
the machine where rt-liberation will be running. It assumes a
GNU/Linux distribution such as Trisquel @uref{http://trisquel.info/}.

You need the address of the remote RT server (note whether it's an
HTTP or HTTPS address), and the username and password for the user
account on that server.

Download a local copy of RT (version 4.2.3 happened to be extant at
the time of writing).

@example
$ wget http://download.bestpractical.com/pub/rt/release/rt-4.2.3.tar.gz
$ tar xzf rt-4.2.3.tar.gz
@end example

Navigate down to the ``bin'' directory and try to run the RT CLI.

@example
$ cd rt-4.2.3/bin
$ ./rt
@end example

If you don't already have Perl LWP installed it will fail to run, in
which case you have to satisfy this dependency. The following command
should do it on a Trisquel GNU/Linux or similar system:

@example
sudo apt-get install liblwp-protocol-https-perl
@end example

Trying to run the RT CLI at this point should work, and you will be
greeted by the friendly RT CLI prompt ``rt>''. Feel free to hit Ctrl-C
at this point because while the RT CLI is running it is still
unconfigured.

The RT CLI looks for a file named ``.rtrc'' in your home directory, so
create an ``~/.rtrc'' file and, using the information collected
earlier, fill in the details.

@example
server https://rt.server.somewhere
user USERNAME-ON-RT
passwd PASSWORD-ON-RT
@end example

Now back to running the RT CLI we can enter a simple RT query to check
the setup. If everything is set up correctly then the result will be a
list of tickets.

@example
rt> ls "Queue=sprockets and Status=new"
Ticket Owner Queue    Age   Told Status Requestor Subject
--------------------------------------------------------------------------------
==========  2 unowned tickets ==========
   701       sproc  5 min        new    admin@@no. foo
   702       sproc  4 min        new    john.foo@@ john's foo
@end example

At this point you know that rt-liberation has everything it needs to
call into the server@footnote{Implementing rt-liberation in this way
has the additional benefit of isolating the rt-liberation code
somewhat from changes in the way the RT CLI communicates with the RT
server.}.

@c --------------------------------------------------

@node Installation
@chapter Installation

@cindex installation

rt-liberation can be configured in the ~/.emacs file.

Place rt-liberation in the load path:

@lisp
(add-to-list 'load-path "/PATH/TO/rt-liberation/")
@end lisp

Tell GNU/Emacs to load the package with:

@lisp
(require 'rt-liberation)
@end lisp

Tell rt-liberation where to find the RT binary and which version is
being used, for example:

@lisp
(setq rt-liber-rt-binary "~/src/rt-3.8.2/bin/rt"
      rt-liber-rt-version "3.8.8")
@end lisp

rt-liberation can issue a command to ``take'' a ticket, that is,
assign it to yourself. For this the variable @var{rt-liber-username}
must be set:

@lisp
(setq rt-liber-username "someuser")
@end lisp

rt-liberation can also launch a Web browser to visit a ticket. For
that to work the base URL needs to be set in
@var{rt-liber-base-url}. For example:

(setq rt-liber-base-url "https://rt.foo.org/")

@c --------------------------------------------------

@node Queries
@chapter Queries

@cindex queries

A typical RT server is meant to manage a large amount of tickets. Much
more that would be convenient to view all at once. Instead queries are
used to view only a subset of the tickets on the server.

rt-liberation has its own Sexp-based query language which maps to RT's
TicketSQL language.

@menu
* Query Compiler::              Compiling Emacs Lisp to TicketSQL.
* Query Language::              A description of the Sexp-based language.
@end menu





@c --------------------------------------------------

@node Query Compiler
@section Query Compiler

@cindex query compiler

In order to browse and view tickets a list of needs to be requested
from the RT server. Typically the tickets answer some kind of
criteria, for example ``tickets no older than a week owned by me which
have \``foobar\'' in their subject line''. In RT these criteria are
formulated with ``TicketSQL'' queries; a structured query language
specific to RT.

rt-liberation provides a query compiler function to compile Emacs Lisp
symbolic expressions into TicketSQL. The query compiler supports a
number of TicketSQL tokens.





@c --------------------------------------------------

@node Query Language
@section Query Language

@cindex query language

rt-liberation's Sexp-based query language covers a portion of the
TicketSQL language. Here are some of the supported TicketSQL tokens:
Boolean tokens as a means of combining query subsections: ``and'', ``or'',
``not''. LIKE attribute tokens: ``subject'', ``content''.

For example here is a query with both Boolean and LIKE tokens:

@lisp
(rt-liber-compile-query
    (and (queue "bugs")
         (content "gnu")))

==> "Queue = 'bugs' AND Content LIKE 'gnu'"
@end lisp

We can also express negation (note that the compiler produces "!=" and
"NOT LIKE" for negation depending on the context):

@lisp
(rt-liber-compile-query
 (and (queue "bugs")
      (not (owner "Nobody"))
      (not (content "sprigz"))
      (status "new")))

==> "Queue = 'licensing' AND Owner != 'Nobody' \
    AND Content NOT LIKE 'sprigz' AND Status = 'new'"
@end lisp

Attribute tokens which match an attribute to a specific field such as:
``owner'', ``status'' and ``queue''. Temporal tokens which limit the search
results to tickets within a certain time interval: ``created'' and
``lastupdated''. Note that temporal keywords such as ``created'' always
accept two arguments: BEFORE and AFTER. When either BEFORE or AFTER
aren't needed, use NIL instead.

One of the advantages of being able to express the TicketSQL queries
as Emacs Lisp is to be able to express queries using Emacs Lisp
functions.

Here is a slightly more involved example to illustrate:

@lisp
(rt-liber-compile-query
 (and (queue "bugs")
      (owner "me@@myaddress.com")
      (status "open")
      (lastupdated nil
                   (format-time-string
                     "%Y-%m-%d"
                     (seconds-to-time
                      (- (time-to-seconds (current-time))
                         (* 60 60 24 7)))))))

==> "Queue = 'bugs' AND Owner = 'me@@myaddress.com' AND Status = 'open' AND LastUpdated > '2009-03-30'"
@end lisp


Here is an example of how the ticket browser and compiler can be used
in function calls:

@lisp
(defun rt-liber-display-ticket (ticket-id)
  "Display ticket with TICKET-ID in the ticket-browser."
  (interactive "MTicket ID: ")
  (rt-liber-browse-query
   (rt-liber-compile-query
    (and (queue "complaints")
         (id ticket-id)))))
@end lisp




@c --------------------------------------------------

@node Ticket Browser
@chapter Ticket Browser

@cindex ticket browser

The ticket browser is a special buffer which provides a convenient
interface to the results of a server query. The ticket browser can be
started by invoking: (rt-liber-browse-query QUERY), where QUERY is a
TicketSQL query. The TicketSQL query can be entered manually as a
string or as the return value of the query compiler.

@deffn Function rt-liber-browse-query QUERY &optional NEW
Runs QUERY against the server and launches the browser.

If NEW is non-nil then the query results will be displayed in a new
buffer, otherwise the query results will override the contents of the
existing ticket browser buffer. If NEW is a string then that will be
the name of the new buffer.
@end deffn

The TicketSQL query can be the return value of the query compiler. For
example:

@lisp
(rt-liber-browse-query
 (rt-liber-compile-query
     (and (queue "bugs")
          (content "gnu")))
@end lisp


Since the return value of the query compiler is just a TicketSQL
string, the following is equivalent:

@lisp
(rt-liber-browse-query "Queue = 'bugs' AND Content LIKE 'gnu'")
@end lisp

The ticket browser defines a number of commands:

@table @kbd
@item q
@kindex q (ticket browser)
@findex rt-liber-browser-mode-quit
Bury the ticket browser buffer.

@item n
@kindex n (ticket browser)
@findex rt-liber-next-ticket-in-browser
Move point to the next ticket.

@item p
@kindex p (ticket browser)
@findex rt-liber-previous-ticket-in-browser
Move point to the previous ticket.

@item RET
@kindex RET (ticket browser)
@findex rt-liber-display-ticket-at-point
Visit the ticket at point in the @xref{Ticket Viewer}.

@item g
@kindex g (ticket browser)
@findex revert-buffer
Refresh the contents of the browser buffer.

@item G
@kindex G (ticket browser)
@findex rt-liber-browser-refresh-and-return
Refresh the contents of the browser buffer. Return point to the
current ticket after the refresh (if possible).

@item s
@kindex s (ticket browser)
@findex rt-liber-browser-mark-as-spam
Mark the ticket as spam.

@item S
@kindex S (ticket browser)
@findex rt-liber-multi-delete-spam
Delete marked tickets as spam (requires rt-liberation-multi package).

@item a
@kindex a (ticket browser)
@findex rt-liber-browser-assign
Assign the ticket to a user.

@item r
@kindex r (ticket browser)
@findex rt-liber-browser-resolve
Mark the ticket as ``resolved''.

@item o
@kindex o (ticket browser)
@findex rt-liber-browser-open
Mark the ticket as ``open''.

@item t
@kindex t (ticket browser)
@findex rt-liber-browser-take-ticket-at-point
Assign the ticket at point to @var{rt-liber-username}.

@item SPC
@kindex SPC (ticket browser)
@findex scroll-up
Scroll the text of the ticket browser upward.

@item DEL
@kindex DEL (ticket browser)
@findex scroll-down
Scroll the text of the ticket browser downward.

@item m
@kindex m (ticket browser)
@findex rt-liber-browser-move
Move the ticket to a different queue.

@item P
@kindex P (ticket browser)
@findex rt-liber-browser-prioritize
Set the numerical priority level of the ticket at point.

@end table

@menu
* Ticket Browser Display::      How tickets are displayed in the browser.
* Ticket Browser Sorting::      How tickets are sorted in the browser.
* Ticket Browser Filtering::    How to filter tickets out of the browser.
* Multiple Ticket Browsers::    More than one ticket browser buffer.
@end menu





@c --------------------------------------------------

@node Ticket Browser Display
@section Ticket Browser Display

@cindex ticket browser display function

The ticket browser displays the tickets in the browser by calling
@dfn{rt-liber-ticketlist-browser-redraw-f} which can be changed and
customized. Any implementation of
@dfn{rt-liber-ticketlist-browser-redraw-f} must leave point at the end
of the ticket text.

The ticket data itself can be displayed using rt-liberation ticket
format string %-sequences:

@table @asis
@item %i
ID number of the ticket in the RT database.
@item %s
Subject line.
@item %c
Ticket creation time. The format to display the time is specified in
the variable @var{rt-liber-browser-time-format-string}.
@item %S
Ticket status (``open'', ``new'' etc.)
@item %r
Whether the ticket is resolved.
@item %R
Requestor/s
@item %C
Creator of the ticket.
@item %o
Owner of the ticket.
@item %q
The queue originating the ticket.
@item %p
The numerical priority of the ticket
@end table

Here is an example implementation of
@dfn{rt-liber-ticketlist-browser-redraw-f} showing the use of the
%-sequences. Note the use of text properties to add color to ticket
text. The use of text properties as opposed to font-locking is meant
to ease customization because otherwise any change in ticket display
would break the font-locking regular expressions.

@lisp
(defun rt-liber-ticketlist-browser-redraw-f (ticket)
  "Display TICKET."
  (insert (rt-liber-format "[%c] %i" ticket))
  (add-text-properties (point-at-bol)
                       (point-at-eol)
                       '(face rt-liber-ticket-face))
  (newline)
  (insert (rt-liber-format "    [%S] %s" ticket))
  (newline)
  (insert (rt-liber-format "    %o <== %R" ticket)))
@end lisp

The function @dfn{rt-liber-high-priority-p} can be used to apply a
different face or text to a ticket if it is high priority. A ticket is
considered high priority if its value is strictly higher than
@var{rt-liber-browser-priority-cutoff}




@c --------------------------------------------------

@node Ticket Browser Sorting
@section Ticket Browser Sorting

@cindex ticket browser sorting

The tickets in the browser are displayed by default in reverse
chronological order. Ticket sorting is done by a call to
@dfn{rt-liber-browser-default-sorting-function}.

Other sorting orders can be used by binding
@dfn{rt-liber-browser-default-sorting-function} to a different
function. To ease writing such functions rt-liberation provides two
predicate functions to perform comparisons between ticket objects:

@defun rt-liber-lex-lessthan-p a b field
Return true if A is lexicographically less than B in FIELD.

Here is an example of sorting tickets lexicographically by owner name
using @dfn{rt-liber-lex-lessthan-p} (note that you can feed
@dfn{rt-liber-lex-lessthan-p} a date/time string and it will sort it
just fine except that it wouldn't make any sense):

@lisp
(defun rt-liber-sort-by-owner (ticket-list)
  "Sort TICKET-LIST lexicographically by owner."
  (rt-liber-sort-ticket-list
   ticket-list
   #'(lambda (a b)
       (rt-liber-lex-lessthan-p a b "Owner"))))
@end lisp

@end defun

@defun rt-liber-time-lessthan-p a b field
Return t if A is chronologically less than B in FIELD.

Here is an example of sorting tickets lexicographically by owner name
using @dfn{rt-liber-time-lessthan-p} (note that feeding
@dfn{rt-liber-time-lessthan-p} anything but a date/time string, in
this case ``Created'' contains a date, will result in an error being
signaled).

@lisp
(defun rt-liber-sort-by-time-created (ticket-list)
  "Sort TICKET-LIST in reverse chronological order."
  (reverse
   (rt-liber-sort-ticket-list
    ticket-list
    #'(lambda (a b)
        (rt-liber-time-lessthan-p a b "Created")))))
@end lisp

@end defun

@c -------------------------------------------------------------------

@node Ticket Browser Filtering
@section Ticket Browser Filtering

@cindex ticket browser filtering filter

The Ticket Browser can also filter out (that is, not display) certain
tickets based on particular criteria. This probably shouldn't be used
instead of a properly formed RT query, but when used in conjunction
with correctly formulated queries it becomes a powerful tool.

During ticket display processing the Ticket Browser will call the
function pointed to by @var{rt-liber-browser-default-filter-function}
on each ticket, passing the function the ticket alist as a single
argument. The function is set by default to
@dfn{rt-liber-default-filter-f}, which is a function which will
display all tickets and filter none.

If any tickets are filtered, the Ticket Browser will display the
filtered ticket count at the bottom ticket listing.

Here is a simple example of how to filter out all of the tickets which
have a status of ``deleted''.

First we define a custom filter function. Note how it accepts a single
argument, which is the ticket alist, and returns nil if the ticket is
to be filtered.

@lisp
(defun rt-liber-browser-deleted-filter (ticket)
  (not
   (and ticket
        (string= (cdr (assoc "Status" ticket))
                 "deleted"))))
@end lisp

Then we assign that function to be our default filtering function:

@lisp
(setq rt-liber-browser-default-filter-function
      'rt-liber-browser-deleted-filter)
@end lisp

@c -------------------------------------------------------------------


@node Multiple Ticket Browsers
@section Multiple Ticket Browsers

@cindex ticket browser multiple buffer

It is sometimes useful to rename the ticket browser buffer to
something more informative than the default
@var{rt-liber-browser-buffer-name}, especially if there are multiple
ticket browsers.

Changing a ticket browser's name can be done normally with
`rename-buffer', but it is also possible to name the ticket browser
when it is created. In the following example two ticket browser
buffers will be created displaying the query results and named
``*updated by supervisor*'' and ``*new tickets*'' respectively:

@lisp
(defun rt-liber-daily-rounds ()
  (interactive)

  (rt-liber-browse-query
   (rt-liber-compile-query
    (and (queue "complaints")
         (owner "lem.e.tweakit")
         (status "open")
         (lastupdatedby "molly.manager")))
   "*updated by supervisor*")

  (rt-liber-browse-query
   (rt-liber-compile-query
    (and (queue "complaints")
         (owner "Nobody")
         (status "new")))
   "*new tickets*"))
@end lisp





@c --------------------------------------------------

@node Ticket Viewer
@chapter Ticket Viewer

@cindex ticket viewer

The ticket viewer is an interface for viewing the contents of a
ticket. It provides font-locking to make reading the contents easier
via @var{rt-liber-viewer-font-lock-keywords} and a number of
key-bindings.

The ticket viewer provides key-bindings to help compose emails to send
to the RT email interface. The key-bindings for composing email
described below are generic, what actually happens when you invoke
them depends on the email-backend system you have installed into
rt-liberation. @file{rt-liberation-gnus.el} provides integration with
Gnus, @xref{Gnus Integration}.

Setting @var{rt-liber-jump-to-latest} to `t' will cause the viewer to
automatically scroll to the latest comment in a ticket when that
ticket is visited. By default @var{rt-liber-jump-to-latest} is set to
`nil'.

When in the ticket viewer buffer, invoking
@dfn{rt-liber-viewer-take-ticket} will ``take'' the ticket.

@table @kbd

@item q
@kindex q (ticket viewer)
@findex rt-liber-viewer-mode-quit
Bury the ticket viewer buffer.

@item n
@kindex n (ticket viewer)
@findex rt-liber-next-section-in-viewer
Move point to the next section in ticket.

@item N
@kindex N (ticket viewer)
@findex rt-liber-jump-to-latest-correspondence
Move point to the newest correspondence section, if any.

@item p
@kindex p (ticket viewer)
@findex rt-liber-previous-section-in-viewer
Move point to the previous section in ticket.

@item V
@kindex V (ticket viewer)
@findex rt-liber-viewer-visit-in-browser
Visit the current ticket in a Web browser.

@item m
@kindex m (ticket viewer)
@findex rt-liber-viewer-answer
Compose an answer to the current ticket.

@item M
@kindex M (ticket viewer)
@findex rt-liber-viewer-answer-this
Compose an answer to the current ticket. The content section around
point will be inserted into the email body and commented out.

@item t
@kindex t (ticket viewer)
@findex rt-liber-viewer-answer-provisionally
Compose a provisional answer to the current ticket.

@item T
@kindex t (ticket viewer)
@findex rt-liber-viewer-answer-provisionally-this
Compose a provisional answer to the current ticket. The content
section around point will be inserted into the email body and
commented out.

@item F
@kindex F (ticket viewer)
@findex rt-liber-viewer-answer-verbatim-this
Compose an answer to the current ticket. The content section around
point will be inserted into the email body verbatim.

@item c
@kindex c (ticket viewer)
@findex rt-liber-viewer-comment
Compose a comment for the current ticket.

@item C
@kindex C (ticket viewer)
@findex rt-liber-viewer-comment-this
Comment on the ticket using the current context

@item g
@kindex g (ticket viewer)
@findex revert-buffer
Refresh and redisplay the current ticket.

@item SPC
@kindex SPC (ticket viewer)
@findex scroll-up
Scroll text of ticket viewer upward.

@item DEL
@kindex DEL (ticket viewer)
@findex scroll-down
Scroll text of ticket viewer downward.

@item h
@kindex h (ticket viewer)
@findex rt-liber-viewer-show-ticket-browser
Display the associated ticket in the ticket browser.

@end table





@c --------------------------------------------------

@node Gnus Integration
@chapter Gnus Integration

@cindex Gnus Integration

The file @file{rt-liberation-gnus.el} implements integration with Gnus
for composing emails. To enable the feature, `require' it after
loading rt-liberation:

@lisp
(require 'rt-liberation-gnus)
@end lisp

In order for rt-liberation-gnus to be useful a few variables need to
be specialized. The following is example code which sets these
variables followed by a more thorough description of the variables:

@lisp
(setq rt-liber-gnus-comment-address "our-rtserver-comment@@ourserver.org"
      rt-liber-gnus-address         "our-rtserver@@ourserver.org"
      rt-liber-gnus-subject-name    "ourserver.org"
      rt-liber-gnus-answer-headers  '(("Gcc" . "nnml:Send-Mail")
                                      ("X-Ethics" . "Use GNU"))
      rt-liber-gnus-signature       "Kind Regards")
@end lisp

@defopt
@var{rt-liber-gnus-address} is the email address which is configured
in the RT server email interface for sending a response to the
ticket's requestor.
@end defopt
@defopt
@var{rt-liber-gnus-comment-address} is the email address which is
configured in the RT server email interface for adding a comment under
the ticket in question.
@end defopt
@defopt
@var{rt-liber-gnus-subject-name} is a string, typically included at
the beginning of the square brackets in the subject. The string is a
part of the subject line which helps the RT server recognize the
email.
@end defopt
@defopt
@var{rt-liber-gnus-answer-headers} defines a list of dotted-pairs
containing the header name and value for additional email headers.
@end defopt
@defopt
A signature can be added automatically to the end of the email by
setting @var{rt-liber-gnus-signature} to be some text. It is useful to
include newlines in this text to make the signature format nicely.
@end defopt

Once rt-liberation-gnus is loaded and customized the key-bindings in
the Viewer will be able to call into it, @xref{Ticket Viewer}.





@c --------------------------------------------------

@node Tracking Updates
@chapter Tracking Updates

@cindex Tracking Updates

The functions in @file{rt-liberation-update.el} help keep up with
updates to the ticket database. To enable the feature, `require' it
after loading rt-liberation:

@lisp
(require 'rt-liberation-update)
@end lisp

Then set @var{rt-liber-update-default-queue} to be the name of the
queue to watch for updates. For example:

@lisp
(setq rt-liber-update-default-queue "complaints")
@end lisp

@defun rt-liber-update &optional no-update
@code{rt-liber-update} is an interactive function which runs a query
against the RT server asking for the tickets which have been updated
since the time @code{rt-liber-update} was last run (each time it runs,
it leaves a time-stamp). If no time-stamp is found, for instance when
you run @code{rt-liber-update} for the first time, today's date is
used.

With the NO-UPDATE prefix, @code{rt-liber-update} will not update the
time-stamp so that the next invocation will produce the same result.
@end defun




@c --------------------------------------------------

@node Batch Operations
@chapter Batch Operations

@cindex Batch Operations

The extension @file{rt-liberation-multi.el} implements performing
batch operations on groups of tickets. It works in two stages: First
mark an arbitrary number of tickets within the same buffer then call a
batch operation function on them. The batch operation functions work
the same way as function which work on single tickets only that they
iterate through all of the marked tickets.

To enable batch operations first load @file{rt-liberation-multi.el}:

@lisp
(require 'rt-liberation-storage)
@end lisp

@table @kbd
@item M
@kindex M (ticket browser)
@findex rt-liber-mark-ticket-at-point
Mark the ticket at point for future action. If the ticket at point is
already marked then unmark it.
@end table

@defun rt-liber-multi-set-status-open
Set the status of all the marked tickets to ``open''.
@end defun

@defun rt-liber-multi-set-status-resolved
Set the status of all the marked tickets to ``resolved.
@end defun

@defun rt-liber-multi-assign name
Assign all of the marked tickets to NAME.
@end defun

@defun rt-liber-multi-flag-as-spam-and-delete
Set the status of all the marked tickets to ``is-spam'' and delete.
@end defun





@c --------------------------------------------------

@node Local Storage
@chapter Local Storage

@cindex Local Storage

@file{rt-liberation-storage.el} implements associating arbitrary
ancillary data with tickets. The data is stored locally and is not
sent to the RT server.

To enable local storage first load @file{rt-liberation-storage.el}:

@lisp
(require 'rt-liberation-storage)
@end lisp

Then enable the display of ancillary data with:

@lisp
(setq rt-liber-anc-p t)
@end lisp

The associated data is edited and displayed in the ticket browser with
the following command key:

@table @kbd
@item A
@kindex A (ticket browser)
@findex rt-liber-browser-ancillary-text
Associate text with the ticket at point. You will be prompted to enter
a string of text.
@end table

Once text is associated with a ticket it will be displayed alongside
that ticket in the ticket browser. This particular feature lends
itself to creating private annotations about tickets.

The implementation distributed with rt-liberation allows associating
text with tickets but is not limited to text. The same implementation
can be extended to associate any arbitrary data with any ticket.


@c including the relevant licenses
@include gpl.texi
@include fdl.texi





@c --------------------------------------------------

@node Concept Index
@unnumbered Concept Index
@printindex cp




@c --------------------------------------------------

@node Function Index
@unnumbered Function Index
@printindex fn




@c --------------------------------------------------

@node Variable Index
@unnumbered Variable Index
@printindex vr




@c --------------------------------------------------

@node Keybinding Index
@unnumbered Keybinding Index
@printindex ky


@bye