=parameter(); function

Outline

The =parameter(); Scripting Engine function is a function that takes static or variable input and retrieves a selected parameter value or constructs a total parameter token based on input properties

Aliases

=parameter();
=param();

Properties

The parameter function has complex input:

 

Property Datatype Default value Description
id GUID [REQUIRED] The uniqueidentifier of the parameter.
This is a GUID-datatype reference to the parameter defined in BA DataCentral
alloutput String [ALL] This string controls which string is returned if the all-option is the current selected option
output String val

The type of parameter usage or output format:

val, total, proc, startperiod and endperiod are supported
 
prefix String and

Used with output = total only
and, or, where etc

colref String Column

Used with output = total only
myColumn etc

operator String =

Used with output = total only
=, <, >, <= etc

dateFormat String I
 
Used with periodic parameters only
 
I, U, CUSTOM
 
customDateFormat String ""
 
Used with periodic parameters only
MM, YYYY etc
 
period String Standard
 
Used with periodic parameters only
Standard, Trend
 
compIdx Integer -1
(all)
 
Used with composite key parameters only
-1 = whole node value
0 - n = composite part of node value
 
fallback String [OUTPUTERROR]
 
If any error is occurring during this parameter parsing the error message will be returned when fallback is set to [OUTPUTERROR].
If you want your own custom string or a empty string to be returned if the parameter parsing fails, you can provide this string with this property.
 
quotes String AUTO

New in 4.2.1
Used to force-wrap a type of quotes around the values.

templ String ""

New in 4.2.1
Used with composite key parameters only
Used to supply a template on how the parameter values should be used in the filter statement

Examples

 

Given parameter ID = "233a028b-620a-4927-94f1-2aa7c36d862e" which is a period parameter and the following three expressions:
=param("id":"233a028b-620a-4927-94f1-2aa7c36d862e");
=param("id":"233a028b-620a-4927-94f1-2aa7c36d862e", "output": "total");
=param("id":"233a028b-620a-4927-94f1-2aa7c36d862e", "prefix": "or", "colref":"dateCol", "dateFormat": "I", "output": "total");
 
If selected value is the all-option, the output would be:
[ALL]
[empty-string] (blank)
[empty-string] (blank)
 
If selected value is year (This year), the output would be:
year
and column between ('2011-01-01 00:00:00' and '2011-12-31 23:59:59')
or dateCol between ('2011-01-01 00:00:00' and '2011-12-31 23:59:59')
 
Given parameter ID = "75ed8d1b-00bb-4859-9632-2ce314bee362" which is a ordinary data parameter and the following three expressions
=param("id":"75ed8d1b-00bb-4859-9632-2ce314bee362");
=param("id":"75ed8d1b-00bb-4859-9632-2ce314bee362", "colref":"newColumn", "operator": ">=", "output": "total");
=param("id":"75ed8d1b-00bb-4859-9632-2ce314bee362", "output": "proc");
 
If selected value is the all-option, the output would be:
[ALL]
[empty-string] (blank)
[ALL]
 
If selected value is 12, the output would be:
12
and newColumn >= 12
12
 
If the selected values are 12 and 16, the output would be:
12,16
and newColumn in (12,16)
'12|16'
 

alloutput property

This string controls which string is returned if the all-option is the current selected option.

ATTN:
When working with composite parameters you can define different alloutputs for every composite part of your parameter and an other one for when there is no nodes selected at all.
If you have composite parameter with two composites (eg. usergroup and user) you chan provide the alloutput like this:
"alloutput":"[allOutputStringForCompIdx0]|[allOutputStringForCompIdx1]|[allOutputStringForNoNodesSelectedAtAll]"

ATTN2:
Alloutput does not validate/use the other properties such as prefix, colref etc.
In scenarios where alloutput is evaluated, the string provided as alloutput will be returned as a raw/static string.

Output property

There are currently four different output types available:

val
This type outputs only the selected option value(s).
If the alloption is the selected one "[ALL]" or [alloutput] is returned
 
total
This type outputs a complete parameter implementation to be used in for example a manual query. The different sections of the output is controlled by the according input parameters:
[prefix] [colref] [operator] [selectedOptionValue]
If multiple values are returned, the [operator]-property is ignored and a in-statement is created.
If the alloption is the selected, a empty string or [alloutput] is returned.
 
proc
This type outputs a parameter implementation dedicated to procedure input usage.
[prefix]/[colref]/[operator] is ignored.
If the alloption is the selected one "[ALL]" or [alloutput] is returned
 
startperiod
This type outputs only the startperiod date of a periodic parameter
 
endperiod
This type outputs only the startperiod date of a periodic parameter
"output": "val"
"output": "total"
"output": "proc"
"output": "startperiod"
"output": "endperiod"

 

prefix property

ATTN: This property is used in conjunction with output type set to total only!

The setting is a simple string that will be placed first in the condition line:

and columnA = 5

Default prefix is and, but you can set it to any string that would make your query syntax valid.

Often used prefixes are: or, where (attn: remember that this line is not rendered if all-option is selected!)

"prefix": "or"

colref property

ATTN: This property is used in conjunction with output type set to total only!

The setting controls the name of the column which the parameter should reference

"colref": "columnA"  =>  and columnA = 5

If the parameter is a hierarchyal composite parameter and the composite index is default (-1), this colref property needs to include column references to all refrenced columns (separated by pipe):

"colref": "colA|colB"

operator property

ATTN: This property is used in conjunction with output type set to total only!

This setting controls the operator of the expression.

"operator": "="  =>  and columnA = 5

ATTN: Always use single value operators. The Scripting Engine parser will automatically reformat the expression to multivalue statements when needed:

= [values] becomes in ([values])
!= [values] becomes not in([values])

Use = or != even if you expect multiple values

dateFormat property

If the parameter is a period parameter, this property sets the date format to be returned:
I - ISO Date (YYYY-MM-DD hh:ss:mm)
U - UNIX Date (seconds since 1970-01-01)
CUSTOM - If [customDateFormat] is used this property needs to be set to "CUSTOM"
"dateFormat": "I"
"dateFormat": "U"

customDateFormat property

If the parameter is a period parameter and [dateFormat] is set to CUSTOM, this property lets you set a custom date format to be returned when ISO or UNIX format is not desired.
See .net date formatting for further details.
"dateFormat": "CUSTOM", "customDateFormat": "yyyy"

period property

If the parameter is a period parameter, this property controls if the standard period or the trend period should be returned.
Standard and Trend are valid values.
See timesheet documentation for further details.

"period": "standard"
"period": "trend"

compIdx property

If current parameter has a composite key this property lets you return only the desired index of the key of the selected option.
The selected value is split by the composite key seperator provided in the parameter definition and the zero based index of the resulting array is returned. eg: compIdx 0 is the first option.

New in 4.2.1:
If the parameter has a composite key and the compIdx is not provided or set to -1 all composite dimensions will be parsed in one go using a autogenerated output template.

Given selected value in parameter = 2_5:

"compIdx": 0  =>  2
"compIdx": 1  =>  5

quotes property

New in 4.2.1:
Default this setting is set to AUTO which will wrap value in single quotes if the value is not numeric (text, date etc).
To force single quotes around the values in output=total, set quotes to '
This property can also be set to any string so if you set it to "WrappingText" and your value is 5 the output will be: WrappingText5WrappingText
"quotes": "'"
 

templ property

New in 4.2.1:
This property is used to supply a template on how the parameter values should be used in the filter statement. The property will only be used on composite parameters with output=total and compIdx=-1 (default).

When output=total, compIdx=-1 and this is a composite parameter, the colref property should contain all columns that you need to reference seperated by a pipe (|):

"colref": "col0nm|col1nm"

Given the above colref and there is no template provided through the templ property there will be autocreated a template like this:

({COL0}{COL1:OR:COL0})

Breaking it down:
First the template is wrapped in parantesis since it is a OR-statement inside which forces the expression inside the parantesis to be parsed in whole before evaluating the output with other parameters.

Next there is a {COL0} string which is the placeholder for the first column (with compIdx=0)

Second there is a {COL1:OR:COL0} string which is the placeholder for the second column (with compIdx=1).
This string has also the :OR:COL0 section which means that the column-value section for COL1 should be prefixed with a OR-operator IF COL0 is present (not set to [ALL])

Given the colref-property and autogenerated template above the parsing will be as the following

Composite value 0 Composite value 1 Actual node value SQL Output
5 10 5_10 AND (col0nm = 5 OR col1nm = 10)
[ALL] / not set 10 [ALL]_10 AND (col1nm = 10)
5 [ALL] / not set 5_[ALL] AND (col0nm = 5)
[ALL] / not set [ALL] / not set [ALL]_[ALL] / not set (empty string)
1,2,3,4 5,6,7 1_5,2_6,3_7,4_[ALL] AND (col0nm in (1,2,3,4) OR col1nm in (5,6,7))

:If this auto generated template is not appropriate for your usage, you can provide your own template through this templ property.

An example could be that you need to use AND between the column references:

"templ": "({COL0}{COL1:AND:COL0})"

ATTN: Remember that you can also provide composite alloutputs for all composites and for the total