Polarion ALM extension for diffing and merging

This Polarion extension provides functionality of diffing:

• fields of 2 documents (either different or the same in different revisions)
• work items of 2 documents (also either of different documents or of the same in different revisions)
• inlined content of 2 documents, inserted there not via work items, but directly
• arbitrary set of work items in one project with their counterpart work items from another project

...and then to merge selected diffs from left to right document. First 2 options are available either via selecting 2 certain documents or via a collection of documents.

In case of diffing work items, appropriate counterpart work items (from another document or another project) are always seeking by selected link role.

Additionally, the extension provides functionality to make a copy of selected document in other location, as well as to copy or move a chapter of one document, with everything below it, into another document.

Quick start

The latest version of the extension can be downloaded from the releases page and installed to Polarion instance without necessity to be compiled from the sources. The extension should be copied to <polarion_home>/polarion/extensions/ch.sbb.polarion.extension.diff-tool/eclipse/plugins and changes will take effect after Polarion restart.

Compatibility

This extension is compatible with:

• Polarion 2606
• Java 21
• PDF-Exporter v9

Polarion configuration

Documents comparison form to appear on a Document's properties pane

1. Open a project where you wish Documents comparison to be available
2. On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration page will be opened.
3. On the administration's navigation pane select Documents & Pages ➙ Document Properties Sidebar.
4. In opened Edit Project Configuration editor find sections-element:

   …
   <sections>
     <section id="fields"/>
     …
   </sections>
   …
   

5. And insert following new line inside this element:

   …
   <extension id="diff-tool" label="Documents Comparison" />
   …
   

6. Save changes by clicking 💾 Save

Documents copy form to appear on a Document's properties pane

Repeat the instructions above except that on the step 5 use the following line:

…
<extension id="copy-tool" label="Documents Copy" />
…

Documents merge form to appear on a Document's properties pane

Repeat the instructions above except that on the step 5 use the following line:

…
<extension id="merge-tool" label="Documents Merge" />
…

Nodes for collections and work items diffing to appear in Polarion's navigation tree

1. Open a project where you wish these nodes to be available
2. On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration page will be opened.
3. On the administration's navigation pane select Portal ➙ Topics.
4. Depending on which view type you are using choose to edit either Default or Admin view.
5. In opened Topics Configuration editor insert following line inside topics-element:

   …
   <topic id="diff-tool"/>
   …
   

6. Save changes by clicking 💾 Save

Fine-tuning the communication between Polarion and Diff Tool extension

The Diff Tool UI makes numerous requests to Polarion using the REST API to retrieve information about documents and their workitems. These requests can be processed in parallel to improve performance. The number of parallel requests can be configured in polarion.properties file:

ch.sbb.polarion.extension.diff-tool.chunk.size=2

Default value is 2. Increasing this value may speed up the process but can also overload your Polarion server.

Project duplication on large projects

Duplicating a project goes through Polarion's IProjectLifecycleManager.createProject API, which has to be wrapped in a single write transaction (this is the pattern Polarion's own "Create Project from Template" wizard uses). For very large source projects the long phase [4/5] Creating project … from template can run for tens of minutes inside that one transaction.

Polarion's SVN repository pool closes idle sessions after com.polarion.repositorySessionTimeout seconds (default 600 s / 10 min). If the createProject phase exceeds this limit, the transaction fails to commit with RepositoryTimeoutException: Failed to retrieve repository. Most likely the operation took too long, and the whole duplication is rolled back.

For large projects, raise the timeout in polarion.properties:

# Maximum age (seconds) an SVN session may sit idle before the pool closes it.
# Must be larger than the longest createProject phase you expect. Default: 600.
com.polarion.repositorySessionTimeout=3600

# How often (seconds) the background timer scans for idle sessions. Default: 180.
com.polarion.repositorySessionTimeoutCheckInterval=600

Polarion must be restarted for these values to take effect — they are read once during startup. The current effective values are printed in the job log right after [1/5] Validating request …, so you can verify they were picked up.

Extension Configuration

1. On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration page will be opened.
2. On the administration's navigation pane select Diff Tool. There are 2 sub-menus with different configuration options for Diff Tool.
3. They have either Quick Help section with short description or their content is self-evident.
4. To change configuration of Diff Tool extension just edit corresponding section and press Save button.

Usage

Documents diffing

1. Open a document in Polarion.
2. In the toolbar choose Show Sidebar ➙ Document Properties ➙ Documents Comparison.
3. Choose another document and desired options and click Compare.
4. Another tab will be opened in browser listing documents differences. Later you can select certain differences and merge them from left to right document.

Document copy creation

1. Open a document in Polarion.
2. In the toolbar choose Show Sidebar ➙ Document Properties ➙ Documents Copy.
3. Choose destination of target document, desired options and click Create Document.
4. When document is created you will see success message with a link to it.

Chapter merge

1. Open the document into which content should be placed.
2. In the toolbar choose Show Sidebar ➙ Document Properties ➙ Documents Merge.
3. Choose the source document and enter the outline number of the chapter to be merged, eg. 2.1.1.
4. Choose the copy mode: copy creates new work items, move moves work items and copies headings.
5. Enter the outline number of the chapter of the current document which is used as an anchor, eg. 3.1.
6. Choose the insert mode: under places the content directly under the anchor chapter, after makes it a new chapter of the same level. Heading levels and outline numbers are adjusted accordingly, so anchor chapter 3.1 with insert mode after and source chapter 2 results in chapter 3.2.
7. Click Merge Chapter. A dialog states what the merge will do and waits to be confirmed.
8. Confirm. The merge is executed as a Polarion job, and the dialog it was confirmed in shows its progress. It cannot be closed while the merge runs.
9. When the merge has finished, the same dialog states what it did and links to the job log. Closing it reloads the document if the merge changed it.

Work items diffing

1. In Polarion navigation tree choose Diff Tool ➙ Multiple Work Items.
2. Choose target project, link role by which items to be linked, then select work items from table below to be compared, preliminary filtering them to show ones you need.
3. Finally, click Compare button.
4. Another tab will be opened in browser listing selected work items differences. Later you can select certain differences and merge them from left to right Work Item.

Collections diffing

1. In Polarion navigation tree choose Diff Tool ➙ Collections.
2. You will see 2 tables listing collections. Left one is displaying collections from current project, right one is displaying collections from project selected in dropdown Target project.
3. Select one collection from left table and one collection from right table, preliminary filtering them to show ones you need.
4. Choose link role by which work items to be linked, then click Compare button.
5. Another tab will be opened in browser listing documents differences. You can change documents from collections to be compared in side pane. Later you can select certain differences and merge them from left to right document.

REST API

This extension provides REST API. OpenAPI Specification can be obtained here.

Calling diff methods from Velocity Context

Diffing text or HTML content

diffText and diffHtml functions are available in Velocity context referenced by $diffTool variable. Example:

$diffTool.diffText("Some text", "Some another text").getResult()

or

$diffTool.diffHtml("<html><body><div>Some text</div></body></html>", "<html><body><div>Some another text</div></body></html>").getResult()

Also, isDifferent can be used if you need to show something specific for cases when the values are the same:

#set($diffResult = $diffTool.diffText("Some text", "Some text"))
#if($diffResult.isDifferent())
  $diffResult.getResult()
#else
  No changes
#end

Diffing work items w/o document context

diffWorkItems compares two work items and returns a WorkItemsPairDiff object containing all differences.

Parameters

Returns

WorkItemsPairDiff - An object containing all field-level differences between the work items, accessible via fieldDiffsMap where each entry contains the field name and diff values.

Example Usage

## Get current project object
#set($projectId = $page.fields().project().projectId())
#set($project = $projectService.getProject($projectId))

<h2>Selected Work Items in Project: $project.name</h2>

## Example: Specific IDs in this project
#set($query = "project.id:$projectId AND (id:EL-1 OR id:EL-2)")
#set($workItems = $trackerService.queryWorkItems($query, "id"))

#set($rightWorkItem = $workItems.get(0))
#set($rightWorkItem = $workItems.get(1))

 #set($diffResult = $diffTool.diffWorkItems($projectId, $rightWorkItem, $rightWorkItem, "Default", ""))

<h3>Work Item Differences</h3>

<table border="1" cellspacing="0" cellpadding="5">
  <tr>
    <th>Field</th>
    <th>$rightWorkItem.id</th>
    <th>$rightWorkItem.id</th>
  </tr>

## Loop through all field differences
#foreach($fieldId in $diffResult.fieldDiffsMap.keySet())
  #set($fieldDiff = $diffResult.fieldDiffsMap.get($fieldId))
  <tr>
    <td>$fieldDiff.getName()</td>
    <td>$fieldDiff.getDiffLeft()</td>
    <td>$fieldDiff.getDiffRight()</td>
  </tr>
#end
</table>