RT 5.0.4 Documentation
Customizing/Articles introduction
Articles
Articles are a way of managing stock answers or frequently asked questions. Articles are a collection of custom fields whose values can be easily inserted into ticket replies or searched and browsed within RT. They are organized into classes and topics.
UI
The user interface to Articles is available from the Articles menu. Admin functionality can be found under Admin -> Articles. Once configured, articles will become available for searching on the Reply/Comment page on tickets. There are "Configuration Options" to make Articles available on ticket creation.
For the Articles menu to be visible to your Privileged users, you must grant Privileged the ShowArticlesMenu right globally (Admin -> Global -> Group Rights). You may grant the right as selectively as you wish if, for example, you only want a certain group of your users to use articles.
Basics
You will need to make some decisions about how to organize your articles. Articles will be organized into one Class and multiple Topics. They will use Custom Fields to store their article data. These Custom Fields can be configured on a Class by Class basis. Classes can be made available globally or on a per-Queue basis.
Organization
Classes
Classes are equivalent to RT's queues. They can be created by going to Admin -> Articles -> Classes -> New Class. Articles are assigned to one Class. When you create Custom Fields for use with Articles, they will be applied Globally or to a Class, like Custom Fields are applied to a Queue in RT.
A common use for Articles is to store frequently used replies for requestors, like troubleshooting steps or how to sign up for a new account. When you insert Article text, you may or may not want to include the Article name and summary, in addition to the content, when inserting the Article in a reply. You can control this behavior on the Class configuration page.
Classes need to be Applied, just like a Custom Field, by using the Applies To link on the Modify Class page (Admin -> Articles -> Classes, select the class to modify). You can apply them globally or on a queue-by-queue basis.
Topics
You can also use Topics to organize your Articles. While editing a Class, there is a Topics tab for Class-specific Topics. You can create global Topics from the Global tab under Admin.
When editing Topics, type the name (and optionally description) of the Topic, and then click the button at the appropriate location in the Topic hierarchy. This should allow you to build a tree of Topics. This tree of Topics should show up when creating or modifying articles in the class. These can be arbitrarily nested.
Global Topics will be available for all Articles, regardless of their Class. Articles can belong to both global and Class-specific Topics.
Article topics can be set from the Modify screen for the article -- simply select as many topics as you desire from the list at the bottom of the screen.
Custom Fields
Articles don't have a single "body" section for each article. Everything is a custom field (except for name, summary and some other basic metadata). So to put information on an Article, you need to create some custom fields to hold the Article body and other data. When you create these new Custom Fields, set the Applies To field to Articles.
Once you've created your Custom Fields, go into your Classes, click on Custom Fields, and add the Custom Fields you want to each Class. Alternatively, use the Applies To link from each Custom Field.
Creating Articles
You can create an Article from scratch by going to Tools -> Articles -> New Article and then picking which Class to create the Article under. You must have a Class to assign the new Article to. The Summary, Description and Custom Fields will all be searchable when including an Article and you can control what Custom Fields end up in your Ticket from the Class configuration page.
Extracting an Article
You can extract the body of a ticket into an article. Within RT, you should now see an "Extract to article" button in the upper right hand corner of RT's UI when working with tickets. When you click that button, RT will ask you which Class to create your new Article in. Once you click on a Class name, the Ticket's transactions will be displayed, along with a set of select boxes. For each transaction, you can pick which Custom Field that transaction should be extracted to. From there on in, it's just regular Article creation.
Including an Article
When replying to or commenting on tickets or creating tickets, there is a UI widget that lets you search for and include Articles in your reply. (They're editable, of course).
The Include Article dropdown contains articles from any classes that are applied to the queue the ticket is in. When the list of articles exceeds the configured "DropdownMenuLimit" in RT_Config, it automatically turns into a search box which allows you to type an article name. The search box will help you by auto-completing to matching articles as you type.
Disabling Escaped HTML
By default, when an article is inserted into the ticket message box, as a security measure, HTML tags are escaped and only text is displayed. For example, RT will display "Me You Greeting Hello world!" from the following XML:
<?xml version="1.0" encoding="UTF-8"?>
<note>
<to>Me</to>
<from>You</from>
<heading>Greeting</heading>
<body>Hello world!</body>
</note>In cases as above, where the content is harmless and displaying it on the ticket might be necessary, there is an option to disable escaping these tags per article class. This can be done by unchecking the "Escape HTML" box on the Modify Class page. Please note this is potentially unsafe and its use should be limited to trusted administrators.
Disabling Ticket Linking
When an article is included in a ticket's comment or reply, the article is automatically added as a link to the ticket. This means that the article will be listed under the Links portlet on ticket display page, and also on the article display page. If you use an article many times, it can result in a very long list of links on the article page.
To avoid this, you can disable automatic linking globally (via "LinkArticlesOnInclude" in RT_Config) or by class. To disable it on the class level, uncheck the "Link article to ticket" option under "When inserting articles in this class into emails" on class modify page. Note that disabling this feature will only affect future comments/replies on tickets. Existing links to articles will remain linked.
Queue-Specific List of Articles
You can use Topics to organize a set of Queue-specific Articles. Simply create a global Topic called 'Queues' and then create Topics under Queues named after each of your Queues. Within each Queue-named Topic, create some Topics and then assign Articles to those sub-topics. This creates a hierarchy like this:
Queues \-> General \-> Topic 1 \-> Topic 2
If you are replying to a Ticket in the General Queue you will be offered a choice of Topic 1 and Topic 2 along with the searching. After choosing Topic 1 or Topic 2, you will be given a list of relevant articles to choose.
You can also organize articles into separate classes and selectively apply classes to the queues they should be used for.
SelfService Interface
If you want unprivileged users to be able to search for articles using the self-service interface, first grant them rights on the classes and articles they should see. Then set $SelfServiceShowArticleSearch to 1 to enable an article search box at the top of the page in self service.
Process Articles
Some work managed on tickets in RT will have a defined process or set of steps to take when handling the ticket. Articles are a convenient place to capture this process and you can then display these steps right on the ticket to make it easy for users to follow.
A queue typically can accept multiple types of tickets, and each of these might have a different process. For example, you might have a queue called "Product Backlog" that tracks work on some software. This queue could receive tickets from multiple sources, some new feature requests and some bug reports.
You might have a different process to handle these two types of tickets. To start, you might categorize these using a custom field on the queue called "Ticket Type". Working from this custom field, RT provides a way to display a different article for each of the options you add for these types.
For example, if the type is set to "Feature Request", the article "Feature Request Process" would be displayed for the ticket. If the type is changed to "Bug Report", the article "Bug Report Process" would be displayed. The next section describes how to configure RT to show these process articles.
Configuring Process Articles
To enable process articles on a queue, first you need to decide which field on that queue to use to drive which article is shown. Create a new custom field with ticket types or categories if you don't already have one.
Next create a new class to contain your process articles. Putting them in their own class allows you to manage them separate from other FAQ type articles you might have for email replies.
Once you have these two created, set %ProcessArticleFields with the custom field, and class to use for your queue.
In the class you created, you can now create a new article for each entry in your custom field. Once you have them created, you will configure the mapping from custom field value to article name using the configuration %ProcessArticleMapping.
Article content can then be updated at any time by modifying the source article. If you add a new option to your custom field, update the configuration to map it to a new article with the corresponding process details.
Configuration Options
ArticleOnTicketCreate
Set this to a true value to display the Article include interface on the Ticket Create page in addition to the Reply/Comment page (Create.html in addition to Update.html).
HideArticleSearchOnReplyCreate
On Ticket Reply (and Create if you set the above config var) RT's Article system normally displays a search box and an include box (for inputting an article id) and configurable dropdowns of Articles. These can be configured using Global Topics or on the Class page.
If you set this to a true value, RT will only display dropdowns and hide the search boxes.
← Back to index