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:

http://www.perforce.com/product/components/defect_tracking_gateway

Creating, editing, and deleting a job

To create a job using Helix’s default job-naming scheme, issue the p4 job command. To assign a name to a new job (or edit an existing job), issue the p4 job jobname command.

Example 36. Creating a job

Gale discovers a problem with Jam, so she creates a job by issuing the p4 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:

Field Name Description Default

Job

The name of the job (white space is not allowed). By default, Helix assigns job names using a numbering scheme (jobnnnnnn).

Last job number + 1

Status
  • open: job has not yet been fixed.
  • closed: job has been completed.
  • suspended: job is not currently being worked on.

open

User

The user to whom the job is assigned, usually the person assigned to fix this particular problem.

Helix user name of the job creator.

Date

The date the job was last modified.

Updated by Helix when you save the job.

Description

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 command: p4 job jobname. Enter your changes in the job form, save the form and exit.

To delete a job, issue the p4 job -d jobname command.

Searching jobs

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 'word1 word2 ... wordN' 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.

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 ( | ) character.
  • 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 37. Searching jobs for specific words

Bruno wants to find all jobs that contain the words filter, file, and mailbox. He types: 

$ p4 jobs -e 'filter file mailbox'

Example 38. Finding jobs that contain any of a set of words in any field

Bruno wants to find jobs that contain any of the words filter, file or mailbox. He types: 

$ p4 jobs -e 'filter|file|mailbox'

You can use the * wildcard to match one or more characters. For example, the expression fieldname=string* matches string, strings, stringbuffer, and so on.

To search for words that contain wildcards, precede the wildcard with a backslash in the command. For instance, to search for *string (perhaps in reference to char *string), issue the following command: 

$ p4 jobs -e '\*string'

Searching specific fields

To search based on the values in a specific field, specify field=value.

Example 39. 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 Status: of open, a User: of bruno, 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 40. 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 word filter.

Using comparison operators

The following comparison operators are available: =, >, <, >=, <=, and ^ 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:

Field Type Description Notes

word

A single word

The equality operator (=) matches the value in the word field exactly.

The relational operators perform comparisons in ASCII order.

text

A block of text entered on the lines beneath the field name.

The equality operator (=) matches the job if the value is found anywhere in the specified field.

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 ShortDescription: that contains only the phrase gui bug, and the expression is 'ShortDesc<filter', the job will match the expression, because bug<filter.

line

A single line of text entered on the same line as the field name.

Same as text

select

One of a set of values. For example, job status can be open, suspended, or closed.

The equality operator (=) matches a job if the value in the field is the specified word. Relational operators perform comparisons in ASCII order.

date

A date and optionally a time. For example, 2011/07/15:13:21:40.

Dates are matched chronologically. If a time is not specified, the operators =, <=, and >= match the whole day.

bulk

Like text, but not indexed for searching.

These fields are not searchable with p4 jobs -e.

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 yyyy/mm/dd or yyyy/mm/dd:`hh:mm:`ss. If you omit time, the equality operator (=) matches the entire day.

Example 41. Using dates within expressions

Bruno wants to view all jobs modified on July 13, 2011. He enters:

$ p4 jobs -e 'ModifiedDate=2011/07/13'

Fixing jobs

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 user form to an expression that matches the job.
  • With the p4 fix command.
  • By editing the p4 submit form.

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.

Linking automatically

You can modify your Helix user specification to automatically attach open jobs to any changelists you create. To set up automatic inclusion, issue the p4 user command and set the JobView: field value to a valid expression that locates the jobs you want attached.

Example 42. Automatically linking jobs to changelists

Bruno wants to see all open jobs that he owns in all changelists he creates. He types p4 user and adds the JobView: field: 

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.

Linking manually

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 the job’s Status: field is changed to closed. Otherwise, the status is not changed.

Example 43. 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 closed.