Polarion 18.2 Deep Dive – “Cross-References”

We announced Polarion 18.2 on this blog a few weeks ago. If you haven’t seen the announcement from my colleague Radek Krotil, you can read it by going to this link here

In today’s Polarion blog post we are going to discuss a new feature added to Polarion 18.2 called “Cross-References”. If you are familiar with cross-references in other document publishing tools then you may already be familiar with the feature, however because Polarion presents a real time dynamic view of lifecycle artifacts, there’s a few subtle differences you should be aware of.

Cross-references allow you to link information to other parts of your Polarion live-doc (and to other live-docs for that matter … but more on that later). So perhaps you want to reference another section that appears earlier or later on in your document. Or you want to reference a table, image or some other figure. Perhaps in a requirement definition, you want to reference something that was already explained in an earlier requirements definition. In either case, cross-references come in very handy, especially when you have a large document that you expect the reader to navigate through. The great thing about cross-references is that they are also exported from Polarion to PDF or Microsoft Word.

Creating cross references

So how do you create cross-references in your documents? The first step is to create the anchor for the cross-reference. Go to the work-item or heading in the live document you want to reference. Click either the heading icon or work-item icon to the left of the document page and click on “copy -> cross reference” as shown in the figure below.

Polarion will then ask you to copy the cross-reference to the copy buffer. Next, in your live-doc scroll to the part of the document text where you would like to insert the cross-reference. It can be anywhere in the document, including work-items and free text fields. Hit paste. (CTRL-V)

Polarion will then present you with a choice as to how you would like to reference your cross-reference link.

You can choose to reference the link with

1. Outline number and title.


2. Outline number only


3. Work-item ID / heading ID and title


4. Work-item ID / heading ID only.


5. A custom label of your choice.

For items 1, 2 and 3, Polarion will automatically update the cross-references if the source reference is changed in some way. Perhaps you update the title of the heading or work-item, or perhaps you insert or delete an item in the live-document that causes the outline number to change. In either case, you can rest assured that any cross-references you have used will automatically be updated. Pretty cool.

Notice that when you insert the cross-reference, it looks different from other types of links that exist in Polarion live-docs. Cross-references are underlined with a dashed gray line. In PDF exports they are unlined with a solid black line.

So here’s few things to know about cross references …

• If a reference to a work-item or heading is removed, any cross-references that points to it will change to “Missing cross-reference”.


• If the reference to a work-item or heading is filtered out using the live-doc filtering, then although the cross-reference links remain in the document, they won’t scroll.


• Cross-references are supported in both branched, variant and reused documents. In each case the cross-reference links are unique to the branch, variant or reused document. Not the master it was created from.

Finally, as I mentioned at the beginning of this blog post, cross-references can be created between documents. When you do this, you get a slightly different choice when you create the cross-reference link.

As you can see, you get the options to either use a standard Polarion link or a custom field. In either case however, clicking on the cross-reference link will take you over to the document where the cross-reference exists and navigate within the document accordingly.

That’s pretty much it. We hope you like this feature as much as we do. Please do check the Polarion on-line help for more information on cross-references. I didn’t cover everything here … so it’s worth familiarizing yourself with some of the other notes outlined in the help.

That’s it for now, please be sure to check back on this blog in the future for more deep dives and information on our Polarion releases.

If you are not already familiar with Polarion and are just itching to take a look at this new cross-reference functionality, why not try the free evaluation? For more information, please visit https://polarion.plm.automation.siemens.com/products/alm/demo

For Polarion Product Management,

Adrian Whitfield