Getting Started With Document PDF Writing

Introduction

The Document PDF writer and the corresponding DocumentPDFStyler transformer are part of the new Document PDF Writer FME package, which is available starting in FME 2024.2 (builds 24783+).

The Document PDF format has no spatial support, unlike the Adobe Geospatial PDF format. It is intended to create text-based documents such as reports. If creating 2D PDF documents with vector drawings and geospatial content is the goal, please see the Creating PDF cartographic output | FME Flow Data Streaming Service tutorial.

This article will show you how to use the DocumentPDFStyler transformer and DocumentPDF writer to create a PDF report in two parts with information about the public library system and its branches in Vancouver, British Columbia, Canada, from the GeoParquet format. 

Part 1 is focused on creating PDF content for the individual library branches through headings, images, text, tables, lists, and page breaks.

Part 2 focuses on creating document content for the entire PDF. This includes creating a title page, table of contents, footer, watermark, and changing page orientation in the middle of a PDF document. 

The completed workspace for part 1, GettingStartedWithDocumentPDF_Part1_Completed.fmwt, and for part 2, GettingStartedWithDocumentPDF_Part2_Completed.fmwt, are attached to the article and can be downloaded from the Files section of the article.

The workspaces were created in FME 2025.1 build 25609 and with version 1.10.2 of the Document PDF FME package. The article steps should work in FME versions supported by the Document PDF package and any versions of the Document PDF package newer than 1.10.2.

The final PDF output after parts 1 and 2 will be a PDF report that contains:

• Title page
• Table of Contents
• Headings
• Text
• Images
• Tables
• Lists
• Page breaks
• Footer
• Page number
• Watermark
• Different page orientations

Requirements

• PDF viewer application
• FME 2024.2 (builds 24783+)

Data Source

cov_libraries.parquet contains a list of the public libraries in Vancouver, BC, Canada. Each of the 21 points contains information about the library, including its address, name, hours of operation, and description of the location. 

Step-By-Step Instructions

In the first part, we will create a PDF using the Document PDF writer that contains information about public library branches in Vancouver using the cov_libraries.parquet file from the Files section of the article. 

If you would like to create your own workspace following the instructions from the tutorial, download the source data, cov_libraries.parquet, from the Files section of the article before starting this tutorial. Otherwise, you can follow along with the completed workspace for part 1, GettingStartedWithDocumentPDF_Part1_Completed.fmwt, also available from the Files section.

Part 1: Create PDF Content for Library Branches

This part demonstrates how to add headings, text, images, tables, lists, and page breaks using DocumentPDFStylers transformers. It also shows how to add page numbers and document metadata through Document PDF writer parameters.

1. Start FME Workbench and Add GeoParquet Data

Start FME Workbench, and click on New to open a blank workspace.

First, we need to add a source dataset. Click on the Reader button. In the Add Reader dialog, enter the following:

• Format: GeoParquet
• Dataset: ./cov_libraries.parquet
  • Click on the ellipsis and browse to the downloaded dataset

Click OK.

2. Create Library Name Heading

The DocumentPDFStyler transformer prepares features for output with the Document PDF writer. All features must pass through a DocumentPDFStyler transformer before they are sent to the Document PDF writer, so the necessary Document PDF format attributes are set on features.

In FME Workbench, add a DocumentPDFStyler. If the Document PDF Writer FME Hub package is not already installed for the version of FME used, you will see a warning dialog warning Workbench is about to install the “Document PDF Writer” package when opening the completed workspace. Select “Install” to install the FME package.

Connect the cov_libraries reader feature type to the DocumentPDFStyler transformer. The library name is contained in the name attribute.

In the DocumentPDFStyler parameter dialog, change the following parameters:

• General
  • Content Type: Heading
• Heading
  • Heading Level: Heading 1
  • Text: @Value(name) Library
• Styling
  • Font Color: 245,81,21
  • Alignment: Center

All other parameters can remain as the default values. For this article, only change the parameters listed in the bulleted lists and then exit the parameters dialog by clicking OK. All parameters not mentioned can remain set to the default values.

These settings will set Document PDF format attributes that tell the Document PDF writer to create centered first-level headings with the text of the library name in an orange color. 

All heading text will also be a bookmark in the output PDF, and the bookmarks may be nested based on their heading level.

3. Add Images of Library Branch

We want to add pictures of each library branch to the PDF. The Document PDF writer allows us to add images using the Image content type in the DocumentPDFStyler.

It is important to note that all content you want to add to the output PDF document must be represented by a feature in the workspace. So, we will need to add a new connection from the GeoParquet reader feature type to the branch of the workflow representing the images we want to add. 

If you add a second DocumentPDFStyler and add a connection from the first DocumentPDFStyler's output port to the second DocumentPDFStyler, only the content from the second DocumentPDFStyler would be written to the destination PDF file. This is because the second instance of the transformer would overwrite any Document PDF format attributes set by the first DocumentPDFStyler.

Every library branch feature has an image as JPEG format binary data in the photo attribute. Since the DocumentPDFStyler only accepts a file path to an image, we need to write the images to a file before sending the features to a DocumentPDFStyler.

As we want any images written to file cleaned up after the workspace runs, add a TempPathnameCreator and connect the GeoParquet feature type to this transformer. This transformer reserves a temporary file path for each input feature. In the TempPathnameCreator parameters, set the following:

• General
  • Extension: jpg

This will reserve a file path with the .jpg extension, but the TempPathnameCreator will not write the image binary data to file. To create the image file at the reserved file path, add an AttributeFileWriter transformer and connect the TempPathnameCreator to this transformer. In the AttributeFileWriter parameters dialog, set the following:

• Source Attribute: @Value(photo)
• Target Filename: @Value(_pathname)
• Target File Encoding: Binary (fme-binary)

Add a second DocumentPDFStyler transformer and add a connection from the AttributeFileWriter. Change the following parameters in the DocumentPDFStyler_2:

• General
  • Content Type: Image
• Image
  • Image Filename: @Value(pathname)
  • Width: 4
• Caption parameter group: Checked
  • Caption: Vancouver Public Library @Value(name)
• Link parameter group: Checked
  • Link: @Value(urllink)
• Styling
  • Alignment: Center
• Caption
  • Font Color: 0,85,127

These settings will set format attributes that tell the Document PDF to create four-inch-wide, centered images with captions in blue under the image. Clicking on the image in the output PDF will cause a web browser to open the library branch’s website.

4. Add Location Information

We will now add location information for the library branches as a Paragraph content type. Add another DocumentPDFStyler and connect the GeoParquet reader feature type to this newly added transformer.

The DocumentPDFStyler supports basic styling and hyperlinks via markdown with any text input, except for the Title content type. 

Multiple markdown syntax can be applied for more than one type of text styling. For example, to style text as bold and italicized, use the following syntax: __**Example**__.

Links are also supported and can link to an external URL, a page or a heading in the document.

Change the following parameters in DocumentPDFStyler_3:

• General
  • Content Type: Paragraph
• Paragraph
  • Text: [@Value(address), Vancouver](@Value(urllink)) - __@Value(location_description)__
• Styling
  • Top Padding: 3
  • Bottom Padding: 3

These settings will create a text content type, starting with the branch address that links to the branch website, followed by a hyphen and the location description in italics.

5. Create Hours of Operation Table

Now we want to add the hours of operation in a tabular form to the PDF. We can add a table using the Table content type in the DocumentPDFStyler. Add a new DocumentPDFStyler and connect the GeoParquet reader feature type to it.

Each feature sent to a table-type DocumentPDFStyler will be a row in the table. The hours of operation for each library branch are stored as a list attribute on the feature with each day of the week as a list element. Since we want each day of the week to be a table row, we must process the list attribute so each day is a feature.

Add a ListExploder transformer and set the following parameters:

• General
  • List Attribute: @Value(hour{})

This will create one feature for each list element in the hour{} list attribute, with the day of the week stored in the day attribute and the hours of operation in the time attribute.

Add a new DocumentPDFStyler and open the transformer parameters dialog to change the following parameters:

• General
  • Content Type: Table

• Table: 

  Column Header	Column Value	If Value is Image Path	Column Width
  	@Value(day)	Insert as Text	STRETCH
  Hours	@Value(time)	Insert as Text	STRETCH

• Styling
  • Border Layout: Internal
• Header
  • Background Color: 222,226,255

These settings will set Document PDF format attributes that will create a table with two columns filling the width of the page margins. The first column will contain the day of the week, and no text will be set as the header. The second column will have the hours of operation and Hours as the header text. The table will have only internal borders, and the header will have a pale blue background.

6. Add Closures List

The last library branch information to add is a list of branch closures. We want to add this information to the PDF as a bulleted list with a bolded “Branch Closures” title above the list. We can do this by adding two separate DocumentPDFStylers: one for the “Branch Closures” set to the Paragraph content type and one set to the List Item content type in their respective DocumentPDFStylers.

We’ll add the text first. Add a new DocumentPDFStyler and connect the GeoParquet feature type to the new DocumentPDFStyler. In DocumentPDFStyler_5, change the following parameters:

• General
  • Content Type: Paragraph
• Paragraph
  • Text:  **Branch Closures**

Now it’s time to add the list of closures.

Like the table content type, each feature sent to a List Item content type will become an item in a bulleted or numbered list, depending on the settings chosen in the DocumentPDFStyler.

Branch closures for each branch are stored as a list attribute on the feature, with each closure date as an item in the list. Since we want each closure to be a separate bullet, we must process the list attribute so each closure is a feature.

Add a ListExploder transformer and set the following parameters:

• General
  • List Attribute: @Value(closures{})

This will create one feature for each list element in the closures{} list attribute, with the closure date stored in the date attribute and the reason for the closure in the holiday attribute.

Add a new DocumentPDFStyler, add a connection from the ListExploder processing the closures{} list attribute, and open the DocumentPDFStyler_6 transformer parameters dialog to change the following parameters:

• General
  • Content Type: List
• List
  • Ordering: Unordered
  • Text: @Value(date) __(@Value(holiday))__

This will create a bulleted list, as the ordering is set to Unordered, with the closure date and the holiday in parentheses after. Notice that we have applied markdown styling using double underscores. As mentioned earlier, markdown styling can be applied to content types other than Paragraphs, except Title content types.

Your workspace should now look similar to this:

7. Add Writer

Add a Document PDF writer to your workspace. In the Add Writer dialog, enter the following:

• Format: Document PDF
• Dataset: C:\TEMP\Vancouver_Libraries.pdf

Click on the Parameters… button in the Add Writer dialog to open the Document PDF Parameters dialog. In this dialog, you can add page numbers to the output PDF, change document metadata, and set page size and page orientation.

Set the following writer parameters:

• Show Page Numbers: Checked
• Metadata
  • Title: Public Libraries of Vancouver, BC, Canada
  • Author: FME Lizard
• Page Size: A5

Then click OK twice to close both writer dialogs.

Connect all six DocumentPDFStylers to the Document PDF writer feature type. The workspace should now look like the image below.

8. Run Workspace

Run the workspace and open the resulting PDF document in a PDF viewer application. The output is a 28-page PDF document. Page numbers are at the bottom center of each page. When viewing the document properties, you can see that the document title is set to “Public Libraries of Vancouver, BC, Canada” and the author is “FME Lizard.”

However, the contents of the PDF may not be what you expected, as each content type is grouped instead of presented logically.

It is important to know that the Document PDF writer will add each item to the output PDF in the order in which features are sent to the writer. If a paragraph content type feature and a header content type feature are sent to the writer in that order, the output PDF will display the paragraph first and the header second.

9. Controlling Data Order

Controlling data order is essential for creating your desired output with the Document PDF writer.

One easy way of controlling data order is to add one or more sorting attributes and use the Sorter transformer. We can add an attribute to sort by and set the value to a number.

It is possible to add a sort attribute using an AttributeCreator or AttributeManager. However, since each DocumentPDFStyler requires a different value set for the sort attribute, this will almost double the number of transformers in the workspace.

An alternative is to add the attribute on a transformer’s output port. Move the cursor over to the output port of the DocumentPDFStyler, creating the library branch name header, and right-click to open a context menu. Select the Add Attribute… option. This will open the Edit Attribute dialog box.

In the Edit Attribute dialog, enter the following:

• Name: content_order
• Value: 1

Click OK to close the dialog. The output port should now have a purple symbol consisting of a V inside a circle. This is a visual indicator for attribute(s) have been created on a transformer's output port. Click on the purple symbol to view exposed attributes on the output port. Notice the purple arrow to the right of the new content_order attribute. This is an indicator that this attribute was created on the transformer's output port.

We have just set the sort value for the header content type. We need to repeat the previous step to create a content_order attribute on the remaining five DocumentPDFStylers. For this tutorial, we want content to be grouped per library branch, and within each group, we want the PDF to present information on each branch in the following order:

So the value of the content_order attribute on each DocumentPDFStyler should correspond to the order number of the table above.

Now that we have created a sort attribute through content_order, we can sort data sent to the Document PDF writer.

Add a Sorter transformer before the Document PDF writer feature type and add connections from all six DocumentPDFStylers to the Sorter. Double-click on the Sorter to open the parameters.

In the Sorter parameters, click on the box below Attribute to show the drop-down menu, then select the name attribute. Set Method to Alphabetic, then Order as Ascending. Next, add content_order and sort by Numeric Ascending. Lastly, add _elem_index and sort by Numeric Ascending. Sorting Exceptions can be left as the default value of "Output Last" for all attributes.

The Sorting Exceptions field in the Sorter transformer is new in FME 2025.1. If you are using an older version of FME, you will not see this field in the Sorter parameters and can ignore for this step.

The sorting by name attribute ensures that all information is grouped by library branch. The content_order will control the order of individual content within each library branch group. The _elem_index keeps the original list attribute order for the respective rows or items in the hours of operation table or the branch closures list.

Your workspace should now look like this after adding the Sorter transformer:

10. Run Workspace Again

Now you are almost ready to rerun the workspace. Make sure to close the PDF output that was previously created, or the Document PDF writer will error because it cannot acquire write permissions on a currently open file.

If data caching (previously known as feature caching) is enabled, you may want to disable it. The TempPathnameCreator transformer creates a temporary file path and deletes it at the end of each translation run. The writer will attempt to use the temporary file paths from the data caches, but will fail because those files no longer exist when using partial runs. You must disable data caching or rerun the entire workspace when data caching is enabled.

Run the workspace and open the output PDF in the PDF viewer application. The output PDF is now 32 pages and is presented in the order specified in the workspace. The writer will detect if the content being written does not fit on the current page and automatically place it on the next page, as demonstrated by the hours of operation table being split between pages 1 and 2.

11. Add Page Breaks

This automatic content placement means the heading for some library branches is placed in the middle of a page. You want the heading for each branch to appear at the top of a page instead, so each branch is more visible in the PDF. This can be done by using page breaks. A page break tells the writer to end the current page and start the next page. Page breaks can be used to separate content.

Go back to Workbench and add a Sampler transformer to the workspace. Connect the GeoParquet reader feature type to the Sampler input port. Double-click on the Sampler to open the transformer dialog. Change the following parameter from the default setting:

• Sampling Type: Last N Features

Now, add another DocumentPDFStyler and connect the NotSampled output of the Sampler to the input port of the new DocumentPDFStyler. Double-click to open the new DocumentPDFStyler and set:

• General
  • Content Type: Page Break

Move the cursor over to the output port of the page break-type DocumentPDFStyler, right-click, and select the Add Attribute… option from the context menu. Enter the following in the Edit Attribute dialog:

• Name: content_order
• Value: 99

Connect the output port of the current PDFDocumentStyler to the Sorter’s input port. 

These two transformers will add a page break feature for each library branch except the last branch. By not adding a page break feature to the end of the last branch group features, you will avoid an empty page at the end of the PDF document.

Setting the content_order attribute to 99 for the page break features isn't required, as its value can be any number greater than the upcoming closures content for a library branch group. Setting it to 99 does have the advantage of allowing you to add more content per library branch without requiring you to change the content_order attribute value.

Your workspace should now look like this after adding the Sampler and the DocumentPDFStyler for page breaks:

Rerun the workspace and open the PDF file in the PDF viewer application. 

The PDF file now has 42 pages and the heading for each library branch is at the top of every second page.

You have successfully created a PDF document with information on library branches in the Vancouver, BC, Canada public library system using the Document PDF Writer FME package.

Part 2: Create Document Content

This part demonstrates how to use DocumentPDFStylers to create a title page, table of contents, footer, watermark, and change page orientation in the middle of a document.

Continue with the workspace from the end of Part 1, step 11 of this article, in FME Workbench. If you skipped Part 1, download GettingStartedWithDocumentPDF_Part1_Completed.fmwt from the Files section of this article and open it in Workbench.

If the Document PDF Writer FME Hub package is not already installed for the version of FME used, you will see a warning dialog warning Workbench is about to install the “Document PDF Writer” package when opening the completed workspace. Select “Install” to install the FME package.

1. Create a Title Page

Add a Creator to the workspace and then add a DocumentPDFStyler. Connect the Creator to the DocumentPDFStyler. Double-click on the DocumentPDFStyler that you have just added to open the parameters dialog and change the following parameters:

• General
  • Content Type: Title Page
• Title
  • Text: Public Libraries of Vancouver, BC, Canada
• Styling
  • Font Color: 245,81,21

All other parameters can remain as the default values. For this article, only change the parameters listed in the bulleted lists and then exit the parameters dialog by clicking OK. All parameters not mentioned can remain set to the default values.

Add a connection between the DocumentPDFStyler’s output port and the Sorter transformer.

These settings will create orange text, “Public Libraries of Vancouver, BC, Canada”, in the default size 28 bold Times New Roman font for the title page.

2. Add a Subtitle to Title Page

You want to add a subtitle after the title. To distinguish between the title and subtitle, you want to use a different font color. To do this, add a second DocumentPDFStyler and connect the Creator’s output port to the input port of the newly added DocumentPDFStyler. Double-click on the second DocumentPDFStyler and change the following parameters:

• General
  • Content Type: Title Page
• Title
  • Text: A Demo for Getting Started with Document PDF Writing Tutorial
• Styling
  • Font: Times New Roman,BOLD,18
  • Font Color: 141,141,141

After closing the parameters dialog, connect this DocumentPDFStyler’s output port and the Sorter transformer's input port.

These settings will create bolded grey text, “A Demo for Getting Started with Document PDF Writing Tutorial”, in size 24 Times New Roman font for the title page.

As previously mentioned in Part 1 of the article, all content added to a PDF document is represented by a feature in the workspace. If you had connected the output of the first DocumentPDFStyler representing the title to the second DocumentPDFStyler representing the subtitle, the settings of the second DocumentPDFStyler would overwrite the first. If this were the case, only the subtitle would be on the title page.

3. Add Table of Contents

DocumentPDF supports adding a table of contents. The table of contents is automatically created from headings within the output PDF document. So any text you want to use for document navigation should have its content type set as Heading.

The heading text within the table of contents is a hyperlink that, when clicked, takes the user to the heading within the document. It is indented according to its heading level.

Add another DocumentPDFStyler, double-click the transformer and change the following parameters:

• General
  • Content Type: Table of Contents
• Styling
  • Heading
    • Font Color: 245,81,21

Add a connection between this DocumentPDFStyler’s output port and the Sorter transformer.

These settings create a table of contents with a centered title “Table of Contents” in orange, bolded Times New Roman font, size 24, and headings in the default black, size 12 Times New Roman font.

4. Set Page Properties

In Part 1, step 7 of this tutorial, we set the document properties, such as page size and orientation, through the Document PDF writer parameters. These writer parameter settings are applied for the entire PDF document.

However, what if you want different page sizes or page orientations in a PDF document? In this case, you can use the Page Properties content type in the DocumentPDFStyler to change aspects such as page size or orientation in the middle of a document.

The Page Properties content type also allows headers and footers to be set, along with a watermark. We will change the page orientation within the document, and add a footer and watermark to the PDF using the Page Properties content type.

Add a new DocumentPDFStyler and double-click on the transformer to open the parameters dialog. Set the following parameters:

• General
  • Content Type: Page Properties
• Page Properties
  • Page Orientation: Landscape
  • Footer Right: Visit www.vpl.ca for current information
• Watermark: Checked
  • Text: DRAFT
• Styling
  • Font: Times New Roman,8
  • Font Color: 141,141,141
• Watermark
  • Font Color: 245,81,21

Add a connection between the DocumentPDFStyler’s output port and the Sorter transformer’s input port.

These parameters will tell the writer to create landscape pages with a footer in size 8, Times New Roman and a DRAFT watermark in orange added to the middle of the page.

It is important to know that these page properties will only apply to PDF content that is sent to the Document PDF writer after this page properties feature. Any PDF content before this page properties feature will have the original page orientation of portrait as set in the writer parameters and no footers, headers, or watermarks.

Your workspace should now have five new transformers compared to the workspace at the end of Part 1: one Creator and four DocumentPDFStylers:

5. Control Data Order

Controlling data order is still important when creating document content. To output the title page first, table of contents second, and then change page properties, you need to ensure the data is sent to the writer in the correct order.

In Part 1, step 9, we controlled the order through the use of a sort attribute and the Sorter transformer. That is one way of controlling the order. We will now use another method for controlling order that does not involve creating a sort attribute.

You can control the order in which transformers run when a transformer outputs to multiple destinations from the same port through the connection runtime order. In the workspace, the Creator has connections to the DocumentPDFStylers, which allows us to set the connection runtime order.

To do this, right-click on a connection between the Creator and a DocumentPDFStyler. In the context menu, select the Select Runtime Connection Order… option to open the Connection Runtime Order dialog.

The Connection Runtime Order dialog shows the order the Creator will run any connection connected transformers. In the image above, the Creator will run the DocumentPDFStyler_7 (representing the title in the title page) first, then DocumentPDFStyler_8 (subtitle in title page), then DocumentPDFSytler_9 (table of contents), and the DocumentPDFStyler_10 (page properties) last. This is the order you want the DocumentPDFStylers to run.

If the connection order is different in your workspace or you want to change the order the transformers are run, select one of the entries in the table, and use the arrows below the connection order table to rearrange the order.

Double-click the Sorter transformer and change the Sorting Exceptions field of the name attribute to "Output First". As the four document content features do not have a name attribute (ie, the attribute is missing), the Output First option tells the Sorter to output features that do not have a name attribute first, meaning they will reach the Document PDF writer before any other features.

If you are using FME 2024.2 or 2025.0, the Sorting Exceptions field will not be available in the Sorter. As a workaround, add _creation_instance as a field to sort (numeric, descending) and promote it above the name attribute to get the same order

This Set Connection Runtime Order method is suitable for the workflow in Part 2 because there is one feature per DocumentPDFStyler, and each document content feature is sent directly to the Sorter before passing through its DocumentPDFStyler. 

This method does not work with the workflow in Part 1 as extra transformers such as TempPathnameCreator, AttributeFileWriter, ListExploders, may cause data to reach the writer in an expected order, due to the extra processing time required for these transformers.

6. Run Workspace

Run the workspace and open the output PDF in the PDF viewer application.

The first two pages of the PDF are in portrait orientation, and subsequent pages are in landscape orientation. There is a title page with a title and subtitle, along with a table of contents. Pages 4-7 contain content about the library branches as created in Part 1 of the article, but these pages now have a footer, watermark, and are in landscape orientation.

You have now created a title page and table of contents page, added document content like footers and watermarks, and changed the page orientation in the middle of the PDF using the Document PDF Writer package.

Troubleshooting

Images not appearing in output PDF

If the library branch images do not appear in the output PDF file, it may be because data caching (previously called feature caching) is enabled on the workspace. 

The TempPathnameCreator transformer creates a temporary file path and deletes it at the end of each translation run. When data caching is enabled, the writer will attempt to use the temporary file paths from data caches. However, those image files will no longer exist when using partial runs unless the TempPathnameCreator transformer is included as part of the partial run.

Either disable data caching on the workspace before running it again or rerun the entire workspace each time data caching is enabled.

PermissiorError [Errno 13]

If the Document PDF writer errors with:

Python Exception <PermissionError>: [Errno 13] Permission denied: 'C:\\TEMP\\Vancouver_Libraries.pdf'

Check the output PDF file is not open in another application. The writer cannot acquire the required permissions to create the PDF if the file is open. Either close the output PDF file or rename the destination PDF to a new file name in the Destination Dataset parameter for the Document PDF writer. 

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.