- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
  - Overview
  - Concepts
- ARGUMENTS
  - -h|-man
- RETURN STATUS

# NAME

JobIncrement.pl - Trigger to increment jobs with custom names.

# VERSION

1.0.3

# SYNOPSIS

Enable this as a form-in trigger on the job form, for example:

Triggers:

`JobIncrement form-in job "/p4/common/bin/triggers/JobIncrement.pl %formfile%"`

OR

`JobIncrement.pl {-h|-man}`

# DESCRIPTION

## Overview

The default job naming convention with Perforce Jobs has an auto-increment feature, so that if you create a job with a 'Job:' field value of 'new', it will be changed to jobNNNNNN, with the six-digit value being automatically incremented.

Perforce jobs also support custom job naming, e.g. to name jobs PROJX-123, where the name itself is more meaningful. But if you use custom job names, you forego the convenience of automatic generation of a new job number. Now typically, if the default job naming feature isn't used, it's because new issues originate in an external issue tracking. So there's no need for incrementing by Perforce; the custom job names just mirror the value in the external system (which handles the numbering of issues).

This script aims to make it easier to use custom job names with Perforce even when there is no external issue tracker. This script provides the ability to generate new job names with automatically incremented numbers on a per-project basis.

## Concepts

1. Job Prefix

   The 'Project:' field in the Jobspec has a 'select' field with pre-defined values for project names. Projects desiring to use custom jobs names will define a counter named JobPrefix-<project_name>. The value will be a tag name, a short form of the project name, to be used as a prefix for job names. For example, a project named joe_schmoe-wicked-good-thing might have a prefix of WGT. Jobs will be named WGT-1, WGT-2, etc. By convention, job prefixes are comprised only of uppercase letters, matching the pattern ^[A-Z]$. No spaces, commas, dashes, underbars, etc. allowed. (There is no mechanism for mechanical enforcement of this convention, nor any needed, as tags are defined and created by Perforce Admins).

   To define a prefix for a project, an admin defines a value for the appropriate counter, e.g. by doing:

   `p4 counter JobPrefix-joe_schmoe-wicked-good-thing WGT`

   To see what job prefixes are currently defined, you can do:

   `p4 counters -e JobPrefix-*`

2. High Number Counter

   For projects with defined tags, there will also be a high number counter tracking the highest numbered job with a give prefix. This counter is created automatically and maintained by this script.

3. JobIncrement trigger (this script).

   This trigger script fires as a 'form-in' trigger on job forms, i.e. it fires on jobs that are on their way into the server. If 'Job:' field value is 'new' and the 'Project:' field value has an associated JobPrefix counter, then the name of the job is determined and set by incrementing the High Number counter, ultimately replacing the value 'new' with something like WGT-201 before it ever gets to the server. If no High Number counter exists for the project, it gets set to '1'.

# ARGUMENTS

## -h|-man

Display a usage message. The -h display a short synopsis only, while -man displays this message.

# RETURN STATUS

Zero indicates normal completion, Non-Zero indicates an error.