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