Configuring PDF Export

You can configure the output of all types of pages and Documents exported to PDF. You can specify header and footer content and formatting as well as some content formatting. You can optionally include a watermark image in the PDF output. The configuration is available in the Repository (global) scope and for each project. The configuration is performed by editing an XML configuration file, on or off line.

To access the configuration file:

  1. Open the project you want to configure, or select the Repository scope in the Open Project dialog.

  2. Click the Administration link in the tool view of Navigation. (It appears only if you have administrator permissions for the scope you are working in.)

  3. In the Navigation panel, expand the Documents and Pages topic and select PDF Export Configuration.

  4. If working in the project scope, and no project configuration exists yet, click Paste global configuration to import the XML of the global configuration into the project.

  5. In the XML editor field, edit the configuration as desired. You will see instructional comments in the configuration file. Save the changed file.

TIP

You can optionally download the XML configuration file using the link found on the Configuration page, edit the configuration offline using your preferred editor, and then upload the modified configuration file via the file selection and upload controls in the Upload... section of the page.

By default, the configuration implements a simple HTML table, presented in CDATA elements inside the <header> and <footer> elements of the XML. You can optionally modify the table structure to add rows or columns, or use some other basic HTML elements such as paragraphs. In the table, you can specify such things as width, alignment of cells, cell padding etc. as long as you use standard HTML.

There are several properties you can specify, which embed data values into the header or footer of generated PDF documents. For example, the default configuration references $[documentTitle] in the <header> element, which causes the title of the exported Document or page to appear in the header of the generated PDF document. The full list of available properties is documented in the Administration Reference: PDF Export Header/Footer Properties.

TIPS

Power users who know XML can configure PDF header and footer for individual Documents or pages. The export dialog contains a link Configure..., which opens the Configure Headers, Footers and Watermarks dialog, which contains an embedded XML editor. The current Document or page configuration is pre-loaded in the editor. If there is no Document or page configuration yet, the XML from the project configuration is loaded, and the user can modify it and save it as the Document or page configuration.

Users of non-ASCII character sets may prefer to use the $[documentTitle] property rather than the $[documentName]property, which supports only ASCII characters.

Referencing Page Variables and Parameters

You can declare custom Velocity variables and/or page parameters in classic Wiki pages, and reference them in the header/footer export configuration. By using conditional logic in the configuration, you can include or exclude content of the variables or page parameters in the header/footer of exported documents.

For example, you could include one or both of the following in some Wiki page(s):

#set ($confidential = "true")
{parameter:internalDoc|type=boolean|value=true}
				

Then, in the Wiki export configuration you could reference these as shown in the following examples:

<!-- Example referencing Velocity variable -->					
#if($confidential)
   <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision]) CONFIDENTIAL</td>
#else
   <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision])</td>
#end

<!-- Example referencing page parameter -->
#if($pageParameters.internalDoc.equals(true))
  <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision]) INTERNAL USE ONLY</td>
#else
   <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision])</td>
#end

<!-- Example referencing both -->
#if($confidential)
   <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision]) CONFIDENTIAL</td>
#else
   #if($pageParameters.internalDoc.equals(true))
      <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision]) INTERNAL USE ONLY</td>
#else
   <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision])</td>
#end					
				

TIP

If a Document has no value in the Title field referenced by $[documentTitle], the value of the Document name (ID) will be used in exports.

Changing Embedded Fonts in Exported PDF

This advanced re-configuration may be necessary if you are exporting documents containing characters from various languages which need to be supported in the PDF. It requires editing of the main configuration properties file polarion.properties, and generation of a properties file using Java. In the following steps [POLARION_PLUGINS_DIR] refers to the location of the "plugins" folder in your installation.

  1. In the polarion.properties file, set the configuration property pdf.export.fonts.dir to the location of the folder containing the fonts that you want to use in exported PDF. IMPORTANT: specify the folder as a file URL. E.g., file:///fonts/directory.

  2. Generate a configuration file for PD4 by running the following Java command from your command line:

    java -jar POLARION_PLUGINS_DIR/com.polarion.alm.ui_*/lib/pd4ml.jar -configure.fonts /fonts/directory

  3. The pd4fonts.properties file is generated in the folder specified as the argument to -configure.fonts in the java command above. Edit this file and map the default font names (Times New Roman, Arial and Courier New) to the names of the custom fonts you want embedded in PDF export.

Specifying PDF Margin Size

You can optionally specify the width of all page margins in the PDF output. Margin widths are specified as attributes of the <pdf> element. For example: <pdf marginLeft="40" marginTop="25" marginRight="20" marginBottom="25">. Place the <pdf> element immediately following the <export> element:

<?xml version="1.0" encoding="UTF-8"?>
<export>
    <pdf marginLeft="40" marginTop="15">
        <header height="35">
        	...
        </header>
    	<footer height="25">
    		...
    	</footer>
    </pdf>
</export>	
				

Any margins not specified default to 20 pixels in the PDF output.

Configuring Different First Page Header/Footer

The scope attribute of the header and footer elements in the PDF export configuration, applicable for projects and individual documents, enables specification of different a header/footer for the first page of an exported PDF document. Modifiers even, odd and skiplast can be optionally used. For example:

# First Page Header:
<header height="25" scope="1"><![CDATA[
    <table width="100%" style="color:rgb(128,128,128); font-size: 9px !important; margin-bottom: 20px;">
        <tr>
            <td width="5%"><img width="30" height="32" src="/polarion/ria/images/logo.gif"></td>
             <td width="35%" style="padding: 0px 0px 5px 5px;">Polarion ALM<br><a style="color:rgb(128,128,128); font-size: 8px !important;" href="https://polarion.plm.automation.siemens.com">Polarion ALM</a></td>
        </tr>
    </table>]]>
</header>

# Header for other pages:
<header height="35" scope="2-72,even,skiplast"><![CDATA[
    <table width="100%" style="color:rgb(128,128,128); font-size: 9px !important; margin-bottom: 20px;">
        <tr>
            <td width="5%"><img width="30" height="32" src="/polarion/ria/images/logo.gif"></td>
            <td width="70%" align="right">$[projectName] $[documentTitle] (rev. $[revision])</td>
        </tr>
    </table>]]>
</header>
			

Configuring Export Watermarks

You can create or modify the global or project-scope PDF Export Configuration to include a watermark image on the pages of exported PDF documents. Users with permission to read or modify Documents can enable or disable an option Include header, footer and watermark, which appears in the Export to PDF dialog, and subsequently edit the export configuration to use a watermark image if one is not yet specified, or a different watermark image of one is specified, and/or change the opacity of a specified watermark. The configuration involves the following main steps:

  1. Upload a watermark image to the required repository folder location, the name of which serves as the watermark ID referenced in a PDF Export Configuration.

  2. Add a <watermark> element to the global and/or project PDF Export Configuration at the required place in the XML code.

Important

The file name of the watermark image file must correspond to the name of the folder that contains it. For example, if the watermark folder is confidential, the valid image file names would be confidential.png or confidential.jpg

Adding a Watermark Image to the Repository

To add a watermark image to the repository:

  1. If performing a project-specific configuration, open the desired project with project administrator permissions. If performing a global configuration, open the Repository.

  2. Open the Repository Browser, and navigate to .polarion/wiki/. If the wiki folder/directory does not exist, use the Add Directory icon to add it as a sub-directory of .polarion.

  3. If it does not already exist, create another new sub-directory, under .polarion/wiki/, name it watermarks and navigate into it.

  4. Create a new sub-directory for the watermark image you want to use in PDF exports for the scope you are configuring. The name of this folder/directory is used as the watermark ID in the PDF Export Configuration, therefore it must not contain spaces. For example, for a watermark that identifies a document as "CONFIDENTIAL", name the folder/directory something like confidential.

  5. Upload the desired watermark image file to this folder/directory using the Upload File icon of the Repository Browser. The image should be a .PNG file with a transparent or white background, or .JPG with white background. Be sure that the file name matches the name of the containing folder.

When you finish these steps, the Repository Browser should be showing a path to an image file that is something like:

[PROJECT NAME]/.polarion/wiki/watermarks/confidential/confidential.png (project-scope configuration)

Including a Watermark in PDF Export

To configure the project PDF export to include a watermark:

  1. Log in with administrator permissions for the scope you want to configure (repository or project), and access the repository or project.

  2. Open Administration > Documents & Pages > PDF Export Configuration

  3. If working in a project and there is no project configuration yet, click the Paste Global Configuration to load the XML code of the global PDF Export Configuration into the XML editor of the page.

  4. In the first <pdf> element, immediately following the closing </footer> tag, enter the following on its own line:

    <watermark id="watermark_directory"/> (replace watermark_directory with the name of the repository directory containing the watermark image you want to appear in PDF exports).

    Example: <watermark id="confidential"/>

  5. If you want to adjust the opacity of the watermark image here (default is 50%) you can enter: <watermark id="confidential" opacity="NN"/> (where NN is a number between 1-100).

    Example: <watermark id="confidential" opacity="33"/>

  6. Save the configuration.

Here is an example of showing where the watermark element should be placed:

    <pdf>
    ...
        </footer> 
        <watermark id="confidential" opacity="35"/>
    </pdf> 
			

Documents will now export to PDF with the configured watermark image. A global configuration may be overridden in individual projects with a project-scope configuration. Users with permissions to read or modify Documents will see the project-scope PDF Export Configuration when they invoke PDF export (or the global configuration of no project-specific configuration exists), and they can modify the XML they are presented. Their options include choosing not to include any watermark (via the Include header, footer and watermark option in the export dialog).

You are not confined to using a single watermark image for all PDF exports. You can optionally set up to use different images for different PDF export options, and create multiple image sets to support different watermarking requirements. The next sections describe how to do this.

Multiple Watermark Images

You can have multiple sets of watermark images in the repository at the same time, to be used automatically by the Exporter when end users invoke different export scenarios: different paper size or orientation, for example. For this, you create a folder/directory under .polarion/wiki/watermarks and populate it with appropriately named image files that are automatically applied to the output when a user selects different export options. The repository directory and image files should have this form: .polarion/wiki/watermarks/<watermarkId>/<watermarkId_orientation_papersize.extension>, where folder watermarkId is a valid Subversion repository folder name.

Within that folder you can have multiple image files using the file name convention previously mentioned, where:

  • watermarkId is the same as the containing folder name.

  • orientation is one of these literals: portrait or landscape.

  • papersize is one of these literals: A4, A3, letter, legal, or tabloid.

  • extension is one of these literals: png or jpg according to the actual file type.

Valid file name patters are:

  • <watermarkId_orientation_papersize.extension>

  • <watermarkId_orientation.extension>

  • <watermarkId.extension>

Image file names that do not correspond to the pattern (e.g. there is only the paper size element in the name, but no orientation) will be ignored. For example, confidential_portrait.png, confidential_landscape.png, or confidential.png are valid, but confidential_A4.png is not, and will be ignored if specified in a PDF export configuration.

Repository Setup Example

You might have a set of images that show the word "CONFIDENTIAL" in exported documents, with different images to be applied for different PDF export options selected by users when exporting. An example of a repository folder for this is .polarion/wiki/watermarks/confidential. In that folder you could have the following image files:

  • confidential_portrait_A4.png

  • confidential_landscape_A4.png

  • confidential_portrait_letter.png

  • confidential_landscape_letter.png

Extending For Different Requirements

It is possible to extend the basic concept. For example, you could add another folder, .polarion/wiki/watermarks/secret and populate it with another set of watermark images (e.g. secret_portrait_A4.png, secret_landscape_A4.png, etc.)

Each PDF export configuration element in Administration > Documents & Pages > PDF Export Configuration can reference one set of watermark images for each export type by a short name which corresponds to the name of the repository folder that contains the image files. For example: "confidential" for images contained in .polarion/wiki/watermarks/confidential/, or "secret" for images contained in .polarion/wiki/watermarks/secret. Syntax for each reference is: <watermark id="[id]" opacity="<opacity number>"/>

  • The id attribute is required.

  • The opacity attribute is optional. Valid value range is 1-100; if not specified, the default is 50.

See also: Including a Watermark in PDF Export.

How Watermarks Are Applied

Assuming compliance with the repository folder setup and image naming convention, Polarion automatically applies the most appropriate watermark image from the folder represented by the id attribute when an end user executes an export to PDF. For example, if the user invokes the export operation specifying landscape orientation and letter size paper, Polarion looks for an image file in the repository the file name of which contains "landscape" and "letter" according to the aforementioned naming convention. If not found, it searches for the closest match to the configuration.

Following the previous example, if the PDF export configuration contains <watermark id="confidential" opacity="33"/>, if the user invokes PDF Export and selects options for Landscape orientation and Letter paper size, Polarion will apply the image confidential_letter_landscape.png with 33 percent opacity to pages in the PDF output file. If that image is not present, will look among the remaining available images for one with the closest match to the configuration and user-selected export parameters. If none is found in the project, the global scope is checked, and if no appropriate image is present, no watermark is displayed in the output, and an error is written to the log files.

TIPS

You can set up the export configuration discussed here in both global and project scopes. These defaults may be overridden by a user in a document-specific configuration when exporting a Document or Work Items. If no project-scope images are available, images from the global configuration are used.

It is possible to override global-scope watermarks by creating a watermark folder in the project repository having the same name, and containing images having the same file names as those in the global configuration. By doing this, you can use the same XML element in global and project PDF export configurations (e.g. <watermark id="confidential" opacity="35"/>), and the image from the appropriate scope will be used. For more detailed information, see the Reference topic PDF Watermarks Order of Precedence.

Organizations can optionally implement restrictions via the plugin API to override PDF export configurations, placing restrictions on individual exports by individual users, to include a different watermark in the exported documents and/or to conform to other required policies. If such a plugin is in use, then when a use invokes PDF export, the PDF Export Wizard dialog shows a message: "Company policy can override these settings".

Configuring Highcharts Export

Polarion integrates the Highcharts library, which enables users to easily create and show various types of simple and complex charts in LiveReport type Pages and Classic Wiki pages. Phantom JS, used for preview and PDF export of Highcharts, is also installed. By default, it starts automatically, and automatically restarts in case the Phantom JS process is killed. Administrators may optionally disable auto-startup and auto-restart by setting the following system property in the polarion.properties file (follow link if you need the location):

com.polarion.highchartExportServer.autoStart=false

If set this way, the administrator is then responsible for starting/restarting the process manually. If not started, then users exporting pages containing Highcharts will not be able to preview them, such pages will not export to PDF properly, and errors will be logged.

To manually restart the process, issue one of the following system commands, depending on your operating system:

  • Windows: phantomjs.exe highcharts-convert.js -host 127.0.0.1 -port 34567

  • Linux: ./phantomjs highcharts-convert.js -host 127.0.0.1 -port 34567

The library is located under the plugin folder com.polarion.alm.ui. The path is polarion\plugins\com.polarion.alm.ui_N.N.N\phantomjs\, where "N.N.N" is the number of your currently installed Polarion version (e.g. "3.8.0").

There are 2 additional system properties for Phantom JS, both optional:

  • com.polarion.highchartExportServer.host - Defines the host name that will be used by the chart renderer server. The default is 127.0.0.1.

  • com.polarion.highchartExportServer.port - Defines the port that will be used by the chart renderer server. The default is 34567. Administrators may change this value to prevent conflict if that port is already in use.

Killing phantomjs Process on Restart

During Polarion start-up, the external phantomjs process starts and binds to localhost:34567. If the Polarion server process is killed or somehow terminates abnormally, the phantomjs process has to be terminated before restarting Polarion. The system does this automatically on restart if the system property com.siemens.polarion.ui.killPhantomJsProcesses is set to "true" (the default).

If you system uses separate phantomjs processes, which would be killed by this default behavior, you can set the value of the system property to "false". If you do, then before restarting Polarion, you should terminate the phantomjs process manually to prevent multiple instances, which can result in phantomjs failing to start, and/or problems with binding to the port. Use one of the following command-line commands:

  • Linux: pkill -f phantomjs

  • Windows: taskkill /F /IM phantomjs.exe /T

After Polarion restarts, re-initialize any separate phantomjs process.