QPR Reporting Add-on

introduction

QPR Reporting Add-on is a combined installation package containing the following parts:

•QPR Web Views

•QPR Word Reports

•Expression Engine for QPR Suite

•QPR Reports Menu

All parts except QPR Reports Menu are .Net 4.5 web services hosted in IIS, and they interact with QPR Suite using QPR Web Services interface. All parts also contain the common expression language.

In addition to the general installation instruction described by this document, the individual parts contain additional settings which are described in their own documentation.

QPR Reporting Add-on doesn’t have any compatibility defined for QPR Suite. See the compatibility of individual accelerators.

installation

Follow these steps to install QPR Reporting Add-on. There are different paths for each QPR Suite version. These instructions use X in the folder names, that is replaced by the number of the corresponding QPR Suite version.

1. Check whether the QPR environment uses Windows authentication (IWA) and/or HTTPS connection. Windows authentication is used when QPR system is connected to LDAP/AD and Windows user accounts are used to login to QPR. HTTPS connection is in use when QPR Portal url starts with “https”.

2. Open Programs and Features (in Windows Control Panel) and click Turn Windows features on or off. Check that components listed in the following table are installed. The installation procedure depends on Windows version. QPR Reporting Add-on needs .Net Framework 4.5.1 or later version.

windows version	required components
Windows 10 (already includes .NET Framework 4.6)	•All components in Internet Information Services (except FTP Server) •Following Windows features: (see image below) .Net Framework 4.6 Advanced Services > ASP.NET 4.6 .Net Framework 4.5 Advanced Services > WCF Services > HTTP Activation
Windows 8 (already includes .NET Framework4.5.1)	•All components in Internet Information Services (except FTP Server) •Following Windows features: (see image below) .Net Framework 4.5 Advanced Services > ASP.NET 4.5 .Net Framework 4.5 Advanced Services > WCF Services > HTTP Activation
Windows Server 2012 R2 (already includes .NET Framework 4.5.1)	•All components in Internet Information Services (except FTP Server) •Following Windows features: (see image below) .Net Framework 4.5 Features > .Net Framework 4.5 .Net Framework 4.5 Features > ASP.NET 4.5 .Net Framework 4.5 Features > WCF Services > HTTP Activation
Windows Server 2012 (needed .Net Framework is not installed by default)	•All components in Internet Information Services (except FTP Server) •Following Windows features: .Net Framework 4.5 Advanced Services > .Net Framework 4.5 .Net Framework 4.5 Advanced Services > ASP.NET 4.5 .Net Framework 4.5 Advanced Services> WCF Services > HTTP Activation •Install .Net Framework 4.5.2: Online installer: http://www.microsoft.com/en-us/download/details.aspx?id=42643 Offline installer: http://www.microsoft.com/en-us/download/details.aspx?id=42642
Windows Server 2008 R2 (needed .Net Framework is not installed by default)	•All components in Internet Information Services (except FTP Server) •All components in .Net Framework 3.5.1 (see image below) •Install .Net Framework 4.5.2: Online installer: http://www.microsoft.com/en-us/download/details.aspx?id=42643 Offline installer: http://www.microsoft.com/en-us/download/details.aspx?id=42642 600px

3 Check that QPR Web Services web.config file is a proper one (located in C:\Program Files\QPR Software Plc\QPR 201X.1 Servers\WebServices). In the default QPR installation there are files web.config and web.config.IWA. If QPR environment uses Windows authentication (refer to step 1), the latter file must be taken into use by renaming

a. web.config to web.config.noIWA, and

b. web.config.IWA to web.config.

4. If using Windows authentication (refer to step 1), make sure C:\ProgramData\QPR Software \QPR 201X\201X.1\Servers\Settings\QPR_Servers.ini has setting IWACGIBinaryHost=127.0.0.1 and CGIBinaryHost=127.0.0.1. The file already contains these setting, but they may be empty. QPR service restart is needed if you need to change this setting.

5. Copy QPRWebServicesExtensions folder to IIS published files in C:\inetpub\wwwroot\ (QPR Reporting Add-on can be deployed in any location in IIS, though).

6. There are following preconfigured files available to be used QPR Reporting Add-on web.config file:

a) web.config: for HTTP connection and Anonymous authentication

b) IWA.web.config: for HTTP connection and Windows authentication

c) HTTPS.web.config: for HTTPS connection and Anonymous authentication

d) HTTPS+IWA.web.config: for HTTPS connection and Windows authentication

Copy a suitable config file to QPRWebServicesExtensions folder and rename as web.config (C:\inetpub\wwwroot\QPRWebServicesExtensions\web.config). Please do not mix up QPR Reporting Add-on web.config file (in C:\inetpub\wwwroot\QPRWebServicesExtensions \web.config) with QPR Web Services web.config file (in C:\Program Files\QPR Software Plc \QPR 201X.1 Servers\WebServices\web.config).

7. Make sure QPR Web Services Server is running: See in the Windows Task Manager (in Details tab) that there is a process Qpr.WebServices.Server.exe. The installation cannot be continued until QPR Web Services Server is running properly.

8. Set the parameters in the QPRWebServicesExtensions web.config’s appSettings section. Parameters are listed in Settings.

9. In IIS Management Console, go to Application Pools (in left side hierarchy). Create a new application pool by clicking Add Application Pool…. Use the settings in the image below (settings v.4.0.x and Integrated). Please do not change settings for existing application pools, if they are used by other web applications because then the other applications may stop working. Especially QPR Suite has an application pool that is v.2.0.x and Integrated.

10. Click the previously created application pool, click Advanced settings… and select Identity setting. In the opening Application Pool Identity window, click Built-in account and select LocalSystem (see the image below). Click OK for the both open windows.

11. Find the QPRWebServicesExtensions folder in IIS Management Console and click Convert to Application (secondary mouse button). Select the previously created application pool QPR Reporting Add-on.

12. Check the IIS authentication settings by clicking QPRWebServicesExtensions web application is IIS Management Console (on the left side hierarchy). Check that Features View is opened (in bottom), and doubleclick Authentication. The authentication settings must match with the web.config file, which was set in step 3:

a. For Windows authentication: Anonymous Authentication must be Disabled and Windows Authentication must be Enabled. (see the image below)

b. For Anonymous authentication: Anonymous Authentication must be Enabled and Windows Authentication must be Disabled.

13. Replace the file C:\Program Files\QPR Software Plc\QPR 201X.1 Servers\WebServices \servicetester.aspx with the new servicetester.aspx. Make a backup copy of the original file with name servicetester.aspx.original. (Alternatively, use the servicetester.patch file that described the changes to the servicetester.aspx file.)

14. Configure QPR Reporting Add-on settings listed in Settings. Especially check the qprwebserviceaddress carefully. Quick guide for usual configurations:

c. When Windows authentication is not in use: wcfsecuritymode=none and qprauthenticationmode=passedsession

d. When Windows authentication is in use: wcfsecuritymode=message and qprauthenticationmode=windows

15. Configure individual report part’s settings, which are mentioned in the documentation of the report part. It’s sufficient to do this only for those parts that need to be set operational.

16. Create folder C:\temp. It is possible to use other folder but its location must be changed to web.config temppath setting.

17. Check that QPR Reporting Add-on is working by making the tests listed in chapter Installation tests. If you encounter any issues, check if any of the error situations described in Troubleshooting were encountered.

18. Copy DWV templates folder as a DWV templates root folder (setting dwvtemplatesphysicalpath in QPR Reporting Add-on’ web.config file). Also copy DWR templates folder as a DWR templates root folder (setting dwrtemplatesphysicalpath in QPR Reporting Add-on’ web.config file) and trend_down.png and trend_up.png files from DWV templates\Images folder to C:\inetpub \wwwroot\qpr201X-1\qprsoftware\portal\images.

19. Deploy Reports Menu addon by replacing mainview.tpl and headerview.tpl in C:\ProgramData \QPR Software\QPR 201X\201X.1\Servers\Templates\WAS\Portal with the files from the Reports Menu folder. (Alternatively, use the externalreportsmenu.patch file.)

20. Copy icon_reports.png from Reports Menu folder to C:\inetpub\wwwroot\qpr201X-1 \qprsoftware\portal\images.

21. Copy jquery.filedownload.js from Reports Menu folder to C:\inetpub\wwwroot\qpr201X1\qprsoftware\Common\scripts.

22. Add the following CSS to C:\inetpub\wwwroot\qpr201X-1\qprsoftware\stylesheets \custom.css:

#ReportsToolbarMenu {   cursor: pointer; }
#ReportsToolbarMenu .activetarget {   background-color: inherit; }
.visiblereportmenulink, .reportmenumain > a {   background: url(../portal/images/icon_reports.png) no-repeat left -1px; }
.disabledreportmenulink {   background: url(../portal/images/icon_reports.png) no-repeat left -1px;   color: #BBBBBB !important;   cursor: default; }
#InformationViewFrame {   background-color: white;
}

10. Restart Windows service for QPR Suite, or clear QPR Portal templates cache. In addition, clear web browser’s cache.

settings

QPR Reporting Add-on is configured using the file C:\inetpub\wwwroot\QPRWebServicesExtensions \web.config. The file has following settings in the configuration > appSettings section. The greyed settings are unusual, so for most installations they can be ignored.

attribute	description
qprwebserviceaddress	QPR Web Services’ url address. This should point directly to QPR Web Services server’s port. The default port is 9002, but the actual port in use can be seen in QPR Configuration Manager (Common > Server locations > Web services server). Example: http://localhost:9002/QPR201X- 1/Portal/QPR.Isapi.dll/ wsforward/mainservice.svc/wshttp Notes: • It’s recommended to use localhost as a hostname if the QPR Web Services Server is in the same computer. • The address starts with http even if QPR environment uses https. • Check the proper url path from QPR Portal address (QPR201X-1 in the example). The path is QPR version specific by default. • Validity of the address can be checked by opening the address in the server computer using browser without the ending /wshttp, e.g. http://localhost:9002/QPR201X-1/Portal/QPR.Isapi.dll/wsforward/ mainservice.svc. A page displaying You have created a service should open. Note that this address doesn’t work in client computers (this is because “localhost” always references to that computer where the browser is running).
wcfsecuritymode	QPR Web Services security settings. Must correspond to QPR Web Services settings (in C:\Program Files\QPR Software Plc\QPR 201X.1 Servers\WebServices\web.config). (Refer to step 3 in the installation instructions.) Options: • none: Use this when Windows authentication is not in use. • message: Use this when Windows authentication is in use • transport: Usually not used. • transportwithmessagecredential: Usually not used.
qprauthenticationmode	• passedsession: QPR Web Services’ session id must be passed as a parameter. The parameter is passed differently in different accelerators. This options is usually used when wcfsecuritymode is none, but also message is possible. • windows: Windows user making the request is used to authenticate to QPR Web Services. When this option is used, wcfsecuritymode must be message (none is not possible). • commonqprauthentication: Common QPR authentication is a mechanism where QPR Suite products have been configured to trust each other in a way that when a user is authenticated to one of the products, the user is also authenticated to other QPR suite products as well. More information: https://devnet.onqpr.com/pawiki/index.php/Common_QPR_Authentication#Linking_between_QPR_Products. When common QPR authentication is in use, session id of the source QPR Suite system is passed as a parameter to QPR Web Services Extensions. • fixedcredentials: A single user account is used for all requests. The account’s username and password are defined in the configuration (see settings username and password). This options is not usually used. For more information, see Authentication and Data Security
dwrtemplatesphysicalpath	Folder in the file system where QPR Word Reports template files are located.
dwvtemplatesphysicalpath	Folder in the file system where QPR Web Views template files are located.
installpath	Path for QPR Web Services Extensions binaries installation folder, which is by default C:\inetpub\wwwroot\QPRWebServicesExtensions. This information is needed by Expression language WebpageAsImage function.
temppath	Path to a file where Reporting Add-on may write temporary files.
templatecaching	Determines whether template files caching is enabled (true) or disabled (false). Template caching means that templates are read from file system to server memory when the IIS web application starts. When template caching is enabled, pages are processed faster and disk load as reduces. Template caching should be enabled for production environments. Template caching is usually be disabled for development work, so that changes in templates can be seen immediately in result pages. When template caching is disabled, all templates are read into memory every time, when a page is requested.
disallowedfunctions	Comma separated list of functions that are not allowed to be executed by the Reporting Add-On. There are some functions which are able to manipulate files in the server computer, and enabling those files may cause security issues. Function names must be written in lowercase.
loglevel	Possible values: None, Error, Information, Verbose.
qprwebapplicationname	Setting for Dynamic Web Views: Name of the QPR web application in IIS. This parameter is not mandatory, but it should be defined, as it can be used by html content to reference QPR resources published in IIS (such as images and css files).
reporttemplateparameter	Setting for Word reports: Defines the name of the parameter which passes the report template path. See chapter Working with Report Templates
qprtemplateidparameter	Setting for Word reports: Parameter name which passes QPR’s Word report template object id. This can be used when the report templates are stored in QPR Portal (i.e. QPR system objects) (see chapter Working with Report Templates)
defaultimageformat	Setting for Word reports: Default image format for QPR Web Service’s GetGraph operation. This setting is used if image format is not explicitly defined
username	Password for QPR Suite when authenticationmode is fixedcredentials.
password	Password for QPR Suite when authenticationmode is fixedcredentials.
executionTimeout (in the httpRuntime tag)	Timeout for request processing in seconds. Usually there is no need to change this setting. The value should be increased if there are heavy requests which take time to run. Note that the timeout limit works as a protection when the processing never ends as a results of an error (this may be possible in e.g. recursive reports).

installation test

Do the following tests to confirm that QPR Reporting Add-on is working:

1. 1. Open QPR Web Services Tester, which is usually in http://SERVERNAME/QPR201X-1/ Portal/QPR.Isapi.dll/wsforward/servicetester.aspx. The SERVERNAME can be found in QPR Portal url address. The address starts with https instead of http, when also QPR Portal address starts with https.

2. Check that the page contains RunExpression tab.

3. Set valid credentials in the Authentication tab.

4. Go to RunExpression tab click Run using the expression it contains by default. It should return Ok (below the Run button). This confirms that the .Net 4.5 application is running in IIS and the QPR Web Services connection works.

a. If this works, you may stop testing here.

b. If this doesn’t work, there is a problem with IIS settings or .Net 4.5 installation.

5. Open http://SERVERNAME/QPRWebServicesExtensions/ExpressionEngine.svc. The address starts with https instead of http, when also QPR Portal address starts with https. There should open a page stating You have created a service. If an internal server error (error code 500) with no error details is returned, test the url in the server, because in the server the error message has more details.

a. If this works, the .Net 4.5 application is running properly in IIS. Go to step 6.

b. If this doesn’t work, there is a problem with IIS settings or .Net 4.5 installation.

6. Confirm that QPR Web Services is working by making a query using QPR Web Services Tester in the QueryObjects tab. You can query for example [UM].users like in the image below. When clicking QueryObjectsAsXml, the test is successful, if a text starting with

<ResultsetHierarchy … appears. Note that your query results may be different than the results in the image. If this test doesn’t work, there is a problem with QPR Web Services.

Authentication and Data Security

This chapter contains information about authentication and data security of the add-on and QPR Suite to make the installation successful also from security point of view. The add-on needs to authenticate to QPR Web Services to get needed data. There are three methods to authenticate:

• Use Windows authentication. Windows user authenticates to the add-on (provided by IIS), and same user is used to authenticate to QPR Web Service (this is called impersonation). It’s advisable to use this authentication method if available.

• Pass QPR Web Service’s session id as a url parameter to the template. The accelerator uses the session id directly when accessing to QPR Web Services. This approach requires a functionality in QPR Portal to first authenticate to QPR Web Service and then pass the session id to the template. Use this authentication method, if Windows authentication is not possible.

• Preset username and password (either QPR or Windows user) in QPR Reporting Add-on configuration. These credentials are used by the add-on when logging in to QPR Web Services. This authentication method is only used for special purposes.

Preset username and password (either QPR or Windows user) in QPR Reporting Add-on configuration. These credentials are used by the add-on when logging in to QPR Web Services. This authentication method is only used for special purposes.

Running Multiple QPR Reporting Add-on Instances Simultaneously

It may be required to run multiple QPR Reporting Add-on instances simultaneously, e.g. when different versions or different QPR Reporting Add-on settings are needed. Running multiple QPR Reporting Add-on instances simultaneously is possible: Copy the QPRWebServicesExtensions folder with a different name to IIS root folder, and make all the settings made to the default folder to that folder. The other instance is referenced using the other folder name in URLs.

Uninstallation

Follow these steps to uninstall QPR Reporting Add-on:

1. In IIS Management Console click Remove for the QPRWebServicesExtensions web application (mouse secondary button).

2. Delete the web application’s folder C:\inetpub\wwwroot\QPRWebServicesExtensions in the disk.

3. Revert the original C:\Program Files\QPR Software Plc\QPR 201X.1 Servers\WebServices \servicetester.aspx from release package.

Troubleshooting

issue	resolution
Web browser returns: Could not load type 'System.ServiceModel.Activation.HttpModule' from assembly 'System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089'.	See the resolution here: https://support.microsoft.com/en-us/kb/2015129
Web browser returns: Memory gates checking failed because the free memory (nnn bytes) is less than x% of total memory. As a result, the service will not be available for incoming requests. To resolve this, either reduce the load on the machine or adjust the value of minFreeMemoryPercentageToActivateService on the serviceHostingEnvironment config element.	The reason for this error is that there is little free memory in the system, and thus the primary solution is to get more free memory in the system. It’s still possible to set the free memory limit to a lower level, but this may cause instability. To do that, find the setting minFreeMemoryPercentageToActivateService from the QPR Web Services Extensions’ web.config and set the limit lower (e.g. to 2). More information: https://msdn.microsoft.com/en-us/library/dn458357(v=vs.110).aspx
Following errors are returned by Expression Engine tester: The message with Action 'http:// schemas.xmlsoap.org/ws/2005/02/trust/RST/ Issue' cannot be processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a contract mismatch (mismatched Actions between sender and receiver) or a binding\security mismatch between the sender and the receiver. Check that sender and receiver have the same contract and the same binding (including security requirements, e.g. Message, Transport, None).Secure channel cannot be opened because security negotiation with the remote endpoint has failed. This may be due to absent or incorrectly specified EndpointIdentity in the EndpointAddress used to create the channel. Please verify the EndpointIdentity specified or implied by the EndpointAddress correctly identifies the remote endpoint.	The reason is the QPR Web Services and QPR Web Services Extensions WCF settings don’t match. Please check installation steps 3, 4 and 6.
When opening QPR Web Services Tester, the following message appears … Redirecting to mainservice page ….	There may be a problem with IIS handler mappings. Tests with following settings: Remove C:\inetpub\wwwroot\web.config if it exists. Make a backup before deleting. Contents of C:\inetpub\wwwroot\qpr201X-1\web.config should be

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <directoryBrowse enabled="false" />
        <httpErrors>
            <clear />
        </httpErrors>
        <handlers accessPolicy="Read, Execute, Script">
            <remove name="AssemblyResourceLoader-Integrated-4.0" />
            <remove name="AssemblyResourceLoader-Integrated" />
            <remove name="AXD-ISAPI-4.0_64bit" />
            <remove name="AXD-ISAPI-4.0_32bit" />
            <remove name="AXD-ISAPI-2.0" />
            <remove name="AXD-ISAPI-2.0-64" />
            <remove name="PageHandlerFactory-ISAPI-4.0_64bit" />             
       <remove name="PageHandlerFactory-Integrated-4.0" />
            <remove name="PageHandlerFactory-ISAPI-4.0_32bit" />
            <remove name="PageHandlerFactory-Integrated" />
            <remove name="PageHandlerFactory-ISAPI-2.0" />
            <remove name="PageHandlerFactory-ISAPI-2.0-64" />
            <remove name="svc-ISAPI-4.0_64bit" />
            <remove name="svc-ISAPI-4.0_32bit" />
            <remove name="svc-Integrated-4.0" />
            <remove name="svc-ISAPI-2.0-64" />
            <remove name="svc-ISAPI-2.0" />
            <remove name="svc-Integrated" />
        </handlers>
    </system.webServer>
</configuration>

•Contents of C:\inetpub\wwwroot\qpr201X-1
\Portal\web.config should be

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers accessPolicy="Read, Execute, Script" />
        <directoryBrowse enabled="false" />
        <defaultDocument>
            <files>
                <clear />
                <add value="Default.htm" />
                <add value="Default.asp" />
                <add value="index.htm" />
                <add value="index.html" />
                <add value="iisstart.htm" />
                <add value="default.aspx" />
                <add value="QPR.Isapi.Dll" />
            </files>
        </defaultDocument>
    </system.webServer>
</configuration>

QPR Expression Engine

Expression Engine for QPR Suite contains the following components:

- Expression Engine Web Service

- Expression Engine Service Tester

Expression Engine Web Service is a web service used to run expressions. This expression engine is embedded into many other accelerators, such as DWR and DWV.

Expression Engine Service Tester is an extension to QPR Web Service Tester, and it can be used to test expressions when e.g. developing report templates or configuration files for other accelerators. It’s possible to define multiple expression which are calculated consecutively in a single web service operation. In that case expression results are stored in variables, and variables can be used in subsequent expression. Example:

var1=3 + 9 / 3

var2=2*[var1]

var3='Value is ' + [var2]

Expression Engine Web Services is a IIS hosted web application, and Expression Engine Service Tester is implemented with changes to QPR Web Service Tester web page html template.

Expression Engine Input Parameters

type:rootobject
attribute	type	description
webServiceSessionId	string	QPR Web Service’s session id. Used only if authenticationmode=passedsession.
expressionSet	string[]	List of expressions
variableNameSet	string[]	List of variable names. The variables get the calculated expression values, and the variables are available as arguments for the next expressions. The value of the last expression is returned by the operation.

Following output data format is used by both services.

Output Data Format

type: ResultDataTable
Attribute	Type	Description
headers	header[]	Array of header rows. There can be one or two headers.
rows	ResultDataTabl eRow[]	Array of data rows
type: ResultDataTableRow
Attribute	Type	Description
cells	ResultDataTableCell[]	Array of data cells
leftIdentifier	string
rightIdentifier	string
type: ResultDataTablecell
Attribute	Type	Description
rawValue	string	Unformatted raw value
formattedValue	string	Value that is displayed to users
sortValue	string	Value that can be used to sort the values
datatype	string	Datatype of the value: string, numeric, int
type: ResultDataTableHeader
Attribute	Type	Description
cells	ResultDataTableHeaderCell[]
type: ResultDataTableHeaderCell
Attribute	Type	Description
label	string
columnspan	int	Number of columns the header extends

Example

Following image shows QPR Web Service tester where Expression Engine Service Tester is installed.

QPR Word Reports

QPR Word Reports is a technology for QPR Suite to generate customized Word reports displaying content from the QPR system. QPR Word Reports works in IIS as a web application, and reports are accesses by a url address (using an http GET request). Data for reports is fetched from QPR system using QPR Web Service interface.

Microsoft Word is not needed on the server side, as Word file generation is implemented using Open XML SDK. Actually Word is not required in the client side either, because Word documents can be opened using OpenOffice (file format is Office Open XML).

Main features

QPR Word Reports contains the following main features:

• The reports are run as they are requested, so the reports always contain the latest data.

• Reports can have parameters affecting report contents.

• QPR Word Reports contains an embedded formula calculation engine. All the tags may be defined using expressions which values are calculated as the report is run.

• The 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 report “parts”.

• Adding Word hyperlinks is possible

Concepts

QPR Word Reports is based on the following concepts:

•Report templates are normal Word files which may have any contents. Reports are based on these template files. 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.

An example url: http(s)://SERVERNAME/QPRWebServicesExtensions/DynamicWordReports.ashx? report=reportname&parameter1=param1value&parameter2=param2value

Configuration

Following table contains QPR Word Reports’s parameters, which are configured in the web.config file of QPR Web Services Extensions.

Parameter name	Description
reporttemplateparameter (optional)	Defines the name of the parameter which passes the report template path. See chapter Working with Report Templates for configuring the report template path.
qprtemplateidparameter (optional)	Parameter name which passes QPR’s Word report template object id. This can be 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.

Note that QPR Word Reports templates are entirely incompatible with QPR - Add-in for Microsoft Office report templates, so running them as QPR - Add-in for Microsoft Office reports is likely to cause an error.

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. Also stack trace is shown, but that is helpful information only for developers.

Template Tags

Tags are used to add 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 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 sub 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 (thus 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 kind of an input 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 visibility tag is processed and its value is false, the tag processing stops at that point. This has an effect on report run performance. In addition, possible later expression errors don’t emerge in that case.

Word has a tendency to use characters “ and ” instead of character " as quotation marks. Characters “ and ” are not suitable quotation marks for QPR Web Service, so QPR Word Reports replaces these characters with " character for strings inputted to QPR Web Service. Also characters ‘ and ’ are replaced by '. Note that all of these quotation marks should be escaped, when there is escaping needed (more about escaping in Expression Language).

All existing tags can be used in following document parts: main document, header, footer, footnotes and endnotes. Only Attribute and Expression tags can be used in comments.

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 operation (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 operation. 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 operation.
options (string)	This is passed as parameter options of GetAttributeAsString or QueryObjects operation. (optional)
expression (exp. 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">

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.
headertemplat e (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)
headertemplat edata (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 - parameters which names are same as column names, containing dataset cell data - same parameters that are passed to the header subreport, i.e. columnheader_1, columnheader_2, … columheader_n (optional)
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)

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 "5 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=="[variable1]">
<#expression value1=="5" formula=="2 * [value1] + 3"> (result is 13).

Image Tag

This tag is used to show an image in the report. Images can be got using QPR Web Service’s GetGraph operation, 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 operation. (optional)
options (string)	This is passed as a parameter options of GetGraph operation. (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)
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 source="embedded" object=="[attachmentId]" options="embeddeddata" maxwidth="17.5" dpi="1.5*[horizontaldpi]">
<#image imagedata=="httpFileData('http://someurl…')">

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, or 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.

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)
portaltemplate (string)	Template name for the looped content for templates stored in QPR Portal in Reports tab. Templates are referenced using syntax "category/header", where category is the name of the category and header the name of the header in the report template.
query (string)	This is passed as a parameter query of QueryObjects operation. "List" attribute is alternative. (optional)
criteria (string)	This is passed as a parameter criteria of QueryObjects operation. This filters the output set of objects. (optional)
sortby (string)	This is passed as a parameter sortby of QueryObjects operation. 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 operation. All the queried attribute values are added as parameters to the subreport. (optional)
options (string)	This is passed as a parameter options of QueryObjects operation. (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 (exp.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 (exp.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)
style (string)	Determines text style. See Defining Styles. (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). Any tag attribute names mentioned in this documentation cannot be used as parameter or variable names (reserved names).
outputname (string)	Parameter name used in the report. If output value is not defined, output value is same as input value. Any tag attribute names mentioned in this documentation cannot be used as parameter or variable names (reserved names). (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 (exp. 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.

Attributes validate and contentdispositiontype are for advanced purposes, so usually they can be ignored.

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 dd-MM-yyyy. (optional)
validate (boolean)	Defines whether a Word document validation is performed. Validation reveals if a Word document contains structural errors (the xml document is inconsistent with the schema). It seems that Word sometimes produces files that are not valid (!). If that kind of file is used as a template, it is probable that the output file produced by QPR Word Reports is not valid either and the validation fails. If the validation fails, an error message is shown and the report cannot be downloaded. By default validation is not performed. Validation is useful, if QPR Word Reports produces a file that Word is not able to open. The validation error message may provide further information of the problem. (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" validate="true">

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)
style (string)	Determines text style. See Defining Styles. (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 (boolean)	Variable name. Any tag attribute names mentioned in this documentation cannot be used as parameter or variable names (reserved names).
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.