View
220
Download
0
Category
Preview:
Citation preview
8/13/2019 Action Sequence Guide
1/76
Creating Action Sequences
8/13/2019 Action Sequence Guide
2/76
This document is copyright 2011 Pentaho Corporation. No part may be reprinted without written permission fromPentaho Corporation. All trademarks are the property of their respective owners.
Help and Support ResourcesIf you have questions that are not covered in this guide, or if you would like to report errors in the documentation,please contact your Pentaho technical support representative.
Support-related questions should be submitted through the Pentaho Customer Support Portal athttp://support.pentaho.com.
For information about how to purchase support or enable an additional namedsupport contact, please contact yoursales representative, or send an email to sales@pentaho.com.
For information about instructor-led training on the topics covered in this guide, visithttp://www.pentaho.com/training.
Limits of Liability and Disclaimer of WarrantyThe author(s) of this document have used their best efforts in preparing the content and the programs contained
in it. These efforts include the development, research, and testing of the theories and programs to determine theireffectiveness. The author and publisher make no warranty of any kind, express or implied, with regard to theseprograms or the documentation contained in this book.
The author(s) and Pentaho shall not be liable in the event of incidental or consequential damages in connectionwith, or arising out of, the furnishing, performance, or use of the programs, associated instructions, and/or claims.
TrademarksPentaho (TM) and the Pentaho logo are registered trademarks of Pentaho Corporation. All other trademarks are theproperty of their respective owners. Trademarked names may appear throughout this document. Rather than listthe names and entities that own the trademarks or insert a trademark symbol with each mention of the trademarkedname, Pentaho states that it is using the names for editorial purposes only and to the benefit of the trademarkowner, with no intention of infringing upon that trademark.
Company InformationPentaho CorporationCitadel International, Suite 3405950 Hazeltine National DriveOrlando, FL 32822Phone: +1 407 812-OPEN (6736)Fax: +1 407 517-4575http://www.pentaho.com
E-mail: communityconnection@pentaho.com
Sales Inquiries: sales@pentaho.com
Documentation Suggestions: documentation@pentaho.com
Sign-up for our newsletter: http://community.pentaho.com/newsletter/
http://community.pentaho.com/newsletter/http://www.pentaho.com/traininghttp://www.pentaho.com/traininghttp://community.pentaho.com/newsletter/mailto:documentation@pentaho.commailto:sales@pentaho.commailto:communityconnection@pentaho.comhttp://www.pentaho.com/http://www.pentaho.com/trainingmailto:sales@pentaho.comhttp://support.pentaho.com/8/13/2019 Action Sequence Guide
3/76| T
Contents
Introduction...............................................................................................................................What is an Action Sequence?.................................................................................................What is a Solution?..................................................................................................................Requirements and Recommendations.....................................................................................
Using Design Studio.................................................................................................................Initial Design Studio Configuration.............................................................................................................Using PDI Data Sources in Action Sequences...............................................................................
The Design Studio Interface.......................................................................................................................Creating Design Studio Templates.............................................................................................................
Creating aSolution Directory...................................................................................................Your First Action Sequence.....................................................................................................Anatomy of an Action Sequence.............................................................................................
Output Types..............................................................................................................................................Input Types.................................................................................................................................................
Resources...................................................................................................................................................Parameter Data Types...............................................................................................................................
Action Definition Reference.....................................................................................................ContentRepositoryCleaner.........................................................................................................................EmailComponent........................................................................................................................................
PrintComponent..........................................................................................................................................2SecureFilterComponent..............................................................................................................................2SubActionComponent.................................................................................................................................2
TemplateComponent (Message Template)................................................................................................JavascriptRule............................................................................................................................................
SimpleReportingComponent.......................................................................................................................JFreeReportComponent.............................................................................................................................
Charting......................................................................................................................................................JFreeChart (ChartComponent)........................................................................................................Pentaho ChartBeans (ChartBeansComponent)...............................................................................
OpenFlashChart (OpenFlashChartComponent)..............................................................................Editing Existing Action Sequences..........................................................................................Internationalization Guidelines.................................................................................................5Action Sequence Error Handling.............................................................................................
Customizing Error Output...........................................................................................................................Error Token Reference...............................................................................................................................
Basic Action Sequence Tips and Tricks..................................................................................Emailing a Report.......................................................................................................................................
Advanced Action Sequence Tips and Tricks...........................................................................Using Java Virtual Machine Input Parameters...........................................................................................
Using Action Sequence Variables in Kettle/PDI.........................................................................................Sharing Result Sets in Action Sequences.................................................................................................Using Security Information In Action Sequences.......................................................................................
Content Linking in Dashboards..................................................................................................................
In-Depth Action Sequence Tutorials........................................................................................Creating a Bar Chart Using the Flash Chart Component..........................................................................
Configuring Design Studio...............................................................................................................Creating the Chart Definition...........................................................................................................
Creating the Action Sequence.........................................................................................................Viewing your Chart in the BI Platform.............................................................................................
Finding More Information.................................................................................................................
Troubleshooting.......................................................................................................................7Action Sequences That Call PDI Content Won't Run................................................................................
Adding PDI Enterprise Repository Content Support to the BA Server............................................
8/13/2019 Action Sequence Guide
4/76| TOC
Null Pointer Exception When Sharing Result Sets....................................................................................
8/13/2019 Action Sequence Guide
5/76Pentaho BI Suite Official Documentation | Introduct
Introduction
Action sequences are a unique and powerful feature of the Pentaho BI Platform; they enable BI developers and
business users to perform advanced tasks that cannot easily be accomplished through Pentaho's design tools anduser interface functions, including interaction with third-party software frameworks. This guide is designed to helpexperienced BI Platform users learn to create and edit action sequences using the Action Sequence Editor built into
Pentaho Design Studio.
Note: This guide is not yet finished. It is being published early because it contains a great deal of useful
information, and the extended delay caused by completing the component reference and action sequenceexamples would unreasonably prevent it from reaching Pentaho Business Analytics Enterprise Edition
customers in an acceptable timeframe. Please do let your Pentaho sales or support representative know if therare unfinished or missing sections that you would like to read.
8/13/2019 Action Sequence Guide
6/76Pentaho BI Suite Official Documentation | What is an Action Sequence?
What is an Action Sequence?
An action sequence is an XML document that defines an ordered set of action definitions that together perform a
single task; it is the smallest complete task that the Pentaho BI Platform's solution engine can perform. It is useful forsequencing small, linear, success-oriented tasks like reporting and bursting, and has the ability to loop through a resulset, call other action sequences, and conditionally execute components.
Action sequences can be created through raw XML (though the DOM for each component can be unique), or through
the graphical interface built into Design Studio (though not every function in every component is supported).
8/13/2019 Action Sequence Guide
7/76Pentaho BI Suite Official Documentation | What is a Solutio
What is a Solution?
A collection of action sequences that fit a common theme or purpose is called a solution, and each solution is typicallin its own directory. By default, all solutions are in subdirectories in the /pentaho/server/biserver-ee/pentahosolutions/directory, which is mirrored in the solution repository database. Mirroring the solutions directory allows thBI Platform to have fine-grained control of user and role access to each file and subdirectory.
8/13/2019 Action Sequence Guide
8/76Pentaho BI Suite Official Documentation | Requirements and Recommendations
Requirements and Recommendations
At its core, an action sequence is an XML file with a .xactionextension. Because each component and plugin has itsown unique inputs, outputs, and action definitions, it's best not to try to create an action sequence by hand with an XMeditor -- you'll quickly get lost. Instead, you should use the Action Sequence Editor built into Pentaho Design Studio.
Design Studio is a standalone tool that facilitates the creation and management of action sequences using a graphicalinterface, and should be your tool of choice when creating, editing, and publishing action sequences. It doesn't require
knowledge or manipulation of the underlying XML, but does offer an XML editor so that you can hand-edit action
sequences that you create through the standard user interface. While you do not necessarily need to understand howto code the bare XML for each component in order to create simple action sequences, more complex operations requi
hand-editing.
Note: Some BI Platform components -- especially very new ones -- may not be fully or correctly implemented Design Studio, and will require hand-editing.
Design Studio is included with a standard Pentaho Business Analytics Enterprise Edition workstation deployment. If
it is not installed on your system, you can either re-run the Pentaho Business Analytics installation utility, or you candownload an individual Design Studio package from the Pentaho Customer Support Portal. If you are on a supported64-bit operating system, you will have to install the Eclipse integrated development environment for your platform on
your own, then download and install the Pentaho Action Sequence Editor Eclipse plugins. Instructions for this processare included in the Pentaho Archive-Based Installation Guide, which is available in the Pentaho InfoCenter.
In order to test and publish your action sequences, you will have to either install Design Studio on the same machineas your BI Server, or you will have to install a standalone BI Server instance for action sequence development on your
workstation. Once you've developed and tested your new action sequence, you can copy it over to your productionserver to deploy it.
8/13/2019 Action Sequence Guide
9/76Pentaho BI Suite Official Documentation | Using Design Stu
Using Design Studio
This section explains how to use the basic functionality of the Action Sequence Editor in Pentaho Design Studio.
Initial Design Studio Configuration
When you first launch Design Studio, you must establish a workspace and an Eclipse project before you can begin
creating action sequences. Follow the below directions to initialize Design Studio.
1. Start Pentaho Design Studio.
On Windows, you can start Design Studio through the Start menu in the Pentaho Business Analytics category. On
Linux, run the /pentaho/design-tools/design-studio/PentahoDesignStudio script.
2. If this is the first time you've run Design Studio, you'll be asked to type in a workspace location. Type in /pentahoserver/biserver-ee/pentaho-solutions/ , or whatever the location of your solutions directory is.
This is where Eclipse (the integrated development environment that Design Studio is based on) stores project files.
Using the solutions directory for the BI Platform ensures that your xactions will be easily accessible from it.
3. Start a new Eclipse project by going to the Filemenu, then selecting New, then clicking Projectin the sub-menu.
A New Project selection window will appear.
4. Click the triangle next to General, then click the Projectitem under it, then click Next.
5. Type learning_solutionsin the Project Name field, then click Finish.
You will return to the Welcome screen.
6. Click Workbenchto go to the Eclipse workbench.
This is the view you will need to be in to perform most Design Studio functions.
Design Studio is now configured with a Pentaho workspace and a project directory for creating and managing new
action sequences.
When you are ready to create production-quality action sequences, you should start a new Eclipse project for each ne
solution.
8/13/2019 Action Sequence Guide
10/76| Pentaho BI Suite Official Documentation | Using Design Studio
Using PDI Data Sources in Action Sequences
If you have any action sequences that rely on Pentaho Data Integration (PDI) data sources that are stored in an
enterprise repository, you must make a configuration change in order to run them.
Create a .kettledirectory in the home directory of the user account that runs the BI Server, and copy therepositories.xmlfile from your local PDI configuration directory to the new one you just created on the BI Servermachine.
You must also edit the /pentaho-solutions/system/kettle/settings.xml file and put in your PDI enterprise
repository information.Once these changes have been made, restart the BI Server. When it comes back up, the Use Kettle Repositoryfunction in Pentaho Design Studio should properly connect to the DI Server.
The Design Studio Interface
Design Studio features a modular interface with the following tabs:
GeneralThis tab enables you to define and modify basic values including the logging level, result type, and icon fothe action sequence.
Define ProcessThis tab is where you define the process inputs, process actions, and process outputs that gotogether to make up an action sequence.
XML SourceThis tab enables you to view the bare action sequence XML.
TestThis tab allows you to test the action sequence inside of Design Studio.
Note: The Testtab does not work on Linux or Solaris. To test an action sequence, publish it to your test serve
Design Studio starts by default in a specialized view that limits its interface options to the actions defined in the
template. You can switch to Generic Component Mode, which shows all possible component parameters, by clickingthe toggle button to the right of Process Inputs, shown in the graphic below underneath the untitled1.xactiontab:
The following example shows the JFree_Quad.xaction in the Define Process tab with some defined process inputs,
process actions, and process outputs. The focus is on the REGION process input, so the right pane shows the optionsfor defining this specific input.
8/13/2019 Action Sequence Guide
11/76Pentaho BI Suite Official Documentation | Using Design Stud
Creating Design Studio Templates
Note: This section is not yet complete.
8/13/2019 Action Sequence Guide
12/76| Pentaho BI Suite Official Documentation | Creating a Solution Directory
Creating a Solution Directory
Before you begin creating action sequences, it makes sense to create a directory to store them in. In theory, this
directory will contain a collection of action sequences that fit a common purpose or theme -- a solution, which wouldmake this a solution directory. You should create a new directory for every solution you develop.
1. Create a new directory in /pentaho/server/biserver-ee/pentaho-solutions/ .
Use underscores instead of spaces in the solution directory name. Ensure that the directory has the appropriate us
and group ownership to be writable from the BI Platform.
2. Using an XML-aware text editor (or Design Studio), create a file named index.xmlin your new solution directory.
3. Copy the following text into the index.xml file, changing the content accordingly:
Example Solution This solution contains examples I created while learning to workwith action sequences. true icons
4. Save the file and close the text editor.
5. Log into the Pentaho User Console as an administrator.
6. Refresh the solution repository cache by going to the Toolsmenu, then selecting the Refreshsubmenu, thenclicking on Repository Cache.
You now have a new solution directory. It will show up in all file dialogues in the Pentaho User Console as well as theSolution Browser in the left pane.
Every time you add or edit an action sequence to your solution directory, you must refresh the repository cache as
explained above. Each user currently logged into the Pentaho User Console must also refresh their session cache; thiis best done by re-logging into the Pentaho User Console.
8/13/2019 Action Sequence Guide
13/76Pentaho BI Suite Official Documentation | Your First Action Sequenc
Your First Action Sequence
Follow the directions below to create the simplest kind of functional action sequence with Design Studio.
1. In Design Studio, go to the Filemenu, then select New, and click on Other...in the sub-menu.
The Newwindow will appear.
2. In the Newwindow, click the triangle next to Pentaho, select New Action Sequence Wizard, then click Next.
3. In the File namefield, type hello_world.xaction.
4. Select Hello Worldfrom the Templatedrop-down box, then click Finish.The wizard will generate the new file and bring you back to the workbench.
5. Click on HelloWorldComponentin the Process Actionssection on the left.
The right side of the screen will change to show the options available for this action: Nameand Message. TheName field controls the name of the component in the Process Actions list on the left; it doesn't do anything else of
note. The Message field contains the text that will appear on the screen when the action sequence is run. It is pre-populated with %quote, which is a token that represents a quote message in a nonexistent properties file. Pentahoused to provide properties files for each example, but they have been removed from the standard Pentaho Busines
Analytics distribution.
6. Replace the %quotewith a sufficiently inspiring message.
Alternatively, you could create a hello_world.propertiesfile and populate it with the appropriate messages andtokens, but that has no advantage unless you intend to internationalize this action sequence.
7. Save the file.
You now have a working action sequence that prints a short text message: "Hello, World." plus whatever you typed intthe Message field. The first part of the message is determined by a message bundle packaged with the Pentaho Web
application archive.
To test the action sequence, use the Test tab if you are on Windows or OS X, or log into the Pentaho User Console anrun it from the Solution Browser.
8/13/2019 Action Sequence Guide
14/76| Pentaho BI Suite Official Documentation | Anatomy of an Action Sequence
Anatomy of an Action Sequence
In the below example action sequence, an email is generated and sent to either Joe or Suzy, depending on which
region the user selects. There are four inputs: region, from, subject, and message-plain. The region input type isdefined as a string, and it has a default value of Central. Region may come from one of two sources: requestorsession. When the RuntimeContextresolves the region input at runtime, it will first look in the request (most likelyan HTTP request). If it doesn't find it in the request, it will look in the session (most likely the HTTP session). If it is notavailable in the session, the defaultvalue will be used. The order that the sources are specified in the XML documentthe order that they will be searched. The default is always used as a last resort.
The other three inputs only specify a default value. This is analogous to hard-coding the parameters to a constant valu
Since the output of this action sequence is an email message, no output parameters will be set.
There are two action-definitionnodes for this sequence. The first invokes the JavascriptRule component and takesa regionparameter as input; it will create a new parameter called rule_resultas output. This new parameter will bemade available to other action-definition nodes in the sequence.
The JavaScript defined in the component-definitionwill be executed and will set the value of rule_resultto theappropriate email address, based on the value of region.
When the first action-definitioncompletes, the second, which defines an interaction with EmailComponent, willexecute. EmailComponent requires four action-inputs: to, from, subject, and message-plain.
You may have noticed that some of the action-inputs (from, subject and message-plain) are also specified in the
inputs section of the action sequence header. The RuntimeContext will take the values from there and pass them toEmailComponent just as it passed region to the JavascriptRule. The source of the action-input is indirectly defined withthe mappingattribute, which tells the RuntimeContext to use the value from rule_resultthat was generated by theJavascriptRule action and use it as the component's toinput.
Example1.xaction
Chuck NorrisEmail to selected userThere is no help when Chuck Norris emails you
Central REGION aRegion
admin@example.com
Pentaho Example1
This is an email from the Pentaho BI Platform - Example1
8/13/2019 Action Sequence Guide
15/76Pentaho BI Suite Official Documentation | Anatomy of an Action Sequenc
JavascriptRule
EmailComponent
Output TypesComponent-specific action-outputs are defined on an individual basis and can vary; however, global output handlers a
static.
The output variable data types are defined in Design Studio, and are reasonably self-explanatory. For the majority
of action sequences, you will only be using stringand content(binary file) data types. All output types can beparameterized by using {curly braces}.
response
This directs previously generated content to whatever agent made the request (usually a Web browser). If you want tosave the content for later use, you should use the fileoutput handler (explained below) instead.
1. content: The default outputstream type. This streams output to a Web browser (or whatever the component'sdestination may be) to be displayed. The type of content and how the browser displays it are determined by theMIME type you specify.
2. redirect: The Web browser will be redirected to the URL defined by the output. The Web browser will automaticallyload the content associated with that URL. The redirect content type is useful when you want to use action sequenclogic to generate a URL or to set programmatically URL parameters before sending the request to another Web
application. It is possible to chain action sequences using the redirect.
3. header: This will return a standard HTTP name/value pair that will go into the header of an HTTP response. This isuseful for setting error codes in the browser.
These three response types stream different kinds of data to your Web browser.
8/13/2019 Action Sequence Guide
16/76| Pentaho BI Suite Official Documentation | Anatomy of an Action Sequence
Below is a typical global output response example; just replace contentwith redirector headerto define otherresponse types:
content
file
This is direct output to a file. The path to the file is defined through a platform-specific URI. The default location is theBI Server's working directory. If the location you specify does not exist, the BI Platform will attempt to create it. If the fil
name you specify is already in use, the existing file will be replaced with the new one you are generating.
file:invoice_{orderkey}.pdf
Apache VFSThis directs output to the Apache Commons Virtual Filesystem. Currently, only the FTP destination type is supported.
vfs-ftp://ftp.example.org|bsmith:password@ftp.example.org/mytest.txt
Custom output types
You can define your own output type in the BI Platform by writing an output class, then mapping it to a new outputtype in the /pentaho/server/biserver-ee/pentaho-solutions/system/pentahoObjects-spring.xmlconfiguration file. Once that work is complete, you can use the new output type in an action sequence. This is usefulfor action sequence output that has to be formatted in a certain way, particularly for use as an input file for other
applications.
myoutput:custom_app_data_{datestamp}.xmp
Input Types
Inputs are typically small, dynamic data sources that are available globally for all actions in an action sequence. Each
declared as a variable with a static data type, one or more methods of retrieving the data, and a default value in case ndata is retrieved.
Note: If you declare a default-valuewithout assigning a value, the user running the action sequence will beprompted for a value, if possible.
There are four potential sources for input values:
1. runtime: parameters that are stored in the runtime context, which retains the inputs and outputs from previousinstances and makes them available to future executions of the same runtime instance-id.
8/13/2019 Action Sequence Guide
17/76Pentaho BI Suite Official Documentation | Anatomy of an Action Sequenc
2. request: the name/value pairs specified on a URL.
3. session: variables that are stored in the user's session and may contain unique values for each user.
4. global: similar to session parameters, except they have the same values for all users. Global scope contains theoutput of any global startup action sequences or any action sequences that have explicitly output to global.
REGION aRegion
Central
In the above example, a single input named regionis declared as a string. The BI Platform first attempts to get thevalue from the REGIONvariable in the browser request; if no value is found, the BI Platform looks in the runtime contefor an aRegionvariable; if no value is found there either, the default value of Centralis assigned.
Resources
Resources define unique input sources that have a specific MIME type and a path. Usually you would use a resourceinstead of an input when you're referring to large or unusual data sources.
file
The full path to a local file (or a file accessible through a local directory), including the file name.
/home/pentaho/samples/reporting/myReport.prpt text/xml
url
A link to a remote file accessible via HTTP.
https://reader010.{domain}/reader010/html5/0621/5b2b2c4da0f23/5b2b2c56c0f image/png
solution-file
A file in the BA Server solution repository; the path is relative to the top-level solution directory (by default this is /pentaho/server/biserver-ee/pentaho-solutions/ ).
myReport.prpt application/zip
stringAn inline block of text in CDATA tags, as opposed to an external text file.
text/plain
xml
Inline XML, as opposed to an external XML file.
An example
8/13/2019 Action Sequence Guide
18/76| Pentaho BI Suite Official Documentation | Anatomy of an Action Sequence
text/xml
Parameter Data Types
Data type Definition
content A large block of data that is generated
within a component.
long A Java long object.
property-map A property map of Java strings.
property-map-list A list of property maps of Java strings.
string The standard Java string.
string-list A list of Java string objects.
8/13/2019 Action Sequence Guide
19/76
8/13/2019 Action Sequence Guide
20/76| Pentaho BI Suite Official Documentation | Action Definition Reference
EmailComponent
The EmailComponent enables you to send email messages from the BI Platform. Most of the inputs are standard ema
parameters and need little explanation. The message-plainand message-htmlvalues are meant to be used in aneither-or scenario; you would use one or the other, but not both.
Attachments are not defined as inputs, but as resources of type filewith the text/plainmime-type. The attachmentresource is then called in the component definition as an attachment-ref, shown in the example action sequencebelow.
Action Input Data Type Definition
message-plain String The email message body in plain text
message-html String The email message body in HTML
formatsubject String The email subject
to String The email address of the message
recipient. You may specify multipleaddresses by using a comma to
separate each
cc String The email address of a secondary(carbon copy) message recipient. Youmay specify multiple addresses by
using a comma to separate each
bcc String The email address of a blind carboncopy message recipient, who will notbe able to see the recipients specified
in the to, cc, or bcc fields. You mayspecify multiple addresses by using a
comma to separate each
from String The email address you want to sendthe message as. If you do not specifyan address, the default value that
you specified in the BI Platformconfiguration will be used (typically th
is set through the Pentaho EnterpriseConsole or Pentaho Administration
Console)
Send Email
1 DEBUG
Joe PentahoSample sequence for sending an email%helpruleHelloEmail.png
8/13/2019 Action Sequence Guide
21/76Pentaho BI Suite Official Documentation | Action Definition Referenc
to
joe.pentaho@pentaho.org
%subject
email-subject
%message
/home/bobs/pentaho/server/biserver-ee/pentaho-solutions/
initech/analysis/tps_latest.analysisview.xaction text/plain org.pentaho.component.EmailComponent The Bobs Consulting
8/13/2019 Action Sequence Guide
22/76| Pentaho BI Suite Official Documentation | Action Definition Reference
the sequence pipe its output to the report-outputparameter. Currently, the JFreeComponent, BIRTComponent, andJasperComponent all have the ability to generate content suitable for the report-outputparameter. If no content to priis specified, the action sequence will fail.
Action Input Data Type Definition
print-file String The file you want to print, including the
path
printer-name String A valid printer name recognized by theJRE, blank if you would prefer to show
a list of detected printers to the user,
and PENTAHO_DEFAULT_PRINTERif you would like to use the default
system printer
copies Integer The number of copies you'd like to pri
report-to-printer.xaction
%title 1
Marc Batchelor
JFree-quadrant-budget-hsql.pngjust testing...report
htmltype
printer
printer
printer
JFreeQuadForRegion.xmltext/xml
8/13/2019 Action Sequence Guide
23/76Pentaho BI Suite Official Documentation | Action Definition Referenc
PrintComponent
true
JFreeReportComponent
report
sqltrueSampleData
QUADRANT_ACTUALS.DEPARTMENT, QUADRANT_ACTUALS.POSITIONTITLE, QUADRANT_ACTUALS.ACTUAL, QUADRANT_ACTUALS.BUDGET,QUADRANT_ACTUALS.VARIANCE from QUADRANT_ACTUALS order by
QUADRANT_ACTUALS.REGION, QUADRANT_ACTUALS.DEPARTMENT]]>
SecureFilterComponent
The SecureFilterComponent has two separate but related functions: It allows you to customize the default prompting
mechanism, and can verify that only valid selections are returned.
The action inputs are custom variables that define each selection and its data source, as defined in the selections
section of the component definition. Each input may have the following attributes:
Input Attribute Data Type Definitionoptional Boolean Specifies whether the parameter is
required or not. If required, the user
must fill in the value before continuing
style String Defines the style of control that will be
presented to the user. Possible valuesare: text-box, radio, select, list, list-
multi, check-multi, check-multi-scroll,check-multi-scroll-2-column, check-
multi-scroll-3-column, check-multi-scroll-4-column.
8/13/2019 Action Sequence Guide
24/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Input Attribute Data Type Definition
prompt-if-one-value Boolean Prompt users even if there is only one
choice
title String Defines the user-viewable text
description
filter String If you do not want to filter a particularselection, you can set filter="none"aan attribute. If you do not set this, you
will have to define a filter inside of theinput tags in the selection section.
When defining a filter, the following attributes apply:
Filter Attribute Data Type Definition
value-col-name String Specifies the name of the input value
display-col-name String Specifies the name of the display valu
secure-sample.xaction
%title 1 debug
Doug Moran%descriptionjust testing...secure-sample.png
htmltype
REGION
REGION_FILTER
Human ResourceHR Dudes
Product DevelopmentThe Smart Guys
Executive ManagementOverhead
8/13/2019 Action Sequence Guide
25/76Pentaho BI Suite Official Documentation | Action Definition Referenc
DEPARTMENT
result
No selections for REGION were found in
your session.
This means you are not logged in or you do nothave permission to view this report.content
JFreeQuadForRegion.xml text/plain SecureFilterComponent
Prompt For Region and Dept
REGION_FILTERSelect the Region
DEPARTMENT_FILTERSelect the Department
CustomReportParameters.xslReport_Window
SQLLookupRule Get Data from Relational
8/13/2019 Action Sequence Guide
26/76| Pentaho BI Suite Official Documentation | Action Definition Reference
SampleData
QUADRANT_ACTUALS.ACTUAL, QUADRANT_ACTUALS.BUDGET,
QUADRANT_ACTUALS.VARIANCE from QUADRANT_ACTUALSwhere QUADRANT_ACTUALS.REGION={PREPARE:REGION} andQUADRANT_ACTUALS.DEPARTMENT={PREPARE:DEPARTMENT} order byQUADRANT_ACTUALS.REGION, QUADRANT_ACTUALS.DEPARTMENT]]>
JFreeReportComponent Pentaho Report html
SubActionComponent
Subactions create content that is used by the parent action. If you need to perform several dependent actions, youwould accomplish them individually through SubActionComponents.
Each input may have the following attributes, all of which are required except the session-proxy:
Input Attribute Data Type Definition
solution String The solution containing the xaction torun
path String Path within the solution that locates thxaction to run
action String The xaction to run
session-proxy String String value that contains an arbitrarysession name. Defining this will cause
the subaction to process in a differentsession (asynchronously)
query String XMLA query to be run
filter String If you do not want to filter a particularselection, you can set filter="none"aan attribute. If you do not set this, youwill have to define a filter inside of theinput tags in the selection section
Each output needs to have a specific name that the parent action will reference as the subaction result.
8/13/2019 Action Sequence Guide
27/76Pentaho BI Suite Official Documentation | Action Definition Referenc
There is a good example in the /pentaho-solutions/cdf/components/jfreechart.xactionaction sequence, but it's a little too long to print here in its entirety. Below isa relevant excerpt that shows SubActionComponent in use:
SubActionComponent Pentaho BI Process
TemplateComponent (Message Template)
The TemplateComponent, also called the Message Template Component, pulls in content from external sources (suchas HTML, XML, graphics, or text files) and inserts it in specific places in an action sequence. That external content can
be parameterized based on user feedback or a previous action's output.
In addition to whatever action inputs you specify, there is one required input for TemplateComponent:
Input Attribute Data Type Definition
template String The file containing the supported
content you want to import
Potential action outputs are:
Output Attribute Data Type Definition
mime-type String The MIME type of the file you're
creatingextension String The three-letter file extension of the fi
you're creating
There is presently no example
JavascriptRule
This component executes the specified block of JavaScript, typically as a way of interacting with BI Platform functionsthat are not available through other components. Parameters specified as inputs will be available to the script for use.
8/13/2019 Action Sequence Guide
28/76| Pentaho BI Suite Official Documentation | Action Definition Reference
The JavascriptRule can have one or more outputs. You can also define library elements in the component definition.Each specified library file must exist in the solution directory, and will be prepended to the script that's specified in the
component definition. In this way, you can create a library of commonly used JavaScript code, and include it at runtimeexecution.
Danger: The JavascriptRule component does not contain any limitations or provide any security checks for theJavaScript you specify. Only the technical validity of the JavaScript code is verified. This means that anythingyou can do with JavaScript will be executed when this action sequence is run. If you are using this component
to make any changes to files, databases, or users and permissions -- or anything else that can potentially bedestructive and cannot be undone -- you should carefully verify that it won't do any harm before testing and
deploying it.You should only use this component if you're familiar with the BI Platform's capabilities and have a good understandin
of what you want to do with this action sequence. Consult the BI Platform Javadoc for further guidance on how tointeract with it: http://javadoc.pentaho.com/bi_platform/.
Required Elements Data Type Definition
script String The JavaScript to be executed. This
code block must be enclosed in a tag.
Action Output Data Type Definition
rule-result Object A list of the values that have been
returned by all the functions that have
not been assigned to variables.
In the example below, the function regionis called but not assigned to a variable. It is the onlyfunction specified, so upon completion of the component execution, rule-resultwill contain the value"Central".
org.pentaho.component.JavascriptRule rule
SimpleReportingComponent
This is the preferred method of generating and manipulating reports programmatically in Pentaho Business Analytics.An older JFreeReportComponentstill works, but has an older, unmaintained feature set and exists primarily for
backwards compatibility with older versions. In order to use SimpleReportingComponent, you need to have generatedPRPT report file with Report Designer version 3.5.0 or later.
There is only one "input" for an action sequence involving this component, and it is defined as a resource in the inputssection of the action sequence, not in the component definition. There are two output attributes defined in the global
input section as well. Essentially you're going to point to your PRPT file, then define the file name and content type thayou want to generate.
http://javadoc.pentaho.com/bi_platform/http://javadoc.pentaho.com/bi_platform/8/13/2019 Action Sequence Guide
29/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Input Attribute Data Type Definition
reportDefinitionPath String Path to the PRPT file you are
generating a report from. Must beenclosed in a tag.Alternatively, you can declare a
reportDefinitionin your globalresources section.
outputType String The generic MIME type of the content
you're generating. Possible values are
text/html mime-message/text/html
application/pdf
application/vnd.ms-excel
application/rtf
text/csv
text/plain
outputTarget String Specifies the MIME type of the output
but allows for more specificity thanoutputType. Possible values are:
table/html;page-mode=stream
table/html;page-mode=page table/excel;page-mode=flow
table/csv;page-mode=stream
table/rtf;page-mode=flow
pageable/pdf
pageable/text
There is only one output, defined in either the global outputs section or the SimpleReportingComponent's action-outpusection:
Output Attribute Data Type Definition
outputstream String The output destination; where the
output will be written.
There are many report options, all of which are technically component inputs, and are positioned in the action-inputs
section. Most of these options are rarely used because most report functionality is determined when you initially createthe report.
Report Attribute Data Type Definition
paginate Boolean Determines whether the interface turn
on the page controller for the report.
report-definition String The path (relative to the top-level
solution directory), to the PRPT file,including the file name.
useContentRepository Boolean Determines whether the output iswritten to the BA Server content
repository.
accepted-page Integer The page number that should beshown when in paginated-html-mode.
print Boolean Determines whether or not you want tsend output to the printer.
printer-name String The (optional) name of the printer.
Default printer is the operating systemdefault printer.
content-handler-pattern String When exporting to HTML, this is thename of the content handler servlet
that sends images and CSS files to thbrowser.
8/13/2019 Action Sequence Guide
30/76
8/13/2019 Action Sequence Guide
31/76Pentaho BI Suite Official Documentation | Action Definition Referenc
SecureFilterComponent
Prompt for Product Line and Report Format
Select Report Format
outputTypeList
SQLLookupRule
SQL Query For Report Data
SampleData
true
SimpleReportingComponent Generate the report using a solution path to the reportdefinition
JFreeReportComponent
This is the deprecatedmethod of generating and manipulating reports programmatically, though it is the only way ofworking with old, non-PRPT, action sequence-based reports created with Report Designer or Report Design Wizardprior to version 3.5.0. If you are working with a PRPT report file generated with Report Designer version 3.5.0 or later,use SimpleReportingComponentinstead. In order to use the JFreeReportComponent, you need to have generated an
XML report file with Report Designer or Report Design Wizard prior to version 3.5.0.
There is only one "input" for an action sequence involving this component, and it is defined as a resource. Essentiallyyou're going to point to your simple or extended .xml file. However, there are many other parameters that go in theinputs section beyond that:
8/13/2019 Action Sequence Guide
32/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Input Attribute Data Type Definition
data String Specifies the main datasource to use
for this report; usually this is default.Other datasources may be defined forsubreports; their names must match
that of the subreport query.
class-location String Specifies the data source classlocation; used in conjunction with
report-jar.
config_parameters String Specifies a map or result set that
is used to populate the report'sconfiguration properties.
report-definition String Dynamically references a reportresource definition.
resource-name String Specifies the resource name in which
to load the report resource definition.
report-location String Specifies the report resource definitio
used in conjunction with report-jar.
res-url String Optional input that may specify thebase URL.
printer-name String If a printer name is specified,PrintComponent will be invoked to
generate the report.output-type String The type of output to be generated
from this report. Possible options are:
html
csv
xml
rtf
xls
swing-preview
yield-rate Integer Calls Thread.yieldat the interval
specified.create_private_report Boolean If set to true, clones the report object t
guarantee a single use.
report-priority String Specifies the thread priority when
generating the report. Possible valuesare:
normal
lower
lowest
content-handler String Specific to HTML inputs. Specifies thecontent handler.
workbook String Specific to Excel inputs. Defines the
workbook name to be used whengenerating the XLS file.
report-controller String Specific to Swing preview inputs. Areference to the report controller.
parent-dialog String Specific to Swing preview inputs. Areference to the parent dialogue.
modal Boolean Specific to Swing preview inputs. If the
dialogue should be modal, set this totrue.
progress-bar Boolean Specific to Swing preview inputs. If aprogress bar is to be displayed, set th
to true.
8/13/2019 Action Sequence Guide
33/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Input Attribute Data Type Definition
progress-dialog Boolean Specific to Swing preview inputs. If a
progress dialog is to be displayed, setto true.
There is only one output:
Output Attribute Data Type Definition
report-output String The default name of the outputstreamAny other output defined will be used
place of the report-output as a name.
%title
1 ERROR
Angelo Rodriguez%descriptionjust testing...reportJFree-quadrant-budget-hsql.png
JFreeQuadForRegion.xmltext/xml
SQLLookupRule
SQL Query For Report Data
SampleDatatrue
QUADRANT_ACTUALS.DEPARTMENT, QUADRANT_ACTUALS.POSITIONTITLE, QUADRANT_ACTUALS.ACTUAL, QUADRANT_ACTUALS.BUDGET,QUADRANT_ACTUALS.VARIANCE from QUADRANT_ACTUALS order by
QUADRANT_ACTUALS.REGION, QUADRANT_ACTUALS.DEPARTMENT]]>
JFreeReportComponent
Create Report Using Query Results
html
8/13/2019 Action Sequence Guide
34/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Charting
There are three components related to charting in the Pentaho BI Platform, each of which uses a different chart engine1. ChartComponent: Uses the JFreeChart engine; this is the default chart engine in the BI Platform.
2. ChartBeansComponent: Uses the Pentaho ChartBeans engine; this is the newest chart engine in the BI Platformand will someday replace JFreeChart.
3. OpenFlashChartComponent: Uses the OpenFlashChart engine; this is a small, limited, but visually impressivechart engine.
Each component has its own reference section below.
JFreeChart (ChartComponent)
JFreeChart is the default charting engine in the BI Platform.
Note: This section is not yet complete.
Pentaho ChartBeans (ChartBeansComponent)
ChartBeans is the next-generation chart engine in the BI Platform.
Note: This section is not yet complete.
OpenFlashChart (OpenFlashChartComponent)
OpenFlashChart is for visually appealing, Adobe Flash-based charts.
Introducing the Flash Chart Component
The Open Flash Chart component, available in the BI Platform version 3.0 and higher, currently employs Open Flash
Chartsas its charting engine.
The OpenFlashChartComponent is a BI component that allows you to create a variety of chart types that include:
Bar
Line
Bar/Line Combinations
Pie
Area
XY dot
Bubble
Sample Action Sequence
The action sequence, (simple_chart.xaction), uses the output from a SQL lookup rule (a Relational data source) as the
input for a OpenFlashChartComponent which generates a bar chart. See the Chart Reference for an explanation of thechart properties.
Simple Bar Chart Example Simple Bar Chart Example 1 DEBUG
http://teethgrinder.co.uk/open-flash-chart/http://teethgrinder.co.uk/open-flash-chart/8/13/2019 Action Sequence Guide
35/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Jake Cornelius This demonstrates generating a simple bar chart types using theOpenFlashChartComponent in an action sequence
chart_width chart_height
flash_barchart.xml text/xml
SQLLookupRule Chart Data Query
OpenFlashChartComponent Open Flash Chart
8/13/2019 Action Sequence Guide
36/76
8/13/2019 Action Sequence Guide
37/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Required Properties
The only property a bar chart requires is the appropriate chart-type
BarChart
Example
The example below contains the full set of additional supported properties with comments on its purpose and valid
values. It is recommended that new users start with this example as a starting place for building their first flash chart.The following chart definition will produce the chart shown directly below it.
BarChart
Chart Title Arial 18 true
vertical false false false false 10 #FF0000 #00ff00
#FFffff #ffffff .70
#top# #bottom# #val# #x_label# #key#
Domain Title
Arial 14 false #000000 #ffffff 1
Range Title Arial 14
8/13/2019 Action Sequence Guide
38/76| Pentaho BI Suite Official Documentation | Action Definition Reference
false #000000 #eaeaea 1 6
#0f3765 #880a0f #B09A6B #772200 #C52F0D #123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611 #772200 #8b2834
Simple Chart
Example with is-glassset to true
8/13/2019 Action Sequence Guide
39/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Example with is-3Dset to true
Example with is-sketchset to true(fun factor = 10)
8/13/2019 Action Sequence Guide
40/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Line Chart
The line chart plots a set of values on a line for each series in the given dataset.
Dataset Guidelines
This chart expects its data as a categoricaldataset.
Required Properties
The only property a line chart requires is the appropriate chart-type.
LineChart
ExampleThe example below contains the full set of additional supported properties with comments about its purpose and valid
values. If you are new to flash charts start here. The following chart definition will produce the chart shown directlybelow it.
LineChart
Chart Title Arial 18
true
2.0 hollow 5
#FFFFFF #FFFFFF
Domain Title
8/13/2019 Action Sequence Guide
41/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Arial 14 true #000000 #CCCCCC 1
Range Title
Arial 14 true #CCCCCC 1 8
#387179 #626638 #A8979A #B09A6B #772200 #C52F0D #123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611
#772200
Flash Line Chart
8/13/2019 Action Sequence Guide
42/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Bar and Line Combination Chart
The bar and line combination chart plots a set of values as bars for each specified series in the given dataset. This cha
will also plot specified series as lines, using the right axis as a range axis for the line series, and the left axis as therange axis for the bars.
Dataset Guidelines
This chart expects its data as a categoricaldataset.
Required Properties
The following properties are required:
chart-typeBarLineChart
bar-series Add one serieselement per series that should be plotted as bars.
actual budget
line-series Add one serieselement per series that should be plotted as lines.
variance
ExampleThe example below contains the full set of additional supported properties with comments on its purpose and valid
values. It is recommended that new users start with this example as a starting place for building your first flash chart.The following chart definition will produce the chart shown directly below it.
BarLineChart
Chart Title Arial
8/13/2019 Action Sequence Guide
43/76Pentaho BI Suite Official Documentation | Action Definition Referenc
18 true
TOTAL COST MARGIN
vertical false false 1 true false 10 #FF0000 #00ff00
#FFffff #ffffff .70
Domain Title Arial 14 false #000000 #ffffff 1
Range Title Arial 14 false #000000 #eaeaea 1 6
40 60
8/13/2019 Action Sequence Guide
44/76| Pentaho BI Suite Official Documentation | Action Definition Reference
#000000 1 6
#0f3765 #880a0f #B09A6B #772200 #C52F0D
#123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611 #772200 #8b2834
Bar/Line Combination Chart
Pie Chart
The pie chart plots a single value per series in a pie shape.
Dataset GuidelinesThe pie chart dataset typically contains two columns. The values in the first column are the series names, and thesecond column contains the data values. If the dataset has multiple rows for each series, the row values will be
aggregated, so that each series appears only once in the pie.
The pie chart also supports the by-row property, meaning that the dataset can be row based. In this case, you mayhave multiple numeric columns in your dataset, whose headers will become the series names, and the data valueswould aggregate across the rows to formulate the series value.
Below is a sample pie dataset:
Department Actuals
Sales 11,168,773
Executive Management 6,299,022
8/13/2019 Action Sequence Guide
45/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Department Actuals
Finance 12,224,220
Human Resource 13,075,463
Marketing and Communication 13,910,753
Product Development 10,644,102
Professional Services 76,317,649
Required Properties
The only property a pie chart requires is the appropriate chart-type.
Example
The example below contains the full set of additional supported properties with comments on its purpose and valid
values. It is recommended that new users start with this example as a starting place for building their first flash chart.The following chart definition will produce the chart shown directly below it.
PieChart
Chart Title
Arial 16 true
#FFFFFF true .90 0
#label# #key# #val#
#880a0f #0f3765 #5d7e33 #795687 #AF3335 #41747e #FDC446
#5d7e33 #1E8AD3 #AA6611 #772200
Pie Chart
8/13/2019 Action Sequence Guide
46/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Area Chart
The area chart plots a set of values on a line per series, and fills the background of the plot area with the series color f
each series in the given dataset. Unlike the ChartComponent (jFreeChart based), the Flash Area chart does not stackthe area.
Dataset Guidelines
This chart expects its data as a categoricaldataset.
Required Properties
The only property an area chart requires is the appropriate chart-type.
Example
The example below contains the full set of additional supported properties with comments on its purpose and validvalues. It is recommended that new users start with this example as a starting place for building their first flash chart.
The following chart definition will produce the chart shown directly below it.
AreaChart
Chart Title Arial
18 true
2.0 hollow 5 .95
#FFFFFF #FFFFFF
8/13/2019 Action Sequence Guide
47/76Pentaho BI Suite Official Documentation | Action Definition Referenc
Domain Title Arial 14 true #000000 #CCCCCC 1
Range Title Arial 14 true #CCCCCC 1 8
#DB0000 #B09A6B #2C00A8 #C52F0D #123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611 #772200
#0f3765 #B09A6B
Flash Area Chart
8/13/2019 Action Sequence Guide
48/76| Pentaho BI Suite Official Documentation | Action Definition Reference
XY Dot Chart
The XY dot chart consists of pairs of values (plotted as points) drawn as marks for each series in the given dataset. Th
chart will have two numeric axes.
Dataset Guidelines
This chart expects its data as an XYdataset.
Required PropertiesThe following properties are required:
chart-type
DotChart
dataset-type
XYSeriesCollection
Example
The example below contains the full set of additional supported properties with comments on its purpose and validvalues. It is recommended that new users start with this example as a starting place for building their first flash chart.
The following chart definition will produce the chart shown directly below it.
DotChart
Chart Title Arial 18 true
XYSeriesCollection 10 {0},{1},{2}
8/13/2019 Action Sequence Guide
49/76Pentaho BI Suite Official Documentation | Action Definition Referenc
#FFFFFF #FFFFFF
Domain Title Arial 14 false
#FFFFFF 1 6
Range Title Arial
14 false #000000 #EAEAEA 1 6
#0f3765
#880a0f #B09A6B #772200 #C52F0D #123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611 #772200 #8b2834
XY Dot Chart
8/13/2019 Action Sequence Guide
50/76| Pentaho BI Suite Official Documentation | Action Definition Reference
Bubble Chart
A bubble chart draws bubbles for each point in a series. The chart expects three values per bubble: the domain
(commonly the X-axis) value, the range (commonly the y-axis) value, and a third value (the Z value) that determines thsize of the bubble to draw around the point.
The size of the bubble is derived from an algorithm that takes the Z value, divides it by the maximum Z value in thedataset, then multiplies that number by the max-bubble-size property value. See the section on required properties
below for more information on the max-bubble-size property.
Dataset GuidelinesThis chart expects its data as an XYZdataset.
Required Properties The following properties are required:
chart-type
BubbleChart
dataset-type
XYZSeriesCollection
max-bubble-size the max-bubble-size property is defaulted to zero, so to see your bubbles, you must set thisproperty! The value should be between 1 and 100, as a percentage of smaller to larger.
90
Example
The example below contains the full set of additional supported properties with comments on its purpose and validvalues. It is recommended that new users start with this example as a starting place for building your first flash chart.The following chart definition will produce the chart shown directly below it.
BubbleChart
Chart Title Arial 18 true
8/13/2019 Action Sequence Guide
51/76Pentaho BI Suite Official Documentation | Action Definition Referenc
XYSeriesCollection {0},{1},{2},{3} $#,###
#FFFFFF #FFFFFF
Domain Title Arial 14 false #FFFFFF 1
6
Range Title Arial 14 false #000000 #EAEAEA
1 6
#0f3765 #880a0f #B09A6B #772200 #C52F0D #123D82 #4A0866 #445500 #FFAA00 #1E8AD3 #AA6611 #772200 #8b2834
Bubble Chart
8/13/2019 Action Sequence Guide
52/76| Pentaho BI Suite Official Documentation | Action Definition Reference
8/13/2019 Action Sequence Guide
53/76Pentaho BI Suite Official Documentation | Editing Existing Action Sequence
Editing Existing Action Sequences
If you used Design Studio to create an action sequence in a previous version of the Pentaho Business Analytics, the
same basic rules and practices apply to later releases. While very little has changed with the core set of components,there are some new plugins available to you like the PojoComponent, the result set burst component, and the Flashchart component.
Reports published by Pentaho Report Designer prior to version 3.5 were in fact machine-generated action
sequences. This has changed as of Report Designer 3.5; published reports are now in the PRPT format, which is an
OpenDocument-compliant file archive. Report Designer has been entirely overhauled in an attempt to eliminate theneed to hand-edit reports with Design Studio, but in previous versions, there were some functions (such as adding use
interactive parameters) that required hand-editing.
If you have already used Design Studio to customize a published report, it is likely that you will continue to have to
follow that process if you want to make changes to the report. Alternatively you could re-create the report in the newReport Designer and republish it to the BI Platform as a PRPT, or you could open the old Report Designer .report
file with the new Report Designer, use its new and more powerful feature set to add in the custom changes that youformerly used Design Studio for, and publish it to the BI Platform.
Report Designer does not yet have equivalent functionality to the SecureFilterComponent, so if you need to put strictlimits on user parameters, you will have to generate the report by hand with Design Studio.
8/13/2019 Action Sequence Guide
54/76| Pentaho BI Suite Official Documentation | Internationalization Guidelines
Internationalization Guidelines
If you need to internationalize your action sequence, you can abstract all of your text content to language-specific
message bundles. For each language you want to translate to, create a properties file with the same name as the actiosequence, plus the two-letter ISO language code. Optionally, you can also append a two-letter ISO country code if youwant to discriminate among different dialects. For instance, using the previously created hello_world.xaction example,
you would internationalize it by creating properties files like these:
hello_world.properties: The default version of the message bundle
hello_world_fr.properties: French language version hello_world_de.properties: German language version
hello_world_fr_CA.properties: French Canadian version of the messages file
It does not matter what the original xaction filename is when it comes to specifying the language and
country code. For instance if the original file were called hello_world_fr_CA.xaction, the resultingproperties file hello_world_fr_CA.propertieswould be the default browser language (usually English), notFrench Canadian. To specify a French Canadian message bundle, you would create a second file called
hello_world_fr_CA_fr_CA.properties.
Each string is replaced by a token (indicated by a percent symbol) in the action sequence, and matches up with contein the properties file. Considering this, the original, unmodified hello_world example created from the Design Studio
template should make more sense now:
Hello World 1 DEBUG
Joe Pentaho The most simple Action Sequence %help rule HelloWorld.png
Hello World Action DEBUG org.pentaho.component.HelloWorldComponent %quote
The helpand quotetags are, by default, abstracted to a properties file. As previously mentioned, Pentaho no longerships Pentaho Business Analytics with properties files for the sample action sequences. So if you want to see this
work, you will have to create a file called hello_world.propertiesin your solution directory (on the same level ashello_world.xaction), and copy the following content to it:
help=Hello World demonstrates the most basic action sequence document. It uses theHello World component.quote=Greetings from the Pentaho BI Platform.
8/13/2019 Action Sequence Guide
55/76Pentaho BI Suite Official Documentation | Internationalization Guideline
Based on the above action sequence and properties file, the output of hello_world.xaction will be:
Hello World. Greetings from the Pentaho BI Platform.
The first part of the message is still pulled in from the global messages.properties file for the BI Platform. This file can
also be changed to internationalize the entirety of the Pentaho User Console and Pentaho Enterprise Console, but thatask is beyond the scope of this guide.
8/13/2019 Action Sequence Guide
56/76| Pentaho BI Suite Official Documentation | Action Sequence Error Handling
Action Sequence Error Handling
When an action sequence fails to execute, it will produce a generic error message. You can bring more specificity to th
error dialogue by pulling in selected details to construct the HTML error page, as explained below.
Customizing Error Output
To customize your error response page, edit the /pentaho/server/biserver-ee/pentaho-solutions/
system/ui/templates/viewActionErrorTemplate.html file and modify it accordingly. Any time an actionsequence fails, a message formatter is applied that will load the template HTML page and replace all the tokens listed
in the next section with the appropriate text. That text may be a label, in which case the source of the text is a messagproperties file, or the text may be actual data pertinent to the error. See the next section for all the tokens that you canuse in your template file.
Note: You are not required to use any tokens at all. The HTML file you use can be as lean or as rich withmessages as you wish; you have full control over the content of the error page.
The default error page is shown here:
%ERROR_HEADING%
%EXCEPTION_MESSAGES_LABEL%%EXCEPTION_MESSAGES% %ACTION_SEQUENCE_LABEL%%ACTION_SEQUENCE% %ACTION_SEQUENCE_EXECUTION_STACK_LABEL%%ACTION_SEQUENCE_EXECUTION_STACK% %LOOP_INDEX_LABEL%%LOOP_INDEX% %EXCEPTION_TIME_LABEL%%EXCEPTION_TIME% %EXCEPTION_TYPE_LABEL%%EXCEPTION_TYPE%
8/13/2019 Action Sequence Guide
57/76
8/13/2019 Action Sequence Guide
58/76| Pentaho BI Suite Official Documentation | Action Sequence Error Handling
Token Description Message bundle key
%INSTANCE_ID% The unique identifier for the runtime
session that executed the actionsequence.
N/A
%ACTION_SEQUENCE_LABEL% Label for the action sequence name.For instance, "Action Sequence:"
RESPONSE_EXCEPTION_ACTION_SEQUENCE_LABEL
%ACTION_SEQUENCE% The name of the xaction file that failed. N/A
%ACTION_SEQUENCE_EXECUTION_STACK_LABEL%
Label for the location of the error. Forinstance, "Execution Stack:"
RESPONSE_EXCEPTION_ACTION_SEQUENCE_EXECUTION_STACK_L
%ACTION_SEQUENCE_EXECUTION_STACK
%
A pointer into the place in the xaction
file's DOM where the error occurred.
N/A
%ACTION_CLASS_LABEL% Label for the component that failed. For
instance, "Action Class:"
RESPONSE_EXCEPTION_ACTION_
%ACTION_CLASS% The name of the component or actionthat failed, as described in the xactionfile.
N/A
%ACTION_DESC_LABEL% Label for the action-type description, if
applicable. For instance, "Action Desc:"
RESPONSE_EXCEPTION_ACTION_
%ACTION_DESC% If the xaction provides an "action-type"
element, that descriptive text goeshere.
N/A
%STACK_TRACE_LABEL% Label for the Java stack trace. For
example, "Stack Trace:"
RESPONSE_EXCEPTION_STACK_T
%STACK_TRACE% The full Java stack trace text (can be
several dozen lines long).
N/A
%EXCEPTION_MESSAGES_LABEL% Label for exception summaries. Forinstance, "Possible Causes:"
RESPONSE_EXCEPTION_MESSAG
%EXCEPTION_MESSAGES% An inverted (root cause first) summaryof the exceptions that occurred for
quicker identification of the rootproblem.
N/A
%SERVER_INFO% The version of the BI Platform andother identifying information.
USER_SERVER_VERSION
8/13/2019 Action Sequence Guide
59/76Pentaho BI Suite Official Documentation | Basic Action Sequence Tips and Tric
Basic Action Sequence Tips and Tricks
This section contains commonly used or frequently requested action sequence tips and tricks. Only the basic, common
tasks are covered here; the next section contains advanced, highly technical action sequence notes.
Emailing a Report
To email a report, you must match the output of SimpleReportingComponent(reportOutputin the example below)
to the EmailComponent's input. The action sequence shown below will execute an SQL query with a user-definedparameter, then use that to generate a report and email it to the specified email address. The PRPT referenced here is
included with the Pentaho sample data, in the /bi-developers/reporting/unified-file-format/ directory.
E-mail Inventory Report in Message
1 ERROR
Kurtis CruzadaSend email with report in the Messagereport
sendto
productline
Classic Cars
reportOutput
inventory.prpt
application/zip
SQLLookupRule
Return list of Product Lines
SampleData
8/13/2019 Action Sequence Guide
60/76| Pentaho BI Suite Official Documentation | Basic Action Sequence Tips and Tricks
SecureFilterComponent
Prompt for Line and Email Address
Select Product LineproductLineListEmail To
SQLLookupRule
SQL Query For Report Data
SampleDatatrue
PRODUCTS.PRODUCTCODE, PRODUCTS.PRODUCTNAME, PRODUCTS.PRODUCTSCALE,
PRODUCTS.PRODUCTDESCRIPTION, PRODUCTS.QUANTITYINSTOCK, PRODUCTS.BUYPRICE, PRODUCTS.MSRFROM PRODUCTS WHERE PRODUCTS.PRODUCTLINE IN ({PREPARE:productline}) ORDER BYPRODUCTLINE ASC, PRODUCTVENDOR ASC, PRODUCTCODE ASC]]>
SimpleReportingComponent
Pentaho Report
EmailComponent
E-Mail HTML
8/13/2019 Action Sequence Guide
61/76Pentaho BI Suite Official Documentation | Basic Action Sequence Tips and Tric
8/13/2019 Action Sequence Guide
62/76| Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tricks
Advanced Action Sequence Tips and Tricks
The tips and tricks in this section apply to rare or specific cases; they highlight unusual and interesting ways to use
action sequences to automate complex tasks.
Using Java Virtual Machine Input Parameters
In an action sequence, you can specify the source of an input parameter as jvmand the Pentaho solution engine
will resolve the parameter from Java's native System.getProperty( )functions. The Pentaho class that retrievesparameters from the Java Virtual Machine properties is org.pentaho.platform.util.JVMParameterProvider.
Here's an example action sequence fragment:
java.version
For common JVM properties, refer to http://java.sun.com/j2se/1.5.0/docs/api/java/lang/System.html#getProperties()
Using Action Sequence Variables in Kettle/PDIIf you have variables in an action sequence that you want to access in a Kettle job or transformation, you must mapthem to command line arguments.
Modifying your ETL process
The first step is to edit your workflow so that accepts command line arguments, as shown in the example KTR belowwhich uses the Get System Infostep to accomplish this. It then passes the parameters to a script step which setsvariables. You would call this KTR as the first part of a job, then go on to other transformations that use the variablevalues, e.g. use ${END_DATE}in a SQL step.
init /
Y N 0.0 0.0 10000 50 50
http://java.sun.com/j2se/1.5.0/docs/api/java/lang/System.html#getProperties()8/13/2019 Action Sequence Guide
63/76Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tric
N Y 50000 Y N 1000
- 2008/10/15 14:28:18.337 Get the period startand end date 16 74 103 32
Change the formatof the start and enddate.Store the start dateas a variable 147 69 105 65
Get System InfoProcess ParametersY Get System Info SystemInfo Y 1 none start_date_str command line argument 1 end_date_str command line argument 2 43 22 Y
8/13/2019 Action Sequence Guide
64/76| Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tricks
Process Parameters ScriptValueMod Y 1 none
Y 0 Script 1 // get the start and end date strings from the previous step// these are formatted like 'Dec 31, 2008'var startDateStr = start_date_str.getString();var endDateStr = end_date_str.getString();
// convert the start and end date strings into Date objectsvar startDate = str2date( startDateStr,"MMM d, yyyy","EN");var endDate = str2date( endDateStr,"MMM d, yyyy","EN");
// convert the start and end date objects into strings formatted like'2008-12-31'
startDateStr = date2str(startDate,"yyyy-MM-dd");endDateStr = date2str(endDate,"yyyy-MM-dd");
var yearStr = endDateStr.substr( 0, 4 );var monthStr = endDateStr.substr( 5, 2 );
var quarterStr = '';if( monthStr == '03' ) {quarterStr = 'Qtr 1';}else if( monthStr == '06' ) {quarterStr = 'Qtr 2';}else if( monthStr == '09' ) {
quarterStr = 'Qtr 3';}else if( monthStr == '12' ) {quarterStr = 'Qtr 4';}
setVariable("START_DATE",startDateStr,"r");setVariable("END_DATE",endDateStr,"r");setVariable("YEAR",yearStr,"r");setVariable("QUARTER",quarterStr,"r");setVariable("DATABASE_NAME","amrs_demo","r"); endDateStr endDateStr String 10 -1 startDateStr startDateStr String 10 -1 170 22 Y
8/13/2019 Action Sequence Guide
65/76Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tric
N
Modifying your action sequence
In the action sequence, you must map the action-inputs to numbered parameters that match what the command linearguments would be, as shown in the snippet below:
start_date end_date
Sharing Result Sets in Action Sequences
In an action sequence, it is possible to use an SQLLookupRule to produce a result-set, which can in turn be used asan input for SecureFilterComponenent. That action-input can have a filter that can be shared among multiple action-
inputs in SecureFilterComponent. If the action-inputs of a SecureFilterComponent share the same filter, and that filter a result-set, you will receive a nullPointerException when running the action sequence.
To solve this, modify the SQLLookupRule's component-definition by setting the value of the element to false, ain this example:
SQLLookupRule Relational
SecureFilterComponent Prompt/Secure Filter
Select payment method for car sales: paymentMethodList Select payment method for bike sales: paymentMethodList
8/13/2019 Action Sequence Guide
66/76| Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tricks
Essentially, if you are using a live result set (live = true), then once you use the result-set, and iterate through it, the
result-set has been used, and it is no longer available. Hence, the NPE. If you use an in-memory result-set (live = falsethe result-set is stored in memory for later use.
Using Security Information In Action SequencesIn addition to providing access to security information within the Web application code, the BI Platform's security systealso provides access to security information within action sequences. That security information then can be used in
JavaScript rules, presented in reporting prompts, provided as input to SQL lookup rules, etc.
A typical action sequence inputs section is defined like this:
someInput
In the above example, the input (called someInput) can be found by looking at the request (HttpServletRequest,PortletRequest, etc.) for a variable called someInput. Then, throughout the rest of the action sequence, specific actioncan reference that input. The Pentaho BI Platform extends the inputs to provide a unique type of input: The security
input. This input presently supports the following input names:
Input Name Type Description
principalName string The name of the currentlyauthenticated user.
principalRoles string-list The roles that the currentlyauthenticated user is a member of.
principalAuthenticated string true if the user is authenticated, false
otherwise.
principalAdministrator string true if the user is considered a PentahAdministrator, false otherwise.
systemRoleNames string-list All the known roles in the system. Usecaution since this list could be quite
long.
systemUserNames string-list All the users known to the system. Us
caution since this list could be quitelong.
The following input section will get the list of the user's roles, and make it available to all the actionsin the action sequence:
principalRoles
8/13/2019 Action Sequence Guide
67/76Pentaho BI Suite Official Documentation | Advanced Action Sequence Tips and Tric
Content Linking in Dashboards
Action sequences used as content in Pentaho Dashboards can broadcast values to other dashboard components in aprocess called, "Content Linking." To enable the dashboard to accept content links from an action sequence, add the
content links to the outputs section.
NA
The actual firing of content link events from your action sequence content is achieved by calling the following
JavaScript:
parent.Dashboards.fireChange('PARAM_NAME',parent.encode_prepare('{PARAM_VALUE}'));
The ChartComponent supports events when values are selected by a user. You can fire a content link by adding the
following to the Chart Definition in the action sequence:
PARAM javascript:parent.Dashboards.fireChange('territory',parent.encode_prepare('{PAurl-template>
_self false ....
8/13/2019 Action Sequence Guide
68/76| Pentaho BI Suite Official Documentation | In-Depth Action Sequence Tutorials
In-Depth Action Sequence Tutorials
This section contains lengthy tutorials that were originally designed as standalone documents.
Creating a Bar Chart Using the Flash Chart Component
This tech tip steps you through the components, tools, and processes for creating a simple chart using the FlashCharting component in the Pentaho BI Platform. To perform this exercise, you must have the following tools:
A text or XML Editor used to create and edit the Chart XML definition. Any standard editor such as Notepad will
do.
Pentaho Design Studio Version 3.0 (or higher) used to create, edit and preview the flash chart action sequence.
It is assumed that you have configured your Design Studio installation to point to the Solution Repository of yourPentaho Server, see Configuring Design Studio.
While the examples in this tech tip provide step-by-step instructions that walk you through the creation of your first Flas
chart, you must have some knowledge and background performing the following tasks:
Editing XML
Building Pentaho Action Sequences including using the Get Data Fromand custom components
Publishing action sequences to a Pentaho BA Server
Overview of the Exercise
In this exercise, you will build a simple Bar Chart to show annual sales by product line using the Steel Wheels sample
data that ships with the Pentaho platform. Building your first Flash Chart involves the following steps:
1. Creating a Chart Definition
2. Creating the Action Sequence
3. Viewing Your Chart in the BI Platform
Configuring Design Studio
Follow the instructions below to point your Penthao Design Studio installation to point to your Solution Repository.
Note: If you have not already done so, install and run the Pentaho BI Server to ensure that it is functional. Alsolog on to the Pentaho User Console and try to display one or two reports in ...pentaho-solutions/steel
wheels/reports.
Important: For the purposes of this document, make sure the BI Server and Design Studio are running on thesame device.
1. Start the Design Studio and click (Close) to exit the Welcome Page.
2. In the menu bar, click New-> Project.
3. In the New Projectwizard, select General-> Projectand click Next.
8/13/2019 Action Sequence Guide
69/76Pentaho BI Suite Official Documentation | In-Depth Action Sequence Tutoria
4. Enter Pentaho Solutionsas the project name and disable Use default location.
5. Click Browseto located your pentaho-solutionsdirectory as shown in the sample image above.
6. Click Finish.
Creating the Chart Definition
The chart definition can be defined in an XML document or passed as a string input directly into your action sequenceIn this example, you will define the chart using an XML document. The chart definition defines the type of chart you
want to create along with properties formatting the chart such as colors, fonts, titles, and axis properties. The quickest
approach to building your first chart is to start with an existing Chart Definition template provided in Using the FlashChart Component, under Bar Chart.
Before you begin the exercise, copy and paste that bar chart definition template from Using the Flash ChartComponent, (under Bar Chart)into a document called sales_barchart.xml.
Customizing the Template
Follow the instructions below to customize the template
1. Change the titleproperty to Annual Sales.
2. Change the is-glassproperty to true.
3. Change the domain-titleproperty to Product Line.
4. Change therange-titleto Total Sales ($).
5. Save your chart definition document into the Pentaho Solution Repository in the following location: ...\pentahosolutions\steel-wheels\charts
You should now have a Chart Definition document that looks like this:
BarChart
Annual Sales Arial 18
true
vertical false false true false 10
8/13/2019 Action Sequence Guide
70/76| Pentaho BI Suite Official Documentation | In-Depth Action Sequence Tutorials
#000000 #000000
#FFFFFF #FFFFFF .70
Product Line Arial 14 false #000000
#FFFFFF
Total Sales ($) Arial 14 false #000000
#EAEAEA 6
#0f3765 #880a0f #B09A6B #772200 #C52F0D #12
Recommended