Customizing Perforce: Job Specifications

Perforce 2000.1 System Administrator's Guide (2000.1.sa.3)


<< Previous Chapter Administering Perforce: Protections	Table of Contents Index Perforce on the Web	Next Chapter >> Scripting Perforce: Daemons and Triggers

Chapter 5
Customizing Perforce:
Job Specifications
Perforce's jobs feature allows changelists to be linked to enhancement requests, problem reports, and other user-defined tasks. The Perforce user's use of p4 job is discussed in the Perforce User's Guide. This chapter covers superuser modification of the jobs system.

Perforce's default jobs template has five fields for tracking jobs. These fields may be sufficient for small-scale operations, but as projects managed by Perforce grow, the information stored in these fields may be insufficient. The p4 jobspec command, which is available only to the Perforce superuser, can be used to add, delete, and change fields in the job template.

This chapter discusses the mechanics of altering the Perforce job template. Certain changes to the template are forbidden. Others are permissible, but are not recommended.


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, we will examine the default Perforce job template. The examples which follow in this chapter will be based upon modifications to this default Perforce job 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: 1998/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 once 105 Description text 0 required 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. Values-Status: open/suspended/closed Preset-Status: open Preset-User: $user Preset-Date: $now Preset-Description: $blank

The Job Template's Fields

There are six fields and field types in the p4 jobspec form. These fields define the template for all Perforce jobs on your server. The fields and field types are:


Field / Field Type	Meaning
`Fields:`	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.
`Required:`	A list of those fields in which values must be entered.
`Readonly:`	A list of fields, the default values of which cannot be changed by the user. Each field in this list requires a corresponding `Preset-fieldname` entry in the job specification.
`Values-fieldname:`	List of possible values for any select fields (defined below)
`Preset-fieldname:`	A default value for field `fieldname`.
`Comments:`	The comments that will appear at the top of the `p4 job` form.

The Fields: Field

The p4 jobspec field Fields: lists the fields to be tracked by your jobs. The default Fields: field lists these fields:


`Fields: 101 Job word 32 required 102 Status select 10 required 103 User word 32 required 104 Date date 20 once 105 Description text 0 required`

Each field must be listed on a separate line, and is comprised of five separate descriptors:


Field Descriptor	Meaning
`ID#`	A unique integer identifier by which this field is indexed. Once a field has been created and jobs have been entered into the system, the name of this field can change, but data will be inaccessible if the ID number changes. ID numbers must be between `101` and `199`.
`Name`	The name of the field as it should appear on the `p4 job` form.
`Data Type`	One of five datatypes, described in the next table.
`Length`	The recommended size of the field's text box as displayed in p4win, the Perforce GUI client. A value of `0` will display a text box with room for multiple lines of input; a nonzero value will display a single line with room for `length` characters. The value of this field has no effect on jobs edited from `p4`, and is not related to the actual length of the values stored by the server.
`Persistence`	Determines whether a field is read-only, contains default values, etc. The valid values for this field are: `optional:` field can take any value or can be deleted. `default:` a default value is provided; it can be changed or erased. `required:` a default is given; it can be changed but the field can't be left empty. `once:` read-only; the field is set once to a default value and is never changed. `always:` read-only; the field value is reset to the default value when the job is saved. Useful only with the `$now` variable to change job modification dates, and with the `$user` variable to change the name of the user who last modified the job. In version 98.2 of Perforce, a field's persistence was specified in a very different way. If you have upgraded from 98.2, no conversion need be done; the old persistences will appear in the `p4 jobspec` form in the new template.

The five field datatypes are:


Field Type	Explanation	Example
`word`	A single word	A userid: `edk`
`text`	A block of text that may span multiple lines	A job's description
`line`	One line of text	A user's real name: `Ed K.`
`select`	One of a set of values. Must have a corresponding `Values-Fieldname:` field entered into the job specification	A job's status. One of: `open/suspended/closed`
`date`	A date value	The date and time of job creation: `1998/07/15:13:21:46`

Caveats, Recommendations, and Warnings

Once a field has been created and jobs have been entered, do not change the field's ID#. Any data entered in that field through p4 job will be inaccessible.
Field names may be changed at any time. When changing a field's name, be sure to also change the fieldname in other p4 jobspec fields that reference this fieldname. For example, if you create a new field 106 named severity and subsequently rename it to bug-severity, then the jobspec's Preset-severity: field will have to be changed to Preset-bug-severity: to reflect the change.
Field ID# 101, the job's name, is required by Perforce and must not be deleted. As is true for all fields, its name may be changed.
Field ID# 102, the job's status, may be deleted; however, Perforce will be unable to update the status of jobs linked to particular changelists. If this field is present, Perforce will always set the value of this field to closed when a changelist containing this job is submitted, even if closed has been deleted from the list of possible values within the jobspec.
Field ID# 105 is assumed to be a job description. If present, it will be used by p4 change and p4 submit to describe the jobs fixed by the changelist.
We strongly recommend leaving the default fields 101 to 105 in the jobs system, using p4 jobspec only to add new fields to your jobs. Do not change the names or types of these fields for any reason!
The comments that you write in the Comments: field are the only way to let your users know the requirements for each field. Please make these comments understandable and complete. These comments are treated specially in P4Win, the Perforce Windows GUI; for P4Win ToolTip compatibility, make sure that the first line of each field's comment can be read on its own.

The Preset-fieldname: Fields

All fields with a persistence of anything other than optional require default values. To assign a default value to a field, create a field in the jobspec form called Preset-fieldname:, where fieldname is the field name to which you're assigning the default value. Any single-line string may be used as a default value.

Three variables are available for use as default values:


Variable	Value
`$user`	The Perforce user creating the job, as specified by the `P4USER` environment or registry variable, or as overridden with `p4 -u` `username` job.
`$now`	The date and time at the moment the job is saved.
`$blank`	The text `<enter description here>`. When users enter jobs, any fields in your jobspec with a preset of `$blank` must be filled in by the user before the job will be added to the system.

The Preset-fieldname: fields and values for the standard jobs template are


`Preset-Status: open Preset-User: $user Preset-Date: $now Preset-Description: $blank`

In version 98.2 of Perforce, the Preset-fieldname fields were called Default-fieldname.

The Values-fieldname: Fields

The set of possible values for any field of datatype select are provided in a Values-fieldname: field. The values are entered on single line, separated by slashes. In the default Perforce job specification, only the Status: field is a select field; its possible values have been set with:


`Values-Status: open/suspended/closed`

The Comments: Field

The Comments: field supplies the comments that will appear at the top of the p4 job form. Since p4 job will not automatically tell your users the valid values of select fields, which fields are required, etc., it is important that your comments 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.

P4Win, the Perforce Windows GUI client, displays these comments in two ways:

When the P4Win user creates or edits a job and presses the Form Info button in the job dialog box, a popup window displays the comments.
Administrators of Perforce servers accessed by P4Win users should take extra care while writing comments.

As the cursor moves over each field, the first line of the comment that correspond to that field is displayed in a ToolTip. P4Win constructs ToolTips by parsing the comments, looking for lines that start with a single word followed by a colon (:). The remainder of each of these lines is displayed as the ToolTip for the field that matches the first word of the line. Only the first line of the comment is displayed; if P4Win encounters the jobspec comments above, the ToolTip for the Status: field will read:

Either `open', `closed', or `suspended'. Can be changed.

Example: Perforce's Custom Template

We designed our jobs system to meet our own evolving needs, and ended up modifying our own job template accordingly.

Our own internal job specification and the job form it uses are provided here as a second example of the relationship between the p4 jobspec template and the p4 job template.

Running p4 jobspec at Perforce displays the following template:


# A Perforce Job Specification. # # Updating this form can be dangerous! # See `p4 help jobspec' for proper directions. Fields: 101 Job word 32 required 106 Type select 10 required 102 Status select 10 required 108 Priority select 10 required 107 Subsystem select 10 required 109 Owned_By word 32 optional 103 Reported_By word 32 required 104 Reported_Date date 20 once 110 Modification_Date date 20 always 112 Call_Numbers word 64 optional 111 Customers text 0 optional 105 Description text 0 required






























































Comments: # Perforce Jobs at Perforce: # # Job: Job number # Type: The type of the job. Acceptable values are # "bug", "sir", "problem" or "unknown" # Status: Has the job been fixed: Acceptable values are # "open", "closed", or "suspended" # Priority: How soon should this job be fixed? # Values are "a", "b", "c", or "unknown" # Subsystem: One of p4/gui/doc/mac/misc/unknown # Owned_by: Who's fixing the bug # Reported_by: Who reported the bug # Reported_date: When the bug was first entered # Mod_date: Last time the bug was updated # Call_Numbers: If from calltrack, the call numbers # Customers: Email addresses of customers, one per line # Description: Textual description of the bug Values-Type: bug/sir/problem/unknown Preset-Type: unknown Values-Status: open/suspended/closed Preset-Status: open Values-Priority: A/B/C/unknown Preset-Priority: unknown Values-Subsystem: p4/gui/doc/mac/misc/unknown Preset-Subsystem: unknown Preset-Owned_By: unowned Preset-Reported_By: $user Preset-Reported_Date: $now Preset-Modification_Date: $now Preset-Call_Numbers: none Preset-Customers: internal

Running p4 job at Perforce displays this job form:


# Perforce Jobs at Perforce: # # Job: Job number # Type: The type of the job. Acceptable values are # "bug", "sir", "problem" or "unknown" # Status: Has the job been fixed: Acceptable values are # "open", "closed", or "suspended" # Priority: How soon should this job be fixed? # Values are "a", "b", "c", or "unknown" # (This is NOT the same as severity!) # Subsystem: One of p4/gui/doc/mac/misc/unknown # Owned_by: Who's fixing the bug # Reported_by: Who reported the bug # Reported_date: When the bug was first entered # Mod_date: Last time the bug was updated # Call_Numbers: If from calltrack, the call numbers # Customers: Email addresses of customers, one per line # Description: Textual description of the bug Job: new Type: unknown Status: open Priority: unknown Subsystem: unknown Owned_By: unowned Reported_By: edk Reported_Date: 1998/06/04 02:13:10 Modification_Date: 1998/06/04 02:13:10 Call_Numbers: none Customers: internal Description: <enter description here>

Observe that he 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.

At Perforce, for instance, the field displayed following the job name is Type:, even though its numeric identifier is 106, not 102.

Integrating with Other Defect Tracking Systems

If Perforce's built-in "jobs" feature doesn't satisfy your defect tracking needs, you can still use it as the interface between Perforce and your preferred defect tracking system. 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.

That is, the third-party system should generate the data and then pass it to a script which 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 a the standard input of a p4 job -i command.

(The -i flag to p4 job allows 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 which 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: Daemons and Triggers" on page 59.

Perforce customers currently integrate Perforce with their own home-grown defect tracking systems, and with third-party systems such as Remedy, Scopus, and ClearTrack.

If you are interested in seeing what other Perforce users have done, visit the Perforce web site and examine the perforce-user mailing list archives, which are available under our Documentation page. You may also wish to consider posting to perforce-user to ask if anyone has integrated Perforce with the third-party tool you're interested in -- someone may have already done all the setup work required to work with your system.

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 attempting to edit a job specification!

Once a field has been created and jobs have been entered, do not change the field's ID#. Any data entered in that field through p4 job will be inaccessible.
Field names may be changed at any time. When changing a field's name, be sure to also change the fieldname in other p4 jobspec fields that reference this fieldname. For example, if you create a new field 106 named severity and subsequently rename it to bug-severity, then the jobspec's Preset-severity: field will have to be changed to Preset-bug-severity: to reflect the change.
Field ID# 101, the job's name, is required by Perforce and must not be deleted. As is true for all fields, its name may be changed.
Field ID# 102, the job's status, may be deleted; however, Perforce will be unable to update the status of jobs linked to particular changelists. If this field is present, Perforce will always set the value of this field to closed when a changelist containing this job is submitted, even if closed has been deleted from the list of possible values within the jobspec.
Field ID# 105 is assumed to be a job description. If present, it will be used by p4 change and p4 submit to describe the jobs fixed by the changelist.
We strongly recommend leaving the default fields 101 to 105 in the jobs system, using p4 jobspec only to add new fields to your jobs. Do not change the names or types of these fields for any reason!
The comments that you write in the Comments: field are the only way to let your users know the requirements for each field. Please make these comments understandable and complete. These comments are treated specially in P4Win, the Perforce Windows GUI; for P4Win ToolTip compatibility, make sure that the first line of each field's comment can be read on its own.

Perforce 2000.1 System Administrator's Guide (2000.1.sa.3)


<< Previous Chapter Administering Perforce: Protections	Table of Contents Index Perforce on the Web	Next Chapter >> Scripting Perforce: Daemons and Triggers