Parameters have been introduced in Perfion to allow for end user customization of reports and other outputs from Perfion. Parameter values can be set by the end user via the Report Dialog when running the report/generating the output.

Parameter Definition

• Parameters are configured in the SuperQuery,

• Parameters can also be supplied as Publication Settings

• Parameters are available in both the report- and table-designer making it possible to customize both.

This page will walk through how incorporate parameters into your reports.

General syntax

Parameters are defined in a SuperQuery and affect the queries performed here (i.e. limit the number of rows etc.). The SuperQuery is defined in the Tools > Reports menu.

Parameters are added to the SuperQuery by making a child-element to the SuperQuery element named OutputParameters. This is done in the example below, note the standard report queries have been removed for brevity:

The above SuperQuery will give an Output dialog as shown in the screenshot below.

Open

A parameter element supports 5 attributes: id, input, value, hide and multi.

1. The id attribute specifies the ID (which is also considered the name) of the parameter. The name may only contain English characters and digits, and may not begin with a digit. It is the same naming scheme that Perfion uses for features.

2. The input attribute specifies what kind of GUI-control is used to show and edit the parameter. The value-attribute tell Perfion what the initial value of the parameter is. This value is reflected in the GUI control associated with each parameter, as can be seen when comparing the SuperQuery and the dialog above.
   Possible values for the input attribute on the parameter-element are:

   • Date: Will show a date picker allowing only input of valid dates (and blank). Date must either be a string formatted using YYYY-MM-DD or, from version 5.1, reference a system date variable like @@UTCNOW. Note that date parameters referencing system date variables supports simple calculations. See the Perfion API Query Reference Guide for further details on supported variables and calculations.

   • Number: Will show an edit box only allowing a number input (and blank).

   • String: Will show an edit box allowing any input.

   • Text: Will show a large edit box allowing any input.

   • <FeatureName>.String: Will show a selector, allowing the user to input any valid value for the feature named FeatureName assuming FeatureName is a String. This works only for selectable features.

   • <FeatureName>.Date: Same as for <FeatureName>.String except that it works for Date-features.

   • <FeatureName>.Number: Same as for <FeatureName>.String except that it works for Number-features.

   • <FeatureName>.Text: Same as for <FeatureName>. Text except that it works for Text-features.

   • <FeatureName>.Id: Same as above, except for that it will return the ID of the picked selectable, not the value it represents.

   • Perfion.LookUp.FilePath: This will allow the user to pick a file and pass the full path to this file into the parameter value as a string.

   • Perfion.LookUp.DirectoryPath: This will allow the user to pick a directory and pass the full path to this directory into the parameter value as a string.

   • Perfion.LookUp.Languages: This will allow the user to pick one or more languages.

   • Perfion.LookUp.Bool: This will show the user a checkbox allowing for quickly selecting between the values “true” and “false”.

   • Perfion.Lookup.ImageResolution: This will show a control allowing the user to pick between Original, Low, Medium, High or Custom resolution. It will return “Original”, “Low”, “Medium”, “High” and for “Custom” the associated DPI-value writable on the control.

   • Perfion.LookUp.OutputNaming: Will allow the user to select between values “Named” and “Enumerated”. Named means that localizable remotes are exported postfixed with the variant name. This is described in the appendix in the end of this document.

   • Perfion.LookUp.FromParameter(@<ParameterName>): This expression was introduced in Perfion 4.5.7. This makes it possible to create a parameter whose possible values can be supplied in another parameter. Looking at the example MyValue is such a parameter taking its value from the parameter named AllMyValues containing 3 values. Notice that AllMyValues cannot be seen in the above dialog. This is because it has the hide-attribute set to true as described below. When using this construct make sure the referred parameter exists, otherwise the control shows up empty.

3. multi allows for entering multiple values for that parameter, as seen on the parameter MyMultiNumberParameter in the above example. The multi-attribute can only be used when input is either Date, Number, String, Text, Perfion.LookUp.Languages or Perfion.LookUp.FromParameter. If multi is not specified it is default set to false with the exception of Languages (which is a System Defined Parameter described later). In case Languages has two or more values (that is languages) assigned to it, multi will default be set to true otherwise it will be false.

4. The attribute hide allows you to hide the parameter with its associated default value for the end user. In order to do that simply set hide to true on the Parameter-element as shown below. A parameter is shown by default except for the System Defined Parameters BinariesOnDemand and OutputBinaries.

Globally Defined Parameters

Perfion has two sets of globally defined parameters, which are used to control different aspects of the generation of the output. The System defined Parameters controls aspects that affect all outputs (Reports, Excel-output, XML-output etc.) while the Output Specific Parameters control aspects that only affects a certain type of Output.

System Defined Parameters

The current set of System Defined Parameters are listed here:

• ImageResolution

• Languages

• VariantNaming

• BinariesOnDemand

Please see the SuperQuery Factsheet for a description of what each of these parameters mean. When showing the Output-dialog the System Defined Parameters will be shown on the Options-tab.

When clicking View or Design you will get a report, and as mentioned only the above System Defined Parameters affect the generation of that report.

Notice that in the example, we have already been using three of these System Defined Parameters, namely Languages, VariantNaming and ImageResolution.

Output Specific Parameters

When not doing a report, but instead making an export, the following Output Specific Parameters control different aspects of each of these different outputs:

XML-export

• CompactFeatureMetaData

• OutputXmlSchema

• OutputBinaries

• SuppressUI

• OutputFilePath

Excel-export

• ForReImport

• OutputBinaries

• SuppressUI

• OutputFilePath

EPI-Server Export

• Address

• ImportAssets

• CommerceVersion

• CatalogName

• CatalogDefaultWeight

• CatalogDefaultCurrency

• CatalogDefaultLanguage

• ImportAssets

• Sites

InBetween Export

• OutputBinaries

• SuppressUI

• OutputFilePath

Notice that some parameters are being used by multiple outputs, as for example OutputFilePath and OutputBinaries.

When using any of these parameters, it will have an impact on the output as defined by the Perfion application. Please see the SuperQuery Factsheet for a description of what each of these parameters does.

All Output Specific Parameters will have a corresponding control shown on the Export-tab in the Output-dialog.

Using parameters

When a parameter is defined in the SuperQuery, you can make use of it in three different places:

• In the queries, which are part of a SuperQuery, parameters can, for example, be used to filter the right-hand side items based on their values or maybe controlling which features are fetched.

• In the Report designer parameters can be used to affect how the output should look based on the values of one or more parameters. Here it can be anything from writing “Draft” in the top-left corner to controlling the visibility of the different bands in the report.

• In the Table Designer, parameters may also be used to filter items to appear in the table.

In the following three sections examples are provided for each of the above. All examples refer to data being in the Demo-database provided by Perfion.

Using a parameter in a where-clause

The example below uses MyFuelParameter to only retrieve cars which have the Fuel-type defined by it:

The user is allowed in the Options dialog to select which fuel type a car should have for it to be part of the report (or XML-output etc.)

As the above example shows: When a parameter is used in the query, its name must be prefixed by a @ (at)-character. After the name of the parameter an optional default value can be specified that is used if the user supplies a blank. In the above example the default-value is specified as “Petrol”, so in case the user does not write or pick a value for MyFuelParameter in the Output-dialog, the default-value “Petrol” would be used. Same thing would happen in the odd case where the parameter is defined with no value and is hidden, not giving the user any chance to specify it. For date values, the default value may use system date calculations as described in the Perfion API Query Reference Guide. As an example, writing @MyDateVariableParameter:@@DATE-7d, means that if the user does not supply a value for the date parameter, the system will default the value to today minus 7 days.

Parameters can also be used in the Select-, Having- and OrderBy-Clauses of a query, in addition to the Where clause seen up till now.

Using a parameter to determine feature to include

You can also use a parameter to determine whether some feature is included in a report. Consider the following Super-query

Notice how the 3^rd feature in the right-hand side query is written:

<Feature id='@MyFeature:Fuel' />

This simply means “include the feature in parameter MyFeature”. If it is empty or not defined, fetch the Fuel-feature.

Defining MyFeature using the Perfion.LookUp.FromParameter makes it possible to create a whitelist of the features that should be available. In the example, the feature named “<None>” is simply the choice of having no feature pulled in using this construct. This works since no feature is named that (it is an illegal feature name) and unknown features are simply ignored by Perfion when executing the query.

Using a parameter in the Report Designer

All parameters are available in the report designer. Simply go to the “Field List”-tab and you will find a Parameters-node in the tree selector containing all the defined parameters:

Open

Parameters can be used just as you would use fields found in the Items, Catalog and Types.

Using new parameters to take control of a Remote feature with variants

Say you, as in the demo database, have a remote feature with variants. Let us start of by taking a look of how such a feature is defined. The following query is basis for a number of such features in the demo-database:

Such a query need to “from the outside” have supplied what variant(s) to fetch. Otherwise it will always fetch the default variants supplied as part of the query (here DKK-net, DKK-ret, EUR-ret and EUR-net.

NetPrice is indeed such a Remote Feature with variants based on the above query.

You can use parameters to let the user choose between which variants to use in a report. Consider the following SuperQuery:

First notice how the feature NetPrice-feature have its variant supplied by the line:

<Parameter id='Variant' value='@NetPriceVariants:DKK-ret' />

Basically this is saying: Fetch the variants you find in the parameter named NetPriceVariants. If that not is defined, fetch DKK-ret.

If you run a report based on the above SuperQuery you will simply fetch only DKK-ret-variants. Now in order to have the user to choose among other variants, you simply define an OutputParameter named NetPriceVariants for example like this:

 This will define the parameter and initially give it two values: EUR-net and DKK-net. This is just a “normal” string parameter allowing for multiple values, so as you would expect, it will indeed show up in the Output-dialog allowing the user to change the initial choices:

Same “trick” can be done for the remaining parameters in the definition of the NetPrice-feature in the SuperQuery (in this case just the Column-parameter).

Using a parameter in the Table Designer

Using parameters in the Table-designer is simply about writing the query getting items for the table, so that it utilizes parameters. This can be done by using the syntax described already. This has the obvious usage that you can filter the items shown in the table based on one or more parameters supplied by the user.

When working with the Table-designer, you will have to supply default-values for the parameters, in order to run the query, since a query in the Table-designer will always run using the supplied default values.

Another usage is being able to choose which variant(s) to fetch using a parameter as we just saw in the previous section.

Consider the following query, as it can be written in the Table Designer:

Note that when designing the table, you should use the default value (here set to DKK-net) to control what value you would like to apply during design. There is no other way to supply parameter-values in the Table Designer (i.e. you cannot for example create an OutputParameters-element in the xml or similar construct). This means, that when running the above query in the table designer it will run as if NetPriceVariants was not defined and hereby be using the suppled default value, in this case DKK-net.

On the other hand: When running a report fetching a Table-feature based on the above query, you can write an OutputParameter-element and have the user pick which variant that should be chosen, just as described in the previous section.

Using Parameters from a publication

When doing a Publication parameters can be defined at the Publication level. When this is done, these parameters will propagate down and hereby affect reports being part of the publication.

Consider the example below:

The parameter MyNumberParameter defined here will be shown in the Publication-dialog allowing the user to modify it. In addition, the MyNumberParameter is available in all reports that are printed as part of this Publication.

It is OK also to define parameters in the individual reports. The Output-dialog will, however, not be shown per report so parameters defined in the individual reports, will be using their default values assigned to them in their respective SuperQueries.

In case the SuperQuery, for some report, has a parameter named exactly as another parameter already supplied in by the publication (that is they have the same ID), then the parameter in the Publication will take precedence.

Example: In the above example, the publication defines that the parameter MyNumberParameter should have a value of 42. If some report in that publication has a SuperQuery that defines a parameter with the exact same name giving it a value of, say, 20, then this value (20) will be overwritten when doing a publication and indeed be 42 also for that report. 

When the report is printed “standalone” (i.e. without being part of the above Publication) the situation is different. Here 20 will be used. This will also be the case, if it is printed as part of another publication not specifying that exact parameter.