Edit and import cross reference files

This topic describes how to edit cross reference files and how to import and export the files.

Overview

A cross reference is an internal record that maps an item in one system to its corresponding item in another system. The list of cross references lets Connect keep the items synchronized and preserve the relationships between the systems.

Cross references are different from field mappings. Cross references identify corresponding items. Field mappings determine how fields, such as Name, Status, or Description, are copied between systems.

A cross reference operates in the following way:

  1. Read an item. Connect reads an item from one endpoint, such as Jira, Azure DevOps, ALM/QC, Octane or another supported system.

  2. Find or create the corresponding item. During synchronization, Connect determines which item on the other endpoint corresponds to the source item.

  3. Store the relationship. Connect records the relationship between the unique ID on the first endpoint and the unique ID on the second endpoint in its internal cross-reference database.

  4. Save for future synchronizations. When Connect sees the item again, the cross reference helps it identify the already-associated item on the other system, instead of treating it as a new, unrelated record.

In the following example, the cross reference tells Connect that Jira item SE-123 and ALM/QC item 9876 are the same associated business item for synchronization purposes.

System A Cross Reference System B
Jira Story ID = SE-123 SE-123 <->9876 ALM/QC Requirement ID = 9876

Duplications

If an item was synchronized between two systems, but there is no matching cross reference for the item in the database, Connect will create a duplicate. Without the cross reference, Connect cannot recognize or detect the older, previously synchronized item.

This is especially relevant if you migrated from another synchronization solution to Connect, without having migrated the cross references. Cross references must also be migrated.

Duplicates may also be created if a cross-reference is deleted or corrupted.

Editing cross references

Cross references are stored internally in a file titled CrossReferences.xml. This file stores a list of all cross references to modify when synchronizing. If a cross reference pair is not included in the XML file during import, it will not be modified. The absence of a cross reference pair from the XML file does not indicate that it was removed. It only indicates that no changes will be made to the existing cross reference.

The sections below describe how to manually edit this file. For details on how to edit cross references directly from the Connect user interface, see Manage cross references.

Import or export cross references

After you synchronize items between data sources, their relationship is stored internally as a cross reference. Cross references can be exported to an XML file. You can manually edit cross references in the XML file, and import them back into the same connection.

To export or import cross references:

  1. Click the Modify connection button adjacent to the connection name.
  2. Select Import Cross References, Export Cross References, or Export Cross Reference Template.

Cross reference file format

Wherever possible, we recommend using the built-in utilities to manage cross references. In some cases, however, you may need to manually modify and import cross references. This section shows a typical format of the CrossReferences.xml file used for import and export.

  • The adds section includes the source-target references to be added.
  • The removes section includes source-target references to be removed.

  • When the same item is involved in both an add and a remove, perform the remove operation first.

Copy code 
<?xml version="1.0" encoding="UTF-8"?>
<sets>
   <set syncsetguid="f5d70a92-eb4c-4de1-b9f5-de83968d9760">
      <source type="Defect" project="scen2_workspace" criteria="Type Rule: AND Application modules EQUALS 3002" />
      <target type="Bug" project="MFCSER:MFCSER board" criteria="Type Rule: " />
      <adds>
         <items>
            <item>
               <source>a source item id</source>
               <target>a target item id</target>
            </item>
         </items>
      </adds>
      <removes>
         <items>
            <item>
               <source>a source item id</source>
               <target>a target item id</target>
            </item>
         </items>
      </removes>
   </set>
   <set syncsetguid="a5d75269-4cce-46e0-8fa4-571cb7dd909f">
      <source type="Defect" project="scen2_workspace" criteria="Type Rule: AND Application modules EQUALS 3001" />
      <target type="Bug" project="MFCRES:MFCRES board" criteria="Type Rule: " />
      <adds />
   </set>
</sets>

Import/export use-case

This section describes a common use-case for exporting and importing cross references.

A Jira project key was changed from COR to RIC. The required modification was made to the connection's project mapping through the user interface. However, all cross references need to be changed to the new key to ensure continuous updates.

To complete the process:

  1. Click the Modify connection button Modify connection button adjacent to the connection name.

  2. Select Export Cross References. A CrossReferences.xml file is generated.

    The project mapping in the syncset references the new key, RIC and board name RIC Board, since the project mapping was already modified in the user interface. The target cross reference IDs still reference the old key, COR.

    The content of the XML file will resemble the following:

    Copy code 
    <?xml version="1.1" encoding="UTF-8" standalone="yes"?><sets>
        <set syncsetguid="c230a61a-25b8-4342-804b-e7f6f7fa783d">
            <source type="Test" project="ED" criteria="Type Rule: NOT"/>
            <target type="TestCase" project="RIC:RIC board" criteria="Type Rule: "/>
            <adds>
                <items>
                    <item>
                        <source>2</source>
                        <target>COR-41</target>
                        <childItems/>
                    </item>
                    <item>
                        <source>4</source>
                        <target>COR-42</target>
                        <childItems/>
                    </item>
                    <item>
                        <source>1</source>
                        <target>COR-39</target>
                        <childItems/>
                    </item>
                </items>
            </adds>
        </set>
        <set syncsetguid="77cb40e8-7569-46ef-90b8-79b1cbf6f87a">
            <source type="Defect" project="ED" criteria="Type Rule: "/>
            <target type="Bug" project="RIC:RIC board" criteria="Type Rule: "/>
            <adds>
                <items>
                    <item>
                        <source>749</source>
                        <target>COR-119</target>
                        <childItems/>
                    </item>
                    <item>
                        <source>753</source>
                        <target>COR-123</target>
                        <childItems/>
                    </item>
                    <item>
                        <source>750</source>
                        <target>COR-120</target>
                        <childItems>
                            <childItem>
                                <source>comment750comment1</source>
                                <target>comment10118</target>
                            </childItem>
                        </childItems>
                    </item>
                </items>
            </adds>
        </set>
    </sets>
  3. Back up the CrossReferences.xml file.

  4. Remove all target cross reference IDs that still reference the old key, COR:

    1. Edit the CrossReferences.xml file and perform a Search and Replace all instances of adds with removes. Save the file.

    2. Click the Modify connection button adjacent to the connection name and choose Import Cross References. Confirm the import.

  5. Add the amended cross references with the new key:

    1. Edit the CrossReferences.xml file and perform a Search and Replace all instances of removes with adds.

    2. Replace all instances of COR- with RIC-. Note: When doing a search and replace, ensure that only the intended text is replaced. If in doubt, verify each replacement manually.

    3. Save the file.

  6. Click the Modify connection button adjacent to the connection name and choose Import Cross Reference. Choose the CrossReferences.xml file that you just modified. Confirm the import.

  7. Validate the cross references:

    1. Click the Modify connection button adjacent to the connection name and choose Export Cross Reference.

    2. Open the CrossReferences.xml file that was generated and inspect it. Make sure that the pairs are correct.