Example Jira implementation

This section describes how multiple Jira defect tracking system server instances can be connected to multiple Helix Core Server instances with P4DTG.

To get the most out of this section we recommend reading the following sections first so you have an overview of how P4DTG works:

Overview

Multiple Jira defect tracking system servers can be connected to multiple Helix Core Servers.

In this example,

Each Jira instance is a defect tracking source using the *ALL* value for the project
Jira segments are defined using the Jira '*Project*' field and the Jira custom field repl-yes. Configuration for Sources and Segments (by project) is done with the p4dtg-config. Adding repl-yes is a manual edit.
Helix Core Server segments are defined using the DTIssue jobspec field. DTIssue is populated when the issue is replicated because of the mapping definition.
ProjectZ in the Jira2 instance is not replicated

Add replication for your first Jira and Helix Core Server instances

These steps set up projects TPONE and TPTWO from Jira server Jira1 to the Helix Core Server Perforce1.

Create a global Helix Core Server jobspec:

Construct a jobspec containing all the Jira fields you want to replicate. The jobspec must contain a DTInstance select field that lists each Jira defect tracking system instance name. This instance name can be any value that identifies the instance. For example: JiraOne, JiraTwo.

Note

Every Helix Core Server instance should have this same jobspec. For an example, see Example - JobSpec.

Manually define Jira custom fields:

Define Custom fields using the jira-rest-config.xml file as a starting point. For an example, see Example - extract of jira-rest-config.xml for Jira Custom Fields.

Make a note of the definition of the ReplicateToPerforce SELECT field because we will use this as a second field for segmenting.

Identify which defect tracker projects will be mapped to which Helix Core Server:

For each Defect Tracking server instance, identify the projects to replicate, and for each project identify the target Helix Core Server instance for replication.

Create the first Jira source:
1. Add the Defect Tracking source with p4dtg-config b y setting For Project to *All*.
2. Edit the attributes of this source so that:
  - Workflow and field definitions points to the name of your jira-rest-config.xml file from Step 2
  - Allow Jira issue creation is set to n
Create Jira Segment for current Helix Core Server:

For the Jira source, Edit Segments and create a new segment from the *Project* SELECT field. Select all projects to be replicated to one Helix Core Server instance.

Image of the Edit segments for datasource dialog

Create the Helix Core Server source and edit the attributes of this source:

Set Generate job ids to y to create Helix Core Server jobs in the format <JiraIssueName>-<mapName>.

Specify whether it is a Unicode server or not.

If it is not a Unicode server, specify a character set, and set Replace missing character set mappings to y.

Note

For non Unicode Helix Core Servers, you can provide a character set for translation of the Jira UTF8 text. If you do not know which character set is required, we suggest you use winsansi.

Image of the Edit data source attributes dialog

Create a Helix Core Server segment:

For the Helix Core Server source, Edit segments and create a new segment from the DTInstance SELECT field and select the value representing the corresponding Jira instance for this Helix Core Server.

Image of the Edit segments for data source dialog

Create your mapping:

Map the Defect Tracking source segment you created previously to the Helix Core Server source segment. Copy fields as required (summary, description, etc.).

Copy the Jira source *Project* field to the Helix Core Server DTInstance field and map all Project Values to the DTInstance value. You should see only one DTInstance value because of the segment definition you created in Step 7.

Note

Although you must map all of the Project Values, only those within the Jira segment definition from Step 5 will be used.

Image of the Define select value mapping dialog

Add a new defect tracker or Helix Core Server

When mapping additional defect tracker or Helix Core Server sources:

If the Jira projects are in an existing source, just add a segment specifying the projects using Step 5 in the previous section (Step 4 is not needed).
If the Jira projects are not in an existing source, create a new source and segment.
If the Helix Core Server has an existing source, just add a segment specifying the DTInstance using Step 7 in the previous section (Step 5 not needed).
If the Helix Core Server does not have an existing source, create a new source and segment.

Segment on two fields (after p4dtg-config)

Important

When this change has been made, it is important that you do not edit the source from p4dtg-config again. If the source is edited, the changes will need to be applied to the file again.

To segment on two fields, manually edit the config files.

Edit the src-<source_name>.xml file in the config directory. In the <FilterSet> element of the appropriate segment, add another <FilterRule> for the additional field and pattern.

Example for segment jira-scm1.xml:

<FilterSets>
    <FilterSet
        name="jira-scm1">
        <FilterRules>
            <FilterRule
                field="*Project*"
                pattern="TPONE" />
            <FilterRule
                field="*Project*"
                pattern="TPTWO" />
            <FilterRule
                field="ReplicateToPerforce"
                pattern="Yes" />
            </FilterRules>

Replicate a new Project (after p4dtg-config)

Important

Because you have manually edited the Defect Tracking source config files, edit the config file manually. Do not edit the Defect Tracking Source within p4dtg-config. If the source is edited, the changes will need to be applied to the file again.

After initial setup, you can add additional projects and replicate them.

To replicate a new project:

Stop replication for the source and mapping you want to edit.
Edit the src file applicable to the defect tracking instance hosting the project to add a new <filterRule> with field="*Project*" and pattern="<newProjectName>".
Edit the map file applicable to this defect tracking instance. Add the new project to the application's '*Project*' <CopyMap> element list.

Status mirroring, from Helix Core Server back to Jira

Warning

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

Unless all of your projects use the identical workflow, status mirroring is not supported. This is because of the large number of workflows you would have to describe and maintain.

The recommended method is to copy the Helix Core Server job status back to another Jira custom field. In the future, you can implement functionality on the Jira side to detect the Helix Core Server job status change and alter the Jira status appropriately.

Additional notes on creating and editing Helix Core Server Jobs

The Generate Job Ids attribute creates the Helix Core Server job name to match the Jira name using the format <JiraIssueName>-<mapName>. To use a different naming convention by using a form-in job trigger, see Example form-in job trigger.

Users can continue to create Helix Core Server jobs if a mapping is in place. However, even if the user sets the DTInstance field to force replication, a Jira issue will not be created. This is because the Jira source attribute Allow jira issue creation is set to no.

Example configuration files

Warning

While the syntax of these examples is correct, the examples include some values that cannot work. Adjust the configuration for your P4DTG installation before attempting to use these examples in testing or production.

Example - JobSpec

 # A Perforce Spec Specification.
 #
Fields:
    101 Job word 32 required
    102 Status select 10 required
    103 DetectedBy word 32 required
    104 DetectedOn date 20 required
    105 Description text 0 required
    106 JiraStatus word 10 optional
    115 Summary line 60 required
    110 ModifiedBy word 32 always 
    111 ModifiedOn date 30 always
    112 Type select 12 required
    113 AssignedTo word 32 optional
    114 Priority select 10 optional
    116 Comments text 0 optional
    120 EstimatedFixTime line 0 optional
    122 PlannedClosingVersion line 0 optional
    124 CurrentEffort line 0 optional
    146 DTG_FIXES text 0 optional
    147 DTG_DTISSUE word 32 optional
    148 DTG_ERROR text 0 optional
    149 DTG_MAPID word 32 optional
    130 DTInstance select 10 required
Values:
    Status Open/InProgress/Reopened/Resolved/Closed
    Type NewFeature/Task/Improvement/Bug/Sub-task
    Priority Major/Minor/Critical/Trivial/Blocker
    DTInstance JiraOne/JiraTwo/None
Presets:
    Status Open,fix/Closed
    DetectedBy $user
    DetectedOn $now
    Description $blank
    Summary $blank
    ModifiedBy $user
    ModifiedOn $now
    Type Bug
    DTInstance None

Example - extract of jira-rest-config.xml for Jira Custom Fields

<CustomFields>
    <CustomField name="Status From Perforce" type="LINE" access="RW" />
    <CustomField name="Current Effort" type="LINE" access="RO" />
    <CustomField name="Test Custom Field Date" type="DATE" access="RO" />
    <CustomField name="ReplicateToPerforce" type="SELECT" access="RW">
        <Option value="Yes" />
        <Option value="No" />
    </CustomField>
</CustomFields>

Example - Jira Rest source xml config files

<?xml version="1.0" ?>
<DTGConfiguration
    version="1"
    updated="2011/05/16 14:27:32 UTC">
    <DataSource
        type="DTS"
        plugin="JIRA-REST"
        nickname="Jira"
        server="https://my-company-jira.atlassian.com"
        user="[email protected]"
        epassword="####"
        module="*All*"
        moddate_field="Updated"
        moduser_field="*Not Supported*">
        <FilterSets>
            <FilterSet
                name="jira-scm1">
                <FilterRules>
                    <FilterRule
                        field="*Project*"
                        pattern="TPONE" />
                    <FilterRule
                        field="*Project*"
                        pattern="TPTWO" />
                    <FilterRule
                        field="ReplicateToPerforce"
                        pattern="Yes" />
                </FilterRules>
            </FilterSet>
        </FilterSets>
    </DataSource>
</DTGConfiguration>

Example - Perforce source xml config file

<?xml version="1.0" ?>
<DTGConfiguration
    version="1"
    updated="2011/05/17 14:11:33 UTC">
    <DataSource
        type="SCM"
        plugin="Perforce Jobs"
        nickname="P4"
        server="20124"
        user="p4dtg"
        epassword="###"
        module="Jobs"
        moddate_field="ModifiedOn"
        moduser_field="ModifiedBy">
        <Attributes>
            <DataAttr
                name="sub_missing"
                value="y" />
            <DataAttr
                name="gen_jobname"
                value="y" />
        </Attributes>
        <FilterSets>
            <FilterSet
                name="Instance1">
                <FilterRules>
                    <FilterRule
                        field="DTInstance"
                        pattern="JiraOne" />
                </FilterRules>
            </FilterSet>
            <FilterSet
                name="Instance2">
                <FilterRules>
                    <FilterRule
                        field="DTInstance"
                        pattern="JiraTwo" />
                </FilterRules>
            </FilterSet>
        </FilterSets>
    </DataSource>
</DTGConfiguration>

Example - mapping xml config file

<?xml version="1.0" ?>
<DTGConfiguration
    version="1"
    updated="2011/05/16 14:32:28 UTC">
    <DataMapping
        id="P4toJira"
        scm_id="P4"
        scm_filter="Instance1"
        dts_id="Jira"
        dts_filter="jira-scm1"
        mirror_conflicts="ERROR">
        <FixRule
            dts_field="Fix"
            copy_type="APPEND"
            file_list="1"
            change_number="1"
            description="1"
            fixed_by="1"
            fixed_date="1" />
        <ScmToDtsRules>
            <CopyRule
                scm_field="Status"
                dts_field="Status From Perforce"
                copy_type="LINE"
                truncate="0" />
        </ScmToDtsRules>
        <DtsToScmRules>
            <CopyRule
                scm_field="AssignedTo"
                dts_field="Assignee"
                copy_type="WORD"
                truncate="0" />
            <CopyRule
                scm_field="DetectedBy"
                dts_field="Reporter"
                copy_type="WORD"
                truncate="0" />
            <CopyRule
                scm_field="JiraStatus"
                dts_field="Status"
                copy_type="WORD"
                truncate="0" />
            <CopyRule
                scm_field="Comments"
                dts_field="Comments"
                copy_type="TEXT"
                truncate="0" />
            <CopyRule
                scm_field="Summary"
                dts_field="Summary"
                copy_type="LINE"
                truncate="0" />
            <CopyRule
                scm_field="Description"
                dts_field="Description"
                copy_type="TEXT"
                truncate="0" />
            <CopyRule
                scm_field="DTInstance"
                dts_field="*Project*"
                copy_type="MAP"
                truncate="0">
                <CopyMap
                    value1="TPTWO"
                    value2="JiraOne" />
                <CopyMap
                    value1="TPONE"
                    value2="JiraOne" />
            </CopyRule>
        </DtsToScmRules>
    </DataMapping>
</DTGConfiguration>