Insert a Cross-reference

Cross-references let you link to Headings or Work Items within a Document.

When clicked, they scroll right to their target.

To distinguish them from Live Links, cross-references are underlined with a dashed gray line.

They are underlined with a solid black line in exported PDFs.

Note:

  • Unlike Live Links, cross-references are only navigational links and do not reflect an item's Status or Severity.

  • The Copy Cross-reference option is only visible for saved items.

  1. Scroll to the Heading or Work Item that you’d like to reference.

  2. Referring to the figure below, click the Heading or Work Item icon in the left margin (1), hover over Copy (2), and finally click Cross-reference (3).

    Tip:

    Always use the method above to copy cross-references. If you copy them any other way, they may not work as expected.

  3. Press Ctrl+C, or the equivalent copy-to-clipboard shortcut for your operating system, when the Copy to Clipboard dialog box appears.

  4. Scroll to, and click where you want to place the cross-reference.

  5. Press Ctrl+V.

    A cross-reference can be added to the Document's body text or to the fields of a Work Item contained within the Document.

  6. If the Document has outline numbering ON in the Document Properties sidebar, then the default link text included them and the section's title in the link. A reference's outline numbers are updated automatically whenever its source's numbers are changed.

  7. Click to keep the default outline numbers and title, or select the options to omit the title or replace the outline numbers with the Project ID.

    Tip:

    Click Custom Label to define your own cross-reference link text.

The cross-reference appears in the selected position.

Note:

  • If a referenced Work Item or Heading is removed, any cross-references pointing to it change to Missing cross-reference.

    (It also contains the missing item's ID, so that it can be easily tracked down.)

  • If the referenced item is filtered out of the Document, then the cross-reference link remains but does not scroll when clicked.

  • For an accurate cross-reference history view it in the Document's History.

  • When comparing different Documents, cross-references are highlighted as changed because they contain different URLs.

When exporting Cross-references:

Exporting to Microsoft Word:

  • Cross-references created in Polarion will survive a Word Round-trip, but instead of scrolling in the Word document, they open the referenced object in Polarion.

  • Cross-references created in Word are not recognized when imported into Polarion.

Exporting Cross-references to PDF:

Note:

Please use Adobe Acrobat Reader to view PDF documents.

  • If a cross-referenced item exists within the same PDF, then clicking its cross-reference scrolls right to it.

  • If a cross-referenced item is not within the PDF, then clicking its cross-reference opens the item in the Document Editor in Polarion.

  • If a Document was filtered before it was exported, cross-references for filtered items are exported as plain text.

    (They do not scroll to, or open the items in Polarion when clicked.)

  • Cross-reference links are underlined with a solid black line in exported PDFs

The difference between a Link and a Cross-reference:

Cross-references in branched, variant or reused Documents:

Things to know about cross-references in Branched or Variant or Reused Documents:

  • If a cross-reference is pointed to a section within a master Document, it will point to its matching counterpart section in Branched or Variant or Reused versions.

  • If a referenced Work Item that is targeted in a cross-reference is overwritten, the cross-reference is updated so that it still scrolls to the same position.

  • When a Work Item is opened in the Work Item form, any cross-reference contained within it link to the master Document.

  • If you change the title of a cross-referenced Heading or Work item, the cross-reference link text updates accordingly.

    (But only within the Document version in that the Heading is changed in.)

Note:

Currently cross-references between Documents, Revisions and Baselines is not fully supported and cannot be rendered as Live Links.

You can repair missing cross-references by inserting the missing item using the Insert Live/Frozen reference merge action.