Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Defect Tracking Gateway Documentation | 2025.1

# Plan your replication

Before you run p4dtg-config, read this section.

Before configuring P4 DTG to replicate between your defect tracker and your Perforce jobs, plan which fields and data you need to transfer between the systems.

## P4 DTG synchronization options

There are three ways to synchronize fields between your Perforce jobs and your defect tracking system.

### Copy to Perforce job

Identify which fields you want to copy to the Perforce job. You can copy any supported field to a suitable job field.

Recommended: the minimum Defect Tracker fields that developers will need to find the job. For example: summary, description, and assignee/owner.

These fields are copied to the Perforce job. Because it is a copy, there is no need to make a select list on the job side.

You might have to create jobspec fields to hold your defect tracker data.

### Copy to defect tracker

Identify which fields you want to copy to your defect tracker's bug or issue.

Recommended: the changelist (fix) detail and optionally the related list of changes.

For fix detail, avoid copying the list of changed files because it might not be efficient if a field integration had a very large number of files.

### Two-way replication(Mirror)

If a mirrored field is updated in the same replication interval, the defect tracker value will overwrite the job value, possibly losing data.

Identify which fields you want to mirror between the two systems.

Recommended: none. Avoid mirroring, if possible.
If mirroring cannot be avoided,

- for every field that is replicated, treat one side as the source of the record and copy it to the other side

- make the defect tracking system the source of record for the defect information with Perforce the source of record for the fix information.

#### Disadvantages of Mirroring

Some administrators want to mirror the Perforce job status with the defect tracker status. This is NOT recommended because:

- Replication is fragile because you have to keep your workflow, Status, and Resolution values in sync between Jira and Perforce.
- For Jira systems, attempting to mirror the Status is especially problematic.

- All updates of mirrored fields show as updated by the p4dtg user. Because all defect tracker status changes are be done by the P4 DTG user, so there is no evidence of which human user changed the status.

- There is no workflow enforcement on the job side. You would need to write your own enforcement in a trigger, resulting in duplicate business logic that must be maintained in both systems.
- For Jira systems, configuring all possible transitions is a tedious manual process. Changing the workflow in Jira means you also have to:
  - change P4 DTG's config files
  - permit the Jira P4 DTG user to be able to perform all transitions

If your defect tracker has simple workflows where the above issues do not apply, mirroring might be appropriate.

#### When mirroring of Status is difficult or impossible

For defect trackers where mirroring of Status is difficult or impossible, if you want a Perforce job status change to close a defect tracking issues:

1. Copy the defect tracker Status into a new Perforce job field (for example, JiraStatus)
2. Alter the P4 Server jobspec Status to be a simple list: open, inprogress, closed.
3. Copy the P4 Server job Status values to a new custom field called P4Status in the defect tracker.
4. Have a defect tracker mechanism (for example, a job save event) in the defect tracker look at the P4Status field to determine whether to advance the Issue to the alternate state.

## Map SELECT fields

Select fields are the fields that have a defined list of values.

Your options are to:

- copy: select field on the source side only
- copy with mapping: select fields on both sides by mapping each value on the source side to a target value.
- mirror: select fields on both sides by mapping values between the systems with one-to-one mappings.

If a mirrored field is updated in the same replication interval, the defect tracker value will overwrite the job value, possibly losing data.

When mapping with mirror or copy with mapping, you must alter the P4 DTG configuration, and possibly the jobspec, whenever the source system select values change.

## Job numbers

There are three options for creating your Perforce job numbers:

1. Default Perforce: jobXXXXXX, starting at job000001
2. DTG configures:<dt-issue-id>-<mapName> where <mapName> is set in the p4dtg-config tool
3. Match: the Perforce job name matches the bug/issue number

Recommended: option b or c:

- Option b: this is the easiest because it is configured in the Source's Attributes (generate job ids) of P4 Server.
- Option c: requires implementing a form-in job trigger (see changeid.pl in the Form-in Job Trigger section below).

## Create new jobs

We recommend that new issues are created in your defect tracking system, and then replicated by the P4 DTG user to Perforce jobs.

We do not recommend letting users create Perforce jobs that are then replicated to your defect tracking system. Some plug-ins, such as Bugzilla, do not support this process.

To block all users other than the P4 DTG user from creating a job, use a form-in job trigger. For information about form-in job triggers, see Form-in Job Trigger.

## User update of job fields

When following our recommendation of having the defect tracker as the source of record, use a form-in job trigger to prevent users from updating jobs. The P4 DTG user must be allowed to update jobs. For information about form-in job triggers, see Form-in Job Trigger

The form-in job trigger will not catch updates to the job Status field.

## Issue Summary and Description fields

Most defect trackers have two separate fields for the summary and description of an issue.

The default P4 Server jobspec has a single field called Description (field id `105`). This field has a special use, the first 60 characters are displayed in the p4 jobs output. Therefore, we recommend that you copy your defect tracker Summary field to your P4 Server jobspec Description field (field id `105`).

If you want to copy the long description from your defect tracker as well, create a new jobspec text field to hold it. For example, you could call this text field LongDescription.

## Status and Resolution fields

Some bug trackers have two fields for Status and Resolution, where the resolution is only set for certain status values. To handle this, P4 DTG creates a special status/resolution field for those defect trackers. This special P4 DTG field should be used for that purpose

## Identify a User for Each System

A P4 DTG user for the defect tracker and for the Perforce jobs is necessary. The defect tracker and job history will show this user.

Job updates and fixes from the P4 DTG user are ignored because this user is for purposes of replication only.

### Permissions for defect tracker P4 DTG user

The defect tracker user requirements are dependent on defect tracker, but typically you need administrator privileges to configure P4 DTG with the runtime privilege to update any bug or issue that might be updated.

#### Jira User Permissions

By default, the Jira installation creates three user groups "jira-users", "jira-developers", and "jira-administrators". Each of these user groups has its own set of permissions. The P4DTG Jira plug-in requires an administrative Jira user for configuration. Assign your defect tracker user for Jira to the "jira-administrators" group. At runtime, this Jira user must be able to read Jira issues, update Jira issues, and add comments.

### P4 Server user requirements

#### User Type

The P4 DTG user must be of user type standard. Other user types will not work.

Job updates from P4 DTG are done by this replicating user. The Modified By field contains this replicating user regardless of the defect tracker user who updated the defect.

Job updates from the P4 DTG user are ignored because this user is for purposes of replication only.

#### Minimum Access Level Privileges

For basic replication, open is required. The user just needs open on one file, existing or not. This is required for running p4 job.

If you replicate fix data to your defect tracker that includes the filenames in the changelist then list access is needed for the files. Files in a changelist to which the P4 DTG user does not have list access will not be listed in the fix details.

Problem: Runtime insufficient privileges error:

If you don't have open access, replication will stop and an error file will be produced.

Example error file:

    Fix defect: BUYMORE-3123
               [UsageError]You don't have permission for this operation.

The error file is p4dtg-install-dir/repl/err-mapName.

Fix: correct your Perforce protections for the P4 DTG user, delete the error file, and restart replication.

#### Sample Protections Table

For a User that will replicate the list of files in all changelists, sample protection table entries are:

    list user p4dtg-user * //...
    open user p4dtg-user * //depot/.dummy

## Filter defect tracking issues or Perforce jobs

Will all issues be replicated or only a subset? Will you need to filter on something in addition to the project? Will the P4 Server hold jobs from multiple defect tracking instances?

segments are how filters are implemented in P4 DTG. The p4dtg-config file allows you define segments by identifying one SELECT field and selecting the possible values for the segment.

It is much easier to set this up when you design your replication than to retrofit later.

For an example of how to define a filter segment, see Example Jira implementation. If you are unsure and need further information, please contact Perforce Support or Perforce Consulting.

## Renaming or Moving Issues

P4 DTG cannot detect the rename of a defect tracking issue. For example, moving a Jira issue from one project to another is not detected by P4 DTG. This means a second job will be created. Cleaning up the original job is a manual process.

## Edit your Perforce Jobspec

Do not change the meaning of fields 101 to 105 in your Perforce jobspec:

- 101: job number field
- 102: job status field
- 103: modified by field
- 104: modified date field
- 105: job description field

Based on your previous analysis above, add fields as needed and change values (such as for Status).

### P4 DTG minimum functional Perforce jobspec

You need to have at least a minimum functional jobspec for P4 DTG:

- Fields 101 to 105

If your jobspec is missing the modified by (103) and Modified date (104) fields you will get the error: Server status: Missing P4 DTG Required Fields

- The four DTG_* fields
- Any additional fields required to store your defect tracker data

#### Example: P4 DTG minimum functional Perforce jobspec

    Fields:
    	101 Job word 32 required
    	102 Status select 10 optional
    	103 ModBy word 32 always
    	104 ModDate date 20 always
    	105 Description text 0 optional
    	106 DTG_FIXES text 0 optional
    	107 DTG_DTISSUE word 32 optional
    	108 DTG_ERROR text 0 optional
    	109 DTG_MAPID word 32 optional

    Values:
    	Status open/suspended/closed

    Presets:
    	ModBy $user
    	ModDate $now

## Form-in Job Trigger

We have previously mentioned using a form-in job trigger to customize job names, disallow non-P4 DTG user job creation, or to update specific fields.

For an example form-in job trigger, see Example form-in job trigger.

## Jira Custom Fields

The Jira Rest config file (default is `jira-rest-config.xml`) defines a custom field data's type (WORD, LINE, SELECT, TEXT) and access (RW or RO). In your Jira distribution, see the Configuring custom fields section in the `doc/jira/README.rest.txt` file.

The P4 DTG Jira Rest plugin only supports a specific set of field types. If your custom field's value is not replicated then it is likely not supported. Generally, only single-value custom field types are supported. Please contact Perforce Support to check if your field is supported.

## Performance Issues

P4 DTG polls each system at a specified interval (5 seconds by default). This is a tradeoff between developer expectations and defect tracker server load. The load on the Perforce server is minimal. The load on the defect tracker depends on the defect tracker. The replication interval is an attribute to the Mapping.

Your search for returned results