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.

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 2512
• 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" />
…

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.

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.

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>