Initial commit 4.0.5-3
[usit-rt.git] / docs / customizing / articles_introduction.pod
1
2 =head1 Articles
3
4 Articles are a way of managing stock answers or frequently asked
5 questions.  Articles are a collection of custom fields whose values can
6 be easily inserted into ticket replies or searched and browsed within
7 RT.  They are organized into classes and topics.
8
9 =head2 UI
10
11 The user interface to Articles is available from the Tools -> Articles
12 menu.  Admin functionality can be found under Tools -> Configuration ->
13 Articles.  Once configured, articles will become available for searching
14 on the Reply/Comment page on tickets.  There are configuration variables
15 to make Articles available on ticket creation.
16
17 =head2 Basics
18
19 You will need to make some decisions about how to organize your
20 articles.  Articles will be organized into one Class and multiple
21 Topics.  They will use Custom Fields to store their article data.
22 These Custom Fields can be configured on a Class by Class basis.
23 Classes can be made available globally or on a per-Queue basis.
24
25 =head2 Organization
26
27 =head3 Classes
28
29 Classes are equivalent to RT's queues.  They can be created by going
30 to Tools -> Configuration -> Articles -> Classes -> New Class.  Articles
31 are assigned to one Class.  When you create Custom Fields for use with
32 Articles, they will be applied Globally or to a Class, like Custom
33 Fields are applied to a Queue in RT.  Each class also controls what
34 information is included into a reply (such as the Class header and
35 footer) and the Article.
36
37 Classes need to be Applied, just like a Custom Field by using the
38 Applied To link.  You can apply them globally or on a queue-by-queue
39 basis.
40
41 hotlist.
42
43 =head3 Topics
44
45 You can also use Topics to organize your Articles.  While editing a
46 Class, there is a Topic tab for Class specific Topics.  You can create
47 global Topics from the Global tab under Tools -> Configuration.
48
49 When editing Topics, type the name (and optionally description) of the
50 Topic, and then click the button at the appropriate location in the
51 Topic hierarchy. This should allow you to build a tree of Topics. This
52 tree of Topics should show up when creating or modifying articles in
53 the class. These can be arbitrarily nested.
54
55 Global Topics will be available for all Articles, regardless of their
56 Class.  Articles can belong to both global and class-specific Topics.
57
58 Articles topics can be set from the 'Modify' screen for the article --
59 simply select as many topics as you desire from the list at the bottom
60 of the screen.
61
62 =head2 Custom Fields
63
64 Articles don't have a single "body" section for each
65 article. Everything is a custom field (except for name, summary and
66 some other basic metadata). So, you need to create some custom
67 fields to hold the Article body and other data.  These Custom Fields
68 should have "Applies To" be "RTFM Articles".
69
70 Once you've created your custom fields, go into your classes and click
71 on "Custom Fields" and add the Custom Fields you want to each class.
72 Alternatively, use the Applies To link from each Custom Field.
73
74 =head2 Creating Articles
75
76 You can create an article from scratch by going to Tools -> Articles ->
77 New Article and then picking which Class to create the Article under.
78 The Summary, Description and Custom Fields will all be searchable when
79 including an Article and you can control what Custom Fields end up in
80 your Ticket from the Class configuration page.
81
82 =head3 Extracting an Article
83
84 You can extract the body of a ticket into an article. Within RT, you
85 should now see an "Extract to article" button in the upper right hand
86 corner of RT's UI when working with tickets. When you click that
87 button, RT will ask you which Class to create your new article in.
88 Once you click on a class name, the Ticket's transactions will be
89 displayed, along with a set of select boxes. For each transaction, you
90 can pick which Custom Field that transaction should be extracted to.
91 From there on in, it's just regular article creation.
92
93 =head2 Including an Article
94
95 When replying to or commenting on tickets or creating tickets, there
96 is a UI widget that lets you search for and include Articles in
97 your reply.  (They're editable, of course).  
98
99 Articles can be included by searching for them, knowing the Id of the
100 article, using the Article Hotlist and using the Queue specific
101 dropdown.
102
103 =head2 Queue Specific List of Articles 
104
105 You can use Topics to organize a set of Queue specific Articles.
106 Simply create a global Topic called 'Queues' and then create Topics
107 under Queues named after each of your Queues.  Within each Queue named
108 Topic, create some Topics and then assign Articles to those
109 sub-topics.  This creates a hierarchy like this:
110
111 Queues
112 \-> General
113     \-> Topic 1
114     \-> Topic 2
115
116 If you are replying to a Ticket in the General Queue you will be
117 offered a choice of Topic 1 and Topic 2 along with the searching.
118 After choosing Topic 1 or Topic 2, you will be given a list of
119 relevant articles to choose.
120
121 Alternately, you can now implement this by applying a single class to
122 your queue and using the L<Article Hotlist> feature described below.
123
124 =head2 Article Hotlist
125
126 If you enable "All articles in this class are on dropdown on ticket
127 reply page" option, there will be a dropdown on the Create or Update
128 page which allows users to quickly include Articles.
129
130 =head2 SelfService Interface
131
132 If you grant the Unprivileged user group the right ShowArticle, they
133 will get a Search box at the top of their interface.  This allows users
134 to look for answer to questions before creating a Ticket.
135
136 =head1 Configuration options
137
138 =head2 ArticleOnTicketCreate
139
140 Set this to a true value to display the Article include interface on the
141 Ticket Create page in addition to the Reply/Comment page (Create.html
142 in addition to Update.html)
143
144 =head2 HideArticleSearchOnReplyCreate
145
146 On Ticket Reply (and Create if you set the above config var)
147 RTFM normally displays a search box and an include box (for
148 inputting an article id) and configurable dropdowns
149 of articles.  These can be configured using Global Topics or
150 on the Class page.
151
152 If you set this to a true value, RTFM will only display
153 dropdowns and hide the search boxes
154
155 =cut