Polarion ALM extension to convert Documents to DOCX files

This Polarion extension provides possibility to convert Polarion Documents to DOCX files.
The extension uses Pandoc as a converter engine and requires it to run in Docker as Service.

Quick start

Please see separate quick start page where briefly summarized all most important and applicable steps and configurations.

If you need deeper knowledge about all possible steps, configurations and their descriptions, please see sections below.

Polarion configuration

Pandoc configuration

This extension supports the use of Pandoc as a REST service within a Docker container, as implemented here.
To change Pandoc Service URL, adjust the following property in the polarion.properties file:

ch.sbb.polarion.extension.docx-exporter.pandoc.service=http://localhost:9082

DOCX exporter extension to appear on a Document's properties pane

1. Open a project where you wish DOCX Exporter 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="docx-exporter" label="DOCX Exporter" />
   …

6. Save changes by clicking 💾 Save

DOCX Exporter view to open via button in toolbar

Alternatively you can configure DOCX Exporter such a way that additional toolbar will appear in document's editor with a button to open a popup with DOCX Exporter view.

1. Open "Default Repository".
2. On the top of its navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Global administration page will be opened.
3. On the administration's navigation pane select Configuration Properties.
4. In editor of opened page add following line:

   scriptInjection.dleEditorHead=<script src="/polarion/docx-exporter/js/starter.js"></script><script>DocxExporterStarter.injectToolbar();</script>

   There's an alternate approach adding DOCX Exporter button into native Polarion's toolbar, which has a drawback at the moment -
   button disappears in some cases (for example when document is saved), so using this approach is not advisable:

   scriptInjection.dleEditorHead=<script src="/polarion/docx-exporter/js/starter.js"></script><script>DocxExporterStarter.injectToolbar({alternate: true});</script>

   
   
5. Save changes by clicking 💾 Save

Configuring logs

For better problem analyses extended logging can be configured in Polarion. By default, Polarion log level is set to INFO. It can be changed to debug in log4j2.xml file.
Find /opt/polarion/polarion/plugins/com.polarion.core.util_<version>/log4j2.xml file and add the following line into Loggerssection:

<Logger name="ch.sbb.polarion.extension" level="debug"/>

It is also possible to write all messages of SBB extensions info separate log file which can be useful to report a problem. In this case new Appender should be added:

<RollingFile name="SBB" fileName="${sys:logDir}/log4j-sbb${fileNameSuffix}" filePattern="${sys:logDir}/log4j-sbb${filePatternSuffix}">
    <PatternLayout pattern="${layoutPattern}"/>
    <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
    </Policies>
</RollingFile>

and the following Logger:

<Logger name="ch.sbb.polarion.extension" level="debug">
    <AppenderRef ref="SBB"/>
</Logger>

Enabling CORS

Cross-Origin Resource Sharing could be enabled using standard configuration of Polarion REST API. In polarion.properties the following lines should be added:

com.siemens.polarion.rest.enabled=true
com.siemens.polarion.rest.cors.allowedOrigins=http://localhost:8888,https://anotherdomain.com

Enabling webhooks

By default, webhooks functionality is not enabled in DOCX Exporter. If you want to make it available the following line should be added in polarion.properties:

ch.sbb.polarion.extension.docx-exporter.webhooks.enabled=true

Debug option

This extension makes intensive HTML processing to extend similar standard Polarion functionality. There is a possibility to log
original and resulting HTML to see potential problems in this processing. This logging can be switched on (true value)
and off (false value) with help of following property in file polarion.properties:

ch.sbb.polarion.extension.docx-exporter.debug=true

If HTML logging is switched on, then in standard polarion log file there will be following lines:

2023-09-20 08:42:13,911 [ForkJoinPool.commonPool-worker-2] INFO  util.ch.sbb.polarion.extension.docx_exporter.util.HtmlLogger - Original HTML fragment provided by Polarion was stored in file /tmp/docx-exporter10000032892830031969/original-4734772539141140796.html
2023-09-20 08:42:13,914 [ForkJoinPool.commonPool-worker-2] INFO  util.ch.sbb.polarion.extension.docx_exporter.util.HtmlLogger - Final HTML page obtained as a result of DOCX exporter processing was stored in file /tmp/docx-exporter10000032892830031969/processed-5773281490308773124.html
2023-09-20 08:42:14,015 [ForkJoinPool.commonPool-worker-2] INFO  util.ch.sbb.polarion.extension.docx_exporter.util.HtmlLogger - DOCX generation timing report was stored in file /tmp/docx-exporter10000032892830031969/timing-report-1234567890.txt

Here you can find out in which files HTML and timing report were stored.

Timing report

When debug mode is enabled, a detailed timing report is generated showing the duration of each DOCX generation stage.
This helps identify performance bottlenecks. The report includes:

• Summary statistics (HTML size, DOCX size, page count, throughput)
• Timing breakdown with visual progress bars
• Time by category (HTML Processing, Pandoc Conversion, DOCX Post-processing, Cover Page)
• Slowest stages with performance indicators
• Execution timeline

Workflow function configuration

It is possible to configure the workflow function which exports a DOCX file and attaches it to a newly created or already existing work item.

To create workflow functions do following:

1. On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration pane will be opened.
2. On the administration's navigation pane select Documents & Pages ➙ Document Workflow.
3. On the opened page you will see a list of document types with their actions. Find type you are interested in and click Edit or Create button for it.
4. On the opened page (Workflow Designer) find the section Actions, appropriate action in it, e.g. archive (or create a new one) and click Edit for it.
5. A popup will be opened with title 'Details for Action: Archive', select 'DOCX Export' in 'Function' dropdown of 'Functions' section and then click
   pencil button. Another popup will be opened with title 'Parameter for: DOCX Export', add appropriate parameters in table of this popup, then click Close.
   Then again Close on previous popup and finally Save when you will be back on Workflow Designer page.
   
   

Supported function parameters:

(*) - either 'existing_wi_id' or 'create_wi_type_id' parameter required.
Providing the first one means reuse already existing workitem to attach the file whereas the second will create a new workitem with the specified type.
In case if both of them specified 'existing_wi_id' has higher priority.

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 DOCX Export. There are expandable sub-menus with different configuration options for DOCX Exporter.
3. For some of these options (Localization, Webhooks and Filename template) Quick Help section available with option short description. For the rest
   (Style Package, Style Package Weights) there's no Quick Help section as their content is self-evident.
   
4. To change configuration of DOCX Exporter extension just edit corresponding section and press Save button.

Usage

1. Open a document in Polarion.
2. In the toolbar choose Show Sidebar ➙ Document Properties.
3. Choose desired options in the DOCX Exporter block and click Export to DOCX.
   For the options details please refer user guide.
   

REST API

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

Advanced configuration

Asynchronous DOCX Export: export jobs timeout

This extension provides REST API to export DOCX asynchronously. Using this API, it is possible to start export job, observe their status and get result.
Finished (succeed or failed) and in-progress export jobs will be preserved in memory until configured timeout. To change this timeout, adjust the following property in the local docx-converter-jobs.properties file:

# Timeout in minutes to keep finished async conversion jobs results in memory
jobs.timeout.finished.minutes=30
# Timeout in minutes to wait until async conversion jobs is finished
jobs.timeout.in-progress.minutes=60

Known issues

Outline (chapter) numbers are displayed twice

The outline (chapter) numbers are currently showing up twice because Word is adding its own numbering. To fix this, heading numbering should be disabled in the Word template used by Pandoc.

Style of table is not assigned automatically

Styles were not applied because the table style in the Word template was defined incorrectly. When converting HTML to DOCX, Pandoc applies only the style named Table, which is considered the default table style. Even if the template contains other custom table styles, Pandoc ignores them unless they are directly linked to the Table style.
To use a custom table style, the Word template must be configured so that the Table style inherits the formatting of the custom style. This can be done by redefining the default Table style within the template or by setting it to be based on the desired custom style.

Heading levels beyond h6

HTML supports heading elements only from h1 to h6, but Polarion documents can contain deeper nesting levels. Added with pandoc-service#152, a Lua filter is included that handles heading levels beyond h6. It converts <div class="heading-N"> elements (where N > 6) into proper Pandoc header blocks, enabling correct processing of deeply nested document structures. Heading levels are capped at 9 for compatibility with Word documents, and the Table of Contents depth has been extended to support levels 1–9.

All good so far.