Working with Jobs
A job is a numbered (or named) work request managed by Helix. Helix jobs enable you to track the status of bugs and enhancement requests and associate them with changelists that implement fixes and enhancements. You can search for jobs based on the contents of fields, the date the job was entered or last modified, and many other criteria.
Your Helix administrator can customize the job specification for your site’s requirements. For details on modifying the job specification, see the Helix Versioning Engine Administrator Guide: Fundamentals.
To integrate Helix with your in-house defect tracking system, or to develop an integration with a third-party defect tracking system, use P4DTG, the Perforce Defect Tracking Gateway. P4DTG is an integrated platform that includes both a graphical configuration editor and a replication engine. For more information, see:
Creating, editing, and deleting a job
To create a job using Helix’s default job-naming scheme, issue the
command. To assign a name to a new job (or edit an existing job), issue the
job jobname command.
Example 39. Creating a job
Gale discovers a problem with Jam, so she creates a job by issuing the
job command and describes it as follows:
Job: job000006 Status: open User: gale Date: 2011/11/14 17:12:21 Description: MAXLINE can't account for expanded cmd buffer size.
The following table describes the fields in the default job specification:
The name of the job (white space is not allowed). By default, Helix assigns
job names using a numbering scheme
Last job number + 1
The user to whom the job is assigned, usually the person assigned to fix this particular problem.
Helix user name of the job creator.
The date the job was last modified.
Updated by Helix when you save the job.
Describes the work being requested, for example a bug description or request for enhancement.
None. You must enter a description.
To edit existing jobs, specify the job name when you issue the
p4 job jobname. Enter your changes in the job form, save the form
To delete a job, issue the
p4 job -d jobname command.
To search Helix jobs, issue the
p4 jobs -e jobview command, where
jobview specifies search expressions described in the sections that below. For
more details, issue the
p4 help jobview command.
Searching job text
You can use the expression
' to find jobs that contain all of word1 through
wordN in any field (excluding date fields). Use single quotes on UNIX and
double quotes on Windows.
word1 word2 ...
When searching jobs, note the following restrictions:
- When you specify multiple words separated by whitespace, Helix searches for
jobs that contain all the words specified. To find jobs that contain
any of the terms, separate the terms with the pipe (
- Field names and text comparisons in expressions are not case-sensitive.
- Only alphanumeric text and punctuation can appear in an expression. To match
the following characters, which are used by Helix as logical operators,
precede them with a backslash:
- You cannot search for phrases, only individual words.
Example 40. Searching jobs for specific words
Bruno wants to find all jobs that contain the words
mailbox. He types:
$ p4 jobs -e 'filter file mailbox'
Example 41. Finding jobs that contain any of a set of words in any field
Bruno wants to find jobs that contain any of the words
mailbox. He types:
$ p4 jobs -e 'filter|file|mailbox'
You can use the
* wildcard to match one or more characters. For example, the
To search for words that contain wildcards, precede the wildcard with a
backslash in the command. For instance, to search for
*string (perhaps in
char *string), issue the following command:
$ p4 jobs -e '\*string'
Searching specific fields
To search based on the values in a specific field, specify
Example 42. Finding jobs that contain words in specific fields
Bruno wants to find all open jobs related to filtering. He types:
$ p4 jobs -e 'Status=open User=bruno filter.c'
This command finds all jobs with a
and the word
filter.c in any non-date field.
To find fields that do not contain a specified expression, precede it with
^, which is the NOT operator. The NOT operator
^ can be used only directly
after an AND expression (space or
&). For example,
p4 jobs -e
'^user=bruno' is not valid. To get around this restriction, use the
wildcard to add a search term before the
^ term; for example:
p4 jobs -e 'job=* ^user=bruno' returns all jobs not
owned by Bruno.
Example 43. Excluding jobs that contain specified values in a field
Bruno wants to find all open jobs he does not own that involve filtering. He types:
$ p4 jobs -e 'status=open ^user=bruno filter'
This command displays all open jobs that Bruno does not own that contain the
Using comparison operators
The following comparison operators are available:
^ for Boolean NOT.
The behavior of these operators depends upon the type of the field in the expression. The following table describes the field types and how they can be searched:
A single word
The equality operator (
The relational operators perform comparisons in ASCII order.
A block of text entered on the lines beneath the field name.
The equality operator (
The relational operators are of limited use here, because they’ll match the job
if any word in the specified field matches the provided value. For example,
if a job has a text field
A single line of text entered on the same line as the field name.
One of a set of values. For example, job status can be
The equality operator (
A date and optionally a time. For example,
Dates are matched chronologically. If a time is not specified, the operators
These fields are not searchable with
If you’re not sure of a field’s type, issue the
p4 jobspec -o command, which
displays your job specification. The field called
Fields: lists the job
fields' names and data types.
Searching date fields
To search date fields, specify the date using the format
If you omit time, the equality operator (
=) matches the entire day.
Example 44. Using dates within expressions
Bruno wants to view all jobs modified on July 13, 2011. He enters:
$ p4 jobs -e 'ModifiedDate=2011/07/13'
To fix a job, you link it to a changelist and submit the changelist. Helix
automatically changes the value of a job’s status field to
closed when the
changelist is submitted.
Jobs can be linked to changelists in one of three ways:
- By setting the
JobView:field in the
p4 userform to an expression that matches the job.
- With the
- By editing the
You can modify job status directly by editing the job, but if you close a job
manually, there’s no association with the changelist that fixed the job. If you
have altered your site’s job specification by deleting the
Status: field, jobs
can still be linked to changelists, but status cannot be changed when the
changelist is submitted. (In most cases, this is not a desired form of
operation.) See the chapter on editing job specifications in the Helix Versioning Engine Administrator Guide: Fundamentals
for more details.
To remove jobs from a changelist, issue the
p4 fix -d command.
You can modify your Helix user specification to automatically attach open jobs
to any changelists you create. To set up automatic inclusion, issue the
user command and set the
JobView: field value to a valid expression that
locates the jobs you want attached.
Example 45. Automatically linking jobs to changelists
Bruno wants to see all open jobs that he owns in all changelists he creates. He
p4 user and adds the
User: bruno Update: 2011/06/02 13:11:57 Access: 2011/06/03 20:11:07 JobView: user=bruno&status=open
All of Bruno’s open jobs now are automatically attached to his default changelist. When he submits changelists, he must be sure to delete jobs that aren’t fixed by the changelist he is submitting.
To link a job to a changelist manually, issue the
p4 fix -c changenum
jobname command. If the changelist has already been submitted, the value of
Status: field is changed to
closed. Otherwise, the status is not
Example 46. Manually linking jobs to changelists
You can use p4 fix to link a changelist to a job owned by another user.
Sarah has just submitted a job called
options-bug to Bruno, but the bug has
already been fixed in Bruno’s previously submitted changelist 18. Bruno links
the job to the changelist by typing:
$ p4 fix -c 18 options-bug
Because changelist 18 has already been submitted, the job’s status is changed to