Manage cross references

This topic describes how to work with cross references. Cross references store the relationship between synchronized items.

Import or export cross references

Cross references are artifact pairs {source artifact id and target artifact id} that describe the relationships between pairs of synchronized items in a syncset. The synchronized items include a source project, source type, target project, and target type.

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.

Cross references are managed at the connection level.

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.

Back to top

Cross reference file format

A cross reference file, CrossReferences.xml , serves as a set of instructions for modifying cross references. If a particular 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 constitute its removal.

Wherever possible, we recommend using the built-in utilities to manage cross references, as described above. However, under some circumstances, 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>

Back to top

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

Back to top