To specify how data is replicated between Helix Server and the defect tracker, you use the P4DTG configuration control panel. To launch the configuration control panel, double-click p4dtg-config.exe. To configure replication, perform the following steps:
The data you enter, change, or delete using the P4DTG configuration control panel is stored (to configuration files on disk) when you click Apply or OK on one of the main tabs. Clicking OK on the data entry dialogs stores your entries temporarily, but they are not stored permanently until you click Apply or OK on one of the main tabs.
For defect trackers, the connection information depends on the requirements of the defect tracker server. For HP Quality Center, the connection information is specified using the syntax host:port. In addition to specifying the connection information, some defect trackers (such as HP Quality Center) require you to specify the project to which you are mapping Helix Server jobs.
To add a defect tracking source:
Click New. The Add Defect Tracking Source dialog is displayed, as shown in the following figure.
Enter the required information as follows:
Field | Description |
---|---|
Name |
An alias for the source and its associated information. Specify the defect tracker type by choosing the type from the drop-down list (if you have installed plug-ins for multiple defect trackers). To connect to a Jira Software Cloud server, select JIRA-REST from the drop-down list. |
Server |
The information required by the defect tracker for client connections. The format is determined by the defect tracker, for example:
|
User name |
The user name to be used to connect to the defect tracking server. For Jira Software Cloud, <your-atlassian-account>. |
Password |
The password for the specified user, if required. Jira Software Cloud: the password is a special API token. To obtain your API token:
|
Reference Field |
The fields that are required to keep Helix Server and the defect tracker synchronized. |
Modified Date Field |
The date that the issue was last changed. |
Modified By Field |
The user that last changed the issue (if supported by your defect tracker). |
The plugin for your defect tracker might enable you to specify other proprietary settings; if so, click Edit Attributes... to change these settings. For details, see Configuring plug-in attributes.
If you intend to use filtered replication for this data source, you must define segments. To define segments, click Edit Segments.... For details, see Filtered replication.
Click Check connection and retrieve fields. If you have correctly specified valid values, the dialog displays a success message and the reference fields retrieved from the defect tracker.
If a connection error is displayed, correct your entries and click Check connection and retrieve fields again.
Choose the defect tracker project from the Project drop-down list.
Click OK to save your entries and dismiss the dialog.
Your newly-defined defect tracking source is now displayed in Defined Defect Tracking Sources.
To edit a defect tracking source, click the source in the Defined Defect Tracking Sources list, then click Edit. To delete a defect tracking source, click the source in the Defined Defect Tracking Sources list, then click Delete. The source is marked for deletion, as indicated in the Defined Defect Tracking Sources list. To finish deletion, click OK or Apply. To undo deletion, click the source marked for deletion, then click Undelete.
Specific defect trackers might require settings outside of those required to configure replication. For example, Bugzilla enables you to specify a MySQL database other than its default database. To configure settings for specific plug-ins, edit its attributes.
To edit attributes, click Edit Attributes.... For details about a specific field, click its help button (which is labeled with a question mark). Attributes and valid entries are specific to each plug-in, and your defect tracker might not require you to set attributes.
Default attribute settings, which are provided by the plug-in, are displayed in light gray. Required attributes are marked with an asterisk (*). Attribute settings are validated by the plug-in when you click OK.
To define Helix Server sources, you specify the information required to connect to the server (the host machine and TCP/IP port) using the syntax host:port. The default host is localhost, and the default port is 1666.
To add a Helix Server source:
Click New. The Add Perforce Server Source dialog is displayed, as shown in the following figure.
Enter the server connection details as follows:
Field | Description |
---|---|
Name |
An alias for the Helix Server and its associated connection information. |
Server |
The name of the Helix Server host machine and the port on which it is running. Specify as host:port; for example 4host 1667. The server host defaults to localhost and the port defaults to 1666. |
User name |
The Helix Server user name used by the replication engine to connect to the Helix Server. Important
To ensure that you can distinguish jobs modified by the gateway, create a dedicated Helix Server user to be used only by the gateway. The user name must be used only for defect replication. Do not use this user name for any other purpose. Ensure that the user name is neither a prefix nor a suffix of any other user name. For example, if you have a user named admin-logger, do not use admin or logger as the user name. |
Password |
The password for the specified user, if required. |
If you intend to use filtered replication for Helix Server jobs, you must define segments. To define segments, click Edit Segments.... For details, see Filtered replication.
Click Check connection and jobspec. If you have entered valid values, configuration control panel retrieves the job specification for the specified server and displays the names of the reference fields, which are the Helix Server job data fields required for replication.
If a connection error is displayed, correct your entries and click Check connection and jobspec again.
If the Server status field says that the server is not configured, you must add the required fields to the Helix Server job specification. For details, see Adding required fields to the Helix Server job specification.
Your newly defined Helix Server source is now displayed in Helix Server sources.
Helix Server sources that have been edited and need to be saved are displayed in bold.
To edit a Helix Server source, click the source in the Helix Server sources list, then click Edit. To delete a Helix Server source, click the source in the Helix Server sources list, then click Delete. The source is displayed in bold, marked for deletion, but is not deleted until you click OK or Apply. To undo deletion, click the marked source, then click Undelete.
To replicate sets of selected defects from a single data source to multiple other defect trackers or version control systems, you define segments. For example, if you use Bugzilla to track your database bugs and HP Quality Center to track your Web application bugs, you can create separate segments for each project and replicate them independently. You can create a segment named “Database” that selects all Helix Server jobs with the Subsystem field set to “db” and another segment named “Web Application” that selects all Helix Server jobs with the Subsystem field set to “webapp.”
To use segments for replication, choose the segment when defining mappings on the Gateway Mappings tab. Note the following requirements:
To create a segment for a Helix Server or Defect Tracking Source:
After defining Helix Server sources and defect tracker sources, you must specify how data is replicated between them when a job or issue is changed. In addition, you can configure the data that is transmitted to the defect tracker when a job is fixed in Helix Server.
Before entering mappings, define the relationships between the data in Helix Server jobs and the data stored by your defect tracker. To display the fields defined for Helix Server jobs, issue the p4 jobspec command. (For details about modifying the job specification, see the Helix Core Server Administrator Guide: Fundamentals.) For details about the data that is stored by your defect tracker, consult the documentation supplied by the defect tracker vendor.
Fields can be replicated in two ways:
Every field has a data type, and mappings between fields must ensure that the data types are compatible, as described in the following table.
Field | Description | Valid target data types | |
---|---|---|---|
Copy | Mirror | ||
word |
A one-word entry |
word, line or text |
word |
line |
A single line of text |
line or text For targets of type word, only the first word is copied. |
line |
text |
Multiple lines of text |
text or line For targets of type line, only the first line is copied. For targets of type word, only the first word is copied. |
text |
date |
A date and time |
date |
date |
select |
A field that is assigned one of a specified set of values. The number of possible values much be identical for Helix Server and the defect tracker. |
select, word, line, text For select fields, all possible values must be mapped. |
select All possible values must be mapped. |
To add a set of mappings:
On the Mappings tab, click New. The Add New Mapping dialog is displayed.
Enter a name for the mapping, and choose the Helix Server source and the defect tracking source that you want to map. Click OK. The Edit Perforce-Defect Tracker Mapping dialog is displayed as shown in the following figure.
List of Change Numbers : LINE * and Fix Details : TEXT (append) * are the fields used for replicating Helix Server fix information.
The Edit Mapping dialog contains the following fields:
Read-only fields are indicated by an asterisk.
For each field you want to replicate, select the field and choose the method of replication, as follows:
When you click a Copy or Mirror button, a list of available target fields is displayed, as shown in the following diagram.
If no valid target fields exist, the list is empty.
If the target field is a select field (meaning a field that can contain one of a defined set of values), the Define Select Value Mapping dialog is displayed, as shown in the following figure.
Bold type indicates unmapped fields.
Specify the correspondence between values in Helix Server and those in the defect tracking system by selecting the Helix Servervalue and its corresponding defect tracker value and clicking Map to. Your mappings are listed in the Current Select Value Mappings field.
All the values of the left-hand list must be mapped. You can save incomplete mappings and exit, but the replication engine cannot run until you have mapped all values. If you save incomplete mappings, the unmapped values are displayed with “(unmap)” in the Field Mappings pane, to indicate that you need to map them.
After you map select fields, the field pair is listed in the Field Mappings pane, indicated by “(map)”. To view the value mappings, place the cursor over the field pair—the mappings are displayed in a tooltip. To change the values mapped for a field, click the field in the Field Mappings pane and click Edit Value Mappings. To remove a mapping, click the mapping in the Field Mappings pane, then click Unmap.
In Helix Server, you can associate a job with a changelist. When the changelist is submitted, the job status is changed, usually to a “closed” status, to indicate that the changes being submitted fix the problem reported in the associated job.
P4DTG enables you to configure how data from fixes submitted in Helix Server are transmitted to the defect tracker. To add fix mappings, click Fix Details in the Perforce Fields list.
To select the Helix Server data that is to be transmitted to the defect tracker when a job is fixed:
On the Mappings tab, scroll to the bottom of the Field Mappings list and select the desired mapping under PERFORCE FIX DETAILS > COPIED > DEFECT TRACKER. The Select Fix Details to Map dialog is displayed, as shown in the following figure.