locale/en_US/manual-xml/admin.xml

   1 <chapter id="admin" revision="$Revision$">
   2         <title>The Administration Panel</title>
   3
   4         <!-- =================================================================== -->
   5
   6         <section id="admin.about">
   7                 <title>About the Administration Panel</title>
   8                 <para>Once you have logged into your user account, you will see an "Administration" tab in the top navigation bar. Click this to be presented with the login screen. Here, login again for an added layer of security.</para>
   9
  10                 <para>In the administration panel, there are numerous options and features that can be accessed through the <link linkend="admin.menu">main menu</link>.</para>
  11
  12                 <para>If you would like more information about a feature, most sections have a small <strong>Help</strong> link in the upper-right corner. You can click this or the section's title to bring up the documentation page for the specific section.</para>
  13         </section>
  14
  15         <!-- =================================================================== -->
  16
  17         <section id="admin.menu">
  18                 <title>The Main Menu</title>
  19                 <para>The primary page of the administration screen is the main menu:</para>
  20
  21                 <mediaobject>
  22                         <imageobject>
  23                                 <imagedata fileref="images/admin_index/main_menu.png" format="PNG" align="center" />
  24                         </imageobject>
  25                 </mediaobject>
  26
  27                 <para>In this menu there is a listing of all the various mutable aspects of your &product; installation. In this manual, we will explain each item in the main menu in the order that they appear.</para>
  28
  29                 <para>We should also note that any option available in the main menu is also in the navigation menu (the pull down bar in the upper-left corner of the window):</para>
  30
  31                 <mediaobject>
  32                         <imageobject>
  33                                 <imagedata fileref="images/admin_index/navigation_menu.png" format="PNG" align="center" />
  34                         </imageobject>
  35                 </mediaobject>
  36
  37                 <para>The <em>Administration Location</em> section of the navigation is simple: the <em>Home</em> link returns you to the main menu and the <em>Logout</em> link logs you out of the administration panel.</para>
  38
  39                 <note>The logout link in the administration panel will not log you out of the entire &product; system--just the administration panel. However, the opposite is true of the logout link in the non-administration interface: if you log out there, you will also be logged out of the administration panel.</note>
  40         </section>
  41
  42         <!-- =================================================================== -->
  43
  44         <section id="admin.settings">
  45                 <title>&product; Settings</title>
  46                 <para>&product;'s main options are broken up into three different sections: <em>General Options</em>, <em>Bug Reporting Options</em>, and <em>Pagination Options</em>. For the most part, you will only have to alter the general settings. In the following three pages, we will explain the key options of each page.</para>
  47
  48                 <!-- ################################################################### -->
  49
  50                 <section id="admin.settings.general">
  51                         <title>General Options</title>
  52                         <para>Most of the general settings are explained by their descriptions, however a few of the options are explicated here.</para>
  53
  54                         <variablelist>
  55                                 <varlistentry>
  56                                         <term>Tracker Title</term>
  57                                         <listitem>This is the name of the entire bug tracking system. The value of this setting will appear at the top of the bug tracker and in most emails sent out to users.</listitem>
  58                                 </varlistentry>
  59                                 <varlistentry>
  60                                         <term>Tracker Base URL</term>
  61                                         <listitem>Set this to the root URL of your tracker--the initial location of the tracker in your web browser. Make sure that there is no trailing slash ("/") at the end of the URL as it could possibly break links that the URL is used in.</listitem>
  62                                 </varlistentry>
  63                                 <varlistentry>
  64                                         <term>Date Format</term>
  65                                         <listitem>For most users, this option will not need to change as the default is perfectly fine. However, if you wish to change the way in which dates appear in your bug tracker, you will need to use PHP's date formatting characters. Follow the table <link xlink:href="http://www.php.net/date">here</link> for the formatting characters.</listitem>
  66                                 </varlistentry>
  67                         </variablelist>
  68                 </section>
  69
  70                 <!-- ################################################################### -->
  71
  72                 <section id="admin.settings.reporting">
  73                         <title>Bug Reporting Options</title>
  74                         <variablelist>
  75                                 <varlistentry>
  76                                         <term>Allow HTML in Bug Reports</term>
  77                                         <listitem>This is an option that should be set to <em>No</em> unless there is good reason to change it. By allowing HTML in bug reports, users would be able to post malicious code that could break the display of the tracker and exploit the system via JavaScript. Only enable this option if you are confident in the users of the system, generally only in private bug trackers.</listitem>
  78                                 </varlistentry>
  79                         </variablelist>
  80
  81                         <para>The rest of the options in <em>Bug Reporting Options</em> are defaults. What that means is that in the new report screen, these values will be entered in by default. If a user has permissions to change the field, he or she can; however, if the user does not, this value will be inserted.</para>
  82                 </section>
  83
  84                 <!-- ################################################################### -->
  85
  86                 <section id="admin.settings.pagination">
  87                         <title>Pagination Options</title>
  88                         <para>The pagination options are advanced features. If you are a novice user and do not have to worry about server load with &product;, these settings do not need changing. These settings control the number of bugs that appear in a listing and how many page navigation links are displayed.</para>
  89
  90                         <variablelist>
  91                                 <varlistentry>
  92                                         <term>Default Per-Page Amount</term>
  93                                         <listitem>The default number of items to be displayed on a single page.</listitem>
  94                                 </varlistentry>
  95                                 <varlistentry>
  96                                         <term>Maximum Per-Page Value</term>
  97                                         <listitem>If a user manually enters a per-page amount, it cannot exceed this value; if it does, the system will use this value instead. If server load is a concern for your system, this setting may need to be lowered.</listitem>
  98                                 </varlistentry>
  99                                 <varlistentry>
 100                                         <term>Number of Page Links</term>
 101                                         <listitem>This controls how many page navigator links appear on either side of the current page. Settings this to <em>0</em> will display all pages, which is highly not recommended. A setting greater than <em>5</em> is also not recommended.</listitem>
 102                                 </varlistentry>
 103                         </variablelist>
 104                 </section>
 105
 106         </section>
 107
 108         <!-- =================================================================== -->
 109
 110         <section id="admin.language">
 111                 <title>Manage Languages</title>
 112                 <para>In the <em>Manage Languages</em> section, you are presented with the language manager:</para>
 113
 114                 <mediaobject>
 115                         <imageobject>
 116                                 <imagedata fileref="images/language_manage/language_manager.png" format="PNG" align="center" />
 117                         </imageobject>
 118                 </mediaobject>
 119
 120                 <para>In &product;, the actual English text is embedded in templates and files. When a new language is added, this English text is looked up against a table of the language's translated text; if there's an entry for a given phrase (called a <em>string</em>), it displays that instead.</para>
 121
 122                 <para>What this means is that the default language ("English (US)") doesn't need to exist. However, we have left it in place because if an administrator wants to change a string, all he or she has to do is edit a translation and then reload the XML file. All of this will be explained later in the manual.</para>
 123
 124                 <para>The language manager has an important link next to each language: <strong>[Reload XML]</strong>. When a language is reloaded, the cache of strings is flushed and recreated from the XML file. This needs to be done if changes made to a language XML file are to be displayed. You will learn about this in the next section.</para>
 125
 126                 <!-- ################################################################### -->
 127
 128                 <section id="admin.language.edit">
 129                         <title>Adding or Editing a Language</title>
 130                         When you add or edit a language, you are presented with this screen:
 131
 132                         <mediaobject>
 133                                 <imageobject>
 134                                         <imagedata fileref="images/language_edit/edit_language.png" format="PNG" align="center" />
 135                                 </imageobject>
 136                         </mediaobject>
 137
 138                         <variablelist>
 139                                 <varlistentry>
 140                                         <term>Title</term>
 141                                         <listitem>The name of the language that is to be displayed to users (if they can select it) and in the administration panel.</listitem>
 142                                 </varlistentry>
 143                                 <varlistentry>
 144                                         <term>Character Set</term>
 145                                         <listitem>This character set often determines what symbols can be displayed on a page. English can be <code>iso-8859-1</code> or <code>utf-8</code>, either value will work. By default, however, we have set it to be <code>utf-8</code> because it will display most characters. If you are unsure, use <code>utf-8</code>.</listitem>
 146                                 </varlistentry>
 147                                 <varlistentry>
 148                                         <term>Direction</term>
 149                                         <listitem>This determines the direction of the text on a page. For instance, English is read left-to-right, while Arabic is read right-to-left.</listitem>
 150                                 </varlistentry>
 151                                 <varlistentry>
 152                                         <term>Path to XML</term>
 153                                         <listitem>
 154                                                 <para>This is the most important setting as it is the path to the translated strings. The default strings file is in <filename>./includes/strings/english-us.strings.xml</filename>. We recommend placing additional string files in the <filename>includes/strings/</filename> folder for continuity.</para>
 155
 156                                                 <para>Strings are stored in this XML file, however, they can be cached in the database (see the <em>Debug Mode</em> setting here) to increase speed. If you make changes to the XML file and you do not have debug mode enabled, you will need to reload the language. You can reload the language by clicking <strong>[Reload Language]</strong> in the <link linkend="admin.language">language manager</link>.</para>
 157                                         </listitem>
 158                                 </varlistentry>
 159                                 <varlistentry>
 160                                         <term>User Selectable</term>
 161                                         <listitem>If this enabled, users will be able to select this language in their options. If it is not, then it will be a private language and only viewable in the administration panel.</listitem>
 162                                 </varlistentry>
 163                                 <varlistentry>
 164                                         <term>Debug Mode</term>
 165                                         <listitem>Debug mode is a special setting that allows strings to be read directly from the XML file on every page load. This is very useful for translators as they can see their results without having to reload the XML every time. If this setting is disabled, which it should be in a production environment, then the strings will be cached from the XML file in the database. This cache will need to be rebuilt (by clicking <strong>[Reload Language]</strong> in the  <link linkend="admin.language">language manager</link>) if any changes made to the XML file are to be displayed.</listitem>
 166                                 </varlistentry>
 167                         </variablelist>
 168                 </section>
 169
 170                 <!-- ################################################################### -->
 171
 172                 <section id="admin.language.translate">
 173                         <title>Translating a Language</title>
 174                         <para>Translating strings for &product; follows the same rules as translating strings for any other ISSO-based application.</para>
 175
 176                         <para>This page will give you the information that is &product;-specific to translating. However, for the general practice of translating in ISSO, please refer to the {{GETTEXT TRANSLATION GUIDE}}.</para>
 177
 178                         <para>The "master strings file" (as it is called in the ISSO translation manual) is located at <filename>includes/strings/english-us.strings.xml</filename>. When you are translating, you will need to:</para>
 179
 180         a) Duplicate the file, if you are editing the XML strings directly, or
 181         b) Download the XML file to your computer (if you have not already) and then specify that file as the master in the translation tool.
 182
 183                         <para>For further instructions, please consult the ISSO manual.</para>
 184                 </section>
 185
 186                 <!-- ################################################################### -->
 187
 188                 <section id="admin.language.upgrade">
 189                         <title>Languages and Upgrades</title>
 190                         <para>When a new version of &product; is released, you will need to merge the <filename>po/en_US.pot</filename> into your PO file using <application>msgmerge</application>.</para>
 191
 192                         <para>The files in the <filename>install/strings/</filename> folder are labeled by version number. If you upgraded from 1.0.0 to 1.0.1, you would look for the <filename>1-0-1.strings.xml</filename> file and then merge it into your strings file.</para>
 193
 194                         <para>If you were to upgrade to a version more than one version above, then you will need to use all the string files. For example, if you were running 1.3.2 and you wanted to upgrade to 1.3.5 (and versions 1.3.3 and 1.3.4 existed), you would need to repeat the merging process for <strong>all</strong> those string files.</para>
 195
 196                         <para>For information on how to merge--both manually and using the translation tool--see the {{GETTEXT MERGING MANUAL}}.</para>
 197                 </section>
 198
 199         </section>
 200
 201         <!-- =================================================================== -->
 202
 203         <section id="admin.userhelp">
 204                 <title>Edit User Help</title>
 205                 <para>The user help manager allows you to edit the help text that is displayed in popups in the user's browser. Next to fields that are help-enabled, a small "?" is placed next to the name of the field; clicking this results in a small pop-up that displays help text.</para>
 206
 207                 <para>By default, &product; has default text entries for all the fields. These entries cannot be deleted (but the text can be modified) as they are standard &product; fields.</para>
 208
 209                 <para>The help text for custom fields is set through the <link linkend="admin.customfields.options">description field</link> in the custom field editor.</para>
 210
 211                 <para>You can also create your own help text entries by clicking <strong>[Add New Help Text]</strong>. You then enter a unique key that is used to identify the text, the title of the text, and then the body.</para>
 212
 213                 <para>Once you have created a custom entry, you can place the following code in any &product; template to create the help link, where "UNIQUE_KEY" is the unique key you specified:</para>
 214
 215                 <programlisting role="php">$help[UNIQUE_KEY]</programlisting>
 216         </section>
 217
 218         <!-- =================================================================== -->
 219
 220         <section id="admin.products">
 221                 <title>Products and Versions</title>
 222                 <para>&product; organizes bugs into products and versions. When a user enters a bug report, he or she is required to specify a product <strong>and</strong> a version. Therefore, you need at least one product and one version in your system to be usable.</para>
 223
 224                 <para>Components are essentially sub-products. They behave in the exact same fashion as products (in that they require a version to be selected, too) but they are like a part of the project. For instance, in a calendar application there could be components for making events, displaying the calendar, notifications and reminders, etc. These are smaller--but yet still significant--portions of the product.</para>
 225
 226                 <para>In the product manager, you see this:</para>
 227
 228                 <mediaobject>
 229                         <imageobject>
 230                                 <imagedata fileref="images/products_and_versions/product_manager.png" format="PNG" align="center" />
 231                         </imageobject>
 232                 </mediaobject>
 233
 234                 <para>This screen allows you to change the display order (the lower the value, the higher it appears in the list) and manage any components or versions. If you wish to add a component or version, simply choose the option from the pulldown on the far-right.</para>
 235
 236                 <para>In this screen, products (but not components) are bold, both components and products are underlined, and versions have no special formatting. This interface feature will help you differentiate (along with the depth marks) which is a product and which is a version.</para>
 237
 238                 <note>A product has all of its versions and then any global versions. A component will inherit the global versions, its product's versions along with the versions defined specifically for the component. This allows you to specify components without locally-defined versions; instead, they can be inherited.</note>
 239         </section>
 240
 241         <!-- =================================================================== -->
 242
 243         <section id="admin.standardfields">
 244                 <title>Priorities, Resolutions, Severities, and Statuses</title>
 245                 <para>Priorities, resolutions, severities, and statuses all follow the same pattern when adding or editing a new one and therefore they are grouped together in this document. The following is an explanation of each bug field:</para>
 246
 247                 <variablelist>
 248                         <varlistentry>
 249                                 <term>Priority</term>
 250                                 <listitem>This is the field that represents the celerity with witch developers should work with to resolve the bug.</listitem>
 251                         </varlistentry>
 252                         <varlistentry>
 253                                 <term>Resolution</term>
 254                                 <listitem>Usually this is the reason why a certain bug has been marked "closed." For instance, if a bug is not reproducible, then it would be closed and this field would probably be set to "Works for Me."</listitem>
 255                         </varlistentry>
 256                         <varlistentry>
 257                                 <term>Severity</term>
 258                                 <listitem>The user defines this field based on how critical the bug is. Be careful to not confuse this with priority. An example is if a security issue (marked "Critical" in this field) was found in an old version of the software that did not affect the new version; while the severity may be critical, because the version is old, the priority would not need to be marked "High."</listitem>
 259                         </varlistentry>
 260                         <varlistentry>
 261                                 <term>Status</term>
 262                                 <listitem>The state of the bug; this is usually set when the bug is triaged--marked as "Verified" or "Assigned" and then again when it is "Closed." It is usually changed to mark a major shift in the bug's occurrence in a product and version.</listitem>
 263                         </varlistentry>
 264                 </variablelist>
 265
 266                 <para>All of these fields have a title, which is the value of the field; for instance "Normal" is the title of a default priority. Each field also has a display order; this value can be used to control the appearance of a given value in the selection list. If you want to change the default value for new bug reports, see <link linkend="admin.settings.reporting">here</link>.</para>
 267
 268                 <note>The status field also has a colour field associated with it. By filling this value in with a HEX code (be sure to include the <code>#</code> when you specify the value), the background colour of the bug rows in lists will fill to this colour according to bug status (this is a user option). For instance, any unconfirmed bugs will be highlighted in red when viewing the bug list.</note>
 269         </section>
 270
 271         <!-- =================================================================== -->
 272
 273         <section id="admin.customfields">
 274                 <title>Custom Bug Fields</title>
 275                 <para>&product; offers many fields to help you track and triage bugs. However, sometimes additional fields are needed for your specific setup. The additional bug fields feature allows you to create those extra fields and exert fine control over the fields.</para>
 276
 277                 <para>The manager shows you all the information regarding the field:</para>
 278
 279                 <mediaobject>
 280                         <imageobject>
 281                                 <imagedata fileref="images/custom_bug_fields/custom_field_manager.png" format="PNG" align="center" />
 282                         </imageobject>
 283                 </mediaobject>
 284
 285                 <para>There are three types of field that can be created: single-line text boxes, check boxes, and drop-down menus. When you click <strong>[Add New Bug Field]</strong>, you are presented with this screen:</para>
 286
 287                 <mediaobject>
 288                         <imageobject>
 289                                 <imagedata fileref="images/custom_bug_fields/add_new_field_type.png" format="PNG" align="center" />
 290                         </imageobject>
 291                 </mediaobject>
 292
 293                 <para>Here you select the type of field you want. After selecting the type of field you want and pressing <strong>[Submit]</strong>, you are taken to the options screen; here you specify all the various options for your field. This is discussed <link linkend="admin.customfields.options">here</link>.</para>
 294
 295                 <!-- ################################################################### -->
 296
 297                 <section id="admin.customfields.options">
 298                         <title>Custom Bug Field Options</title>
 299                         <para>All custom fields have the same standard options:</para>
 300
 301                         <mediaobject>
 302                                 <imageobject>
 303                                         <imagedata fileref="images/custom_bug_fields_options/global_options.png" format="PNG" align="center" />
 304                                 </imageobject>
 305                         </mediaobject>
 306
 307                         <variablelist>
 308                                 <varlistentry>
 309                                         <term>Field Type</term>
 310                                         <listitem>The type of field that you are creating (selected previously)</listitem>
 311                                 </varlistentry>
 312                                 <varlistentry>
 313                                         <term>Description</term>
 314                                         <listitem>Describe the field and its use; this is displayed as the help text to users.</listitem>
 315                                 </varlistentry>
 316                                 <varlistentry>
 317                                         <term>Required</term>
 318                                         <listitem>Whether or not the field is required to be specified by the user.</listitem>
 319                                 </varlistentry>
 320                                 <varlistentry>
 321                                         <term>Can Be Searched</term>
 322                                         <listitem>Whether or not the field appears on the search form.</listitem>
 323                                 </varlistentry>
 324                         </variablelist>
 325
 326                         <para>Additionally, each field has custom permissions that you can set on a per-usergroup level (these can also be set in the <link linkend="admin.usergroups">usergroup editor</link>. You can specify <em>No Permission</em>, <em>Can View</em>, or <em>Can View and Edit</em> settings:</para>
 327
 328                         <mediaobject>
 329                                 <imageobject>
 330                                         <imagedata fileref="images/custom_bug_fields_options/field_permissions.png" format="PNG" align="center" />
 331                                 </imageobject>
 332                         </mediaobject>
 333
 334                         <para>Each type of field also has a unique set of options:</para>
 335
 336                         <section id="admin.customfields.options.singleline">
 337                                 <title>Single-Line Text Field</title>
 338                                 <variablelist>
 339                                         <varlistentry>
 340                                                 <term>Default Value</term>
 341                                                 <listitem>Specify a default value for the field to be entered in new reports.</listitem>
 342                                         </varlistentry>
 343                                         <varlistentry>
 344                                                 <term>Regular Expression Match</term>
 345                                                 <listitem>You can use a regular expression to match against the field's contents and the value will be rejected if the match fails.</listitem>
 346                                         </varlistentry>
 347                                         <varlistentry>
 348                                                 <term>Maximum Length</term>
 349                                                 <listitem>If you want to limit the amount of characters (including spaces) that can be typed in the field, you can specify it here.</listitem>
 350                                         </varlistentry>
 351                                 </variablelist>
 352                         </section>
 353
 354                         <section id="admin.customfields.options.checkbox">
 355                                 <title>Checkbox Flag</title>
 356                                 <variablelist>
 357                                         <varlistentry>
 358                                                 <term>Checked By Default</term>
 359                                                 <listitem>Setting this to <em>Yes</em> will make the checkbox clicked on.</listitem>
 360                                         </varlistentry>
 361                                 </variablelist>
 362                         </section>
 363
 364                         <section id="admin.customfields.options.dropdown">
 365                                 <title>Drop-Down Menu</title>
 366                                 <variablelist>
 367                                         <varlistentry>
 368                                                 <term>Selection Values</term>
 369                                                 <listitem>A list of values to display in the menu, separated by a new line. If you remove a value that has been set by some bugs, it will still display in the non-edit mode of the bug display.</listitem>
 370                                         </varlistentry>
 371                                         <varlistentry>
 372                                                 <term>Make the First Option Default</term>
 373                                                 <listitem>If you want to make the first option in the selection values list (above) be selected by default, change this to <em>Yes</em>. Otherwise, the menu will have a blank option selected by default.</listitem>
 374                                         </varlistentry>
 375                                 </variablelist>
 376                         </section>
 377
 378                 </section>
 379
 380         </section>
 381
 382         <!-- =================================================================== -->
 383
 384         <section id="admin.automations">
 385                 <title>Automations</title>
 386                 <para>Often, the same task is performed repeatedly, such as marking a bug "closed and fixed," or "not reproducible," or "please provide more information." These common responses often involve changing multiple fields (status, resolution, etc.) and then leaving a standard comment. Automatic actions make this process significantly easier as you simply define a "macro" of sorts that sets all of the fields and enters the comment automatically. You use these "macros" when viewing a bug. You select one of the automatic actions from a list and when you commit the changes to the bug, the changes specified in the automatic action will be applied.</para>
 387
 388                 <para>The three required fields are:</para>
 389
 390                 <variablelist>
 391                         <varlistentry>
 392                                 <term>Name</term>
 393                                 <listitem>The name of the automatic action. This is displayed on the bug display and users select an action by this name.</listitem>
 394                         </varlistentry>
 395                         <varlistentry>
 396                                 <term>Description</term>
 397                                 <listitem>Remarks about what the action does.</listitem>
 398                         </varlistentry>
 399                         <varlistentry>
 400                                 <term>Add Comment</term>
 401                                 <listitem>The comment to add to the bug when the action is run. If the user has specified a comment and runs the automatic action at the same time, the automatic comment will be appended to the user's.</listitem>
 402                         </varlistentry>
 403                 </variablelist>
 404
 405                 <para>Below this is a list of fields and you can specify a value for each. When the automatic action is run, these will set the bug's field accordingly. If a field is left blank here, then it will have no effect on the bug. If the user specifies a value for one of the fields and runs an automatic action at the same time, the automatic action will take precedence and override the user.</para>
 406
 407                 <note>If the user is in a usergroup that does not have permission to change one of the fields that is specified in the automatic action, the field will change despite this when the automatic action is run.</note>
 408         </section>
 409
 410         <!-- =================================================================== -->
 411
 412         <section id="admin.users">
 413                 <title>User Management</title>
 414                 <para>In &product;, you can control and edit the profiles of all registered users. If you want to change a user's options, simply specify a display name, email, or a user ID at this screen:</para>
 415
 416                 <mediaobject>
 417                         <imageobject>
 418                                 <imagedata fileref="images/user_manage/user_search.png" format="PNG" align="center" />
 419                         </imageobject>
 420                 </mediaobject>
 421
 422                 <para>If more than one user matches your search criteria, you will get a listing of users that match. Otherwise, you will be redirected to the edit screen:</para>
 423
 424                 <mediaobject>
 425                         <imageobject>
 426                                 <imagedata fileref="images/user_manage/user_edit.png" format="PNG" align="center" />
 427                         </imageobject>
 428                 </mediaobject>
 429
 430                 <para>Here, you can change all the options that the user can change in his or her profile.</para>
 431         </section>
 432
 433         <!-- =================================================================== -->
 434
 435         <section id="admin.usergroups">
 436                 <title>Usergroups</title>
 437                 <para>Usergroups are at the backbone of &product;'s permissions system. There are two textual options for usergroups:</para>
 438
 439                 <variablelist>
 440                         <varlistentry>
 441                                 <term>Usergroup Title</term>
 442                                 <listitem>This is the internal name of the usergroup; it is never displayed to the users, but administrators use it to place users in groups.</listitem>
 443                         </varlistentry>
 444                         <varlistentry>
 445                                 <term>Display Title</term>
 446                                 <listitem>
 447                                         <para>Under a comment poster's name, this text is placed to help distinguish regular users from developers, administrators, and guests.</para>
 448
 449                                         <para>The majority of the permissions on this page are similar to those of <link linkend="admin.usergroups.permissions">test</link> and they are explained in-depth <link linkend="admin.usergroups.permissions.reference">here</link>. Those that are not part of the usergroup permissions system are listed here.</para>
 450                                 </listitem>
 451                         </varlistentry>
 452                         <varlistentry>
 453                                 <term>Can Search Bugs</term>
 454                                 <listitem>A usergroup's ability to use the search function. If this is not enabled, then searches cannot be performed by the given usergroup.</listitem>
 455                         </varlistentry>
 456                         <varlistentry>
 457                                 <term>Can Be Assigned Bugs</term>
 458                                 <listitem>If this is set to <em>Yes</em>, all the users in this usergroup will appear in the "Assigned" field drop-down menu for bug reports.</listitem>
 459                         </varlistentry>
 460                         <varlistentry>
 461                                 <term>Can Access Control Panel</term>
 462                                 <listitem>This controls whether or not users in this usergroup can login to the <link linkend="admin.about">Admin Control Panel</link>.</listitem>
 463                         </varlistentry>
 464                         <varlistentry>
 465                                 <term>Can Administer Bug Reports</term>
 466                                 <listitem>Currently, this only controls access to the <link linkend="admin.automations">Automatic Actions</link> feature.</listitem>
 467                         </varlistentry>
 468                         <varlistentry>
 469                                 <term>Can Administer Additional Bug Fields</term>
 470                                 <listitem>If this is set to <em>Yes</em>, users in this group will be able to define and edit <link linkend="admin.customfields">custom bug fields</link>.</listitem>
 471                         </varlistentry>
 472                         <varlistentry>
 473                                 <term>Can Administer Products / Components / Versions</term>
 474                                 <listitem>Allows users to define and edit <link linkend="admin.products">products, versions, and components</link>. This privilege should be sparingly given out as users can also delete products, versions, and components and thus remove all associated bugs.</listitem>
 475                         </varlistentry>
 476                         <varlistentry>
 477                                 <term>Can Administer Users</term>
 478                                 <listitem>Controls access to the <link linkend="admin.users">user manager</link> and the ability to edit and delete users.</listitem>
 479                         </varlistentry>
 480                         <varlistentry>
 481                                 <term>Can Administer Usergroups</term>
 482                                 <listitem>Setting this to <em>Yes</em> gives the users in this group the ability to control all aspects of usergroups--including permissions. Please be careful when defining this permission.</listitem>
 483                         </varlistentry>
 484                         <varlistentry>
 485                                 <term>Can Administer Settings / Maintenance Tools</term>
 486                                 <listitem>Access to this allows control of <link linkend="admin.language">languages</link> and <link linkend="admin.settings">settings</link>.</listitem>
 487                         </varlistentry>
 488                 </variablelist>
 489
 490                 <para>Additionally, the usergroup manager has the custom field permissions system, similar to the one found on the <link linkend="admin.customfields">custom field editor page</link>, the difference being that this is by field whereas the other is by usergroup.</para>
 491
 492                 <!-- ################################################################### -->
 493
 494                 <section id="admin.usergroups.permissions">
 495                         <title>Usergroup Permissions</title>
 496                         <para>In the <link linkend="admin.usergroups">usergroups manager</link>, you can set the default permissions that apply to every product. However, sometimes you may need finer control over the permissions. Using the permissions manager, you can override the default permissions set by the usergroup.</para>
 497
 498                         <para>The default screen shows a list of all the usergroups with an <strong>[Expand]</strong> link next to them. Clicking this link will display a list of all available products underneath the usergroup:</para>
 499
 500                         <mediaobject>
 501                                 <imageobject>
 502                                         <imagedata fileref="images/usergroups_permissions/expanded.png" format="PNG" align="center" />
 503                                 </imageobject>
 504                         </mediaobject>
 505
 506                         <para>If you want to override the permissions for a certain product, simply click the <strong>[Customize]</strong> link to go to a permissions page, similar to the one in the usergroup editor. You can find an explanation of these permissions <link linkend="admin.usergroups.permissions.reference">here</link>.</para>
 507
 508                         <para>After you have customized permissions, but you find that you no longer want the customizations, simply click the <strong>[Revert]</strong> link.</para>
 509                 </section>
 510
 511                 <!-- ################################################################### -->
 512
 513                 <section id="admin.usergroups.permissions.reference">
 514                         <title>Permissions Reference</title>
 515                         <para>This is a list of the permissions that can be customized on the <link linkend="admin.usergroups.permissions">per-product level</link>. These--plus some additional permissions that are not available on the product-level can be found in the <link linkend="admin.usergroups">usergroup editor</link>.</para>
 516
 517                         <variablelist>
 518                                 <varlistentry>
 519                                         <term>Can View Bugs</term>
 520                                         <listitem>Permits the ability to view bugs of this product.</listitem>
 521                                 </varlistentry>
 522                                 <varlistentry>
 523                                         <term>Can View Hidden Bugs and Comments</term>
 524                                         <listitem>Allows viewing of bugs and comments that have been marked <em>Hidden</em>. {{NEED LINK: HIDING}}</listitem>
 525                                 </varlistentry>
 526                                 <varlistentry>
 527                                         <term>Can Subscribe to Bugs</term>
 528                                         <listitem>Controls the ability to add bugs of this product to the user's "favourite" list. {{NEED LINK: FAVOURITES}}</listitem>
 529                                 </varlistentry>
 530                                 <varlistentry>
 531                                         <term>Can Vote on Polls</term>
 532                                         <listitem>The ability to vote for a bug. Voting shows the amount of interest in a bug. {{NEED LINK: VOTING}}</listitem>
 533                                 </varlistentry>
 534                                 <varlistentry>
 535                                         <term>Can Submit Bugs</term>
 536                                         <listitem>Determines if users can submit bugs under this product.</listitem>
 537                                 </varlistentry>
 538                                 <varlistentry>
 539                                         <term>Can Post Comments</term>
 540                                         <listitem>Controls whether or not users can post comments to bugs with this product.</listitem>
 541                                 </varlistentry>
 542                                 <varlistentry>
 543                                         <term>Can View Attachments</term>
 544                                         <listitem>Ability to view attachments in bugs with this product.</listitem>
 545                                 </varlistentry>
 546                                 <varlistentry>
 547                                         <term>Can Upload/Edit Own Attachments</term>
 548                                         <listitem>Whether or not the user can edit and upload his or her own attachments to bugs with this product.</listitem>
 549                                 </varlistentry>
 550                                 <varlistentry>
 551                                         <term>Can Manage All Attachments</term>
 552                                         <listitem>Ability to edit other users' attachments.</listitem>
 553                                 </varlistentry>
 554                                 <varlistentry>
 555                                         <term>Can Edit Own Bugs</term>
 556                                         <listitem>Can edit the basic fields of bugs submitted by the user herself. The basic fields are: hidden, summary, product/component/version, severity, duplicates, and dependencies.</listitem>
 557                                 </varlistentry>
 558                                 <varlistentry>
 559                                         <term>Can Edit Others' Bugs</term>
 560                                         <listitem>The same as <em>Can Edit Own Bugs</em> except it applies to bugs that the user did not submit.</listitem>
 561                                 </varlistentry>
 562                                 <varlistentry>
 563                                         <term>Can Edit Own Comments</term>
 564                                         <listitem>Ability to edit comments submitted by the user herself to bugs with this product.</listitem>
 565                                 </varlistentry>
 566                                 <varlistentry>
 567                                         <term>Can Edit Others' Comments</term>
 568                                         <listitem>The same as <em>Can Edit Own Comments</em> but it applies to comments submitted by everybody who is not the current logged in user.</listitem>
 569                                 </varlistentry>
 570                                 <varlistentry>
 571                                         <term>Can Assign Bugs</term>
 572                                         <listitem>The ability to control the "Assigned To" field.</listitem>
 573                                 </varlistentry>
 574                                 <varlistentry>
 575                                         <term>Can Change Status</term>
 576                                         <listitem>Controls the ability to edit the status, resolution, and priority fields.</listitem>
 577                                 </varlistentry>
 578                         </variablelist>
 579                 </section>
 580
 581         </section>
 582
 583 </chapter>