Enhanced Jobs

= Enhanced Jobs Project (EJP) =

Background and Overview
The Enhanced Jobs Project (EJP) was developed in response to growing concerns about the limitations of the jobs subsystem, as compared to some of the commercial defect tracking systems available today. EJP does not attempt to transform the current jobs system into a fully-functioned defect tracking application. What it does is address what have been identified as the key &quot;pain points&quot; in the current system, while correcting a couple of long-standing weaknesses.

EJP is a set of small improvements to the standard jobs system that were designed to make our life with jobs just a little easier.

Features of the Enhanced Jobs Project
EJP provides the following features:


 * Improved triggers on jobs
 * Improved support for handling of duplicates
 * Improved support for handling of related jobs
 * Job change history
 * Better management of job ownership
 * New validations on jobspec fields



Improved triggers on jobs
As part of this project, a couple of holes in the server's trigger handling were repaired:
 * Any event that affects a job will fire a form-commit trigger. For example:
 * p4 submit
 * p4 fix
 * p4 fix -d
 * p4 changelist
 * The JobID of a newly-submitted job will now be available to &quot;commit&quot; triggers.



Improved support for handling of duplicates
The proper handling of duplicates involves several separate steps, and has always been prone to error. This project automates some of that process, and imposes restrictions to prevent some common errors. In a nutshell, this feature: What this means for users is that all we'll have to do, when we discover a duplicate, is enter the primary, or original job number in the DuplicateOf field and set the Status to &quot;duplicate&quot;, and EJP will take care of the rest.
 * Makes sure that when a bug is marked as a &quot;duplicate&quot; the job that it is a duplicate of is identified.
 * Automatically updates the corresponding job to identify the duplicate one as being related to it. (I.e., creates the cross-reference.)
 * Copies customer and call information from the duplicate job back to the original, or primary one.



Improved support for handling of related jobs
Currently, it's common for a job description to include a notation like, "See also job012345". EJP formalizes this practice by adding a RelatedJobs field that will hold a set of JobIDs for jobs that are similar to the current one, but that might not be exact duplicates. When a JobID is entered in this field, a corresponding entry is automatically made in the related job, providing more complete cross-referencing of this data.

Note that this behavior is similar to the &quot;duplicate&quot; handling described above. The main difference is that customer and call information is not affected for &quot;related&quot; jobs.



Job change history
Currently, anyone can view the history of a job by looking at its revision history in the spec depot. This is very convenient for a single job, but can be labor intensive if a large number of jobs need to be reviewed.

The Enhanced Jobs Project addresses this problem by adding a system-maintained field (121 History) that holds a brief summary of each change that affects a job. With this feature, you can get a quick overview of the history of a job by looking at a single field.



Better management of job ownership
One of the key &quot;pain points&quot; identified in the current jobs system is that job ownership is mainly an ad hoc and/or manual process. Because of this, it's fairly easy for a job to languish without an owner, which can seriously delay any action being taken on it.

EJP implements an internal data structure that is used to automatically assign an owner to a job, based on the job's Subsystem and Status. The standard assignments can be overridden, if necessary, but if a subsystem has been configured to have a default set of owners (based on job status), then the owner field can't inadvertently be left blank. That is, if the user entering the job doesn't specify an owner, then the system will fill that field in with the designated default owner.

With EJP, if the Status field is updated, but the OwnedBy field is not, ownership will automatically transfer to the appropriate individual (based on a pre-defined matrix of subsystems, status values, and usernames). If the OwnedBy field is explicitly set, EJP will not update it using that matrix, but will retain the value that was entered.



New validations on jobspec fields
EJP provides the following validation specifiers, which can be used for jobspec fields:

Field validation specifiers are set in the &quot;Values&quot; section of the jobspec. For example:
 * JobID - Value must be an existing JobID.
 * UserID - Must be an existing UserID.
 * Changelist - Must be an existing Changelist number
 * DepotPath - Must be a path to a file or directory in the depot.
 * FilePath - Must be a path to a specific file in the depot.

... Values: OwnedBy UserID ...

In addition, two kinds of &quot;group&quot; fields have been defined:

Lists and collections are also specified in the Values section of the jobspec. For example:
 * ListOf - An ordered list of a specified type.
 * SetOf - A collection of unique values of a specified 			type.

... Values: DuplicateJobs SetOf(JobID) ...

Administration
On a day-to-day basis, EJP will &quot;just work&quot;, but when product assignments or procedures change, EJP will need to be adjusted accordingly. This will involve making updates to one of the following files:


 * P4Data.rb
 * P4Logic.rb
 * job_commit.rb

P4Data.rb

P4Data.rb encapsulates:


 * The default ownership for a job, based on subsystem and status.
 * The name of the field that will be used to maintain the job's change history.
 * A list of fields that will not be included in the change history summary.
 * A list of the fields that are maintained by EJP, and that are to be treated as &quot;read only&quot; otherwise.
 * The names of fields that will be copied during duplicate processing.

P4Logic.rb

P4Logic.rb holds the logic for handling new jobs and changed jobs, including duplicates, and &quot;related&quot; jobs:


 * Blocks manual entry into system-maintained fields.
 * Copies data from duplicate jobs to the original, or primary, one.
 * Updates the History field.

job_commit.rb


 * Rejects the job change if any value was entered into a system-maintainted field.
 * If the job status is changed to &quot;Duplicate&quot;, moves customer call information (call numbers and contacts) from the duplicate job to the original, or primary, one.
 * Updates the History field to add a summary of the current change.

New Fields for the production jobspec

To support all of the new features in the Enhanced Jobs Prototype, several fields will need to be added to the production jobspec:

Again, once the system is up and running, administration requirements are expected to be minimal, and to consist primarily of making changes to P4Data.rb to keep the mappings between subsystems and owners up to date.