Document assembling

Most often the documents created with RPE contain data obtained from product repositories through reportable APIs supported by RPE. The flow of the document is linear, that is the position of a template element in the output document matches the order in which the element appears in the template.

There are however scenarios for document generation where data comes from other documents and it’s possible that the output flow to be different from the input flow. Moreover it is possible that the output does not start from a blank document but rather continues and fills an existing document.

The examples used in this post are available here [DevWorks].

Include file

Limited to the Word and “New PDF” outputs.

The “INCLUDE FILE” template element allows inserting the content of another document in the output. The format currently supported by RPE and newer are doc, docx, docm, dot, dotx, dotm and rtf.

The included file can be located on the filesystem or from web via http/https. If the included is included from a web location RPE first downloads the file in a temporary system folder and includes it from there.

NOTE it is recommended you embed included files if you want to share them with other users easily. To break links ( embed the included files) in Office 2007/2010 select the entire content with Ctrl+A than press Ctrl+Shift+F9

NOTE the content of the included files will not be visible in the output document until the fields are updated manually or via a macro ( such as the rpe macro).

The template is available here [DevWorks].

Template regions

These are template elements that allow redirecting the normal output flow to specific parts of the output.RPE will create markers in the output for each region and any element using the region will have its content directed to the marker position. The markers used depend on the output format. For Word the markers are Word bookmarks.

In the example below the container will be rendered at the start of the document although it’s not the first template element.

To direct a template element and its children to a specific section you need to specify the target region’s name in the common/target region property. The target region can be a region in the template as in this case or a bookmark in a stylesheet.

NOTE if a region does not exist the content goes in the normal output flow.

A snapshot of the template showing the region and a container using it is shown below. The template is available here [DevWorks].

Here is the PDF Output showing the disclaimer text coming ahead of the include file. The full PDF document is available here [DevWorks].

NOTE regions are static elements evaluated by RPE at the start of the document generation. As such you cannot have them generated dynamically nor can you conditionally include or exclude them (RPE Studio allows defining conditions for regions but that is a defect).

Any template content can be redirected to a region.


Limited to the Word and “New PDF” outputs.

The main purpose for stylesheets is to define the styles (formatting) used in a template. They are useful tools to use since they allow users familiar with Microsoft Word to use that tool and also increase the reuse of your template.

Decoupling the formatting from the report content whenever possible is considered a best practice for document generation with RPE. Define the structure and content in the template and add/change/refine the formatting using stylesheets.

Besides providing formatting to documents the stylesheets can also provide content to your document. The most common scenario is having the front page content defined in the stylesheet. Using stylesheet regions as shown below take the utility further transforming them into forms that RPE will fill with data.

Stylesheet regions

Limited to the Word and “New PDF” outputs.

A more interesting and dynamic scenario is using regions defined in stylesheets. The stylesheet regions are nothing more than bookmarks in the Word document used as stylesheet.

When such a stylesheet is provided and the template is designed to use the regions in it the document generation process is very similar to filling a form where the blanks are the stylesheet regions.

The stylesheet used in the example is shown below. It defines 3 regions that will be used in the template: bmkAuthor, bmkLegal and bmkIntroduction. The stylesheet is available here [DevWorks] and the result is here [DevWorks].

NOTE when generating the Word output do not forget to update the fields ( Ctrl+A, F9 on Word 2007/2010) to make visible the included files.

NOTE Word bookmarks are limited to 40 characters in size

The template has been modified to use regions defined in the stylesheet as it directs various parts of it to the bmk* regions. The template is available here [DevWorks]. A document specification setup to use the template and stylesheet is available here [DevWorks].


Using the “INCLUDE FILE”, Template Regions, Stylesheets and Stylesheet Regions you can use RPE to assemble Word documents using document fragments and data coming from tool repositories. With RPE and its New PDF output the functionality is available for the PDF output also.


Author: Dragos Cojocari

Architect for Rational Publishing Engine

7 thoughts on “Document assembling”

  1. Could you please fix the links? I think there are broken as the wiki has changed

  2. Dragos,

    I am trying to use target regions to update the text of a bookmark in a Word Stylesheet that is then used later in the stylesheet (document name and number). I was able to use the Target Region on a text element and the text showed up in the generated document. However, the dummy text in the stylsheet for the bookmark definition was not replaced. Is there a way to have the contents of the original bookmark replaced?

    Did you find the documents referenced in this article? Can they be made available again?

    Jamie Berry (General Dynamics)

  3. Hi Dragos,

    I am trying to include an HTML document (which has links to images) into an RPE template (RPE 2.0 iFix01).
    This HTML content is a representation of an XSD generated by a 3rd party application.

    The HTML text content renders perfectly (including tables), however the images are not being included, and are instead the “image not found” picture is displayed. All links to the images in the HTML file use a relative URL.

    Can you please give me some advice on how to correcly include this HTML content (without having to perhaps convert the HTML content into a Word document first).

    Thanks in advance,

  4. Hi Dragos,

    I would like to set the position of the normal output flow to be placed just after an existing bookmark in the .dot file instead of the end of the document. How can this be achieved?

    Note: I already tried to put the whole output inside the bookmark using Target Region. This is not exactly what I expect and I could accommodate with this solution except that it introduced unacceptable side-effects: all dynamic bookmarks created by RPE in the Word output do imbricate and span with each other. As a consequence the final vba macro that deals with these bookmarks gave unpredictable results.

    Thanks for your help,
    Pierre (using RPE 2.1)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s