Difference between revisions of "QPR PowerPoint Reports"

From Mea Wiki
Jump to navigation Jump to search
Line 196: Line 196:
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
 
| dataset (dataset)
 
| dataset (dataset)
||Dataset shown by the tag.
+
||Dataset looped by the tag. There will be as many slides as there are rows in the dataset (if only one slide is looped). All columns data is available as parameters in the tag. The parameters need to be defined in the slide content.
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
 
|slidecount (integer)
 
|slidecount (integer)

Revision as of 16:06, 23 March 2018

Note: This page contains documentation of functionality that hasn't been released yet.

Introduction to QPR PowerPoint Reports

Concepts related to QPR Word Reports also apply to QPR PowerPoint Reports.

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). Report templates can be either pptx or pptm files. Mediatype for the downloaded file is application/vnd.openxmlformats-officedocument.presentationml.presentation.

QPR PowerPoint Reports can be accessed using the following url:

http(s)://SERVERNAME/QPRWebServicesExtensions/DynamicPowerPointReports.ashx?report=reportname&parameter1=param1value&parameter2=param2value

The report template is processed into the final report as follows. Slides are processed one by one starting from the first slide. When a slide is processed, the slide notes are processed first, and following tags are searched in the notes: parameter, variable, reportsettings and loop. The scope for the defined parameters and variables is the notes part only. If loop tag is defined, new slides are created based on how many times the slide is looped (it's also possible to loop multiple slides). When the loop tag is processed, the slide processing is stopped, and the processing starts again from the first looped slide. Now slide content and comments are processed, and following tags are searched: parameter, variable, reportsettings, attribute, expression and link (note that loop tags cannot be used here). Parameters and variables need to be defined for each slide separately.

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.

Tags

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 restricted. In case an image cannot be fetched, 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.

Image size in the report 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 for that (expanding or shrinking the image)
  • maxwidth and maxheight restrictions are applied last maintaining the aspect ratio (always shrinking)

In the expressions of the dpi, scaling, maxwidth and maxheight parameters, 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)

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 e.g. png, jpg or gif. (optional)
dpi (decimal) Determines the image size as dots per inches. If not defined, dpi information in the image data is used. (optional)
scaling (decimal) Image scaling as percentage value ("100" means no change in size). 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)
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)
centerhorizontally (boolean) When replacing the placeholder image with the real one, this setting determines whether to keep the center spot of the image in the same place. When false, the left border of the image is stays in the same place. (optional)
centervertically (boolean) When replacing the placeholder image with the real one, this setting determines whether to keep the center spot of the image in the same place. When false, the top border of the image is stays in the same place. (optional)
visible (boolean) Determines content visibility shown by the tag. See Setting Content Visibility. (optional)

Examples

<#image object=="QprGraphData([diagramid], 'graphtype=processlevel,witdh=1500')" maxwidth="17.5" dpi="1.5*[horizontaldpi]">
<#image imagedata=="httpFileData('https://www.qpr.com/')">

Link Tag

Link tag is used to add a clickable hyperlink to a slide. If the link address is empty or other ways invalid, no link is displayed in the report. Note that the tag generates the hyperlink, so the report template should not already contain a hyperlink, but only the tag as text.

Parameter Description
address (string) Url address (location) which the hyperlink is 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 the first looped slide.

Attribute Description
dataset (dataset) Dataset looped by the tag. There will be as many slides as there are rows in the dataset (if only one slide is looped). All columns data is available as parameters in the tag. The parameters need to be defined in the slide content.
slidecount (integer) 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 slides as parameters. Note that the above mentioned attributes are not passed as parameters, as they have a special purpose in the 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)
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.