[Summary view] [Print] [Text view]

   1  <?xml version='1.0' encoding='utf-8' ?>
   2  <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   3  <!ENTITY % BOOK_ENTITIES SYSTEM "Admin_Guide.ent">
   4  %BOOK_ENTITIES;
   5  ]>
   6  <chapter id="admin.user">
   7      <title>User Management</title>
   8  
   9      <section id="admin.user.create">
  10          <title>Creating User Accounts</title>
  11  
  12          <para>In MantisBT, there is no limit on the number of user
  13      accounts that can be created.  Typically, installations with thousands
  14      of users tend to have a limited number of users that have access level
  15      above REPORTER.</para>
  16  
  17      <para>By default users with ADMINISTRATOR access level have access to create
  18      new user accounts.  The steps to do that are:
  19  
  20              <itemizedlist>
  21              <listitem>
  22                  <para>Click "Manage" on Main Menu.</para>
  23                  </listitem>
  24                  <listitem>
  25                      <para>Click "Manage Users" (if not selected by default).</para>
  26                  </listitem>
  27                  <listitem>
  28                      <para>Click "Create New Account" button just below the alphabet
  29          key.</para>
  30                  </listitem>
  31                  <listitem>
  32                      <para>Enter user name, email address, global access level (more details about
  33          access levels later).  Other fields are optional.</para>
  34                  </listitem>
  35                  <listitem>
  36                      <para>Click "Create Users".</para>
  37                  </listitem>
  38              </itemizedlist>
  39      </para>
  40  
  41          <para>Creating a user triggers the following actions:
  42      <itemizedlist>
  43          <listitem>
  44              <para>Creating a user in the database.</para>
  45          </listitem>
  46          <listitem>
  47              <para>If email notifications ($g_enable_email_notification) is
  48          set to ON, then the user will receive an email allowing them to
  49          activate their account and set their password.  Otherwise, the
  50          account will be created with a blank password.</para>
  51          </listitem>
  52          <listitem>
  53              <para>If email notifications ($g_enable_email_notification) is
  54          set to ON, users with access level about
  55          $g_notify_new_user_created_threshold_min will get a
  56          notification that a user account has been created.  Information
  57          about the user like user name and email address are provided.
  58          The IP of the user that created the account is also
  59          included.</para>
  60          </listitem>
  61      </itemizedlist></para>
  62  
  63      <para>When the 'Protected' flag is set on a user account, it indicates
  64      that the account is a shared account (e.g. demo account) and hence users
  65      logged using such account will not be allowed to change account
  66      preferences and profile information.</para>
  67  
  68      <para>The anonymous user account specified with the $g_anonymous_account
  69      option will always be treated as a protected user account. When you are
  70      creating the anonymous user account, the 'Protected' flag is essentially
  71      ignored because the anonymous user is always treated as a protected
  72      user.</para>
  73  
  74      </section>
  75  
  76      <section id="admin.user.enable">
  77          <title>Enabling/Disabling User Accounts</title>
  78  
  79      <para>The recommended way of retiring user accounts is to disable them.
  80      Scenarios where this is useful is when a person leaves the team and it
  81      is necessary to retire their account.</para>
  82  
  83      <para>Once an account is disabled the following will be enforced:
  84      <itemizedlist>
  85         <listitem>
  86             <para>All currently active sessions for the account will be
  87             invalidated (i.e. automatically logged out).</para>
  88         </listitem>
  89         <listitem>
  90             <para>It will no longer be possible login using this account.</para>
  91         </listitem>
  92         <listitem>
  93             <para>No further email notifications will be sent to the account
  94             once it is disabled.</para>
  95         </listitem>
  96         <listitem>
  97             <para>The user account will not show anymore in lists like
  98             "assign to", "send reminder to", etc.</para>
  99         </listitem>
 100          </itemizedlist></para>
 101  
 102      <para>The disabling process is totally reversible.  Hence, the account
 103      can be re-enabled and all the account history will remain intact.  For
 104      example, the user will still have issues reported by them, assigned to
 105      them, monitored by them, etc.</para>
 106      </section>
 107  
 108      <section id="admin.user.delete">
 109          <title>Deleting User Accounts</title>
 110  
 111      <para>Another way to retire user accounts is by deleting them.  This
 112      approach is only recommended for accounts that have not been active
 113      (i.e. haven't reported issues).  Once the account is deleted, any
 114      issues or actions associated with such account, will be associated with
 115      user123 (where 123 is the code of the account that was deleted).  Note
 116      that associated issues or actions are not deleted.</para>
 117  
 118      <para>As far as the underlying database, after the deletion of a user,
 119      records with the user id as a foreign key will have a value that no
 120      longer exists in the users table.  Hence, any tools that operate
 121      directly on the database must take this into consideration.</para>
 122  
 123      <para>By default administrators are the only users who can delete user
 124      accounts.  They can delete accounts by clicking Manage, Manage Users,
 125      locating the user to be deleted and opening it details page, then
 126      clicking on the "Delete User" button which deletes the user.</para>
 127  
 128      <para>Note that "Deleting Users" is not a reversible process.  Hence, if
 129      it is required to re-add the user account, it is not possible to
 130      recreate the user account so that it gets the same ID and hence retains
 131      its history.  However, manually creating a record in the users table
 132      with the same id, can possibly do that.  However, this approach is not
 133      recommended or supported.</para>
 134      </section>
 135  
 136      <section id="admin.user.signup">
 137          <title>User Signup</title>
 138  
 139      <para>For open source and freeware projects, it is very common to setup
 140      MantisBT so that users can signup for an account and get a REPORTER
 141      access by default (configurable by the
 142      $g_default_new_account_access_level configuration option).  The signup
 143      process can be enabled / disabled using the $g_allow_signup
 144      configuration option, which is enabled by default.</para>
 145  
 146          <para>If email notifications ($g_enable_email_notification) is
 147          set to ON, users with access level about
 148      $g_notify_new_user_created_threshold_min will get a
 149      notification that a user account has been created.  Information
 150      about the user like user name, email address, IP address are included in
 151      the email notification.</para>
 152      </section>
 153  
 154      <section id="admin.user.passwordreset">
 155          <title>Forgot Password and Reset Password</title>
 156  
 157      <para>It is pretty common for users to forget their password.  MantisBT
 158      provides two ways to handle such scenario: "Forgot Password" and "Reset
 159      Password".</para>
 160  
 161      <para>"Forgot Password" is a self service scenario where users go to the
 162      login page, figure out they don't remember their password, and then click
 163      the "Lost your password?" link.  Users are then asked for their user
 164      name and email address.  If correct, then they are sent an email with a
 165      link which allows them to login to MantisBT and change their password.</para>
 166  
 167      <para>"Reset Password" scenario is where a user reports to the
 168      administrator that they are not able to login into MantisBT anymore.
 169      This can be due to forgetting their password and possibly user name or
 170      email address that they used when signing up.  The administrator then
 171      goes to Manage, Manage Users, locates the user account and opens its
 172      details.  Under the user account details, there is a "Reset Password"
 173      button which the administrator can click to reset the password and
 174      trigger an email to the user to allow them to get into MantisBT and set
 175      their password.  In the case where email notifications are disabled,
 176      resetting password will set the password to an empty string.</para>
 177      </section>
 178  
 179      <section id="admin.user.passwordchange">
 180          <title>Changing Password</title>
 181  
 182      <para>Users are able to change their own passwords (unless their account
 183      is "protected").  This can be done by clicking on "My Account", and then
 184      typing the new password in the "Password" and "Confirm Password" fields,
 185      then clicking "Update User".  Changing the password automatically
 186      invalidates all logged in sessions and hence the user will be required
 187      to re-login.  Invalidating existing sessions is very useful in the case
 188      where a user going onto a computer, logs into MantisBT and leaves the
 189      computer without logging out.  By changing the password from another
 190      computer, the session on the original computer automatically becomes
 191      invalidated.</para>
 192      </section>
 193  
 194      <section id="admin.user.pruning">
 195          <title>Pruning User Accounts</title>
 196  
 197      <para>The pruning function allows deleting of user accounts for accounts
 198      that have been created more than a week ago, and they never logged in.
 199      This is particularly useful for users who signed up with an invalid email
 200      or with a typo in their email address address.</para>
 201  
 202      <para>The account pruning can be done by administrators by going to
 203      "Manage", "Manage Users", and clicking the "Prune Accounts" button
 204      inside the "Never Logged In" box.</para>
 205      </section>
 206  
 207      <section id="admin.user.access">
 208          <title>Authorization and Access Levels</title>
 209  
 210      <para>MantisBT uses access levels to define what a user can do.  Each
 211      user account has a global or default access level that is associated
 212      with it.  This access level is used as the access level for such users
 213      for all actions associated with public projects as well as actions that
 214      are not related to a specific project.  Users with global access level
 215      less than $g_private_project_threshold will not have access to private
 216      projects by default.</para>
 217  
 218      <para>The default access levels shipped with MantisBT out of the box are
 219      VIEWER, REPORTER, UPDATER, DEVELOPER, MANAGER and ADMINISTRATOR.  Each
 220      features has several configuration options associated with it and
 221      identifies the required access level to do certain actions.  For
 222      example, viewing an issue, reporting an issue, updating an issue, adding
 223      a note, etc.</para>
 224  
 225      <para>For example, in the case of reporting issues, the required access
 226      level is configurable using the $g_report_bug_threshold configuration
 227      option (which is defaulted to REPORTER).  So for a user to be able to
 228      report an issue against a public project, the user must have a
 229      project-specific or a global access level that is greater than or equal
 230      to REPORTER.  However, in the case of reporting an issue against a
 231      private project, the user must have project specific access level (that
 232      is explicitly granted against the project) that is higher than REPORTER
 233      or have a global access level that is higher than both
 234      $g_private_project_threshold and $g_report_bug_threshold.</para>
 235  
 236      <para>Note that project specific access levels override the global
 237      access levels.  For example, a user may have REPORTER as the global
 238      access level, but have a MANAGER access level to a specific project.  Or
 239      a user may have MANAGER as the global access level by VIEWER access to
 240      a specific project.  Access levels can be overridden for both public and
 241      private projects.  However, overriding access level is not allowed for
 242      users with global access ADMINISTRATOR.</para>
 243  
 244      <para>Each feature typically has multiple access control configuration
 245      options to defines what access level can do certain operations.  For
 246      example, adding a note may require REPORTER access level, updating a
 247      note my require DEVELOPER access level, unless the own was owned by the
 248      same user and in this case REPORTER access level.  Such threshold
 249      configuration options can be set to a single access level, which means
 250      users with such threshold and above are authorized to do such action.
 251      The other option is to specify an array of access level which indicates
 252      that users with the explicitly specific thresholds are allowed to do
 253      such actions.</para>
 254  
 255          <para>It is also worth mentioning that the access levels are defined by
 256      the $g_access_levels_enum_string configuration option, and it is
 257      possible to customize such list.  The default value for the available
 258      access levels is '10:viewer, 25:reporter, 40:updater, 55:developer,
 259      70:manager, 90:administrator'.  The instructions about how to customize
 260      the list of access levels will be covered in the customization section.</para>
 261      </section>
 262  
 263      <section id="admin.user.autocreate">
 264          <title>Auto Creation of Accounts on Login</title>
 265  
 266      <para>In some cases MantisBT is setup in a way, where it allows users
 267      that already exists in a directory or another application to be
 268      automatically authenticated and added to MantisBT.  For example, a
 269      company may setup their MantisBT installation in a way, where its staff
 270      members that are already registered in their LDAP directory, should be
 271      allowed to login into MantisBT with the same user name and password.
 272      Another example, is where MantisBT is integrated into some content
 273      management system, where it is desired to have a single registration and
 274      single sign-on experience.  In such scenarios, once a user logs in for
 275      the first time, a user account is automatically created for them,
 276      although the password verification is still done against LDAP or the
 277      main users repository.</para>
 278      </section>
 279  
 280      <section id="admin.user.prefs">
 281          <title>User Preferences</title>
 282  
 283      <para>Users can fine tune they way MantisBT interacts with them via
 284      modifying their user preferences.  User preferences can only be managed
 285      by users and are not available for the administrators to tweak.  The
 286      administrators can only tweak the default value for such preferences.
 287      However, once a user account is created, it is then the responsibility
 288      of the user to manage their own preferences.  The user preferences
 289      include the following:
 290  
 291      <itemizedlist>
 292          <listitem>
 293              <para>Default Project: A user can choose the default project
 294          that is selected when the user first logs in.  This can be a
 295          specific project or "All Projects".  For users that only work on
 296          one project, it would make sense to set such project as the
 297          default project (rather than "All Projects").  The active
 298          project is part of the filter applied on the issues listed in
 299          the "View Issues" page.  Also any newly reported issues will be
 300          associated with the active project.</para>
 301               </listitem>
 302           <listitem>
 303              <para>Refresh Delay: The refresh delay is used to specify the
 304          number of seconds between auto-refreshes of the View Issues
 305          page.</para>
 306           </listitem>
 307           <listitem>
 308              <para>Redirect Delay: The redirect delay is the number of
 309          seconds to wait after displaying flash messages like "Issue created
 310          successfully", and before the user gets redirected to the
 311          next page.</para>
 312           </listitem>
 313           <listitem>
 314              <para>Notes Sort Order: The preference relating to how notes
 315          should be ordered on an issue is viewed or in email
 316          notifications.  The ascending order is where notes are ordered
 317          so that ordered notes appear before newer notes, the descending
 318          order is the reverse.</para>
 319           </listitem>
 320           <listitem>
 321              <para>Email on New: If unticked, then email notifications
 322          relating to creation of a new issue would be disabled.  Note
 323          that the preference is only used to disabled notifications that
 324          as per the administrator's configuration, this user would have
 325          qualified to receive them.</para>
 326           </listitem>
 327           <listitem>
 328              <para>Email on Change of Handler: TODO - is this preference
 329          used?</para>
 330           </listitem>
 331           <listitem>
 332              <para>Email on Feedback: TODO - is this preference used?</para>
 333           </listitem>
 334           <listitem>
 335              <para>Email on Resolved: TODO</para>
 336           </listitem>
 337           <listitem>
 338              <para>Email on Closed: TODO</para>
 339           </listitem>
 340           <listitem>
 341              <para>Email on Reopened: TODO</para>
 342           </listitem>
 343           <listitem>
 344              <para>Email on Note Added: TODO</para>
 345           </listitem>
 346           <listitem>
 347              <para>Email on Status Change: TODO</para>
 348           </listitem>
 349           <listitem>
 350              <para>Email on Priority Change: TODO - is this preference used?</para>
 351           </listitem>
 352           <listitem>
 353              <para>Email Notes Limit: This preference can be used to limit
 354          the number of issue notes to view or to be included in an email
 355          notifications.  Specifying N here means that the latest N
 356          notes will be included.  The value 0 causes all notes to be
 357          included.</para>
 358           </listitem>
 359           <listitem>
 360              <para>Language: The preferred language of the user.  This
 361          language is used by the GUI and in email notifications.  Note
 362          that MantisBT uses UTF8 for encoding the data, and hence, the
 363          user can be interacting with MantisBT user interface in Chinese
 364          while logging issue data in German.</para>
 365           </listitem>
 366           </itemizedlist>
 367       </para>
 368      </section>
 369  
 370      <section id="admin.user.profiles">
 371          <title>User Profiles</title>
 372  
 373      <para>A user profile describes an environment that the user uses to run
 374      the software for which issues are being tracked.  The profile
 375      information include "Platform", "Operating System", "OS Version", and
 376      "Additional Description".  Each user has access to profiles that they
 377      create (can be multiple), in addition to global ones that are shared
 378      created by other users.  When reporting issues, users can elect to enter
 379      information like platform, operating system, version manually, or they
 380      can choose from the list of profiles that are already defined.</para>
 381  
 382      <para>Global profiles are typically used by the administrator to define
 383      a set of standard profiles that are typically used by the MantisBT
 384      users.  This makes it easier for the users to use such profiles without
 385      having to define create them.  The access level required for users to be
 386      able to create global profiles is configured by the $g_manage_global_profile_threshold
 387      configuration option and it is defaulted to MANAGER.</para>
 388      </section>
 389  </chapter>