{section}
{column:width=50%}
*Petals View* *Configuration and Installation*
{column}
{column:width=50%}
{panel}{toc}{panel}
{column}
{section}

h1. Introduction

h2. Overview

Petals View is a webapplication dedicated to Petals ESB flows monitoring.

h3. Installation in a nutshell:

* download these JBI components: petals-se-notification-X.zip and petals-se-kpi-X.zip;

* download the petals view's war (petals-view-ui-X.war);

* create all the service assemblies for the KPI. You need to get the infos you want (with prior installation and configuration of related components and services assemblies).

h3. How does it work?

* You configure a component so that when it is installed, it will register in petals-se-notification base: "I can send notifications to you".

* Upon reception, petals-se-notification forwards these notifications to petals-se-kpi (configured with its own services assemblies -- sa-kpi).

* What is a sa-kpi? It's a set of filters that will select specific information among the whole flow data. Whenever an exchange fits with a sa-kpi, a notification (with selected data only) is send from the component and will be saved in a relational database. This database has to be shared between KPI Service Engine and Petals View.

* Petals View then connects to this database to retrieve informations.

* Messages are saved into the database in a "raw" format. Petals View will give them meaning by naming and organizing them in a human-readable way.



This diagram presents monitoring-related relationships between Petals ESB, various components, SE-notification, SE-KPI, configured sa-kpi and Petals View.

!http://doc.petalslink.com/download/attachments/4194419/worddavdf7cef4d8fe2c89965f69ae681bc7de0.png|height=318,width=718!\\

This documentation details Petals View installation in 5 steps:
* First one is to set up the persistent environment, and configuration file for database access.

* Second one is to add to some configurations to make the persistent environment common between Petals View and SE-kpi component.

* Third one is to set up the notification environment, in other words configure the components so that they register in petals-se-notification.

* Fourth one is, through practical examples, to create the sa-kpi which will filter notification (select only the ones we really want to know about).

* Fifth one is to configure the referential in Petals View, to give meaning to the raw data stored in the database.



h3. Servers tested

* Tomcat: versions: 5.5.27, 6.0.29

* JBoss: versions: 4.0.5.GA, 4.2.3.GA, 5.0.1.GA, 5.1.0.GA

* Glassfish: version 3

* Jonas: version 5.1.5



h3. Databases tested

* H2

* MySQL: version: 5.0

* PostgreSQL: version:8.3

* Oracle: version 10g



h1. First stage: setting up persistent environment

{note}The default configuration uses an H2 database that we don't recommend to use in a production environment.{note}



If you don't have any MySQL (or PostgreSQL) database server up and ready yet, download and install it following your system's procedure.



* Create a database for Petals View:

example: petalview



* Create a user with all rights granted to this database

example: user: view

pwd: view



* Create the database access configuration file. The name of this file is mandatory:

*petals-view.properties*



This file will hold the following informations.

All database tables will be automatically created at Petals View's first launch.



An exemple *petals-view.properties* is provided here with H2 datasource implementation (and MySQL and PostgreSQL examples):



{code}
\###########

### Petals View properties file

\############

h3. petals-se-kpi component

* Download the KPI component (petals-se-kip.zip)

* Browse to petals-se-kip.zip/META-INF

* Open the jbi.xml file.

* On the line <petals-se-kpi:hibernateURL>: fill in the path of the file petals-view.properties (that you created in Stage 1).

example:

If you use MySQL or Oracle database, You need to copy mysql-connector-java-5.1.x.jar or oracle-jdbc-10g.jar in your petals-se-kpi component with the others dependencies.

Save the changes.

h3. PetalsView.war

* Download Petals View (PetalsView.war)
* Browse to PetalsView.war/WEB-INF/spring
* Open the file petals-view-hibernate.xml
* Change the hibernate dialect and configure others informations (if necessary):

{code}
<property name="hibernateProperties">

<props>
<!-- #################################
Here, the hibernate dialect must be defined.
for MySQL: com.ebmwebsourcing.petalsview.persistence.util.MySqlInnoDBDialect
for PostgreSQL: org.hibernate.dialect.PostgreSQLDialect
for H2: org.hibernate.dialect.H2Dialect
for Oracle 10g: org.hibernate.dialect.Oracle10gDialect
################################# -->
<prop key="hibernate.dialect">
org.hibernate.dialect.H2Dialect
</prop>

<!-- #################################
Here, the hibernate hbm2dll can be defined:
create (create the sql schema)
update (update the sql schema)
validate (check that the sql schema is right)
################################# -->

<prop key="hibernate.hbm2ddl.auto">
update
</prop>

<!-- #################################
Here, the sql queries logs can be defined
true: the sql queries appear in logs
false: the sql queries don't appear in logs
################################# -->
<prop key="hibernate.show_sql">
false
</prop>
</props>
</property>

{code}

* Save the changes.
* If you use MySQL database or Oracle database, you need to copy mysql-connector-java-5.1.x.jar (PetalsView does not work with mysql-connector.java-5.0.x) or oracle-jdbc-10g.jar in your server repository.
* Define the jndi name to access database in your server: it must be named PetalsViewDataSource (for JBoss, Jonas and WebLogic) or jdbc/PetalsViewDataSource (for Glassfish).

If you use Tomcat, you must change the file PetalsView.war/META-INF/context.xml and configure here your informations. An exemple context.xml is provided here with H2 datasource configuration uncommented and MySQL, PostgreSQL and Oracle configuration commented:

By default, the datasource access is provided by JNDI.
Here, the database must be specified (its driverClass, jdbcUrl,user, password),
the c3p0 properties can be modified (maxPoolSize, minPoolSize, acquireIncrement).
#################################
-->

If you use WebLogic, you must delete comments in the web.xml file (in PetalsView.war/WEB-INF/ repository) and package PetalsView.war in .ear (with in ear/META-INF repository weblogic-application.xml file).

An exemple weblogic-application.xml is provided here:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<weblogic-application>
<prefer-application-packages>
<package-name>antlr.*</package-name>
<package-name>javax.persistence.*</package-name>
</prefer-application-packages>
</weblogic-application>
{code}
{multi-excerpt}

{multi-excerpt:name=Configuring and setting up notification environment}
h1. Stage 3: Configuring and setting up notification environment

* Setting up Petals ESB and its components:

* Download and install Petals ESB

* Install the SE-Notification component

{warning}{color:#ff0000}You HAVE to install this component BEFORE ANY OTHER, otherwise there could be configuration conflict preventing notifications to work.{color}{warning}

* Install all components that you don't need to emit notifications

* Install the SE-KPI component (petals-se-kpi.zip) using the configuration created at Stage 2

* Configuring the components which will emit notifications: follow this procedure for each one of them:

** Browse to yourcomponent.zip/META-INF/

** Open the jbi.xml file

** Find the following line and set up its value to "true" and save it :



{code:lang=xml}
<petalsCDK:notifications xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:jbi="http://java.sun.com/xml/ns/jbi"

xmlns:soap="http://petals.ow2.org/components/soap/version-x"

xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-x">

true

</petalsCDK:notifications>

{code}



* Install the component in Petals ESB

* Install all Services Assemblies you want to use with these components.
{multi-excerpt}



{multi-excerpt:name=Creating your SA-KPI.zip and corresponding SU-KPI.zip}



h1. Stage 4: Creating your SA-KPI.zip and corresponding SU-KPI.zip



You can use Petals Studio to create the SA-KPI needed for notification configuration. For this guide, we'll use an example of SA/SU batch to show you how to create them.

A SA-KPI is composed of: a META-INF folder which will contain jbi.xml file and the su-kpi.zip.

example of a jbi.xml file from a sa-kpi.zip :



{code:lang=xml}
<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi">

<service-assembly>

<identification>

<name>sa-in</name>

<description>SA in.</description>

</identification>

<service-unit>

<identification>

<name>su-notif-in</name>

<description>su in description.</description>

</identification>

<target>

<artifacts-zip>su-notif-in.zip</artifacts-zip>

<component-name>petals-se-kpi</component-name>

</target>

</service-unit>

</service-assembly>

</jbi>

{code}



A SU-KPI is composed of: a META-INF folder containing SU's jbi.xml file and a special file, modelNotification.xls

example of jbi.xml file of a SU:

{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>

<\!--JBI descriptor for the PEtALS' "petals-se-kpi" component (WS-Notification).

Originally created for the version 1.0-SNAPSHOT of the component. \-->



<jbi:jbi version="1.0" xmlns:notification="http://petals.ow2.org/petals-se-notification"

xmlns:wsn-br="http://docs.oasis-open.org/wsn/br-2"

xmlns:kpi="http://petals.ow2.org/petals-se-kpi"

xmlns:jbi="http://java.sun.com/xml/ns/jbi"

xmlns:petalsCDK="http://petals.ow2.org/components/extensions/version-5"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:st="http://www.ebmwebsourcing.com/wsnotification/specificTypes">



<\!-\- Import a Service into PEtALS or Expose a PEtALS Service => use a BC. \-->

<jbi:services binding-component="false">



<\!-\- Expose a PEtALS Service => consumes a Service. \-->

<jbi:consumes

interface-name="wsn-br:NotificationBroker"

service-name="notification:NotificationBrokerService"

endpoint-name="NotificationBrokerServiceEndpoint">



<\!-\- CDK specific fields \-->

<petalsCDK:operation>Subscribe</petalsCDK:operation>

<petalsCDK:mep>InOut</petalsCDK:mep>

<\!-\- Component specific elements \-->

<\!-\- Subscription to process on init : \-->

<kpi:TopicExpressionDialect>[http://docs.oasis-open.org/wsn/t1/TopicExpression/Full]</kpi:TopicExpressionDialect>

<kpi:TopicExpressionNamespace>[http://petals.ow2.org/topic]</kpi:TopicExpressionNamespace>

<kpi:TopicExpressionPrefix>petals</kpi:TopicExpressionPrefix>

<kpi:TopicExpressionContent>petals:component/cdk/producer/in\[\]</kpi:TopicExpressionContent>



<kpi:MessageContentXpath>boolean(/\*[local-name()='publishBusinessEntity'|local-name()='publishBusinessEntity'])</kpi:MessageContentXpath>

<kpi:MessageContentXpathDialect>[http://www.w3.org/TR/1999/REC-xpath-19991116]</kpi:MessageContentXpathDialect>

<kpi:MessageContentSOADialect>[http://www.ebmwebsourcing.com/wsnotification/soaparameter]</kpi:MessageContentSOADialect>



<kpi:MessageContentSOAInterfaceNamespace>[http://org.ow2.petals/demo/travelagency/agency/]</kpi:MessageContentSOAInterfaceNamespace>

<kpi:MessageContentSOAInterfaceName>travelAgency</kpi:MessageContentSOAInterfaceName>

<kpi:MessageContentSOAServiceNamespace>[http://org.ow2.petals/demo/travelagency/agency/]</kpi:MessageContentSOAServiceNamespace>

<kpi:MessageContentSOAServiceName>travelAgencyService</kpi:MessageContentSOAServiceName>



<kpi:TransformPolicy>/modelNotification.xsl</kpi:TransformPolicy>



<kpi:ContextPolicyCorrelationId>true</kpi:ContextPolicyCorrelationId>

<kpi:ContextPolicyInterface>true</kpi:ContextPolicyInterface>

<kpi:ContextPolicyEndpoint>true</kpi:ContextPolicyEndpoint>

<kpi:ContextPolicyMeuuid>true</kpi:ContextPolicyMeuuid>

<kpi:ContextPolicyNotifDate>true</kpi:ContextPolicyNotifDate>

<kpi:ContextPolicyService>true</kpi:ContextPolicyService>

<kpi:ContextPolicyStatus>true</kpi:ContextPolicyStatus>



<kpi:ProcessPolicyAction>create</kpi:ProcessPolicyAction>

</jbi:consumes>

</jbi:services>

</jbi:jbi>{code}



* The text in red defines for which state you configure the present SU: in -- out -- status \--fault.

* Texts in blue define the filtering you want to apply to notifications:

<kpi:MessageContentXpath>boolean(/*\[local-name()={color:#23b8dc}'{color}{color:#0084d1}publishBusinessEntity'{color}\])</kpi:MessageContentXpath> :

** here you can apply filtering criteria on content fields, as long as they are present in the messages. If you don't want any content filtering, set the value to "true".

Example : <kpi:MessageContentXpath>boolean({color:#0084d1}true(){color})</kpi:MessageContentXpath>

** You can filter directly on service's endpoint or interface (these fields are not mandatory). You can also filter on endpoint:

<kpi:MessageContentSOAInterfaceNamespace>{color:#0084d1}[http://org.ow2.petals/demo/travelagency/agency/]{color}</kpi:MessageContentSOAInterfaceNamespace>

<kpi:MessageContentSOAInterfaceName>{color:#0084d1}travelAgency{color}</kpi:MessageContentSOAInterfaceName>

<kpi:MessageContentSOAServiceNamespace>{color:#0084d1}[http://org.ow2.petals/demo/travelagency/agency/]{color}</kpi:MessageContentSOAServiceNamespace>

<kpi:MessageContentSOAServiceName>{color:#0084d1}travelAgencyService{color}</kpi:MessageContentSOAServiceName>

<kpi:MessageContentSOAEndpoint>{color:#0084d1}travelAgencyEndpoint{color}</kpi:MessageContentSOAEndpoint>



* Text in orange defines the name of the file which will be used as a model for the notifications.



example of the modelNotification.xls file:

{code}
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' >

<xsl:output method="xml" indent="yes"/>

<xsl:template match="/">

<wsnebm:NotifyContent xmlns:wsnebm="http://www.ebmwebsourcing.com/WS-BaseNotification/NotifyContent"

processType="1" xmlns:age="\[http://org.ow2.petals/demo/travelagency/agency/">

<wsnebm:params>

<wsnebm:param><xsl:value-of select="//age:lastname/text()"/></wsnebm:param>

<wsnebm:param><xsl:value-of select="//email/text()"/></wsnebm:param>

</wsnebm:params>

</wsnebm:NotifyContent>

</xsl:template>

</xsl:stylesheet>

{code}



processType: here you have to type the same integer value as in Petals View's referential for this type of flows.

xmlns:age="[http://org.ow2.petals/demo/travelagency/agency/|http://org.ow2.petals/demo/travelagency/agency/]": here, you define a parameter

{code}
<wsnebm:params>

<wsnebm:param><xsl:value-of select="//age:lastname/text()"/></wsnebm:param>

<wsnebm:param><xsl:value-of select="//email/text()"/></wsnebm:param>

</wsnebm:params>

{code}

Here you define the parameters you want to attach to your step.
{multi-excerpt}

* Deploy Petals View's war in an application server

* Connect to Petals View through any web browser ([http://server/PetalsView]\|http://server/PetalsView).

* To connect for the first time, use the default admin user (login/password: admin/admin)

For more details on configuring a referential in Petals View, check our PetalsView-UserGuide.pdf

Click on "Referential Management" in left menu panel.

h2. If you already launched at least one flow in PetalsESB:

* Click on the "Unknown" flow type:

** its type is automatically filled in and cannot be changed

** define its human-readable name.

* Click on "CREATE"'

** You'll arrive directly on the flow type's edition page. Normally, all steps composing this flow should appear together with their service/interface name.



To configure each one and any of the unknown steps:

* Click on an "unknown" step:

** Functional (human-readable) name: give it the name of your choice

** Interface name / Service name: these are automatically filled in with the right info

** Start flow? and End flow? checkboxes are used to define whether this step is first and/or last one of the flow.

** Success message: the message which will be displayed when step is in "Success" status.

** Error message: the message which will be displayed when your step is in "Error" status.

* Click on "Submit" to save changes and come back on flow type's edition screen.



You can notice that now, the step you defined is not shown on "Unknown tables" anymore, but instead in the referential table.

Click on any defined step to access its edition screen.

To configure a parameter {{in}}:

* In functional fields click on "ADD" and fill in the following informations:

** Index: relates to its rank in notification, will be automatically incremented.

** Name: give it the human-readable name of your choice

** Global: if you check it, this parameter will not only be visible in step view, but also in global view of any flow of this flow type.

* Click on "Submit" to save changes and come back on step's edition screen.



Repeat the procedure to configure any and all steps and parameters in.



To configure a parameter {{out}} or {{fault}}:


* In functional fields click on "ADD" and fill in the following informations:

** Name: give it the human-readable name of your choice

* Click on "Submit" to save changes and come back on step's edition screen.

Repeat the procedure to configure any and all steps and parameters out or fault.


h2. If you didn't launch any flow in Petals ESB yet:

* Click on ''ADD'' button

** Give a numerical value type (this value corresponds to ProcessType you define in your model notification)

** define its human-readable name.

* Click on "CREATE" to save it and go to edition screen of the flow type's referential you just created. Here you can add steps.



* Click on "Add" to add and configure steps to your referential (fields in yellow are mandatory)

** Functional name: give it the name of your choice

example: Travel agency

** Interface name: fill in the qualified name of your interface

example: \{\[http://org.ow2.petals/demo/travelagency/agency/\]} travelAgency

** Service name: fill in the qualified name of your Service

example: \{\[http://org.ow2.petals/demo/travelagency/agency\]} travelAgencyService

** Start flow? and End flow? checkboxes are used to define whether this step is first and/or last one of the flow.

** Success message: the message which will be displayed when step is in "Success" status.

** Error message: the message which will be displayed when your step is in "Error" status.

* Click on "Submit" to save and go to the edition screen of the step you just created. You can then configure parameters.

* Click on "Add" to add parameters to your step.

** Index: relates to its rank in notification, will be automatically incremented.

** Name: give it the human-readable name of your choice

** Global: if checked, this parameter will be visible in step view AND in global view of any flow of this flow type.

* Click on "Submit" to save the changes.



Repeat the procedure to configure all steps and parameters you want to be shown in Petals View.
{multi-excerpt}



h1. Known problems





h2. Unable to start the application under tomcat 6



Under some Operating System (checked on Red Hat Entreprise 5), by default, the Tomcat Security Manager doesn't allow the access to classes with a restricted user. So the application doesn't start. So you must add this lines into the catalina.policy file (you can found it into the conf directory of your tomcat installation):

{code}
grant codeBase "file:${catalina.home}/webapps/petals-view-ui-X/WEB-INF/classes/-" { };

{code}

Then you restart the tomcat server, and now the application may start.



h2. Exception opening port H2 TCP Server



If you use the SE KPI with its default configuration (using H2 database - File mode and server enabled), on RedHat like distribution (RHEL, Federo, CentOS) you can get the following error:



{code}
Could not obtain connection to query metadata org.apache.commons.dbcp.SQLNestedException: Cannot create PoolableConnectionFactory (Exception opening port H2 TCP Server (tcp://localhost:40374) (port may be in use), cause: timeout [90061-114])

{code}

This error is due to the default classic security policy of the previously listed operating systems that allow only to use port lower than 8900.



Two solutions:

# break this default security configuration: more performant, less secure

# using the H2 database file mode and server disabled: more secure, less performant. To do this replace into the configuration the line 'jdbc.url = jdbc:h2:~/test/db/petalsview;AUTO_SERVER=TRUE' by the line 'jdbc.url = jdbc:h2:[file:~/test/db/petalsview]'

# replace the H2 database, that is not recommended, by another database engine.

h2. Petal View not deploy in JBoss 6

PetalsView does not run with JBoss Application Server 6 because of incompatible versions of CXF. JAS provides a version of CXF that can't be used by PetalsView, and the classloader isolation of JBoss does not work correctly.