Configure export watermarks

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)

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

2. Working in the scope you want to configure, open AdministrationDocuments & PagesPDF Export Configuration.

3. If working in a project, and there is no project configuration yet, click Paste Global Configuration to load the XML code of the global PDF Export Configuration into the XML editor of the page. This is the basis for the project-scope configuration that you can now modify.

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 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 box).

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.

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 are ignored — when there is only the paper size element in the name, but no orientation, for example. Thus, confidential_portrait.png, confidential_landscape.png, or confidential.png are valid, but confidential_A4.png is not, and will therefore be ignored if specified in a PDF export configuration.

Let us consider a 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

It is possible to extend the basic concept for different requirements. For example, you could add another folder, .polarion/wiki/watermarks/secret and populate it with another set of watermark images — secret_portrait_A4.png, secret_landscape_A4.png, for example.

Each PDF export configuration element in AdministrationDocuments & PagesPDF 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 value is 50.

See also Include a Watermark in PDF Export.

I can be important to understand how watermarks are applied by Polarion. 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"/>, then 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 thirty-three 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, Polarion checks the global scope, and if no appropriate image is present, no watermark is displayed in the output, and an error is written to the log files.