Parameterization Engine

Parameterization is the process of building a query, an event filter expression or report's source data expression which will prompt the user for various parameters when it is run. Once you've done this process, you get a simple string -- a piece of text you can use as the text for a query or an event filter expression.

The source data for parameterization engine has XML format. It defines a number of parameters that must be entered during parameterization process. Normal use is like this: administrators create parameterization source data (XML) and put into a parameterized query or event filter. Users then specify parameters on-the-fly, when executing the query or filter.

PARAMETERS_FORMAT is the format of the Data Table that will be created and shown to the user in editable mode so he could change its fields. The values of these fields will be then converted to strings and inserted into EXPRESSION_TO_PARAMETERIZE. The data table constructed from PARAMETERS_FORMAT always contains just a single record. This table allows the user to interactively define parameter values which will then be used within EXPRESSION_TO_PARAMETERIZE.

PARAMETERS_FORMAT is the Table Format encoded to a string using "visible" characters. More information on encoding can be found in the appendix, under Encoding Data Tables. The minimum and maximum number of records specified by the Table Format are ignored, because there's just a single record.

The PARAMETERS_FORMAT string is nested into a CDATA block. CDATA is an element of XML language which allows using normal XML markup characters ("<", ">" etc.) without escaping them. This is needed because the PARAMETERS_FORMAT string employs such characters.

This example defines two fields: A boolean field called "byusername" (with a "user-friendly" description, "Filter by User Name") and a string field called "username" ("User Name"). The first parameter may be used, for example, to enable filtering by a specific user in a query, and the second parameter will be name of user.

The user will then be prompted to enter these parameters (screenshot made in AggreGate Client):

This format defines many fields and some relations between them that are controlled by bindings ("<B=...>"). For example, the binding "username#enabled={byusername}" makes it so that a user can only fill in the "User Name" ("username") parameter if filtering by user names is enabled (i.e, the "byusername" field is set to TRUE). To learn more about what , <D>, <S>, , <D> etc, see Encoding Data Tables.

When running a filter using this format, the user is prompted to enter parameters using the following dialog (screenshot made in AggreGate Client):

EXPRESSION_TO_PARAMETERIZE is just the text used to build a query or an AggreGate Expression used by an event filter or a report. This text may contain two special constructs that depend on the values of parameters specified by fields of PARAMETERS_FORMAT.

As EXPRESSION_TO_PARAMETERIZE contains XML tags (see below) it cannot be written inside the CDATA block like PARAMETERS_FORMAT. Therefore characters used by XML syntax must be escaped. For example, if & character must appear in the resulting expression, it must be written as & inside the EXPRESSION_TO_PARAMETERIZE.

A conditional paragraph defines a block of text that will be inserted into the parameterized expression only if the expression defined in its header is TRUE. This expression may contain references to various fields within PARAMETERS_FORMAT.

ENABLING_CONDITION_EXPRESSION is an AggreGate expression that may contain references to the cells of the Data Table built from PARAMETERS_FORMAT. Format of references is {FIELD_NAME} where FIELD_NAME is the name of the field defined by PARAMETERS_FORMAT. More information about references can be found here.

With this ENABLING_CONDITION_EXPRESSION, the text of conditional paragraph will be inserted to the parameterized expression only if the values of two Boolean fields filterByName and filterByValue are TRUE. These fields must be defined in PARAMETERS_FORMAT.

SELECT * FROM users.*:childInfo WHERE childInfo$phone IS NOT NULL

In this example, childInfo$phone refers to the "phone number" field within a user information record (You can learn more about this under Queries.) ENABLING_CONDITION_EXPRESSION refers to the Boolean field showOnlyUsersWithPhones defined in PARAMETERS_FORMAT (for example, like this: "<<showOnlyUsersWithPhones><D=Show only users that have phone numbers>>"). If this field is set to FALSE by the user during parameterization process, the resulting parameterized expression will be "SELECT * FROM users.*:childInfo". If the field is set to TRUE, the resulting expression will be "SELECT * FROM users.*:childInfo WHERE childInfo$phone IS NOT NULL", i.e. TEXT_OF_CONDITIONAL_PARAGRAPH is included in the result.

The conditional paragraph doesn't necessarily have to be at the end of the query/filter string. In the following example, it's in the middle of the expression (right before the ORDER BY clause):

SELECT * FROM users.*:childInfo WHERE childInfo$phone IS NOT NULL ORDER BY childInfo$name DESC

As covered above, Expression_to_parameterize is just a string. It's not an AggreGate Expression in itself. However, it may include AggreGate Expressions. Such AggreGate expressions may contain references to the cells of the Data Table built from PARAMETERS_FORMAT. The expression is evaluated, and the result of the evaluation is converted to a string and inserted into the final parameterization result (the AggreGate query or filter expression which is the product of the parameterization process).

This expression may contain references to the cells of Data Table built from PARAMETERS_FORMAT, exactly like ENABLING_CONDITION_EXPRESSION of conditional paragraph (see above).

Example:

SELECT * FROM users.*:childInfo WHERE childInfo$phone = '<e>{phone}</e>'

The ' marks above are necessary - they're used to escape the SQL string literal.

This example assumes a "phone" field exists in PARAMETERS_FORMAT. For example, if a user has entered phone "123-45-67" during the parameterization process, the result of parameterization will be "SELECT * FROM users.*:childInfo WHERE childInfo$phone = '123-45-67'".

1) Conditional paragraphs let you add/remove various pieces of your final expression based on a yes/no (Boolean) result of some expression.

2) Expressions let you insert specific values, deriving from their evaluation, into your final parameterization result.

3.	The resulting Data Table with parameters filled by the operator is preserved and made available for use, for example as a default table for additional report parameter values calculation.

4.	EXPRESSION_TO_PARAMETERIZE is now modified, using parameters from step (2): text of conditional paragraphs is inserted or removed, expressions are evaluated and the evaluation result is inserted into the final string.