QPR Word Reports
Introduction to QPR Word Reports
QPR Word Reports is a technology to generate Word (.docx) and pdf reports displaying content from QPR systems. QPR Word Reports works in IIS as a web application, and reports are accesses by a url address. Data for reports is fetched from QPR systems using QPR Web Service interfaces. QPR Word Reports generates Open XML documents, which can be opened in Microsoft Office or OpenOffice.
Pdf reports are created by converting a generated Word document into pdf. Templates for the pdf reports are same Word templates as for the Word reports. The pdf reports are very versatile and support practically all features that the Word reports are able to show. By default, the created report is in the Word format, and when adding a parameter reportformat=pdf to the request url, the report is generated as pdf.
QPR Word Reports contains the following main features:
- Reports are run as they are requested, so the reports always contain the latest data.
- Reports can have parameters affecting report contents.
- All the tags may be defined using expressions (formulas) which values are calculated as the report is run.
- Report templates are normal Word files so they can contain any Word file features (such as headings, tables, cross references, headers, footers and images).
- Reports may get theirs content from other reports, called subreports. Also recursive reports are supported (reports calling themselves). Subreports makes it possible to assemble the report from smaller parts.
- Adding Word hyperlinks is possible
QPR Word Reports is based on the following concepts:
- Report templates are normal Word files and there are no restrictions in the allowed contents in the templates. When a report is run, a template is taken as a basis, and during processing of the report, content from QPR system is added to the template, forming the final report.
- Templates contain tags, which instruct how the content is added to the report and how dynamic parts of the report are built.
- Tags contain attributes, which offer additional information for the tag.
- QPR Web Service is used through its operations. Operations used by QPR Word Reports are GetAttributeAsString, QueryObjects, GetGraph, GetBinaryData and GetPortalUrl. All QPR Web Service operations are documented under http://kb.qpr.com/qpr2017-1/index.html?functions.htm.
- Subreport is a report that is called from another report (main report). The subreport is processed like any report and its contents are embedded in the main report. Main report may pass parameters to the subreport.
- Loop is a list of QPR system objects (elements) returned by QPR Web Service’s QueryObjects operation. In a loop, a subreport is called for every looped object.
To open QPR Word Reports reports in QPR Portal, QPR Reports Menu is needed. It’s able to automatically pass parameters, such as model or selected object to the report.
QPR Word Reports cannot itself store previously run reports, or run reports based on a schedule. When a report is viewed, it’s always generated at that point and data for the report is fetched from QPR system. Because of this, there may be a delay when getting a report, especially if the report contains dozens of pages.
Reports are accessed using a url address, which determines the report to be run and the url also passes all needed parameters to the report. The url depends on the server computer name and the path where QPR Word Reports is installed in IIS. Note that parameter names are case sensitive.
Example url to get a Word report:
http(s)://SERVERNAME/QPRWebServicesExtensions/DynamicWordReports.ashx?report=reportname¶meter1=param1value¶meter2=param2value
Example url to get a pdf report:
http(s)://SERVERNAME/QPRWebServicesExtensions/DynamicWordReports.ashx?report=reportname&reportformat=pdf¶meter1=param1value¶meter2=param2value
Configuration
Following table contains system parameters used by QPR Word Reports, configured in the web.config file of QPR Web Services Extensions.
| Parameter name | Description |
|---|---|
| reporttemplateparameter (optional) | Defines name of the parameter which passes the report template path. See chapter Working with Report Templates for configuring the report template path. The default parameter name is report. |
| reportformatparameter (optional) | Defines name of the parameter which passes the desired report format. The default parameter name is reportformat. The parameter can have values docx or pdf depending on which format is desired. Media type in the http response for Word reports is application/vnd.openxmlformats-officedocument.wordprocessingml.document and for pdf reports application/pdf. |
| qprtemplateidparameter (optional) | Defines name of the parameter which passes QPR Word Reports template object id. The default parameter name is qprtemplateid. This is used when the report templates are stored in QPR Portal (i.e. QPR system objects) (see chapter Working with Report Templates). Instead of report template path, the Word report template object id can be passed as a parameter. The Word report template object id gets a priority over report template path. |
| defaultimageformat (optional) | Default image format for QPR Web Service’s GetGraph operation. This setting is used if image format is not explicitly defined. |
Working With Report Templates
QPR Word Reports is based on Word report templates, which are normal Word files. When a report is run, the template is taken as a basis, and the tags in the template file are processed. Content is added to the report defined by the tags.
There are two options to reference to the used templates:
- Reports tab in QPR Portal: This option is suitable for running reports in production environments, because the report templates can be updated by QPR users (Portal administrator rights are required), and no access to QPR server is needed. Also, the report templates are stored in QPR system (i.e. in QPR database).
- A disk drive to where there is an access from the server running QPR Word Reports. This option is suitable for developing reports. It is faster for development because the developed template may be open while running the report. Also, option 1 requires the template to be saved manually to QPR Portal so that it can be run.
Both options can be used at the same time. If there are two templates with the same name in both places, the QPR Portal stored templates have priority.
Both Word file extensions (docx and docm) are supported. The output extension is the same as the extension of the main report template. File extension is not specified when referencing to template names in disk. If there are two files with the same name but different extension in the same folder, docx is selected as a template. Subreport extensions don’t affect the result report.
When stored in a disk, reports may be organized in folders. In that case report templates are referenced using syntax folderName/reportName. Folders inside folders are also supported. Report template root location is determined by configuration setting reporttemplatephysicalpath.
When a report processing fails, an html page showing an error message is displayed. The error message is likely to reveal in which report template and tag the error occurred.
Tags
Tags are used to add dynamic content to the report. Syntax for defining tags is following: <#tagname attribute1="attribute1 value" attribute2="attribute2 value" attribute3="attribute3 value">
If an attribute value is calculated using an expression (formula), two equals signs are used after the parameter name instead of one, e.g. <#tagname attribute1=="1+1" attribute2="1+1"> (attribute1 value is integer 2, attribute2 value is string "1+1").
In the following chapters optional tag attributes are marked with (optional). Other tags are mandatory – if any of them is missing, an error is caused. In addition, for some of the mandatory attributes the value of the attribute must not be empty (i.e. attributeName="" is not allowed). If the attribute value comes from an expression, note that the expression may evaluate as empty causing an error in non-empty mandatory attribute.
When processing a tag, attribute expressions are calculated from left to right. All report parameters, report variables and already calculated attribute values are available as expression arguments when later attribute expressions are calculated. An argument is a variable that can be used in an expression with syntax [argumentName]. E.g.: <#expression attribute1="3" value=="[attribute1] + 2"> (result is 5)
Tag specific arguments have a priority over report parameters and report variables, when there are same names used. Attribute names should only contain characters a-z, 0-9 and _.
Values for all boolean valued tags (such as visible) may be defined as true or false or as a boolean valued expression, e.g. visible=="[variable1]=1" (the result of the equality comparison is of type boolean). Tag visibility is processed in the normal left to right order. When the visible parameter is processed and its value is false, the tag processing stops at that point.
Following abbreviated tag names can be used: attribute = att, expression = exp, parameter = par and variable = var. Tags must be written in lower case.
Attribute Tag (att)
This tag is used to get properties of QPR objects by using QPR Web Service’s GetAttributeAsString method (more information: http://kb.qpr.com/qpr2017-1/index.html?getattributeasstring.htm).
This tag uses QueryObjects instead of GetAttributeAsString, if there are multiple id’s in the object attribute or if attribute followrelations used (more information below). If QueryObjects is used, separator and sortby attributes are applied
| Attribute | Description |
|---|---|
| object (string) | Object id or list of object id’s separated by comma (,). If this contains only one id, it is passed as a parameter objectId of GetAttributeAsString method. If this attribute is not provided or is empty, the tag will be evaluated to empty. (optional) |
| attribute (string) | This is passed as parameter attribute of GetAttributeAsString or QueryObjects method. |
| options (string) | This is passed as parameter options of GetAttributeAsString or QueryObjects method. (optional) |
| expression (expression string) | An expression where the result is put as an argument "value" (see the examples). (optional) |
| followrelations (string) | Name of the relation attributes to follow to get another object or a set of other objects. If there are multiple subsequent relations to follow, the relations are separated by comma (,) (see the examples). (optional) |
| separator (string) | Character(s) separating list of attributes of different objects. Empty values are not shown (i.e. no empties between separators). Default is a new line characters. (optional) |
| sortby (string) | Sorting if there are multiple objects returned. Default sorting is by attribute “name”. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| style (string) | Determines text style. See Defining Styles. (optional) |
Examples
<#attribute object=="[objectId]" attribute="name"> <#attribute object="[measureId]" attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" expression="[value] * 2.54"> <#attribute object=="[measureId]" followrelations="childobjects,childobjects"attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" separator=", " sortby="name">
Chart Tag
This tag fills in data to a chart when the report is run. The data is defined using a dataset, and it's placed on the Excel workbook that is embedded into the chart in the Word document. The chart needs to have a content control tag which points the chart (placeholder chart) to be modified by the chart tag. The content control tag is removed when the report is run, so it doesn't appear in the resulting report. The content control tag can be added to a chart as follows:
- Enable the Developer tab in Word settings (if not already visible).
- Create and select the placeholder chart.
- Click the Rich Text Content Control button (leftmost button having the "Aa" icon) in the Developer tab.
- Click the Properties button in the Developer tab (while the chart is selected) to open the Content Control Properties dialog.
- Define a Title and click OK. (cctag value needs to match with the title, and there must not be several content controls with the same name).
The following chart types are supported by the chart tag: Column, Line, Bar, Pie, Doughnut, Area and Surface (also 3-D and stacked charts are supported). Note that other chart types do not work and may cause a creation of an invalid Word file.
The chart tag has following attributes:
| Attribute | Description |
|---|---|
| data (dataset) | Data to fill in to the chart. |
| categorycolumn (string) | Name of the column in the dataset containing categories (horizontal axis labels). If not defined, the first column in the dataset is used for the category data. (optional) |
| cctag (string) | Name of the content control tag, pointing the placeholder chart to fill the data. Each chart needs to have different name for the content control tag. See above, how to add a content control tag for the placeholder chart. |
| seriescolumns (string array) | List of columns in the dataset containing the series data. Defined as an array of column names. If not defined, the columns starting from the second are used as series. (optional) |
| serieslabels (string array) | Names of the series shown in the chart. If not defined, the series column names in the dataset are used as visible series names. (optional) |
| title (string) | Defines a title for the chart, that is set dynamically when the report is run. If not defined, the title in the report template is preserved. (optional) |
| visible (boolean) | Determines whether the chart is visible. See Setting Content Visibility. (optional) |
Example:
<#variable name="chartData" value=="AddDatasetRow(AddDatasetRow(AddDatasetRow(CreateDataset(Array('Region', 'Rev', 'Cost')), 'Dallas', 8, 5), 'New York', 4, 2), 'Los Angeles', 3, 1)">
<#chart cctag="Chart1" data=="chartData" categorycolumn="Region" seriescolumns=="Array('Rev', 'Cost')" serieslabels=="Array('Revenue', 'Cost')" title="Performance by regions">
Dataset Tag
This tag is for showing information from a dataset in the report. Dataset consists of multiple columns and rows. Dataset tags shows a header subreport (once) and row subreports for each row in the dataset. Dataset tag has following attributes
| Attribute | Description |
|---|---|
| data (dataset) | Dataset shown by the tag. |
| headertemplate (string) | Subreport template for dataset header. The header subreport is shown once in the report above the row subreports. Header subreport can be used e.g. for showing a column names. Header subreport is optional, so if the parameter is left out, no header subreport is shown. Following type of parameters are passed to the header subreport: columnheader_1, columnheader_2, … columheader_n containing names of the dataset columns. If the column names are known, the header can be set fixed in the mainreport and header subreport is not needed. (optional) |
| headertemplatedata (byte array) | Alternative to headertemplate. Contains the used header template as a byte array. (optional) |
| rowtemplate (string) | Subreport template for dataset rows. The subreport is looped for each row in the dataset in the order rows appear in the dataset. Following parameters are passed to the rows subreport:
- column_1, column_2, … column_n containing dataset cell data |
| rowtemplatedata (byte array) | Alternative to row template. Contains row template as a byte array. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the looped subreports as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the Dataset tag. (optional)
NOTE: In QPR Reporting Add-on 2019.1, there is a bug, causing that the other attributes are not passed to the subreport, if the headertemplate or headertemplatedata is not defined. If the header is not needed, a workaround is to define in empty file to be used as a headertemplate. This issue is fixed by the next release. |
Embeddedfile Tag
This tags inserts an embedded file (using OLE technology) into the report. The file can be of any type. In addition to the file, an icon image needs to be defined. The size of the embedded object icon is set based on the size of the icon image.
| Attribute | Description |
|---|---|
| filedata (byte array) | Embedded file data as byte array. See available functions in expression language documentation in Binary Data Functions. |
| icondata (byte array) | Icon image as byte array. See available functions in expression language documentation in Binary Data Functions. Icondata is not needed when using replace mode and replaceable embedded file is showing its content in the Word instead of icon (DrawAspect="Content"). (optional) |
| contenttype (string) | Embedded file media type (also called MIME type). This information can be defined as fixed (when the content type is known in report design), or fetched using function available in expression language documentation in Binary Data Functions. List of media types: http://www.iana.org/assignments/media-types/media-types.xhtml |
| replace (boolean) | Enables the replace mode. This makes it possible to use an existing embedded file (a.k.a. placeholder content) in the template which is replaced by the actual embedded file. The replace mode enables to use Word styles and formatting, which will end up in the actual content of the report. The placeholder embedded file must be in the same or next paragraph of the tag. It’s advisable to use as small files as possible as a placeholder embedded objects so that the size of the template remains small.
Replace mode is activated with "true" or deactivated with "false". Default is false. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See chapter Setting Content Visibility. (optional) |
Example:
<#embeddeddata filedata=="qprEmbeddedFileData([objectid], ‘embeddedata’, ‘’)" icondata=="httpFileData(‘http://url…/’ + GetAttribute([objectid], ‘embeddedfilemimetype’, ‘’) + ‘.png’)" contenttype=="GetAttribute([objectid], ‘embeddedfilemimetype’, ‘’)">
Expression Tag (exp)
This tag is for adding a result of an expression (formula) in the report. The defined expression is evaluated and the result is set in place of this tag.
Note that the tag may contain any attributes which are serving as arguments to the value expression (see examples).
| Attribute | Description |
|---|---|
| value (object) | Shown value itself. Note that the values shown in the report are always technically strings (sequence of characters), so the value must be of a type that can be converted into a string, such as string, integer, double, datetime, boolean, or an array of any of the previous types. If the value is not a string, an implicit conversion to string is made.
In case of datetime type, dateformat defined in the Reportsettings tag is used. |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| style (string) | Determines text style. See Defining Styles. (optional) |
Examples:
<#expression value=="'Value is: ' + [variable1]"> <#expression value1=="5" value=="2 * [value1] + 1"> (result is 11).
Image Tag
This tag is used to show an image in the report. Images can be got using QPR Web Service’s GetGraph method, which can be used to get graphical content from QPR system, such as EA/PD diagrams, Metrics dashboards or measure graphs. For more information about GetGraph, see http://kb.qpr.com/qpr2017-1/index.html?ws_getgraph.htm.
When getting images using http, many kind of errors may be encountered, such as the image is not found, it’s not available, or user rights restrict. In case an image cannot be got, the report run still succeeds. If the reason for the error is not known, it’s possible to see the http error message by using the loggingmode. Note also the noimagemessage attribute which is used in case of these errors.
Image size in Word depends on its resolution and the properties listed below. Image size is calculated as follows:
- dpi defines image base size (dpi can be defined explicitly or used image’s dpi value)
- scaling is applied after that (expanding or shrinking)
- maxwidth and maxheight restrictions are applied last (always shrinking)
In attributes dpi, scaling, maxwidth and maxheight expression it’s possible to use following arguments representing information from the image (see an example below):
- width (int)
- height (int)
- horizontaldpi (decimal)
- verticaldpi (decimal)
- format (string) (e.g. png, jpeg, gif)
Note that image resolution (width and height in pixels) is determined by QPR Web Service, so that can be affected only using web service’s parameters (parameter options).
If you need an image to appear always as a certain size regardless of its resolution, the scaling can be defined as a large enough number, and set maxwidth (or maxheight) to be the desired image size. This way the maximum width restriction is always applied and the size of the image is the desired.
| Attribute | Description |
|---|---|
| imagedata (byte array) | Image as a byte array. See available functions in expression language documentation in Binary Data Functions. Note that the type of the file needs to be a bitmap image e.g. png, jpg or gif. (optional) |
| object (string) | This is passed as a parameter objectid of GetGraph method. (optional) |
| options (string) | This is passed as a parameter options of GetGraph method. (optional) |
| dpi (decimal) | Determines the image size as dots per inches. If not defined, dpi information of the image itself is used. (optional) |
| scaling (decimal) | Image scaling as percentage value ("100" means no change). The scaling is used to change the size of the image in the report.
E.g. value "200" doubles the size of the image. Scaling is applied before maximum width and height restrictions. (optional) |
| maxwidth (decimal) | Maximum image width in centimeters. If the image is wider than this maximum width, the image is scaled smaller to so that its width is this maximum width. (optional) |
| maxheight (decimal) | Maximum image height in centimeters. If the image is higher than this maximum height, the image is scaled smaller to so that its height is this maximum height. (optional) |
| crop (boolean) | Determines whether unnecessary borders are removed from the image. Needed if the image contains too much white (or other background color) space. If the whole image is white color it is removed. Either "true" or "false". Default is false. (optional) |
| croptop (integer) | Number of pixels to remove from the top side of the image. If trying to remove more than the size of the image, heigth of the resulting image will be one pixel. (optional) |
| cropright (integer) | Number of pixels to remove from the right side of the image. If trying to remove more than the size of the image, width of the resulting image will be one pixel. (optional) |
| cropbottom (integer) | Number of pixels to remove from the bottom side of the image. If trying to remove more than the size of the image, heigth of the resulting image will be one pixel. (optional) |
| cropleft (integer) | Number of pixels to remove from the left side of the image. If trying to remove more than the size of the image, width of the resulting image will be one pixel. (optional) |
| backgroundcolor (string) | Defines the background color of the image for cropping unnecessary borders. The background color is defined as an RGB hexadecimals, e.g. "00FFb7". Default is white ("FFFFFF"). (optional) |
| replace (boolean) | Enables the replace mode. There is a possibility to use an existing picture (a.k.a. placeholder picture) in the template which is replaced by the actual picture (this is the replace mode). The replace mode makes it possible to use Word styles and formatting, which will end up in the actual picture in the report. The placeholder picture must be in the next paragraph of the Graph tag. The placeholder picture may be any picture, and its size don’t matter.
Replace mode is activated with “true” or deactivated with “false”. Default is false. (optional) |
| noimagemessage (string) | A text appearing instead of the image if no image could be added to the report for some reason. The reason may be that QPR Web Service didn’t return any image or there was nothing left of the image after the cropping. This message is the only case when style attribute is needed for this tag.
For instance the message could be "No image is available". (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| style (string) | Determines text style. See Defining Styles. (optional) |
Examples
<#image object=="[diagramid]" options="graphtype=processlevel,witdh=1500" dpi="100" maxwidth="17.5">
<#image imagedata=="httpFileData('https://www.qpr.com/')">
Link Tag
This tag is used to add a hyperlink in the report (both QPR Portal and external links). If the link address is empty or not valid for any reason, no link is displayed by the tag.
| Attribute | Description |
|---|---|
| address (string) | Hyperlink’s url address or location. Note that the address must not be added as a Word’s hyperlink format but as a text. QPR Portal links can be got using an expression and GetPortalUrl function. |
| text (string) | Link’s displayed text. |
| screentip (string) | Link’s screen tip (see Insert hyperlink window). (optional) |
| target (string) | Link’s target (see Insert hyperlink window). (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| style (string) | Determines text style. See Defining Styles. (optional) |
Example
<#link address=="getportalurl([diagramid], '', '')" text="Link to QPR Portal" target="_BLANK" screentip="Click here is go to QPR Portal">
Loop Tag
This tag is for looping through content in following alternative ways:
- Set of QPR elements defined by a QPR Web Service query (for more information of QueryObjects, see http://kb.qpr.com/qpr2017-1/index.html?queryobjects.htm).
- List of strings (using attribute list). The list itself is a string where items are separated using defined character.
The defined subreport is called for every looped object.
There is a loopindex parameter passed to the subreport (starting from 0).
Word sections are not transferred from subreports to a mainreport.
| Attribute | Description |
|---|---|
| template (string) | Template name for the looped content for file system templates (without the file type extension). For more information see Working With Report Templates. (optional) |
| templatedata (byte array) | Looped template file as a byte array. See available function from Binary Data Functions. (optional) |
| query (string) | This is passed as a parameter query of QueryObjects method. "List" attribute is alternative. (optional) |
| criteria (string) | This is passed as a parameter criteria of QueryObjects method. This filters the output set of objects. (optional) |
| sortby (string) | This is passed as a parameter sortby of QueryObjects method. This determines the order of the looped objects. Note that without sorting the report may look different between runs. (optional) |
| attributes (string) | This is passed as a parameter attributes of QueryObjects method. All the queried attribute values are added as parameters to the subreport. (optional) |
| options (string) | This is passed as a parameter options of QueryObjects method. (optional) |
| loopparameter (string) | Defines the name of the parameter that is passed to the subreport containing the looped object id. Like other parameters, also this parameter needs to be defined in the subreport. |
| filter (expression string) | Additional filtering for returned objects. This filtering is applied after QPR Web Service query results have been returned to QPR Word Reports. The filter is defined as an expression (it’s not a QPR Web Service criteria), which must evaluate to boolean. The filter expression is evaluated for each returned object separately. If it is evaluated to false, the object is filtered out.
All looped subreport parameters, and report parameters and expressions are available as arguments for the expression. This additional filtering may be used if the desired condition cannot be written using QPR Web Service’s criteria. Using QPR Web Service’s criteria is recommended because it offers better performance. (optional) |
| sortvalue (expression string) | An expression which results are used to sort the returned objects. This sorting is applied after the QPR Web Service’s sorting (which is determined by attribute sortby). All looped subreport parameters, (main)report parameters, (main)report variables are available as expression arguments (subreport parameters have a priority in name conflicts).
Note that because sortvalue is an expression itself, only a single equation sign is usually used. |
| list (array) | List of items as an array that is looped through (instead of a QPR Web Service query). When this attribute is used, no QPR Web Service query is made, and thus the following attributes are ignored: query, criteria, sortby, attributes and options. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the looped subreports as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the Loop tag. (optional) |
Example
<#loop template="Process report" loopparameter="diagramid" query=="'[' + [diagramid] + '].ChildObjects(hierarchy=\"processlevels\")'" sortby="name" attributes="description,owner.name(as=\"processowner\")" recursionlevel=="[recursionlevel] + 1">
In the example, "recursionlevel" is an additional parameter that is passed to the subreport. Also parameters "description" and "processowner" are passed to the subreport.
Parameter Tag (par)
This tag defines parameters for the report. Only parameters that are defined using these tags are used by the report. The report request url may contain other parameters which are omitted.
| Attribute | Description |
|---|---|
| inputname (string) | Name of the parameter (url parameter name or a parameter name passed to subreport). |
| outputname (string) | Parameter name used in the report. If this is not defined, the used name is same as input name. (optional) |
| defaultvalue (object) | The default value is used when a parameter value is not passed to the report. If no default value is defined and no parameter value is passed, an error occurs. (optional) |
| validation (expression string) | Validation expression for the parameter. There is an argument “value” available for the expression containing the parameter value. If the expression returns false, a validation error is thrown by the report. |
| validationmessage (string) | Error message to show, if the validation fails (see parameter “validation”). |
Example
<parameter inputname="nameOfUrlParameter" outputvalue="nameInTheReport" defaultvalue="value1">
Reportsettings Tag
This tag is for defining report level settings. In subreports this tag is not used (it’s ignored). The tag is optional. Only one tag of this type can exist in a template.
| Attribute | Description |
|---|---|
| name (string) | Name of the downloaded file. If this is not defined, file name is same as name of the template. (optional) |
| updatefields (boolean) | Defines that Word updates all the fields in the document (table of contents, references, etc.) when the document is opened. Alternatives are “true” or “false”. Default is false. Note that Word shows an message when a document is opened that fields are to be updated, and gives also an alternative of not to do it. (optional) |
| dateformat (string) | Format for showed dates. More information about formatting http://msdn.microsoft.com/enus/library/8kb3ddd4(v=vs.100).aspx. Default value is yyyy-MM-dd. (optional) |
| contentdispositiontype (string) | Alternative values are attachment and inline. This is the http response’s content disposition’s disposition type. Default value is attachment. For more information http://www.ietf.org/rfc/rfc2183.txt. (optional) |
Example
<#reportsettings name="Process report" updatefields="true" contentdispositiontype="inline">
Subreport Tag
This tag is for adding content of another report (subreport) to a report (main report). This tag is useful e.g. when there are parts in a report that are structurally similar (making it possible to reuse a subreport where a part is defined once).
Word sections are not transferred from subreports to a mainreport.
| Attribute | Description |
|---|---|
| template (string) | Report template name (without file type extension in file system templates). For more information see Working With Report Templates. (optional) |
| templatedata (byte array) | Looped template file as a byte array. See available function to get data in Binary Data Functions. (optional) |
| passallparameters (boolean) | Passes all report parameters and variables to the sub report. |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the subreport as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the Subreport tag. (optional) |
Example
<#subreport template="Report 2" param1="value1" param2="value2" param3="value3">
Variable Tag (var)
This tag is used to add variables to the report. One tag defines one variable. Variables can be referenced in other tags using expression arguments. Variables are processed in the order they appear in the report. It’s a good practice to place the variables in a same place in the beginning of a report. Variable values cannot be changed during the report run – their value is calculated when the report run begins.
Variables are useful, when there is an expression which value is used several places in the report. Variables may also be used to simplify formulas, when part of a formula is defined as a variable.
There must not be a variable having a same name as a parameter in the same report. The scope of variables is the report template. If the variable must available in a subreport, the variable must be passed as a parameter to the subreport.
| Attribute | Description |
|---|---|
| name (string) | Variable name. |
| value (object) | Variable value. |
Example: Report has tag <#variable name="variable1" value="2">. This variable can be used in other expressions, e.g. <#expression value="3 + [variable1]"> (result is 5).
Direct Tags
It’s possible to reference to report parameters and variables using tags which name equal parameter or variable name. These are called direct tags. For example if a report has a variable var1, a tag <#var1> can be used. Note that, the same result can be achieved using variable tag: <#variable value=="[var1]">. Purpose of direct tags is to shorten tag syntax.
Note the following when using direct tags:
- Direct tags cannot contain any attributes, unlike all other tags always contain at least one attribute.
- In the direct tags, variable value is implicitly converted into string. E.g. date variables are converted using date format defined in the Reportsettings tag.
- In direct tags it’s not possible to define styles using styles attribute.
- It’s not possible to use "visible" attribute.
- When writing direct tags, note the letter case in parameter and variable names.
Expression Language
QPR Word Reports uses an expression language enabling all tag parameters can be written using expressions (formulas). Expressions makes it possible to define values dynamically (values that are calculated when the report is run). Expression parameters are defined using two equal signs instead of one. As an example, a parameter value may be static, such as visible="false", or the parameter value may come from an expression, such as visible=="[typename]='Activity'".
When writing tags, characters escaping is needed. There are three levels where escaping need to be done, explained in the table below.
| Level | Purpose | Needed escapings | Example |
|---|---|---|---|
| 1 | QPR Web Services | Characters \ and " are written \\ and \" | QPR Web Service query: [PG].models(criteria="name=\"model'1\"") |
| 2 | Expressions | Characters \ and ' are written \\ and \' | Previous query escaped for an expression: [PG].models(criteria="name=\\"model\'1\\"") |
| 3 | Template tags | Character " is written \" | Previous expression escaped for template tag: [PG].models(criteria=\"name=\\\"model\\'1\\\"\") |
Note that the escaping for expressions (level 2) is only needed, when the query is an expression.
Data from main report to subreport may be passed in any datatype, so it doesn’t have to be converted to string. Still, parameters passed to a main report from a url are always strings.
If an expression returns a datetime value, it is implicitly converted to string if it’s shown in Word report (reportsettings tag’s dateformat parameter is used here).
Setting Content Visibility
All applicable tags support the parameter visible, which is used to remove the whole content that the tag is about to render. Available values are true (shown) or false (hidden). The value may be a static or a result of an expression. By default, the visible property is true (the tag is shown).
Defining Document Styles
There are two ways to defined styles in the reports:
- Apply styles in the template (static way): All the styles applied in the template are in the final reports. Styles can also be defined for tags, meaning that the style is applied for the content produced by the tag. If a style of a text block is always same, it is easiest to use this way.
- Use the "styles" parameter (dynamic way): All applicable tags support the parameter style, which is used to dynamically determine the style of the paragraph or characters that is rendered by the tag. Value of the style tag is simply the name of the style. Both paragraph and character styles may be used.
Note that the style must exist in the Word file, so that it can be used dynamically. All the available styles in Word are not necessary stored in the Word file, although they are visible in the ribbon in the Word application. To make sure the style definition is in the Word file, the style needs to be used somewhere in the template. If you need to add text to the report that should not to be in the final report, it is possible to use Variable tags for this purpose because they disappear in the final report.
As an example, in recursive reports the heading level is determined by how deep the processing is in the recursive tree. For that you can add style==‘Heading ’ + [recursionlevel]", where recursionlevel is a parameter or a variable increased by one on every subreport call when going deeper in the hierarchy.
Authentication and Data Security
When using QPR Word Reports there are the following levels of security to consider:
- QPR Web Service: Data to the report is fetched using QPR Web Service, and thus available data is restricted by the rights of the user that is used to authenticate to the QPR Web Service. Authentication options to the QPR Web Service is explained in the configuration instructions.
- Report template files: The report templates are in the file system, and thus there are no security restrictions to the report template files itself (the files cannot be accessed, but the result report may reveal the content of the template).
- Links to reports: Reports are run by referencing them using a url, and these links may be in the portal (e.g. in the reports dropdown list). It's advisable that users which don't have rights to a report, don't see the report link at all (otherwise they get a not found error message). This is actually a usability issue, not security issue.
Best Practices for Developing Reports
- Use the QPR Web Services tester: Most of the errors are related to QPR Web Services query or the expression language syntax. That’s why, before placing queries to QPR Word Reports templates, use the QPR Web Services tester to check that the query syntax is right.
- Use descriptive names for templates and variables: Prefer names that describe content of report or variables.
- Use subreports to reuse report parts: If there are parts in a report that are structurally same, they can be put in a subreport and reused by calling the subreport with different parameters.
- Use variables to split complex tags: If there are complex formulas, parts of the formulas can be put in variables. This makes the report templates easier to read. Also, if there is same static formula in multiple tags, the formula may be put in a variable, so that it is calculated only once for the report offering performance advantages.
- Prefer to run the logic in QPR Web Service: When possible, write logic to run in QPR Web Service instead of formulas, because it offers performance advantages when round trips to Web Service are reduced.