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 consists of Format and Parameterized Expression. It defines a number of parameters that must be entered during parameterization process. Normal use is like this: administrators create parameterization source data and put into a parameterized query or event filter. Users then specify parameters on-the-fly, when executing the query or filter.

Parameters Format

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 Parameterized Expression. The data table constructed from Format always contains just a single record. This table allows the user to interactively define parameter values which will then be used within Parameterized Expression.

Here's an example of a Format fields table:

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 boolean parameter may be used, for example, to enable filtering by a specific user in a report, and the string parameter will be the name of user.

The user will then be prompted to enter these parameters:

Here is a much more complex format:

Which also includes bindings:

This format defines many fields and some relations between them that are controlled by bindings. 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).

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

Parameterized Expression

Parameterized Expression is just the text used to build a query or an Iotellect 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 Format.

As Parameterized Expression contains XML tags (see below) it cannot be written inside the CDATA block. 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 Parameterized Expression.

Conditional Paragraphs

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 Format.

Syntax:

<p enabled="ENABLING_CONDITION_EXPRESSION">TEXT_OF_CONDITIONAL_PARAGRAPH</p>

ENABLING_CONDITION_EXPRESSION is an Iotellect expression that may contain references to the fields of the Format. Format of references is {FIELD_NAME} where FIELD_NAME is the name of the field defined by Format. More information about references can be found here.

Example ENABLING_CONDITION_EXPRESSION:

{filterByName} && {filterByValue}

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 Format.

Example of Parameterized Expression with a conditional paragraph:

SELECT * FROM users.*:childInfo <p enabled="{showOnlyUsersWithPhones}">WHERE childInfo$phone IS NOT NULL</p>

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 Format. 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 <p enabled="{showOnlyUsersWithPhones}">WHERE childInfo$phone IS NOT NULL</p> ORDER BY childInfo$name DESC

Expressions

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

Syntax:

<e>EXPRESSION</e>

This expression may contain references to the fields of the 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 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.

Parameterization Process Flow

  • Parameterization data is parsed and validated.

  • The user is prompted to enter the parameters specified by Format.

  • Parameterized Expression 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.

  • The resulting final string is used as the query or filter expression.

Was this page helpful?