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 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. 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 35to Admin -> Articles -> Classes -> New Class. Articles 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 38Fields are applied to a Queue in RT. 39 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. 46 47Classes need to be Applied, just like a Custom Field, by using the 48Applies To link on the Modify Class page (Admin -> 49Articles -> Classes, select the class to modify). You can apply 50them globally or on a queue-by-queue basis. 51 52=head3 Topics 53 54You can also use Topics to organize your Articles. While editing a 55Class, there is a Topics tab for Class-specific Topics. You can create 56global Topics from the Global tab under Admin. 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 65Class. Articles can belong to both global and Class-specific Topics. 66 67Article topics can be set from the Modify screen for the article -- 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 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. 79 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. 82Alternatively, use the Applies To link from each Custom Field. 83 84=head2 Creating Articles 85 86You can create an Article from scratch by going to Tools -> Articles -> 87New Article and then picking which Class to create the Article under. 88You must have a Class to assign the new Article to. 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 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 100displayed, along with a set of select boxes. For each transaction, you 101can pick which Custom Field that transaction should be extracted to. 102From there on in, it's just regular Article creation. 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 110The Include Article dropdown contains articles from any classes that 111are applied to the queue the ticket is in. When the list of articles 112exceeds the configured L<RT_Config/DropdownMenuLimit>, it 113automatically turns into a search box which allows you to type an 114article name. The search box will help you by auto-completing to 115matching articles as you type. 116 117=head3 Disabling Escaped HTML 118 119By default, when an article is inserted into the ticket message box, 120as a security measure, HTML tags are escaped and only text is displayed. 121For example, RT will display "Me You Greeting Hello world!" from the 122following XML: 123 124 <?xml version="1.0" encoding="UTF-8"?> 125 <note> 126 <to>Me</to> 127 <from>You</from> 128 <heading>Greeting</heading> 129 <body>Hello world!</body> 130 </note> 131 132In cases as above, where the content is harmless and displaying it on the 133ticket might be necessary, there is an option to disable escaping these 134tags per article class. This can be done by unchecking the "Escape HTML" 135box on the Modify Class page. Please note this is potentially unsafe and 136its use should be limited to trusted administrators. 137 138=head3 Disabling Ticket Linking 139 140When an article is included in a ticket's comment or reply, the article 141is automatically added as a link to the ticket. This means that the article 142will be listed under the Links portlet on ticket display page, and also on 143the article display page. If you use an article many times, it can result 144in a very long list of links on the article page. 145 146To avoid this, you can disable automatic linking globally (via 147L<RT_Config/LinkArticlesOnInclude>) or by class. To disable it on the class 148level, uncheck the "Link article to ticket" option under "When inserting 149articles in this class into emails" on class modify page. Note that 150disabling this feature will only affect future comments/replies on tickets. 151Existing links to articles will remain linked. 152 153=head2 Queue-Specific List of Articles 154 155You can use Topics to organize a set of Queue-specific Articles. 156Simply create a global Topic called 'Queues' and then create Topics 157under Queues named after each of your Queues. Within each Queue-named 158Topic, create some Topics and then assign Articles to those 159sub-topics. This creates a hierarchy like this: 160 161Queues 162\-> General 163 \-> Topic 1 164 \-> Topic 2 165 166If you are replying to a Ticket in the General Queue you will be 167offered a choice of Topic 1 and Topic 2 along with the searching. 168After choosing Topic 1 or Topic 2, you will be given a list of 169relevant articles to choose. 170 171You can also organize articles into separate classes and selectively 172apply classes to the queues they should be used for. 173 174=head2 SelfService Interface 175 176If you grant the Unprivileged user group the right ShowArticle, they 177will get a Search box at the top of their interface. This allows users 178to look through your Articles for answers to questions before creating 179a Ticket. 180 181=head1 Configuration Options 182 183=head2 ArticleOnTicketCreate 184 185Set this to a true value to display the Article include interface on the 186Ticket Create page in addition to the Reply/Comment page (Create.html 187in addition to Update.html). 188 189=head2 HideArticleSearchOnReplyCreate 190 191On Ticket Reply (and Create if you set the above config var) 192RT's Article system normally displays a search box and an include box 193(for inputting an article id) and configurable dropdowns 194of Articles. These can be configured using Global Topics or 195on the Class page. 196 197If you set this to a true value, RT will only display 198dropdowns and hide the search boxes. 199 200=cut 201