Skip to main content

Import reference


Tag: import tag: <wr:import ... />

Use this tag to import an external file into the report at the time the report is generated. For example, you can use it for a cover sheet for the report, an image such as your company logo, or other templates for individual report modules that you are combining to create this report.

Your data source must contain the location (either a URL or filename) of the content to import, not the actual content itself. For example, with HTML and images, the location of the data must be in the data source, 

not the data itself. If the actual data is in the data source, you would use the out tag instead.

Import Limitations

There are several limitations when you import an RTF or WordML file, because there can only be one final document (your resulting report). All header information in the imported file is ignored, including the default language, font, style, page size, margins, headers and footers. Footer information in sub-templates is not currently supported and will be blank. However, section breaks and their settings are imported into the final document. Adding section breaks to the beginning of the sub-template(s) and removing page breaks from main template will correctly load the sub-template orientation in the final report.


All styles will map over by name. Identical style names are not checked for, and if they occur, there is no check to see if they have identical settings. The settings used will be those of the parent template, which is the template you are importing files into. Fonts and colors map to the resulting document using existing entries from the parent document, if they exist, and adding new entries if they don't exist. All list entries in the imported document become new list entries in the parent document — no attempt is made to map identical list entries together.


Note: Version 13 introduced an import tag that allows you to choose between parent and child when there is a style conflict (for example, when the Normal style is different in the two documents).  For more information see the article Applying Master Styles to Imported Sub-Documents.

Importing Templates

When the template being imported has the same style names as the master template, but the settings for that style differ, then text set to that style in the sub-template can either retain the formatting in the sub-template or can have the master style applied to it.

Previous to version 11.1.24 what occurred here was undefined and in practice depended on the report format.

There are now two modes that can be set for the engine on a global basis:

Retain Sub-Template Formatting (Default)

The sub-template text will retain the formatting it has in the sub-template. Where formatting is due to the style applied to characters in the sub-template, and that formatting is different from the master template, those formatting settings will be explicitly set on the range of characters.

If a given style has some settings different, but other settings that are identical, the identical settings will not be explicitly set.

Apply Master Template Styles

To use this mode, you must set the following in your properties file:


All styles in the sub-template that have matching styles in the master template will be set to use the style settings in the master template. Any formatting explicitly set will be left alone.

How This Plays Out

  1. The style sheet in the master template, and all the style settings in that master template will not change. Regardless of settings, that is left alone.
  2. When an imported template has a style that is not in the master template list of styles, that style will be added to the master template's list of styles and that style will carry across as used in the imported template.
  3. When an imported template has a style with the same name, and all settings are the same, then everything is imported and left alone (this is the best way to do it).
  4. When an imported template has a style with the same name, but different settings then:
    1. If import.use.child.styles=false then the imported template has no changes made to any formatting and so the style applied, as defined in the master template, is now applied to the child content. However, if any text in the child content has explicit formatting set, that explicit formatting remains. SO if the master style is bold, the child style is regular, and in the child text some of the text is explicitly set to regular, then after imported, that explicitly set text will remain regular while the rest will become bold.
    2. If import.use.child.styles=true, then imported text with a style with the same name but different settings will retain that style setting, but for the formatting settings that are different, and only the ones that are different, will be set explicitly at the start of the paragraph so that the paragraph will be formatted as in the imported document. Again, and places where the text is explicitly formatted will not be changed.
  5. And for bulleted & numbered lists, all bets are off. They way they are set in Word is through multiple sets of indirection and there is no safe way to marry them up.

Passing a URL

When we are passed a URL, we assume it is not encoded. If the url includes “%20” which, in an encoded url means a space, we assume it is actually a % followed by the string “20” and will then encode it to “%2D20”. There are good arguments both for assuming a url is encoded and a url is not encoded. We went with pass it in not encoded. 


One of these two attributes must be set:

  • select - required
  • break - The break tag can have multiple settings separated with a ;. For example "before-page;after-inline". For conflicting values, such as "before-inline;before-page", it will use the more significant setting (distinct trumps all, page trumps inline).
    • before-page - places a section page break before the import
    • after-page - places a section page break after the import
    • both-page - places a section break before and after the import
    • before-inline - places the section page break before the import
    • after-inline - places the section page break after the import
    • both-inline - places the section break before and after the import
    • distinct - Section page break before and after, remove empty paragraph before/after import tag. If preceded by a section break or document start, the imported section will be assigned to that section and there will not be a preceding section break. The original settings in the master document will be assigned to the trailing section break.
  • credentials - The credentials for opening the imported file. In the form username:password or ${var} 
  • source – optional (Java engine only). The URL will ordinarily be read in this order: To force the URL to be read as one specified source, set the source attribute to one of these values:
    • THREAD - Thread.currentThread().getContextClassLoader()
    • APP-CLASS - ProcessReport.class.getClassLoader()
    • SYSTEM-CLASS - ClassLoader.getSystemResource(propFile)
    • URL - as a URL (using URL.openStream())
    • FILE - as a file via filename, local path or UNC path

                    These protocols are only used if explicitly set

  • REST - read using the REST protocol for http requests and responses.
  • ASSEMBLY - (.net only) read from the application's assembly.
  • SHAREPOINT - (.net only) read using the SharePoint forms based authentication API. You must set credentials to use this mode.
  • type – optional. The file type to import. If this attribute is set, the file’s extension is ignored. Valid file types are: TEMPLATE, BITMAP, PDF AND TXT.

  • If using PDF (only supported for output to PDF), make the type property, 'type=PDF'. How this functions will depend on what report type you output to:
    • If you output your report to PDF format, the PDF file(s) are separate pages inserted at the beginning of your report. Windward Reports starts a new page, adds the imported file as the next N pages, then resumes the report at the top of a new page following the imported PDF. If there are two PDF imports in a row, the second starts on a new page after the first. In other words, the imported PDF pages are not modified or combined with any Windward Reports commands; they are inserted at the start of your report.
    • Other formats that are page-based (DOCX, XLSX, WordML) will have a single blank page for each imported PDF file.
    • Other formats that are not page-based (html) will skip the PDF file.
  • default – optional. If the node in the select attribute does not exist or is empty, it will use the URL of this attribute. Note that this is used as a URL or filename, not as the contents of a file

  • display - 

    • notEmpty. Display only if string is not empty.

    • notNull. Display if the data node exists, even if it is an empty string.

    • Always. Display even if the node does not exist.

A boolean expression. For example you could use <wr:out select=’\root\company\address2’ display=’expression’/> where true is displayed and false isn’t.

BITMAP Type Only

  • wrap – optional. For bitmaps only, set this attribute to control how the image is placed.

    • INLINE (default) - This is the way Word normally places an image into a document, with text before and after it continuing to flow, but with only one line of text matched up with the image.

    • FRONT – The image is placed above the text. The text is not moved around the image.

    • BEHIND – The image is placed below the text. The text is not moved around the image.

    • SQUARE – The text is placed on both sides of the image – if it fits – but will have multiple lines of text to the sides, depending on how tall the image is.

  • image-size
    • bitmap - use the size of the bitmap (most bitmaps have a DPI setting. So pixels/DPI is inches.)
    • specified - use the width and height setting.
    • specified-width - use the width setting and scale the height by the same amount.
    • specified-height - use the height setting and scale the width by the same amount.
    • fill-width - set the width to the width of the paragraph or table cell the image is in and scale the height by the same amount.
  • height - set the height in twips.
  • width - set the width in twips.
  • horz-align - left, center, or right.
  • vert-align - top, center, or bottom.
  • horz-position - column, inline, margin, or page.
  • vert-position - inline, margin, page, or para.

XML Usage

<wr:import url="./name"/>

This will read the value from the node and will assume the value is a filename. This file is then read in. The file extension is used to determine what type of file it is, unless overridden with the type attribute.


<wr:import value="${item}"/>

which will replace that tag with the text in the referenced variable. The ${item} elements can come from the var and varStatus attributes in a forEach tag, the var attribute in a select tag, from a map of key/value pairs programmatically passed to Windward Reports, or from a view (in the case of a JDBC data source) programmatically passed to Windward Reports.

SQL Usage

<wr:import url="select FILENAME from PRODUCTS where PRODUCT_ID = %{item.PRODUCT_ID}"/>

This select (like all selects) returns all matching rows. Next, the value in the first column of the first row returned is read as a filename. This file is then read in. The file extension is used to determine what type of file it is, unless overridden with the type attribute.

Complex Example

<wr:import url="./name" type=”JPG” source="FILE"/>

where ./name will return “c:/picture.jpg”.

<wr:import url="./name" type="JPG" source="URL"/>

where ./name will return "".

Deprecated Information

RTF support for new features has been deprecated, please use the DOCX format for your files that you will import in the future.

To read more access the article below:

Windward has discontinued new feature support of the RTF format


One of these two attributes must be set:

  • url – [DEPRECATED, replaced by SELECT] required (unless value is set). The node that contains the filename.

  • value – [DEPRECATED, replaced by SELECT] required (unless url is set). Displays the contents of a variable. Set this attribute to the name of the variable. (The data source is not accessed.)

  • Was this article helpful?