• Home
• ch.sbb.polarion.extensions
• ch.sbb.polarion.extension.pdf-exporter
• 7.3.1
• source code
• about.html

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

webapp.pdf-exporter-admin.html.about.html Maven / Gradle / Ivy

Polarion ALM extension to convert Documents to PDF files
This Polarion extension provides possibility to convert Polarion Documents to PDF files.

This is an alternative to native Polarion's solution.

The extension uses WeasyPrint as a PDF 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
WeasyPrint configuration
This extension supports the use of WeasyPrint as a REST service within a Docker container, as implemented here.

To change WeasyPrint Service URL, adjust the following property in the polarion.properties file:

ch.sbb.polarion.extension.pdf-exporter.weasyprint.service=http://localhost:9080
PDF exporter extension to appear on a Document's properties pane

Open a project where you wish PDF Exporter to be available
On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration page will be opened.
On the administration's navigation pane select Documents & Pages ➙ Document Properties Sidebar.
In opened Edit Project Configuration editor find sections-element:
…
<sections>
  <section id="fields"/>
  …
</sections>
…

And insert following new line inside this element:
…
<extension id="pdf-exporter" label="PDF Exporter" />
…

Save changes by clicking 💾 Save

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

Open "Default Repository".
On the top of its navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Global administration page will be opened.
On the administration's navigation pane select Configuration Properties.
In editor of opened page add following line:
scriptInjection.dleEditorHead=<script src="/polarion/pdf-exporter/js/starter.js"></script><script>PdfExporterStarter.injectToolbar();</script>
There's an alternate approach adding PDF 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/pdf-exporter/js/starter.js"></script><script>PdfExporterStarter.injectToolbar({alternate: true});</script>


Save changes by clicking 💾 Save

PDF Exporter view to open in Live Reports
Live Reports also can be converted to PDF with help of this extension.
First of all you need to inject appropriate JavaScript code into Polarion:

Open "Default Repository".
On the top of its navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Global administration page will be opened.
On the administration's navigation pane select Configuration Properties.
In editor of opened page add following line:
scriptInjection.mainHead=<script src="/polarion/pdf-exporter/js/starter.js"></script>

Save changes by clicking 💾 Save

Then open a project, its Live Report you wish to export, and click "Expand Tools" on top of the page.

As a result report's toolbar will appear. Click "Edit" button in a toolbar, as a result the report will be switched into an edit mode. Add an empty region on top of the report, place cursor there, choose "Generic" tag on "Widgets" sidebar on right hand side of the page, find "Export to PDF Button" widget there and click it to add to the report. Then save a report clicking 💾 in a toolbar and then return to a view mode clicking "Back" button. When you click "Export to PDF" button just added to the report, PDF Exporter view will be opened in a popup and you will be able to proceed with exporting the report to PDF. Be aware that in report's context limited set of properties are available for configuration in PDF popup, the rest of them are relevant only in Live Document context.

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 PDF Exporter. If you want to make it available the following line should be added in polarion.properties:
ch.sbb.polarion.extension.pdf-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.pdf-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.pdf_exporter.util.HtmlLogger - Original HTML fragment provided by Polarion was stored in file /tmp/pdf-exporter10000032892830031969/original-4734772539141140796.html
2023-09-20 08:42:13,914 [ForkJoinPool.commonPool-worker-2] INFO  util.ch.sbb.polarion.extension.pdf_exporter.util.HtmlLogger - Final HTML page obtained as a result of PDF exporter processing was stored in file /tmp/pdf-exporter10000032892830031969/processed-5773281490308773124.html

Here you can find out in which files HTML was stored.
PDF Variants configuration
This configuration property allows selecting a PDF variant to be used for PDF generation. The following variants are supported:



Variant
Description




pdf/a-1b
Basic visual preservation (older PDF standard)


pdf/a-2b
Basic visual preservation with modern features like transparency


pdf/a-3b
Visual preservation with file attachments


pdf/a-4b
Visual preservation using PDF 2.0 standard


pdf/a-2u
Visual preservation + searchable text (Unicode)


pdf/a-3u
Visual preservation + searchable text with file attachments


pdf/a-4u
Searchable text + PDF 2.0 features


pdf/ua-1
Accessible PDF for assistive technologies



To configure the PDF variant, adjust the following property in the polarion.properties file:
ch.sbb.polarion.extension.pdf-exporter.weasyprint.pdf.variant=pdf/a-2b
The default value is pdf/a-2b.
Extension configuration

On the top of the project's navigation pane click ⚙ (Actions) ➙ 🔧 Administration. Project's administration page will be opened.
On the administration's navigation pane select PDF Export. There are expandable sub-menus with different configuration options for PDF Exporter.
For some of these options (Cover page, Header and Footer, Localization, Webhooks and Filename template) Quick Help section available with option short description. For the rest

(Style package, Stylesheets) there's no Quick Help section as their content is self-evident.

To change configuration of PDF Exporter extension just edit corresponding section and press Save button.

Usage

Open a document in Polarion.
In the toolbar choose Show Sidebar ➙ Document Properties.
Choose desired options in the PDF Exporter block and click Export to PDF.

For the options details please refer plugin documentation.


REST API
This extension provides REST API. OpenAPI Specification can be obtained here.
Advanced configuration
Asynchronous PDF Export: export jobs timeout
This extension provides REST API to export PDF 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 pdf-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
All good so far.
Upgrade
Upgrade from version 6.x.x to 7.0.0
In version 7.0.0 /export-filename REST API endpoint changed. As a result, if the endpoint has been used, it's required to adjust the calls accordingly.
DocumentType enum in ExportParams has been changed. As a result, if enum values have been used, it's required to adjust the calls accordingly.
Main package has been renamed from ch.sbb.polarion.extension.pdf.exporter to ch.sbb.polarion.extension.pdf_exporter. As a result, if the extension has been used in another OSGi bundles, it's required to adjust the package imports accordingly.
There was also added a CSS fragment for better display of Test Run pages in PDF, please add this fragment to your CSS definitions if they differ from default one, or update your CSS definitions via UI clicking button "Default" and later saving it. Here is this fragment:
#polarion-rp-widget-content > .polarion-TestRunOverviewWidget-table > tbody > tr > td:first-child {
   width: 46% !important;
}
.polarion-TestRunOverviewWidget-buttonName {
   padding-top: 20px;
}
In version 7.1.0 the property ch.sbb.polarion.extension.pdf-exporter.internalizeExternalCss has been removed. polarion.properties should be updated accordingly.
Upgrade from version 5.x.x to 6.0.0
In version 6.0.0 WeasyPrint CLI support was removed. As a result, if WeasyPrint CLI has been using to generate PDFs, it's required to switch to WeasyPrint Service.
The configuration properties ch.sbb.polarion.extension.pdf-exporter.weasyprint.connector and ch.sbb.polarion.extension.pdf-exporter.weasyprint.executable have been removed due to the removal of WeasyPrint CLI support. polarion.properties should be updated accordingly.
Upgrade from version 4.x.x to 5.0.0
In version 5.0.0 not only label of configuration parameter "Fit images and tables to page width" was modified to be "Fit images and tables to page",

but also underlying parameter was renamed to reflect this change. As a result if you had "Fit images and tables to page width" ticked in your configuration prior to version 5.0.0,

after installation of this version you will have to go to configuration again and re-tick property "Fit images and tables to page", both on global repository level and on level of projects.


Another change is default CSS which was modified to reflect different possible paper sizes as well as additional styling for images to jump into next page if they can't be fully displayed on current one.

Thus please either reset your saved CSS into last version if you didn't have your own CSS definitions or merge your saved version with new default version.