Page Comparison

The article this week addresses a common task that community users are asking about over and over - how do you specify parameters to a report, and pass a list of valid values for the user to select the parameter from? While there are several ways to do this, we are going to step through one example using the Pentaho Design Studio. The Design Studio eliminates the frustration of writing XML, and should make the parameter passing a bit easier to understand and implement.

...

1. Right-click on the folder named Inputs in the Process Inputs box. Select Add... | Input from the menu.
2. In the new editor page, type REGION in the textbox labeled "Name".  Leave the Type defaulted to string.
3. Check the box labeled "Has Default Value". Set the default value to Central by typing Central in the text box labeled "Default Value".
4. Add another input following the same steps, naming it "REGION_SELECTIONS".
5. This time, change the value in the Type combobox to "result-set" by scrolling down in the list of options.
6. Once again, select the "Has Default Value" checkbox. You should notice that the dialog has changed for setting the default value. You should see a two column table, columns named key0 and key1.
7. Change the name of the columns to Name and Value, in that order. Select the first row in the table, right-click and select the "Manage Columns" option. You will be prompted with a dialog populated with the column names. Rename key0 to Name, and key1 to Value.
   Image Added
8. Now we can enter the list of values that are valid for our REGION parameter. The values we enter in the name column are the descriptions we want to display in the prompt page. The values we enter in the Values column are the corresponding values that are to be passed to the report query. This is very useful when you have, for example, ugly codes that describe your products that you must pass to your query, but you want the descriptive names to be displayed to your users for product selection. Enter the following values in the table:
   Image Added
9. Save your action sequence now.

Fleshing Out the Process

Now that we have defined our inputs, we need to perform two more tasks: 1.) associate the REGION input with our report query, and 2.) provide the mechanism for displaying the REGION_SELECTIONS values to our user.

1. Click on the "report" entry in the Process-Actions box. You should see the editor page populated with  the report definition.
2. Locate the report query, halfway down the page. Add the following where clause in the middle of the existing query:

   Code Block
   WHERE QUADRANT_ACTUALS.REGION='{REGION}'

   Image Added
3. Notice that the {REGION} string shows up as a Report Parameter, just above the query. This is called a replaceable parameter, and in one more step we will associate the value selected from the REGION_SELECTIONS with this replaceable parameter.
4. Right click in the Process Actions box. Click on the Add... menu option, then select the Secure Filter. This will add a secure filter component to your action sequence. The secure filter component allows you to filter data by a selected value, and protect your queries by not allowing the URL back to the server to execute with any other values than those provided as options via the component.
5. Drag the secure filter component above the report entry in the Process Actions box.
6. Select the Secure Filter in the Process Actions box, so that the editor page displays the options for the Secure Filter.
7. Drag the REGION Input parameter FROM the Process Inputs box TO the Selections box of the Secure Filter page.
8. Next, select REGION in the Selections box.
9. A Title and Filter boxes appear. In the Title textbox, add the prompt for the REGION parameter (ie., What region would you like to see data for?).
10. In the Filter box, select <REGION_SELECTIONS>. You should note that some new options are now available to you, named Filter Details.
11. In Filter Details, change the Selection Style to "pulldown".
12. Type "Value" in the text box labeled "Value Column", and type "Name" in the text box labeled "Name Column". Remember these are the names we gave our columns when we were describing our table of values in the REGION_SELECTIONS input parameter.
    Image Added
13. Save your action sequence now.
    

Step-By-Step: How to Test Your Solution

Here is where the Pentaho Pre-configured Install comes in. Follow the steps given to test out your new solution in the server.

1. First, make sure your PCI is up and running. If you don't know how to get it started, or are unsure as to whether it's already running, see the Pentaho Getting Started Guide for how to successfully start the server.
2. Next make sure that the solution folders you are using in the PCI contains your modified JFree_Quad.xaction!! 
3. Switch to the Test tab of the Action Sequence Editor. Verify that the "Server URL" at the top of the page is indeed the URL to your PCI by clicking the "Test Server" button. You will see see the home page of the PCI if all is operating properly.
4. You should see the URL for the action sequence we want to test in the textbox labeled "Generated URL". Just after that text box is a "Run" button.
5. Click the "Run" button to test your action sequence. You should see a prompt page asking for the region. When you select submit, you will recieve your report filtered down to the region you selected.
   Image Added

Should you encounter any problems or if you just want to peruse the solution, you can find the xml for this exercise here.