Workflow.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Admin_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="admin.lifecycle">
	<title>Issue Lifecycle and Workflow</title>

<section id="admin.lifecycle.create">
	<title>Issue Creation</title>

	<para>The life cycle of an issue starts with its creation.  An issue can
	be created via one of the following channels:

	<itemizedlist>
	    <listitem><para>MantisBT Web Interface - This is where a user logs
	    into MantisBT and reports a new issue.</para></listitem>
	    <listitem><para>SOAP API - Where an application automatically
	    reports an issue into MantisBT using the SOAP API web services
	    interfaces.  For example, the nightly build script can automatically
	    report an issue if the build fails.</para></listitem>
	    <listitem><para>Email - This is not supported out of the box, but
	    there are existing MantisBT patches that would listen to emails on
	    pre-configured email addresses and adds them to the MantisBT
	    database.</para></listitem>
	    <listitem><para>Others - There can be several other ways to report
	    issues.  For example, applications / scripts that directly injects
	    issues into MantisBT database (not recommended, except for one-off
	    migration scripts), or PHP scripts that use the core MantisBT API
	    to create new issues.</para></listitem>
	</itemizedlist>
	</para>
    </section>

    <section id="admin.lifecycle.status">
        <title>Issue Statuses</title>

	<para>An important part of issue tracking is to classify issues as
	per their status.  Each team may decide to have a different set of
	categorization for the status of the issues, and hence, MantisBT
	provides the ability to customize the list of statuses.  MantisBT assumes
	that an issue can be in one of three stages: opened, resolved and
	closed.  Hence, the customized statuses list will be mapped to these
	three stages.  For example, MantisBT comes out of the box with the
	following statuses: new, feedback, acknowledged, confirmed, assigned,
	resolved and closed.  In this case "new" -> "assigned" map to opened,
	"resolved" means resolved and "closed" means closed.</para>

	<para>Following is the explanation of what the standard statuses that
	are shipped with MantisBT means.

	<itemizedlist>
	    <listitem><para>New - This is the landing status for new issues.  Issues
	    stay in this status until they are assigned, acknowledged, confirmed
	    or resolved.  The next status can be "acknowledged", "confirmed",
	    "assigned" or "resolved".</para></listitem>
	    <listitem><para>Acknowledged - This status is used by the development team
	    to reflect their agreement to the suggested feature request.  Or to
	    agree with what the reporter is suggesting in an issue report, although
	    they didn't yet attempt to reproduce what the reporter is referring
	    to.  The next status is typically "assigned" or "confirmed".</para></listitem>
	    <listitem><para>Confirmed - This status is typically used by the
	    development team to mention that they agree with what the reporter
	    is suggesting in the issue and that they have confirmed and
	    reproduced the issue.  The next status is typically
	    "assigned".</para></listitem>
	    <listitem><para>Assigned - This status is used to reflect that the issue
	    has been assigned to one of the team members and that such team
	    member is actively working on the issue.  The next status is
	    typically "resolved".</para></listitem>
	    <listitem><para>Resolved - This status is used to reflect that the issue
	    has been resolved.  An issue can be resolved with one of many
	    resolutions (customizable).  For example, an issue can be
	    resolved as "fixed", "duplicate", "won't fix", "no change required",
	    etc.  The next statuses are typically "closed" or in case of the
	    issue being re-opened, then it would be "feedback".</para></listitem>
	    <listitem><para>Closed - This status reflects that the issue is completely
	    closed and no further actions are required on it.  It also typically
	    hides the issue from the View Issues page.  Some teams use "closed"
	    to reflect sign-off by the reporter and others use it to reflect the
	    fact that the fix has been released to customers.</para></listitem>
	</itemizedlist>
	</para>
    </section>

    <section id="admin.lifecycle.workflow">
        <title>Workflow</title>

	<para>Now that we have covered how an issue gets created, and what are
	the different statuses during the life cycle of such issues, the next
	step is to define the workflow.
	The workflow dictates the valid transitions between statuses and the user
	access level required of the user who triggers such transitions;
	in other words, how issues move from one status to another and who is
	authorized to trigger such transitions.
	</para>
	<para>MantisBT provides the ability for teams to define their own custom
	workflow which works on top of their custom status
	(see <xref linkend="admin.customize.status" />).
	</para>

        <section id="admin.lifecycle.workflow.transitions">
	    <title>Workflow Transitions</title>

		<para>By default, there is no workflow defined, which means that all
			states are accessible from any other, by anyone.
		</para>

		<para>The "Manage &gt; Manage Configuration &gt; Workflow
			Transitions" page allows users with ADMINISTRATOR access level to do the
			following tasks:

			<itemizedlist>
				<listitem><para>Define the valid next statuses for each status.
				</para></listitem>
				<listitem><para>Define the default next status for each status.
				</para></listitem>
				<listitem><para>Define the minimum access level required for a
					user to transition to each status.
				</para></listitem>
				<listitem><para>Define the default status for newly created issues.
				</para></listitem>
				<listitem><para>Define the status at which the issue is
					considered resolved.  Any issues a status code greater
					than or equal to the specified status will be considered
					resolved.
				</para></listitem>
				<listitem><para>Define the status which is assigned to issues
					that are re-opened.
				</para></listitem>
				<listitem><para>Define the required access level to change the
					workflow.
				</para></listitem>
            </itemizedlist>
	    </para>

	    <para>Note that the scope of the applied change is
	    dependent on the selected project.  If "All Projects" is selected,
	    then the configuration is to be used as the default for all
			projects, unless overidden by a specific project.  To configure for
			a specific project, switch to it via the combobox at the
			top right corner of the screen.
		</para>

		<para>The Global ("All Projects") workflow can also be defined in the
			<emphasis>config_inc.php</emphasis> file, as per the following
			example.
			<programlisting>
$g_status_enum_workflow[NEW_]           ='30:acknowledged,20:feedback,40:confirmed,50:assigned,80:resolved';
$g_status_enum_workflow[FEEDBACK]       ='30:acknowledged,40:confirmed,50:assigned,80:resolved';
$g_status_enum_workflow[ACKNOWLEDGED]   ='40:confirmed,20:feedback,50:assigned,80:resolved';
$g_status_enum_workflow[CONFIRMED]      ='50:assigned,20:feedback,30:acknowledged,80:resolved';
$g_status_enum_workflow[ASSIGNED]       ='80:resolved,20:feedback,30:acknowledged,40:confirmed';
$g_status_enum_workflow[RESOLVED]       ='90:closed,20:feedback,50:assigned';
$g_status_enum_workflow[CLOSED]         ='20:feedback,50:assigned';
</programlisting>
		</para>
		<note>
			<para>The workflow needs to have a path from the
				statuses greater than or equal to the 'resolved' state
				back to the 'feedback' state (see
				<emphasis>$g_bug_resolved_status_threshold</emphasis> and
				<emphasis>$g_bug_feedback_status</emphasis> under
				<xref linkend="admin.config.status" />),
				otherwise, the re-open operation won't work.
			</para>
		</note>
		<note>
			<para>The first item in each list denotes the default
				value for this status, which will be pre-selected in the
				Change Status combobox in the View Issues page.
			</para>
		</note>
	</section>

	<section id="admin.lifecycle.workflow.thresholds">
		<title>Workflow Thresholds</title>

		<para>The "Manage &gt; Manage Configuration &gt; Workflow
			Thresholds" page allows users with ADMINISTRATOR access level to
			define the thresholds required to do certain actions.  Following is
			a list of such actions and what they mean:
		</para>

		<itemizedlist>
			<listitem><para>Report an issue - The access levels that are
				allowed to report an issue.
				</para>
			</listitem>
			<listitem><para>Update an issue - The access levels that are
				allowed to update the header information of an issue.
				</para>
			</listitem>
			<listitem><para>Allow issue to be closed on resolved - The
				access levels that are allow to resolve and close an issue in
				one step.
				</para>
			</listitem>
			<listitem><para>Allow reporter to close issue - Indicates if
				reporters should be allowed to close issues reported by them.
				</para>
			</listitem>
			<listitem><para>Monitor an issue - The access levels required
				for a user to be able to monitor an issue.  Once a user monitors
				an issue, the user will be included in all future email
				notifications relating to changes in the issue.
				</para>
			</listitem>
			<listitem><para>Handle an issue - The access levels required for
				a user to be shown in the list of users that can handle an
				issue.
				</para>
			</listitem>
			<listitem><para>Assign an issue - The access levels required for
				a user to be able to change the handler (i.e. assign / unassign)
				an issue.
				</para>
			</listitem>
			<listitem><para>Move an issue - The access levels required for a
				user to be able to move an issue from one project to another.
				(TODO: are these access levels evaluated against source or
				destination project?).
				</para>
			</listitem>
			<listitem><para>Delete an issue - The access levels required for
				a user to be able to delete an issue.
				</para>
			</listitem>
			<listitem><para>Reopen an issue - The access levels required for
				a user to be able to re-open a resolved or closed issue.
				</para>
			</listitem>
			<listitem><para>Allow Reporter to re-open Issue - Whether the
				reporter of an issue can re-open a resolved or closed issue,
				independent of their access level.
				</para>
			</listitem>
			<listitem><para>Status to which a reopened issue is set - This
				is the status to which an issue is set after it is re-opened.
				</para>
			</listitem>
			<listitem><para>Resolution to which a reopen issue is set - The
				resolution to set on issues that are reopened.
				</para>
			</listitem>
			<listitem><para>Status where an issue is considered resolved -
				The status at which an issue is considered resolved.
				</para>
			</listitem>
			<listitem><para>Status where an issue becomes readonly - Issues
				with such status and above are considered read-only.  Read-only
				issues can only be modified by users with a configured access
				level.  Read-only applies to the issue header information as
				well as other issue related information like relationships,
				attachments, notes, etc.
				</para>
			</listitem>
			<listitem><para>Update readonly issues - The access levels
				required for a user to be able to modify a readonly issue.
				</para>
			</listitem>
			<listitem><para>Update issue status - The access levels required
				for a user to be able to modify the status of an issue.
				</para>
			</listitem>
			<listitem><para>View private issues - The access levels for a
				user to be able to view a private issue.
				</para>
			</listitem>
			<listitem><para>Set view status (public vs. private) - The
				access level for a user to be able to set whether an issue is
				private or public, when reporting the issue.  If the user
				reporting the issues doesn't have the required access, then the
				issue will be created with the default view state.
				</para>
			</listitem>
			<listitem><para>Update view status (public vs private) - The
				access level required for a user to be able to update the view
				status (i.e. public vs. private).
				</para>
			</listitem>
			<listitem><para>Show list of users monitoring issue - The access
				level required for a user to be able to view the list of users
				monitoring an issue.
				</para>
			</listitem>
			<listitem><para>Set status on assignment of handler - The access
				levels required for a user to be able to re-assign an issue when
				changing its status.
				</para>
			</listitem>
			<listitem><para>Status to set auto-assigned issues to - The
				status - This is the status that is set on issues that are auto
				assigned to users that are associated with the category that the
				issuer is reported under.
				</para>
			</listitem>
			<listitem><para>Limit reporter's access to their own issues -
				When set, reporters are only allow to view issues that they have
				reported.
				</para>
			</listitem>
			<listitem><para>Add notes - The access levels required for users
				to be able to add notes.
				</para>
			</listitem>
			<listitem><para>Update notes - The access levels required for
				users to be able to update issue notes.
				</para>
			</listitem>
			<listitem><para>Allow user to edit their own issue notes - A flag
				that indicates the ability for users to edit issue notes report by them.
				</para>
			</listitem>
			<listitem><para>Delete note - The access levels required for a
				user to delete a note that they may or may not have reported
				themselves.
				</para>
			</listitem>
			<listitem><para>View private notes - The access levels required
				for a user to be able to view private notes associated with an
				issue that they have access to view.
				</para>
			</listitem>
			<listitem><para>View Change Log - The access levels required for
				a user to be able to view the change log.
				</para>
			</listitem>
			<listitem><para>View Assigned To - The access levels required
				for a user to be able to know the handler of an issue that they
				have access to.
				</para>
			</listitem>
			<listitem><para>View Issue History - The access levels required
				for a user to be able to view the history of changes of an
				issue.
				</para>
			</listitem>
			<listitem><para>Send reminders - The access levels required for
				a user to be able to send reminders to other users relating to
				an issue that they have access to.
				</para>
			</listitem>
			</itemizedlist>
		</section>
	</section>
</chapter>