p4 jobspec

Synopsis

Edit the jobs template.

Syntax

p4 [g-opts] jobspec
p4 [g-opts] jobspec [-i]
p4 [g-opts] jobspec -o

Description

The p4 jobspec command presents the Perforce administrator with a form in which job fields can be edited, created, deleted, and refined.

Do not confuse the names of the fields in the p4 jobspec form with the names of the fields within a job. The fields in the p4 jobspec form are used to store information about the fields in the p4 jobs form.

Form Fields

Field Name Description

Fields:

A list of field definitions for your site’s jobs, one field per line. Each line is of the form code name datatype length fieldtype.

  • code: a unique integer that identifies the field internally to Perforce. The code must be between 106 and 199. Codes 101 to 105 are reserved for Perforce use; see Usage Notes for more details.

  • name: the name of the field. This can be changed at any time, while the code should not change once jobs have been created.

    Field names must not contain spaces.

  • datatype: the datatype of the field. Possible values are:
  • word: a single arbitrary word (a string with no spaces)
  • date: a date/time field
  • select: one of a fixed set of words
  • line: one line of text
  • text: a block of text, starting on the line underneath the fieldname.
  • bulk: like text, but not indexed for searching with p4 jobs -e.
  • length: recommended length for display boxes in GUI clients accessing this field. Use a value of 0 to let a Perforce application choose its own value.
  • fieldtype: does the field have a default value? Is it required? Is it read-only? Possible values are:
  • optional: field can take any value or be erased.
  • default: a default value is provided; it can be changed or erased.
  • required: a default value is provided; it can be changed but the user must enter a value.
  • once: read-only; the field value is set once to a default value and is never changed.
  • always: read-only; the field’s value is set to a new default when the job is edited. This is useful only with the $now and $user variables; it allows you to change the date a job was modified and the name of the modifying user.

Values:

Contains a lists of fields and valid values for select fields.

Enter one line for each field of datatype select. Each line must contain the fieldname, a space, and the list of acceptable values separated by slashes. For example:

JobType bug/request/problem.

Presets:

Contains a list of fields and their default values for each field that has a fieldtype of default, required, once, or always.

Each line must contain the field name and the default value, separated by a space. For example:

JobType bug

Any one-line string can be used, or one of three built-in variables:

  • $user: the user who created the job
  • $now: the current date

  • $blank: the phrase <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 is added to the system.

See Usage Notes for special considerations for field 102.

Comments:

Textual comments that appear at the top of each p4 job form. Each line must begin with the comment character #.

See Usage Notes for special considerations for these comments if your users need to enter jobs through P4V, the Perforce Visual Client.

Options

-i

Read the jobspec form from standard input.

-o

Write the jobspec form to standard output.

g-opts

See “Global Options”.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

admin,
or list to use the -o option

  • 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. Only use p4 jobspec 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) to closed (or some other value defined in the Presets: for field 102) upon changelist submission, even if the administrator has redefined field 102 to for use as a field that does not contain closed as a permissible value, leading to unpredictable and confusing results.

  • The information in the Comments: fields is the only information available to your users to tell them how to fill in the job form, and is also used by P4V, the Perforce Visual Client, to display tooltips. Please make your comments complete and understandable.

  • 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.

    By default, a job’s status is set to closed after you use p4 fix, p4 change, or p4 submit. To change the default fix status from closed to some other fixStatus (assuming that you have defined the fixStatus as a valid select setting in the Values: field), use the special syntax of jobStatus,fix/fixStatus in the Presets: field for field 102 (job status). To change the behavior of p4 fix, p4 change, and p4 submit to leave job status unchanged, use the special fixStatus of same.

  • See the "Customizing Perforce: Job Specifications" chapter of the Helix Versioning Engine Administrator Guide: Fundamentals for an example of a customized jobspec.

Related Commands

To create, edit, or view a job

p4 job

To attach a job to a changelist

p4 fix

To list jobs

p4 jobs

To list jobs attached to specific changelists or changelists attached to specific jobs

p4 fixes