A deeper dive into Collections

By Adrian Whitfield

In today’s blog we are going to take the collections feature that came in Polarion 20R1 and discuss it in more detail. By the way, if you haven’t read about the new Polarion 20R1 release, you can do so here.

So, first things first. What is a collection?  Well, simply put, a collection is a set of Polarion live document revisions or baselines that is either in an open or closed state.

Figure 1 – Polarion Collection View

So, you’re probably asking yourself why might you want to create a collection of document revisions? Good question. Given that Polarion live documents normally represent (software) requirements at different levels of the development lifecycle, up to this point, it wasn’t easy to create sets of document revisions in Polarion. You were able to create spaces, with containing documents, but these documents would always represent current documents. Now for the first time with collections, you can easily group up all the documents and their associated revisions in one place with easy access, navigation and viewing capabilities. Something we hear our customers say would be helpful during audits or regulatory compliance activities.

Collections also can help with reuse. This is because the same document revision or baseline can exist in multiple collections. This is particularly useful when you have different teams of engineers that are responsible for different parts of your design but both teams must work with the same higher-level specification revision. In that instance, two collections could be created to represent these two active team streams, with the same higher-level specification placed in both collections.

What’s powerful about collections is that Polarion makes it easy to visually understand and see the context of the collection. This means that when you open a document inside of a collection (see Figure 2), in the left side navigation pane, you only see the other documents that are contained in the collection.  Its super easy to hop around and navigate within the contents of the collection. Move from document to document, or traverse links. If you ever leave a collection, and its context, its very easy to see that too.

Figure 2 – A Document open from a Collection

One interesting feature of the collection comes with links and traceability. One of the primary goals of collections was that Polarion would ensure that links between the artifacts inside the collection would always be valid. Collections make it easy to create links between work items that are contained in documents that exist in a collection. If you try and create a link to work item that isn’t contained in a collection you will receive an error. However, it may be the case that there are links inside a document that go to a target that isn’t in the collection because the link was created before it was added to a collection. In order to check for these potential problems, the new collection capability includes an consistency checker (see Figure 3) which will warn you if you have links from documents and their associated work-items pointing to artifacts outside the collection.

Figure 3 – Consistency checker results

Now at the beginning of this blog I mentioned that collections are sets of document revisions. This is of course true, but the one thing I didn’t say was that collections can also contain head revisions, or current documents. There is one important rule though and that is that a document head revision can only be contained in one collection. This means that not only can collections be used for archiving and creating historic document revisions, they can also be used to work inside of with current document revisions, or a mix of current and historic document revisions.

The approach of working inside a collection is particularly supportive of parallel development activities. We touched on this during our Polarion 21R1 release blog post. In V-lifecycle development, organizations cannot wait for all the documents that represent the different levels of development to be completed before they move on to the next version or product release.

Figure 4 – The V-Lifecycle showing the concept of concurrent development

Often, the higher-level documents representing the next product release are worked on at the same time as the lower level documents of the previous product release. In Figure 4 above, as an example, as Team C works on their high level (HL) software specification version 2, Team D is working on the low level (LL) software specification Version 1.4 at the same time. By using Polarion collections to support the V-lifecycle parallel development activities, one can organize one’s documents in a manner that allows these documents to be developed concurrently. Collections ensures that the context is always maintained and the links between documents is valid, thus reducing any room for error that could be caused because the user was working with the wrong document revision. When the work finally finishes on a product release, the collection can be closed, at which point its frozen and cannot be modified any more. Only with the special user permissions could the collection be re-opened for further modification.

There is one more thing that you should be aware of when working with traceability links inside of a collection. If you link from work-items that are contained in a current document revision (head), back to work-items that are contained in a document revision or baseline, for the first time, Polarion will show you links (or backlinks) from the point of view of the document revision work-items. In other words, you will see the traceability links in both directions.

So in summary:

  • Collections provide a super easy way of creating sets of document revisions, where a document revision can be reused in multiple collections if desired. When used in this manner collections are appropriate for audit and regulatory compliance needs.
  • Collections can also be used to work inside of, with a mix of current and historic document revisions or baselines. Collections allow you to remain within a context and make it very easy to create links between document and work-item revisions. When the work is complete on the current collection, it can be closed and frozen. When used in this manner collections are appropriate to support parallel or concurrent development activities within the V-lifecycle.

At the bottom of this blog, I’ve recorded a very short demo showing you some of the points we covered in this blog post.

We believe collections offer some powerful capabilities to our customers. We’ve already heard some great feedback and would like to further explore these concepts. So, what might be next for collections? Certainly, being able to add documents from other projects would be interesting, as well as providing more intuitive ways to search for collections. We also see being able to reuse an entire collection scope for another product iteration or variant would be useful too.

Having said all of this we always welcome your feedback. So, don’t hesitate to contact us directly or alternatively through your account representative. If you’re entirely new to Polarion and reading this blog post, why not consider giving Polarion a trial and see if it might work for you on your next project. Its very easy to download and get started quickly or you can use one of the hosted options too – just by following this link.

On behalf of everyone on the Polarion Product Management Team,


Adrian Whitfield.


3 thoughts about “A deeper dive into Collections
  • There are new API functions available in Polarion 20-R1 – to access data about Collections: you can get all collections, get status, custom fields, included LiveDocs and their versions. I created some useful macros in velocity to display Collection’s Info in LiveDoc (embedded macro) or on LiveReport page, to compare Collections side-by-side.

    EXAMPLE of code:
    #set($Collections = $transaction.baselineCollections().search())
    #foreach($collection in $Collections)

  • Hi Konstantin,

    thank you for the input! Do you know if there is a way of implmenting the same functionality using the Web Service API?

    Thanks in advance and best regards,

Leave a Reply

This article first appeared on the Siemens Digital Industries Software blog at