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