QPR PowerPoint Reports
Note: This page contains documentation of functionality that hasn't been released yet.
Report processing sequence
Slides are processed one by one starting from the first one. First slide notes are processed. Following tags are searched in the notes part: parameter, par, variable, var, reportsettings, loop. After looping, notes, slides and comments are processed, and following tags are searched: "parameter", "par", "variable", "var", "reportsettings", "attribute", "att", "expression", "exp", "link"
Configuration
Following table contains QPR PowerPoint Reports parameters, which are configured in the QPR Reporting Add-on web.config file (by default in C:\inetpub\wwwroot\QPRWebServicesExtensions\web.config).
| Parameter | Description |
|---|---|
| dprtemplatesphysicalpath | Folder in the file system where QPR PowerPoint Reports template files are located. |
| reporttemplateparameter (optional) | Defines the name of the parameter for the report template path. By default, it is report. See chapter Working with Report Templates for configuring the report template path. |
| defaultimageformat (optional) | Default image format for QPR Web Service’s GetGraph method. This setting is used if image format is not explicitly defined in the GetGraph options. |
QPR PowerPoint Reports supports Open XML files, which can be opened e.g. in Microsoft Office and OpenOffice (more information: https://support.office.com/en-us/article/open-xml-formats-and-file-name-extensions-5200d93c-3449-4380-8e11-31ef14555b18). Mediatype for the downloaded file is application/vnd.openxmlformats-officedocument.presentationml.presentation. Report templates can be either pptx or pptm files.
Attribute Tag (att)
Attribute tag is used to show a property of an object. The attribute value is fetched 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, 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.
| Parameter | Description |
|---|---|
| object (string) | A single object id or a comma separated list of object id's. If there is only one object, it is passed as a parameter objectId of GetAttributeAsString method. If there are no object id's at all, the tag result will be empty. (optional) |
| attribute (string) | Attribute name to be shown. This is passed as a parameter attribute of GetAttributeAsString or QueryObjects method. |
| options (string) | This is passed as a parameter options of GetAttributeAsString or QueryObjects operation. (optional) |
| expression (expression string) | An expression used to modify the returned attribute values, e.g. to make conversions etc. The attribute value is placed as an argument "value" to this expression (see the examples). (optional) |
| followrelations (string) | Name of the relations 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) | If multiple objects are defined, this property defined the character(s) separating the shown attributes of multiple objects. Empty values are not shown (i.e. no empties between separators). Default is a new line character. (optional) |
| sortby (string) | Applied sorting if there are multiple objects returned. Default sorting is by attribute "name". (optional) |
| visible (boolean) | Determines content visibility shown by the tag. (optional) |
Examples
<#attribute object=="[objectId]" attribute="name"> <#attribute object=="[measureId]" attribute="measure.value(series=\"ACT\",period=\"1 / 2018\")" expression="[value] * 2.54"> <#attribute object=="[measureId]" followrelations="childobjects,childobjects"attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" separator=", " sortby="name">
Expression Tag (exp)
Expression tag is for adding a result of an expression (formula) in a slide. The defined expression is evaluated and the result is set in place of this tag. Note that the tag may contain any parameters which are provided as arguments to the expression (see examples).
| Parameter | Description |
|---|---|
| value (object) | Value shown by the tag. Expression behavior is achieved when this parameter is defined as an expression. Note that the values shown in the report are always 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 date type, dateformat defined in the Reportsettings tag is used. |
| visible (boolean) | Determines content visibility shown by the tag. (optional) |
Examples:
<#expression value=="[variable1]"> <#expression value1=="5" formula=="2 * [value1] + 3"> (result is 13).
Image Tag
Image tag is used to show an image in the slide. Images can be fetched from different sources, for example 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, different 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) |
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
Link tag is used to add a hyperlink to a slide. If the link address is empty or someways invalid, no link is displayed. Note that the tag generates the hyperlink, so the report template should not contain a the desired hyperlink (only the tag in a textual form).
| Parameter | Description |
|---|---|
| address (string) | Url address (location) which hyperlink to pointing to. |
| text (string) | Link’s displayed text. |
| screentip (string) | Link’s screen tip. (optional) |
| target (string) | Link’s target. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. (optional) |
Example
<#link address=="getPortalUrl([diagramid], '', '')" text="Link to QPR Portal" target="_BLANK" screentip="Click here is go to QPR Portal">
Loop tag
Loop tag is used to repeat slides. This tag must be defined in the notes section of a slide.
| Attribute | Description |
|---|---|
| data (dataset) | Dataset shown by the tag. |
| slidecount | Number of slides that are repeated. By default only the slide where the Loop tag is defined is repeated. (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) |
Parameter Tag (par)
Parameter tag defines parameters for the slide. Only parameters that are defined using these tags are available in the report. The report request url may contain other parameters which are omitted.
| Parameter | Description |
|---|---|
| inputname (string) | Name of the parameter (url parameter name). |
| 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 validation parameter). |
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) |
| 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">
Variable Tag (var)
This tag is used to define a variable in the slide. Variables can be used in other tags as expression arguments. 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 cannot be a variable having a same name as a parameter in the same report.
| 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 slide 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]">.
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.