Customizing Perforce: Job Specifications
Perforce's jobs feature enables users to link changelists to enhancement requests, problem reports, and other user-defined tasks. Perforce also offers P4DTG (Perforce Defect Tracking Gateway) as a means to integrate third-party defect tracking tools with Perforce. See “Working with third-party defect tracking systems” for details.
The Perforce user's use of p4 job is discussed in the P4 User's Guide. This chapter covers administrator modification of the jobs system.
Perforce's default jobs template has five fields for tracking jobs. These fields are sufficient for small-scale operations, but as projects managed by Perforce grow, the information stored in these fields might be insufficient. To modify the job template, use the p4 jobspec command. You must be a Perforce administrator to use p4 jobspec.
This chapter discusses the mechanics of altering the Perforce job template.
Warning!
Improper modifications to the Perforce job template can lead to corruption of your server's database. Recommendations, caveats, and warnings about changes to job templates are summarized at the end of this chapter.
The default Perforce job template
To understand how Perforce jobs are specified, consider the default Perforce job template. The examples that follow in this chapter are based on modifications to the this template.
A job created with the default Perforce job template has this format:
# A Perforce Job Specification. # # Job: The job name. 'new' generates a sequenced job number. # Status: Either 'open', 'closed', or 'suspended'. Can be changed. # User: The user who created the job. Can be changed. # Date: The date this specification was last modified. # Description: Comments about the job. Required. Job: new Status: open User: edk Date: 2011/06/03 23:16:43 Description: <enter description here>
The template from which this job was created can be viewed and edited with p4 jobspec. The default job specification template looks like this:
# A Perforce Job Specification. # # Updating this form can be dangerous! # See 'p4 help jobspec' for proper directions. Fields: 101 Job word 32 required 102 Status select 10 required 103 User word 32 required 104 Date date 20 always 105 Description text 0 required Values: Status open/suspended/closed Presets: Status open User $user Date $now Description $blank Comments: # A Perforce Job Specification. # # Job: The job name. 'new' generates a sequenced job number. # Status: Either 'open', 'closed', or 'suspended'. Can be changed. # User: The user who created the job. Can be changed. # Date: The date this specification was last modified. # Description: Comments about the job. Required.
The job template's fields
There are four fields in the p4 jobspec form. These fields define the template for all Perforce jobs stored on your server. The following table shows the fields and field types.
Field / Field Type |
Meaning |
---|---|
|
A list of fields to be included in each job. Each field consists of an ID#, a name, a datatype, a length, and a setting. Field names must not contain spaces. |
|
A list of fields whose datatype is
For each |
|
A list of fields and their default values. Values can be either literal strings or variables supported by Perforce. |
|
The comments that appear at the top of the p4 job form. They are also used by P4V, the Perforce Visual Client, to display tooltips. |
The Fields: field
The p4 jobspec field Fields:
lists the fields to be tracked by your jobs and specifies the order
in which they appear on the p4 job form.
The default Fields:
field includes these fields:
Fields: 101 Job word 32 required 102 Status select 10 required 103 User word 32 required 104 Date date 20 always 105 Description text 0 required
Warning
Do not attempt to change, rename, or redefine fields 101 through 105. Fields 101 through 105 are used by Perforce and should not be deleted or changed. Use p4 jobspec only to add new fields (106 and above) to your jobs.
Each field must be listed on a separate line. A field is defined by a line containing each of the following five field descriptors.
Field descriptor |
Meaning |
---|---|
ID# |
A unique integer identifier by which this field is indexed. After a field has been created and jobs entered into the system, the name of this field can change, but the data becomes inaccessible if the ID number changes.
ID numbers must be between |
Name |
The name of the field as it should appear on the p4 job form. No spaces are permitted. |
Data type |
One of five datatypes ( |
Length |
The recommended size of the field's text box as displayed
in P4V, the Perforce Visual Client. To display a text box
with room for multiple lines of input, use a length of
The value of this field has no effect on jobs edited from the Perforce command line, and it is not related to the actual length of the values stored by the server. |
Field type |
Determines whether a field is read-only, contains default values, is required, and so on. The valid values for this field are:
|
Fields have the following five datatypes.
Field Type |
Explanation |
Example |
---|---|---|
|
A single word (a string without spaces). |
A userid: |
|
A block of text that can span multiple lines |
A job's description |
|
One line of text |
A user's real name: |
|
One of a set of values
Each field with datatype |
A job's status. One of:
|
|
A date value |
The date and time of job creation:
|
bulk |
A block of text that can span multiple lines, but which is not indexed for searching with p4 jobs -e. |
Alphanumeric data for which text searches are not expected. |
The Values: fields
You specify the set of possible values for any field of datatype
select
by entering lines in the
Values:
field. Each line should contain the name
of the field, a space, and the list of possible values, separated
by slashes.
In the default Perforce job specification, the
Status:
field is the only
select
field, and its possible values are
defined as follows:
Values: Status open/suspended/closed
The Presets: field
All fields with a field type of anything other than
optional
require default values. To assign a
default value to a field, create a line in the jobspec form under
Presets
, consisting of the field name to which
you're assigning the default value. Any single-line string can be
used as a default value.
The following variables are available for use as default values.
Variable |
Value |
---|---|
|
The Perforce user creating the job, as specified by the
|
|
The date and time at the moment the job is saved |
|
The text
When users enter jobs, any fields in your jobspec with a
preset of |
The lines in the Presets
: field for the standard
jobs template are:
Presets: Status open User $user Date $now Description $blank
Using Presets: to change default fix status
The Presets:
entry for the job status field
(field 102) has a special syntax for providing a default fix
status for p4 fix, p4 change
-s, and p4 submit -s.
To change the default fix status from closed
to some other fixStatus
(assuming that
your preferred fixStatus
is already
defined as a valid select
setting in the
Values:
field), use the following syntax:
Presets: StatusopenStatus
,fix/fixStatus
In order to change the default behavior of p4
fix, p4 change, and p4
submit to leave job status unchanged after fixing a job
or submitting a changelist, use the special
fixStatus
of same
.
For example:
Presets: Status open,fix/same
The Comments: field
The Comments:
field supplies the comments that
appear at the top of the p4 job form. Because
p4 job does not automatically tell your users
the valid values of select
fields, which fields
are required, and so on, your comments must tell your users
everything they need to know about each field.
Each line of the Comments:
field must be
indented by at least one tab stop from the left margin, and must
begin with the comment character #
.
The comments for the default p4 job template appear as:
Comments: # A Perforce Job Specification. # Job: The job name. 'new' generates a sequenced job number. # Status: Either 'open', 'closed', or 'suspended'. Can be changed # User: The user who created the job. Can be changed. # Date: The date this specification was last modified. # Description: Comments about the job. Required.
These fields are also used by P4V, the Perforce Visual Client, to display tooltips.
Caveats, warnings, and recommendations
Although the material in this section has already been presented elsewhere in this chapter, it is important enough to bear repeating. Please follow the guidelines presented here when editing job specifications with p4 jobspec.
Warning!
Please read and understand the material in this section before you attempt to edit a job specification.
-
Do not attempt to change, rename, or redefine fields 101 through 105. These fields are used by Perforce and should not be deleted or changed. Use p4 jobspec only to add new fields (106 and above) to your jobs.
Field 101 is required by Perforce and cannot be renamed nor deleted.
Fields 102 through 105 are reserved for use by Perforce applications. Although it is possible to rename or delete these fields, it is highly undesirable to do so. Perforce applications may continue to set the value of field 102 (the
Status:
field) toclosed
(or some other value defined in thePresets:
for field 102) upon changelist submission, even if the administrator has redefined field 102 for use as a field that does not containclosed
as a permissible value, leading to unpredictable and confusing results. -
After a field has been created and jobs have been entered, do not change the field's ID number. Any data entered in that field through p4 job will be inaccessible.
-
Field names can be changed at any time. When changing a field's name, be sure to also change the field name in other p4 jobspec fields that reference this field name. For example, if you create a new field
106
namedseverity
and subsequently rename it tobug-severity
, then the corresponding line in the jobspec'sPresets:
field must be changed tobug-severity
to reflect the change. -
The comments that you write in the
Comments:
field are the only way to let your users know the requirements for each field. Make these comments understandable and complete. These comments are also used to display tooltips in P4V, the Perforce Visual Client.
Example: a custom template
The following example shows a more complicated jobspec and the resulting job form:
# A Custom Job Specification. # # Updating this form can be dangerous! # See 'p4 help jobspec' for proper directions. Fields: 101 Job word 32 required 102 Status select 10 required 103 User word 32 required 104 Date date 20 always 111 Type select 10 required 112 Priority select 10 required 113 Subsystem select 10 required 114 Owned_by word 32 required 105 Description text 0 required Values: Status open/closed/suspended Type bug/sir/problem/unknown Priority A/B/C/unknown Subsystem server/gui/doc/mac/misc/unknown Presets: Status open User setme Date $now Type setme Priority unknown Subsystem setme Owned_by $user Description $blank Comments: # Custom Job fields: # Job: The job name. 'new' generates a sequenced job number. # Status: Either 'open', 'closed', or 'suspended'. Can be changed # User: The user who created the job. Can be changed. # Date: The date this specification was last modified. # Type: The type of the job. Acceptable values are # 'bug', 'sir', 'problem' or 'unknown' # Priority: How soon should this job be fixed? # Values are 'a', 'b', 'c', or 'unknown' # Subsystem: One of server/gui/doc/mac/misc/unknown # Owned_by: Who's fixing the bug # Description: Comments about the job. Required.
The order of the listing under Fields:
in the
p4 jobspec form determines the order in which the
fields appear to users in job forms; fields need not be ordered by
numeric identifier.
Running p4 job against the example custom jobspec displays the following job form:
# Custom Job fields: # Job: The job name. 'new' generates a sequenced job number. # Status: Either 'open', 'closed', or 'suspended'. Can be changed # User: The user who created the job. Can be changed. # Date: The date this specification was last modified. # Type: The type of the job. Acceptable values are # 'bug', 'sir', 'problem' or 'unknown' # Priority: How soon should this job be fixed? # Values are 'a', 'b', 'c', or 'unknown' # Subsystem: One of server/gui/doc/mac/misc/unknown # Owned_by: Who's fixing the bug # Description: Comments about the job. Required. Job: new Status: open User: setme Type: setme Priority: unknown Subsystem: setme Owned_by: edk Description: <enter description here>
Working with third-party defect tracking systems
Perforce currently offers two independent platforms to integrate Perforce with third-party defect tracking systems. Both platforms allow information to be shared between Perforce's job system and external defect tracking systems.
P4DTG, The Perforce Defect Tracking Gateway
P4DTG, the Perforce Defect Tracking Gateway, is an integrated platform that includes both a graphical configuration editor and a replication engine.
The Perforce Defect Tracking Gateway (P4DTG) includes a graphical configuration editor that you can use to control the relationship between Perforce jobs and the external system. Propagation of the data between the two systems is coordinated by a replication engine. P4DTG comes with plug-ins for HP Quality Center, JIRA, Redmine, and Bugzilla.
For more information, see the product page at:
http://www.perforce.com/product/components/defect_tracking_gateway
Available from this page are an overview of P4DTG's capabilities, the download for P4DTG itself, and a link to the Perforce Defect Tracking Gateway Guide, which describes how to install and configure the gateway to replicate data between a Perforce server and a defect tracker.
Building your own integration
Even if you don't use Perforce's integrations as your starting point, you can still use Perforce's job system as the interface between Perforce and your defect tracker. Depending on the application, the interface you set up will consist of one or more of the following:
-
A trigger or script on the defect tracking system side that adds, updates, or deletes a job in Perforce every time a bug is added, updated, or deleted in the defect tracking system.
The third-party system should generate the data and pass it to a script that reformats the data to resemble the form used by a manual (interactive) invocation of p4 job. The script can then pipe the generated form to the standard input of a p4 job -i command.
(The
-i
flag to p4 job is used when you want p4 job to read a job form directly from the standard input, rather than using the interactive "form-and-editor" approach typical of user operations. Further information on automating Perforce with the-i
option is available in the Perforce Command Reference.) -
A trigger on the Perforce side that checks changelists being submitted for any necessary bug fix information.
-
A Perforce review daemon that checks successfully submitted changelists for job fixes and issues the appropriate commands to update the corresponding data in your defect tracking system.
For more about triggers and review daemons, including examples, see Scripting Perforce: Triggers and Daemons.