Plan your replication

Tip

Before you run p4dtg-config, read this section.

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

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

Note

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.

Tip

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)

Warning

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 P4DTG 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 P4DTG's config files
- permit the Jira P4DTG 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:

Copy the defect tracker Status into a new Perforce job field (for example, JiraStatus)
Alter the Helix Core Server jobspec Status to be a simple list: open, inprogress, closed.
Copy the Helix Core Server job Status values to a new custom field called P4Status in the defect tracker.
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.

Warning

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 P4DTG configuration, and possibly the jobspec, whenever the source system select values change.

Job numbers

There are three options for creating your Perforce job numbers:

Default Perforce: jobXXXXXX, starting at job000001
DTG configures:<dt-issue-id>-<mapName> where <mapName> is set in the p4dtg-config tool
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 Helix Core 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 P4DTG 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 P4DTG 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 P4DTG user must be allowed to update jobs. For information about form-in job triggers, see Form-in Job Trigger

Tip

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 Helix Core 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 Helix Core 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, P4DTG creates a special status/resolution field for those defect trackers. This special P4DTG field should be used for that purpose

Identify a User for Each System

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

Important

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

Permissions for defect tracker P4DTG user

The defect tracker user requirements are dependent on defect tracker, but typically you need administrator privileges to configure P4DTG 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.

Helix Core Server user requirements

User Type

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

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

Important

Job updates from the P4DTG 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 P4DTG 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 P4DTG 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 Helix Core Server hold jobs from multiple defect tracking instances?

segments are how filters are implemented in P4DTG. 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

P4DTG cannot detect the rename of a defect tracking issue. For example, moving a Jira issue from one project to another is not detected by P4DTG. 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).

P4DTG minimum functional Perforce jobspec

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

Fields 101 to 105

Tip

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

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

Example: P4DTG 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-P4DTG 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 P4DTG 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

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