Managing Reports Using the Report Builder › Data Objects › Runtime Variables

Runtime Variables

Data objects can use runtime variables to alter behavior and selection criteria dynamically.

For Query data objects, you can use runtime variables in the SQL query. As a prerequisite, define these runtime variables in the Variables list. That list includes default Query variables, and you can add your own.

For example, consider a report based on a SQL query that displays a list of users. The data object can take a Last_Name value as a runtime variable to indicate the starting characters of the last name. Users of the data object are prompted for the Last_Name value. You can use the runtime variable of type String named %Last_Name% in the SQL statement. Use this variable to restrict the results to user records that start with the value entered by the user. The following SQL statement provides a sample query:

SELECT first_name,middle_name,last_name FROM ca_contact WHERE (ca_contact.last_name like '%Last_Name%%')

Note: Users are prompted for only the runtime variables in the SQL query.

For plug-in data objects, you can pass runtime variables to the Java class as name-and-value pairs. As a prerequisite, verify that the Java report plug-in class takes the name-and-value pairs for the plug-in data object.

For example, consider the com.ca.usm.reporting.Plugins.RequestFulfillmentReport plug-in class. This plug-in class takes a parameter of Date type named START_DATE. Therefore, START_DATE is required in the data object that uses this plug-in class. In this case, do either of the following:

• Hard-code START_DATE as a constant
• Prompt the user for the date START_DATE value and pass that value to the plug-in

You can use contextual system variables with runtime variables, for the following purposes:

• As default values when you prompt the user
• As constant values to pass to the plug-in
• As values to use in a query

The contextual system variables are as follows:

Add a Query Runtime Variable

You can add a custom runtime variable to use with a Query data object. An example is adding a query runtime variable that is a drop-down variable.

Follow these steps:

1. Click Administration, Report Builder.

   The Report Builder page appears, with Data Objects selected in the left menu under the main menu.

2. Do one of the following:
   • Add a new data object
   • Edit an existing data object

   The page changes to match your action of creating or editing a data object.

3. Click Create Variable.

   The Create Runtime Variable or Edit Runtime Variable dialog appears.

4. Specify the name, type, and other data in the fields provided. Use the following guidelines:
   • To specify advanced data, click Advanced.
   • To view help text, click the Help (question mark) icon. This icon appears at the end of the title bar of the dialog.
5. Click Create Variable.

   The Catalog system saves your variable definition.

You can use the variable in an SQL query for a Query data object. Users are prompted to enter a value when they run the data object.

Note: When you add a query runtime variable that is a drop-down variable, the number of values in the resulting drop-down list is limited to 1000. If the report query returns more than 1000 values, the system truncates these additional values. Consequently, the user cannot view them in the drop-down list. If necessary, you can increase the number of values that appear in the drop-down list to be greater than 1000. For details, see the Implementation Guide.