Configuring P4DTG

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:

  1. Define defect tracking sources
  2. Define Helix Server sources
  3. Map job fields to defect fields, optionally including replication of fixes
Note

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.

Defining defect tracker sources

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:

  1. Click New. The Add Defect Tracking Source dialog is displayed, as shown in the following figure.

  2. 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:

    • For HP Quality Center, specify host:port.
    • For Jira Software Cloud, specify your Jira Software Cloud server: https://<your-site-name>.atlassian.net.

    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:

    1. Go to https://id.atlassian.com/manange/api-tokens
    2. Log in with your Atlassian administrator credentials.
    3. Click Create and name your API token something recognizable, for example p4jira.
    4. The API token is displayed in a dialog.
    5. Copy the token and paste it into the Password field. It is a good idea to save the API token somewhere safe in case you need it in the future.

    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.

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

  4. Choose the defect tracker project from the Project drop-down list.

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

Configuring plug-in attributes

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.

Defining Helix Server sources

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:

  1. Click New. The Add Perforce Server Source dialog is displayed, as shown in the following figure.

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

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

  4. Click OK to save your entries and dismiss the dialog.

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.

Filtered replication

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:

  1. On the Helix Server Source or Defect Tracking Source tab, click Edit Segments.... The Edit Segments dialog is displayed.
  2. Specify the field to be used to filter defects by choosing the field from the Segment using SELECT field list. (The fields listed are SELECT fields returned by the data source plugin.)
  3. To add a segment, click New.... In the New Segment dialog, specify a name for the segment and click OK.
  4. Specify the values that you want to include in the segment by moving them from the Unassigned options column to the Included options column.
  5. To save your segment definition and dismiss the dialog, click OK.
  6. To save your changes, click OK on the Helix Server Source or Defect Tracking Source tab.

Mapping data between Helix Server and P4DTG

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:

  1. On the Mappings tab, click New. The Add New Mapping dialog is displayed.

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

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

  4. Choose the target field to which you want to map the selected source field and click OK.
  5. 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.

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

  7. Click OK to save your entries and dismiss the dialog.
  8. On the Gateway Mappings tab, click Apply to save your changes.

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.

Mapping fix data

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:

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

  2. Check the fields that you want transmitted to the defect tracker, then click OK to save your changes and dismiss the dialog.