How To Connect Perforce and Jira

Perforce Defect Tracking Gateway — Any% Speedrun

Published in

XRLO — eXtended Reality Lowdown

11 min readApr 21, 2021

Changes in how we work over the last year have brought me a new appreciation for reliable communication between departments. When we were in the office, it was all too easy to simply ask a colleague questions such as “How are we getting on with that feature?” or “Did we get to that bug?” as we walked past on our way to get a coffee.

Perforce Tracking Gateway (P4DTG) reduces the communication friction and overhead across all our teams and ensures information consistency between our agile planning system and issue system — Atlassian’s Jira, and our version control system — Perforce Helix, closer together.

Both of these systems are core parts of how we manage and deliver projects at REWIND. In the past, we have attempted this connection by manually inserting the ticket ID into the commit description field and adding comments to the Jira ticket referencing the changelist numbers. Perforce’s Defect Tracking Gateway allows these reference links to be automatically created between changelist commits and tickets, replicating relevant information between the two platforms.

My hope is that this article will provide you with a primer on what P4DTG does and allow you to bootstrap your integration.

Jira Prep

Create Service User for integration

This does consume a licence, however, anything that can change or otherwise modify content requires one too. You can use an existing user, but any updates from Perforce will be posted as that user.

When creating the user, it doesn’t need admin access or any advanced privileges. Just Site and Jira Software access with the Basic role.

Generate API Token

Give the token a sensible name, and remember to copy the access key somewhere as this is the only time you will be shown it. If you forget to do this, you’ll need to revoke the old one and recreate it. Ask me how I know!

That is all the work you need to do in Jira, other than possibly setting a sweet user icon!

Perforce Prep

As with the Jira user, it is best to have a separate user to manage the interaction with the jobs system and again, this will consume a licence. This user doesn’t require any special access beyond being able to interact with the database and all depots (read/write) so you don’t need to give them any administration privileges here either.

Perforce Defect Tracking Gateway (P4DTG)

Alright, now let’s glue these things together.

*Always* run P4DTG-Config with elevated permissions — It needs to write configuration files into ‘C:\Program Files’ which is a protected location, and install the synchronisation service.

Defect Tracking Sources

There aren’t many configuration options needed to get yourself up and running on the defect gateway side. Give it a name (this will be used in the mappings later, so shorter is better), and the type should be JIRA-REST for cloud and simply Jira for a locally hosted defect tracker.

There are several options for custom trackers, but those are out of scope for this walkthrough.

Server: is the full name, including the https:// portion and any custom ports required.

User Name: is the name set up in the first part for the Jira account.

Password: this one can trip people up. When Perforce originally published the defect tracker you could use simple login credentials, since then Atlassian has moved to tokens for API access, so this should be the access token you generated (you remembered to save it, yes?)

Validate these details with the Check Connection button and if that returns Valid Connection to the server, we are ready to continue.

At this point, you will be asked which projects you wish to link. Unless you wish to investigate Segmentation to limit the results for your Jobs, it’s best to select *ALL* at this point, with the understanding that we will look at Perforce filters momentarily. It’s worth noting that once you perform a mapping, you cannot change this field.

We have a fairly unique configuration here at REWIND, so we may revisit Segmentation Field Mapping in the future with a follow-up article.

p4 jobspec

In preparation for creating the job entries in the Perforce database, we need to configure the jobspec. These provide the fields required to map a job with a defect in Jira.

At a minimum, we need the following:

nnn DTG_FIXES text 0 optional

nnn DTG_DTISSUE word 32 optional

nnn DTG_ERROR text 0 optional

To dissect these lines the ‘nnn’ is a unique identifier, and priority, for the spec, by using nnn it will simply assign the next available number. As long as they are unique, you can largely ignore this.

DTG_FIXES, DTISSUE and ERROR are the fields to generate and map to when adding Jobs to the database. This is what the API and synchronisation tasks will be looking for, so are mandatory fields.

Next up we have text and word, these are the data types expected for each of the fields, an exhaustive list is available from the P4 Command Ref but simply put, a word is a block of characters (max length 32 in this case) with no spaces, and text is a block of words.

The last entry on this line is optional, which means that there is no restriction on what data is entered into those fields (even empty), has no default value and will copy or mirror to/from the defect tracker based on mappings we shall configure later.

To add these entries, pull open a terminal on a machine with P4 CLI tools and administration access then issue the “p4 jobspec” command. It will open up a notepad window with the temporary file and allow you to configure the jobs specification.

At this point, I would like to point out some entries that are great quality-of-life options when we perform the mapping operation later. I’ll go into details then, but you might be able to get an idea of what they do from their names.

nnn Owned_By text 0 optional

nnn Priority select 10 optional

nnn Assignee text 0 optional

To support Priority as it is a select data type, you will also need to ensure there is an option in the Values list. I added this below the default Status line.

Priority highest/high/medium/low/lowest

Once these entries have been made, save the notepad and then close it. This will then add these configuration changes to the server. We can now move on to linking P4DTG to Helix Core.

Perforce Server Sources

As with the Defect Tracker configuration, you need a Server Address, Username and Password. As you can see in this screenshot, the tracking gateway is being run on the same machine as Helix Core, but it can of course be anywhere that can access your server.

Validate your connection and it will also retrieve the jobspec configured in the previous step. At this point, it’s important to confirm it has populated the Modified Date and Modified By reference fields.

Once this is confirmed, we can perform a few small changes. Click the “Edit Attributes…” button and you will be presented with the following screen.

Generate job ids — Defaults to “n” and will create jobs with a default identification (jobNNNNNNN). For us at least, it was preferable to have the ID reflect that of the Jira ticket ID.

Non-Unicode server character set — may or may not be a requirement and will depend on your Helix Core configuration settings. We required translating the defect trackers character set to ‘winansi’ for ours. If this is the case, you should also set Replace missing character set mappings to “y” to present a valid character in your job details.

Gateway Mapping

*Important Note* Gateway mappings are critical to the successful operation of P4DTG. Any changes in these fields will cause the synchronisation process to halt. This should be flagged with whoever is responsible for your Jira Workflows so that they are aware of which fields should not be altered.

Once you have valid connections to both your servers, it’s now time to create a mapping between the various fields and data sources on each side. I’ll describe ours here, but this is where your own Jira workflows will come into play. Now is a good time to make sure you are familiar with how you progress a ticket through your ticket server.

Field mappings come in 3.5 flavours. Entries marked with an asterisk “*” are read-only in the context of that server, so not everything can be replicated between the systems.

DEFECT TRACKER <- MIRRORED -> PERFORCE data is synchronised in both directions between Jira tickets and Perforce Jobs.

DEFECT TRACKER -> COPIED -> PERFORCE data is only replicated from Jira tickets over-writing any existing data in Perforce Jobs.
PERFORCE -> COPIED -> DEFECT TRACKER data is only replicated from Perforce jobs over-writing any existing data in Jira tickets.
PERFORCE FIX DETAILS -> COPIED -> DEFECT TRACKER specific mapping for P4 change list(s) associated with this Perforce Job to be replicated to the Jira ticket. Sorry, no, I don’t know why this is separate from the above Perforce-to-Defect link P4Fix is the only thing that goes in here.

The basic method of mapping fields is to select from either the Defect Tracker or Perforce field lists, and then click the “Copy To” button. P4DTG will then present a dialogue with available targets that are likely to match from the list of remaining unmapped options.

Reporter -> Owned_By this is where some of the optional jobspec entries start to pay off. Here we have the Jira ticket reporter copied to Owned_By in the Perforce Job. This means whoever is working on the job can easily see who is their first point of contact for questions, without having to leave Perforce to pull up ticket details from Jira.

Assignee -> Assignee is another fairly straightforward map, but again one of our optional jobspec entries. If your Jira and Perforce servers have the same Usernames they will automatically match, but if not they are easily used in filters.

Summary -> Description takes the Jira ticket title and maps it to the Description of the Perforce Job.

Priority -> Priority (map) another optional jobspec, assists in sorting by most important jobs where applicable. As these are configurable in Jira, it’s a good idea to mirror them to Perforce for consistency, but it’s not mandatory.

Status -> Status (map) I’ve presented this to demonstrate how you can perform multiple mappings to the same items and to highlight why these should not be changed on Jira. As shown I have mapped “To Do” and “In Progress” as “open” and Done as “Closed”. As previously mentioned, Status is a read-only field on the defect tracker, there is no way to “close” the ticket from the Perforce Job interface, as Jira is part of a larger workflow (you may need to add working times, or mark it for QA Approval, for instance).

P4Fix -> Fix (Append) This will take your changelist submission and add the details to the Jira ticket. By default the Fix Description is not ticked, I do recommend it as it makes the comment entries in the Jira ticket so much more useful.

All that’s left to do is apply the settings and start the replication. You’ll need to pick a time to start your initial replication from. This could be the very beginning of your Jira server’s life, but that is likely to include quite a lot of closed and stale tickets. The last couple of months is usually sufficient, and as the system uses the last-modified date as a trigger to synchronise, if any of those stale tickets are updated they will be pulled across as fresh jobs accordingly.

Enter the date, tick the box, and hit “start replication”. All being well, you shall receive a popup declaring P4TDG service has been installed.

Depending on how many tickets fall inside the scope of your initial replication, you should expect to see them come through into the jobs screen within a few minutes. Once that initial download has completed the default polling time is 5 seconds, so you are never far away from an update.

Submitting a changelist to a job

This is where it all comes together. You can access the jobs interface in a couple of places, but this is where it gets the most use. In the changelist interface, you have access to the browse button, from which you can select your job. When you submit your changelist, it also attaches this data to the ticket as a comment which looks like this.

Ta-Daaaaaa! You now have a fully working interface between your Jira Defect Tracker and your Perforce Helix server.

Bonus Round — Perforce Job Filters

Filters make using the Job list significantly easier, and this is where some of the additional fields configured earlier start to earn their keep.

From the Select Jobs browser (or anywhere the job search interface is invoked) you can use the query builder to filter your results so you don’t have to scroll through all the tickets that have been ingested by the jobs system. Don’t forget to save them from the rightmost funnel button so they are always handy.