Activities that the Pentaho BI Platform performs are defined by Action Sequence XML documents.  Action Sequences define activities such as database queries, report generation, email actions and the order in which they occur. Data can be passed between Actions within an Action Sequence or between executions of other Action Sequences.  They define the inputs that must be available prior to execution, the processes that will be performed and the outputs that will be available to other Action Sequences after execution is complete.

The purpose of the Action Sequence Editor is to facilitate the creation and management of action sequence documents. Delivered as an Eclipse plugin, it allows the user to create and edit action sequences within their Pentaho solutions.

Let's take a look at one of the action sequences that comes with the sample solution delivered with the Pentaho BI Server. Using the Package Explorer view on the left side of the Design Studio, double-click on the action sequence located as pentaho-solutions/bi-developers/bursting/BurstActionSequence.xaction. A new action sequence editor should open displaying the contents of the sample action sequence.

Now, let's take a look at the various parts of the action sequence editor.

General Tab

As the name implies, the General tab is where the general information about the action sequence is managed. Stuff like the title, description, and icon that will appear with the action sequence when browsing your solution. Additionally, you can indicate the logging level you would like to use for this action sequence. Logged messages will appear in the application server's log. If you're having problems getting your action sequences working, the log file is a good place to look for clues as to what the problem might be.

A quick look at the Getting Started portion of the Pentaho Demo how the General Information is displayed. If you haven't yet installed the Pentaho Demo you may want to take a look at the Getting Started with the BI Platform.

Notice that the design studio shows the title for action sequence to be "%title". The "%" indicates that this is the name of a string, whose value is defined in a properties file with the same name as the action sequence. In this case, the property file is named BurstActionSequence.properties. This is how action sequences accommodate internationalization.

You can indicate the logging level you would like to use for this action sequence. Logged messages will appear in {INSTALL_DIR}/biserver-ce/tomcat/logs/catalina.out or the appropriate catalina.<date>.log file.

When exploring a solution on-line using your favorite browser, the title and description are what identify the items to the user. The title and description, along with the specified icon, also appear in the flyover popup window.

The Help text on the general tab is not currently used by the Pentaho Demo.

Finally, note that on the Action Sequence Editor general tab, if the Visible checkbox is checked, the action sequence will not be listed in the browser. This is useful when creating utility action sequences that are not meant to be available to the user via the browser.

Define Process Tab

This tab is where the actual work done by the action sequence is defined. The tab is broken down into two sections. The outline, shown on the left hand side, lists all the action sequence inputs and outputs along with all the steps performed by the action sequence. The detail editor, shown on the right side of the tab, shows the details of the item selected in the outline, and allows you to modify the item.

Action Sequence Outline

The outline can be viewed using a tree (the default) or a flowchart. You can switch between the two by selecting the button in the upper left hand corner. Currently the tree is more functional, but we'll be taking care of that over time. However, the flowchart sometimes helps to better visualize what is going on. Let's take a closer look at the inputs, outputs, and process.
 
--> This icon doesn't exists in V2.0.0 RC 1

Process Inputs

This represents the "contract" this action sequence has with the outside world regarding information that will be needed for this action sequence to run. Selecting an input in this section will display a detailed look at the input to the right of the inputs tree. You can add and remove new action sequence inputs and resources using the and buttons that appear above the inputs.

The inputs are the pieces of information the action sequence will need from the outside world when it runs. They can come from four sources; runtime, request, session, global and default. Runtime parameters are parameters that are stored in the Runtime Context. Remember, the Runtime Context stores the inputs and outputs from previous instances and makes them available to future executions of the same runtime instance id. Request parameters are the name-value pairs specified on a URL. Session parameters are variables that are stored in the user's session and may contain unique values for each user. Global parameters are similar to session parameters except they have the same values for all users. Default values can be specified for each input and in the Action Sequence document and are used as a last resort.

Session and Global parameters can be used to provide secure filtering of data within the Action Sequence. A session parameter gets initialized by executing an action sequence when the user logs onto the system. The Action Sequence called upon login can be set up to perform a query using the user's login name in the where clause. The result is stored in the user's session and is available to subsequent Action Sequences. Global parameters are initialized when the system starts up and are available for all users. See the "Securing Data Access with Session and Global Filters" document for information on how to set up the filters and use them.

There are two implicit inputs instance-id and solution-idthat are always available and do not need to be specified as inputs or outputs. They are the... well I'm sure you can guess what they are.

Resources are the files needed by the action sequence to complete its job. For example: if the action sequence is going to run a JFree report, one of the resources would be the location of the JFree report definition file. Generally, the action sequence editor will manage the resources for you. If, for example you were going to generate a JFree Report, when you specify the location of the JFree report file, the action sequence editor will automatically add that file to the list of resources referenced by the action sequence. So, you likely won't be manually adding and modifying resources to the Process Inputs.

Process Outputs

The outputs are what this action sequence will leave behind when it's complete, stuff that other action sequences can use long after this action sequence is gone. Notice that above the Process Outputs tree there is a button that you can use to remove an output from the list of action sequence outputs, but there is no button. An obvious question would be "How do I add action sequence outputs and where do they come from?". They come from the outputs of the individual actions within the action sequence. If you expand each of actions listed in Process Actions you'll see the outputs that come from each action. Just drag the action output from the Process Actions section and drop it on the Process Outputs section and your done. The action output will become an action sequence output which will be available to the outside world after the action sequence is complete. Once you've created an ouput you need to identify where the output will be stored. To do this select the output to view its details then select an output destination. Outputs can have four destinations: runtime, session, or global, and response. The first three destinations correspond to the input sources discussed above. The fourth destination indicates that the output will be put in the http response header or content.

Process Actions

What you see in the Process Actions section is a list of all the actions to be performed by this action sequence. There are a large variety of actions available for your use. Each performs a particular type of task. There are actions to perform SQL queries, generate reports, prompt the user for input, execute JavaScript, etc. Note that the order is important here. The topmost action will be run first, followed by the one below it, and so on. Two types of actions require special mention, they are the loop action and the conditional action. These are synonymous with the "while" and "if" statements found in most modern programming languages. Actions within a loop action will be performed multiple times, depending on what it's set to loop on. When using an if option the condition of the loop is defined using JavaScript. Actions can be added and removed using the and buttons respectively. You can also reorder actions using the and buttons.If you select an action in the tree you'll notice that the details of the action will appear in a details editor that appears to the right of the outline.

Details Editor 

As mentioned earlier, whenever an item is selected from the outline, the details of that item show up on the right hand side of the actions sequence editor. Let's take a look at the details of an Email action. You'll notice that there is a place for entering a brief name. Its a good idea to enter a user friendly name here, as it makes the action sequence outline easier to read. As you would expect the Email action has an area to specify a "To" and "From" address, but the the current values don't look like valid email adresses. The "<   >"  indicates that what you're actually looking at is the name of parameters where the addresses will be found. In this case the parameter names are "EMAIL" and "from". Where do these parameters come from? They're either action sequence inputs, or outputs from previous actions in the action sequence. There are two ways to assign a parameter to the "To" address. You can select one of the parameters shown in the "To" pulldown menu, which lists all the available parameters. Alternatively, you can drag an action sequence input or action output from the outline and drop it in the "To" text area. Pulldown menus and drag/drop are the common ways of assigning parameter to  items within an action. Keep in mind that there are different types of parameter, so if you drag an integer parameter and try and drop it on the "To" address, the drag and drop will be ingnored. Similarly the "To" pulldown menu will only contain parameters of the proper type. Of course if you don't want to use a parameter you can simply type in a  valid email address.


If you're wondering what the button in the upper left hand corner is all about, you can use this to switch over to an advanced view of the action. In the advanced view you have more direct access to the action XML. Use of this view is strongly discouraged. Only the most advanced users should use this view.

XML Source Tab

Ultimately an action sequence document is nothing more than an XML document. The XML Source Tab is where to go if you wish to view or edit the raw XML. Keep in mind that manually manipulating the XML is not encouraged. 

Test Tab 

If you have a Pentaho BI Server running, the test tab can be used to test your action sequence against the running server. Simply enter the URL to the running Pentaho server and select "Run". The editor will generate the URL necessary to submit the action sequence to the running BI server, then submit the request and display the result in the browser window embedded within the tab. By default the server URL is set up to point to "http://localhost:8080/pentaho. To modify the default Pentaho Server URL select Preferences from the Windows pulldown menu at the top of the Design Studio. From the Preferences dialog select Pentaho Design Studio and enter the URL to your BI Server. There are a few other buttons available on the test tab that can be used to help make testing a bit easier. They are:

• Test Server - Submits an HTTP request to the Pentaho Server URL. If things are working properly the BI server home page should appear.

• Generate URL - Generates and displays the URL that, when submitted to the BI Server, would execute the action sequence. You can then modify the URL (to add parameters for example) before selecting Run.

• Browser URL - Display the URL that was used to display the page currently be displayed.

 

Putting It All Together

Let's take a look at the action sequence we've been using as an example. We'll investigate how the actions in this action sequence are working together to get something useful done. As we go through this don't get tied up in all the little details. The idea is to get a feel for how the actions work together. Later we'll learn about the details of each individual type of action.

Let's start with the first action in the actions tree. It performs a SQL query to extract some region, manager, and email information from a database. As mentioned earlier, it leaves some outputs behind. The query results are saved in an output called burst-data. The other three outputs tell the world the column names for information in the results. Anytime you run a SQL query action make sure you include the column names in the output. That way other actions know what data is available in the rule result.

Next is the action loop. If you select it you'll notice that there isn't a whole lot to it. One notable point is that whenever you see "<" and ">" around a string it indicates that a parameter is being referenced. In this case the input to the loop references the output result set from the preceding query action.

The next three actions are all similar. They're each string formatting actions. They take some input strings, place them into a formatted message, and leave the formatted string as an output. Basically they get things in order for the last two actions. If you click on the "+" sign next to each of these actions in the Process Actions tree, you'll see the outputs that each leaves behind.

Next, you'll find a print statement that simply prints out the value of some of some parameters used in this action sequence to the server console. This is basically a debug statement  that you can use to debug your action sequences.

Following the print statement is a sql query that queries a database for the data to be used by the report. The report data is stored in an output called "reportData".

The action titled "Create The Report" creates the JFree report. Notice that the report data is coming from the output of the preceding query. Finally you'll notice that the report is being saved in an output called "reportOutput". So we've generated this report and it's sitting in an action output parameter called "report-output". Now what?

Select the last action in the sequence. The name says it all. This action will email the report to the manager of the region for which the JFree report was generated.

Again, don't be too concerned if you don't understand every detail. Each type of action has its own set of inputs and outputs. Once you get familiar with them you'll soon be putting them together to do all kinds of useful stuff.