The purpose of the Pentaho Design Studio is to facilitate the creation and management of files within your Pentaho solutions. The Design Studio helps organize these files and provides editors for each type of file. There are several levels of organization within the Design Studio: workspaces, project, views, editors, and perspectives. If you haven't done so already start up the design studio and take a look at the basic layout.
A workspace is a directory that contains a collection of projects, along with preferences and other settings related to the projects it contains. When working in the Design Studio keep in mind you are working with a single workspace. If you would like to change the workspace currently being used by the Design Studio simply select the Set Workspace option from the File menu. The Design Studio comes with a preexisting workspace containing a single project called Default Project.
Projects, Folders and Files
There are three different types of resources in the Design Studio: projects, folders, and files. Projects are the largest structural unit used by the Design Studio. Projects contain folders and files, and they can be opened, closed, or built. Folders can contain other folders and files. The Design Studio provides a number of mechanisms for working with projects, folders and files. A Pentaho BI solution is typically represented as a project of the Design Studio. The folders and file represent the hierarchy of content within solutions. As mentioned earlier, the design studio comes preconfigured with a workspace that contains a single project name "Default Project". If you expand the project in the left hand tree you'll notice that the project contains a single file named "untitled.xaction".
A view is a visual component within the Design Studio. It is typically used to navigate a hierarchy of information (such as the resources in the Design Studio), open an editor, or display properties for the active editor. Modifications made in a view are saved immediately. Normally, only one instance of a particular type of view may exist within a Design Studio window. The "Package Explorer" displayed in the left hand side of the Design Studio is an example of a view. It The Package Explorer view displays the projects within the active workspace, and allows you to navigate the folders and files located within a each project.
An editor is also a visual component within the Design Studio. It is typically used to edit or browse a resource. Modifications made in an editor follow an open-save-close lifecycle model. Multiple instances of an editor type may exist within a Design Studio window. The Action Sequence Editor is one example of an editor. To see the Action Sequence Editor in action expand the "Default Project" in the Package Explorer view and double-click on untitled.xaction. The action sequence editor should appear.
A perspective is a group of views and editors in the Design Studio window. One or more perspectives can exist in a single Design Studio window. Each perspective contains one or more views and editors. Within a window, each perspective may have a different set of views but all perspectives share the same set of editors. You can think of a perspective is a visual organization of the windows within a workspace. The default Design Studio configuration contains a single Perspective name "Pentaho". Note that the active perspective is displayed in the upper right hand corner of the Design Studio. The Pentaho perspective is a very simple perspective containing the Package Explorer view and an area reserved for the editor.
Action Sequence Editor
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 Pentaho Action Sequence Editor is an Eclipse plugin which allows the user to create and edit action sequences within their Pentaho solutions. From within the Design studio let's quickly create a new action sequence and take a look at how it appears within the editor. Select the Default Project within the Package Explorer view on the left side of the Design Studio. From the toolbar at the top of the Design Studio select "New Action Sequence" from the Pentaho Toolbar Item. The Action Sequence Wizard should appear. From the Template pulldown select Sample Burst Action then select Finish. A new action sequence editor should open displaying the contents of the action sequence we just created. Now let's take a look at the various parts of the action sequence editor.
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 for this 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 pentaho-bi-suite/jboss/server/default/log/server.log file. 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.
Define Process Tab
Notice along the left hand side of this tab are three sections labeled "Process Inputs", "Process Actions" and "Process Outputs." Taken together these three sections define the task to be performed my this action sequence. Let's take a closer look at each.
This represents the "contract" this action sequence has with the outside world regarding information that will be needed for this action sequence to run. Inputs can come from the request (URL in most cases), the session or runtime. Resources are the files needed by the action sequence to complete its job. For example, if an action sequence is going to run a JFree report (which this one does), one of the resources would be the location of the JFree report definition file.
Selecting an input in this section will display a detailed look at the input to the right of the inputs tree. The Source of Input Section is where you indicate where to look for each input. When this action sequence runs there are three possible places each input can come from. One is the request (usually the http request). Input values coming from the request are determined by looking at the URL that caused the action sequence to run. Alternatively, input values can come from the session (usually the http session within which the action sequence is running). Finally, the default source, is the runtime context. That's the place where the outputs for each action sequence are placed and made available to other action sequences. In our example the inputs won't be available in any of those three locations. Instead this action sequence has default values assigned for each input. It is possible to assign multiple sources to an action input, in addition to a default value. In this case the sources will be searched in the order in which they are specified, and the default value will be used as a last resort.
Taking a look at the resources we see that there's only one, and it's called "Report Definition". Select it and let's have a look at the details. It looks like it's a file located, but someone seems to have forgotten to type in the file location. As the creator of this new action sequence it's our job to fill in the actual file location.
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 this particular action sequence doesn't have any outputs.
What you see in the Process Actions section is a list of all the actions to be performed by this action sequence. Note that the order is important here. The topmost action will be run first, followed by the one below it, and so on. The second action, the one that starts with "Action Loop" probably deserves special mention. It's a loop action that will perform the actions it contains multiple times, depending on what it's set to loop on. In this case it looks like there are five actions contained in the loop. Let's explore a bit more. Click on the first action in the list, the one that starts with "Lookup", and see what else we can find.
On the right side you can view the details of the Lookup action. You'll notice that there is a place for entering a brief description of the action. It's not necessary to enter anything here, but it's a good idea, as it makes the action sequence much easier to read. This particular action has an area to specify the database connection, the query, and the expected contents of the query result. Now lets click on the "+" sign next to this action in the Process Actions tree. Notice that there are four outputs from this action. The rule-result output is where the results of the query are stored. The remaining three outputs correspond to particular columns within the rule-result output. Other actions that follow can use these outputs as their inputs. So, one action can leave outputs that following actions can use as inputs. Additionally each action has available to it the inputs from the document. These are the things that are coming in from the outside world. The idea is that each little action has something it can do really well. It takes in some input does some work and leaves some output for some other action(s) to use. Your job is to tie these individual actions together to do something meaningful.
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.
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". Your action sequence will be submitted to the server for execution and the results will be displayed within the tab.
Templates are a great way to get a jump start on building action sequences. If you find that you're repeatedly creating action sequences with a similar set of steps, this might be a good candidate for an action sequence template. To create a template simply create an action sequence containing the basic steps and save it to your project. Make sure that on the General tab you give the action sequence title uniquely identifies the template. Now copy this new action sequence into the <eclipse_install_dir>/plugins/org.pentaho.designstudio.editors.actionsequence_x.x.x.x/templates directory. Next time you create a new action sequence, the Action Sequence Wizard will include your action sequence in the list available templates.