{section}
{column}
h1. Summary
This tutorial explains how to create KPI configurations for Petals View.
\\
These KPI configurations are deployed in Petals and target the [Petals KPI component|petalscomponents:Petals-SE-KPI].
At runtime, these configurations act as probes that collect and filter information from the bus and its services.
The collected data are stored in a database and displayed by Petals View.
\\
Technically, this tutorial shows the creation of a service-unit for the Petals-SE-KPI component in *consumes* mode.
{info}
*Level:* Intermediate-Advanced
*Estimated time:* from 2 to 20 minutes, depending on your filters
*Expected skills:* be able to write XPath expressions
{info}
{column}
{column:width=350px}
{panel}{toc}{panel}
{column}
{section}
h1. Creating a new KPI configuration (SOA)
h2. Creating the projects
The SOA dialect means the KPI filter is based on service identifiers.
Click *File > New* and select *KPI Configuration* under the *Petals Attic* category.
!petals-studio-tuto-consumes-kpi-1.jpg!
\\
On the first page, select *SOA Dialect* in the *Watching Filter* list.
Specify a process name. A project name is generated automatically.
The project name is the name of a Service Assembly project.
!petals-studio-tuto-consumes-kpi-2.jpg!
Click *Next*.
\\
On the next page, you are asked to select the services that will define the filters.
Click *Add* and select services from the [Petals Services view (provided it was populated)|Getting familiar with the Petals Services view].
!petals-studio-tuto-consumes-kpi-3.jpg!
\\
You can add several services.
!petals-studio-tuto-consumes-kpi-4.jpg!
Once you have all the required services for this filter, click *Next*.
\\
On the next page, you are asked to select the flows to watch for each selected service.
These flows represent the different kinds of Petals messages:
* *IN* represents the input messages or requests.
* *OUT* represents the output messages, or responses.
* *FAULT* represents faults, i.e. a response that indicates an exception occurred during the service processing.
* *STATUS* represents acknowledgements (ACK). They are used to end an exchange between a service consumer and a service.
!petals-studio-tuto-consumes-kpi-5.jpg!
\\
Each flow will result in a Service-Unit project for the KPI component.
Do not forget to specify the *Process Type* value.
Make it randomly generated only in demonstrations or tests.
Click *Finish*.
h2. Checking the result
The result is a set of projects:
* There is a Service Assembly project...
* ... and a set of Service-Unit projects.
!petals-studio-tuto-consumes-kpi-6.jpg!
\\
Each service-unit contains a jbi.xml and a XSL style sheet.
The jbi.xml references the target service.
{code:lang=xml}
...
<!-- Use the SOA dialect, or the XPath dialect, or both of them -->
<kpi:MessageContentSOADialect>http://www.ebmwebsourcing.com/wsnotification/soaparameter</kpi:MessageContentSOADialect>
<kpi:MessageContentSOAInterfaceNamespace>http://petals.ow2.org/components/xslt/version-2</kpi:MessageContentSOAInterfaceNamespace>
<kpi:MessageContentSOAInterfaceName>XsltInterface</kpi:MessageContentSOAInterfaceName>
<kpi:MessageContentSOAServiceNamespace>http://petals.ow2.org/components/xslt/version-2</kpi:MessageContentSOAServiceNamespace>
<kpi:MessageContentSOAServiceName>fgh</kpi:MessageContentSOAServiceName>
<kpi:MessageContentSOAEndpoint>fghEndpoint</kpi:MessageContentSOAEndpoint>
...
{code}
\\
And the XSL style sheet contains XPath expressions used to filter elements from the messages sent to the target service.
{code:lang=xml}
<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="863656392">
<wsnebm:params>
<!-- Add filtering parameters -->
<!--
<wsnebm:param><xsl:value-of select="//*[local-name()='include']/text()"/></wsnebm:param>
-->
</wsnebm:params>
</wsnebm:NotifyContent>
</xsl:template>
</xsl:stylesheet>
{code}
h1. Creating a new KPI configuration (XPath)
h2. Creating the projects
The XPath dialect means the KPI filter is based on all the messages from the bus that match the XPath constraints.
Click *File > New* and select *KPI Configuration* under the *Petals* category.
!petals-studio-tuto-consumes-kpi-1.jpg!
\\
On the first page, select *XPath Dialect* in the *Watching Filter* list.
Specify a process name. A project name is generated automatically.
The project name is the name of a Service Assembly project.
!petals-studio-tuto-consumes-kpi-7.jpg!
Click *Next*.
\\
On the next page, you are asked to define the various XPath expressions for the flows to watch.
These flows represent the different kinds of Petals messages:
* *IN* represents the input messages or requests.
* *OUT* represents the output messages, or responses.
* *FAULT* represents faults, i.e. a response that indicates an exception occurred during the service processing.
* *STATUS* represents acknowledgements (ACK). They are used to end an exchange between a service consumer and a service.
!petals-studio-tuto-consumes-kpi-8.jpg!
Once it is done, click *Next*.
\\
On the next page, you are asked to select the flows to watch for each selected service.
It might be redundant with the previous page, but it not. The onyl constraint is that any configuration to create must have a defined XPath expression.
!petals-studio-tuto-consumes-kpi-9.jpg!
\\
Each flow will result in a Service-Unit project for the KPI component.
Do not forget to specify the *Process Type* value.
Make it randomly generated only in demonstrations or tests.
Click *Finish*.
h2. Checking the result
The result is a set of projects:
* There is a Service Assembly project...
* ... and a set of Service-Unit projects.
!petals-studio-tuto-consumes-kpi-10.jpg!
\\
Each service-unit contains a jbi.xml and a XSL style sheet.
The jbi.xml references the target service.
{code:lang=xml}
...
<!-- Use the SOA dialect, or the XPath dialect, or both of them -->
<kpi:MessageContentXpathDialect>http://www.w3.org/TR/1999/RECxpath19991116</kpi:MessageContentXpathDialect>
<kpi:MessageContentXpath>//*</kpi:MessageContentXpath>
...
{code}
\\
And the XSL style sheet contains XPath expressions used to filter elements from the filtered messages.
{code:lang=xml}
<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="813728661">
<wsnebm:params>
<!-- Add filtering parameters -->
<!--
<wsnebm:param><xsl:value-of select="//*[local-name()='include']/text()"/></wsnebm:param>
-->
</wsnebm:params>
</wsnebm:NotifyContent>
</xsl:template>
</xsl:stylesheet>
{code}
h1. Creating a new KPI configuration (mix)
h2. Why a mix of the approaches?
The KPI configurations constitute a set of disparate pieces.
The way these pieces must be assembled and ordered, is called a _process_ and is managed by Petals View.
A process defines a set of steps, each step being defined by a service-unit for the Petals KPI configuration.
\\
{info}
The studio assumes a process is defined by a Service Assembly project for the [Petals KPI component|petalsesb:Petals-SE-KPI].
It also assumes this project embeds all the service-units for the steps that constitute this process.
{info}
\\
As a user, you might want to have some steps using the SOA dialect and some others using the XPath dialect.
The studio supports and provides utilities to help you in this mix.
h2. A two-step construction
First, create KPI configurations using one of the two dialects.
It results in a Service Assembly project and one or several Service-Unit projects.
\\
Then, launch the KPI Configuration wizard again.
Select the second dialect in the *Watching filter* list.
On the first page, you may have noticed the *Process name* has a drop-down list, which lists processes that were created previously.
!petals-studio-tuto-consumes-kpi-11.jpg!
\\
Select the last created process. The project name is updated and an error indicates the project already exists.
To remove this error, activate *Append to an existing process*.
The next configurations will not be added to a new Service Assembly project, but appended to the existing one.
!petals-studio-tuto-consumes-kpi-12.jpg!
\\
Go on with the wizard as described in the previous sections.
When the wizard completes, it creates the new KPI configurations and update the Service-Assembly project (jbi.xml and pom.xml).
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the created artifacts can be edited using the JBI and XSL editors.
The Service Assembly project can be [packaged like any other Service Assembly project|Working with Service Assembly projects#Export for Petals].
h2. Deployment
The deployment of the created service assembly can be achieved with the Petals web console.
Or you can do it by dropping the service assembly in the install directory of your Petals installation.
This second option should only be used in development steps.
\\
Be careful, the [Petals KPI component|petalscomponents:Petals-SE-KPI] must be configured first.
This steps is described in details in the \[install guide of Petals View\|petalsview:InstallGuide\].
{column}
h1. Summary
This tutorial explains how to create KPI configurations for Petals View.
\\
These KPI configurations are deployed in Petals and target the [Petals KPI component|petalscomponents:Petals-SE-KPI].
At runtime, these configurations act as probes that collect and filter information from the bus and its services.
The collected data are stored in a database and displayed by Petals View.
\\
Technically, this tutorial shows the creation of a service-unit for the Petals-SE-KPI component in *consumes* mode.
{info}
*Level:* Intermediate-Advanced
*Estimated time:* from 2 to 20 minutes, depending on your filters
*Expected skills:* be able to write XPath expressions
{info}
{column}
{column:width=350px}
{panel}{toc}{panel}
{column}
{section}
h1. Creating a new KPI configuration (SOA)
h2. Creating the projects
The SOA dialect means the KPI filter is based on service identifiers.
Click *File > New* and select *KPI Configuration* under the *Petals Attic* category.
!petals-studio-tuto-consumes-kpi-1.jpg!
\\
On the first page, select *SOA Dialect* in the *Watching Filter* list.
Specify a process name. A project name is generated automatically.
The project name is the name of a Service Assembly project.
!petals-studio-tuto-consumes-kpi-2.jpg!
Click *Next*.
\\
On the next page, you are asked to select the services that will define the filters.
Click *Add* and select services from the [Petals Services view (provided it was populated)|Getting familiar with the Petals Services view].
!petals-studio-tuto-consumes-kpi-3.jpg!
\\
You can add several services.
!petals-studio-tuto-consumes-kpi-4.jpg!
Once you have all the required services for this filter, click *Next*.
\\
On the next page, you are asked to select the flows to watch for each selected service.
These flows represent the different kinds of Petals messages:
* *IN* represents the input messages or requests.
* *OUT* represents the output messages, or responses.
* *FAULT* represents faults, i.e. a response that indicates an exception occurred during the service processing.
* *STATUS* represents acknowledgements (ACK). They are used to end an exchange between a service consumer and a service.
!petals-studio-tuto-consumes-kpi-5.jpg!
\\
Each flow will result in a Service-Unit project for the KPI component.
Do not forget to specify the *Process Type* value.
Make it randomly generated only in demonstrations or tests.
Click *Finish*.
h2. Checking the result
The result is a set of projects:
* There is a Service Assembly project...
* ... and a set of Service-Unit projects.
!petals-studio-tuto-consumes-kpi-6.jpg!
\\
Each service-unit contains a jbi.xml and a XSL style sheet.
The jbi.xml references the target service.
{code:lang=xml}
...
<!-- Use the SOA dialect, or the XPath dialect, or both of them -->
<kpi:MessageContentSOADialect>http://www.ebmwebsourcing.com/wsnotification/soaparameter</kpi:MessageContentSOADialect>
<kpi:MessageContentSOAInterfaceNamespace>http://petals.ow2.org/components/xslt/version-2</kpi:MessageContentSOAInterfaceNamespace>
<kpi:MessageContentSOAInterfaceName>XsltInterface</kpi:MessageContentSOAInterfaceName>
<kpi:MessageContentSOAServiceNamespace>http://petals.ow2.org/components/xslt/version-2</kpi:MessageContentSOAServiceNamespace>
<kpi:MessageContentSOAServiceName>fgh</kpi:MessageContentSOAServiceName>
<kpi:MessageContentSOAEndpoint>fghEndpoint</kpi:MessageContentSOAEndpoint>
...
{code}
\\
And the XSL style sheet contains XPath expressions used to filter elements from the messages sent to the target service.
{code:lang=xml}
<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="863656392">
<wsnebm:params>
<!-- Add filtering parameters -->
<!--
<wsnebm:param><xsl:value-of select="//*[local-name()='include']/text()"/></wsnebm:param>
-->
</wsnebm:params>
</wsnebm:NotifyContent>
</xsl:template>
</xsl:stylesheet>
{code}
h1. Creating a new KPI configuration (XPath)
h2. Creating the projects
The XPath dialect means the KPI filter is based on all the messages from the bus that match the XPath constraints.
Click *File > New* and select *KPI Configuration* under the *Petals* category.
!petals-studio-tuto-consumes-kpi-1.jpg!
\\
On the first page, select *XPath Dialect* in the *Watching Filter* list.
Specify a process name. A project name is generated automatically.
The project name is the name of a Service Assembly project.
!petals-studio-tuto-consumes-kpi-7.jpg!
Click *Next*.
\\
On the next page, you are asked to define the various XPath expressions for the flows to watch.
These flows represent the different kinds of Petals messages:
* *IN* represents the input messages or requests.
* *OUT* represents the output messages, or responses.
* *FAULT* represents faults, i.e. a response that indicates an exception occurred during the service processing.
* *STATUS* represents acknowledgements (ACK). They are used to end an exchange between a service consumer and a service.
!petals-studio-tuto-consumes-kpi-8.jpg!
Once it is done, click *Next*.
\\
On the next page, you are asked to select the flows to watch for each selected service.
It might be redundant with the previous page, but it not. The onyl constraint is that any configuration to create must have a defined XPath expression.
!petals-studio-tuto-consumes-kpi-9.jpg!
\\
Each flow will result in a Service-Unit project for the KPI component.
Do not forget to specify the *Process Type* value.
Make it randomly generated only in demonstrations or tests.
Click *Finish*.
h2. Checking the result
The result is a set of projects:
* There is a Service Assembly project...
* ... and a set of Service-Unit projects.
!petals-studio-tuto-consumes-kpi-10.jpg!
\\
Each service-unit contains a jbi.xml and a XSL style sheet.
The jbi.xml references the target service.
{code:lang=xml}
...
<!-- Use the SOA dialect, or the XPath dialect, or both of them -->
<kpi:MessageContentXpathDialect>http://www.w3.org/TR/1999/RECxpath19991116</kpi:MessageContentXpathDialect>
<kpi:MessageContentXpath>//*</kpi:MessageContentXpath>
...
{code}
\\
And the XSL style sheet contains XPath expressions used to filter elements from the filtered messages.
{code:lang=xml}
<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="813728661">
<wsnebm:params>
<!-- Add filtering parameters -->
<!--
<wsnebm:param><xsl:value-of select="//*[local-name()='include']/text()"/></wsnebm:param>
-->
</wsnebm:params>
</wsnebm:NotifyContent>
</xsl:template>
</xsl:stylesheet>
{code}
h1. Creating a new KPI configuration (mix)
h2. Why a mix of the approaches?
The KPI configurations constitute a set of disparate pieces.
The way these pieces must be assembled and ordered, is called a _process_ and is managed by Petals View.
A process defines a set of steps, each step being defined by a service-unit for the Petals KPI configuration.
\\
{info}
The studio assumes a process is defined by a Service Assembly project for the [Petals KPI component|petalsesb:Petals-SE-KPI].
It also assumes this project embeds all the service-units for the steps that constitute this process.
{info}
\\
As a user, you might want to have some steps using the SOA dialect and some others using the XPath dialect.
The studio supports and provides utilities to help you in this mix.
h2. A two-step construction
First, create KPI configurations using one of the two dialects.
It results in a Service Assembly project and one or several Service-Unit projects.
\\
Then, launch the KPI Configuration wizard again.
Select the second dialect in the *Watching filter* list.
On the first page, you may have noticed the *Process name* has a drop-down list, which lists processes that were created previously.
!petals-studio-tuto-consumes-kpi-11.jpg!
\\
Select the last created process. The project name is updated and an error indicates the project already exists.
To remove this error, activate *Append to an existing process*.
The next configurations will not be added to a new Service Assembly project, but appended to the existing one.
!petals-studio-tuto-consumes-kpi-12.jpg!
\\
Go on with the wizard as described in the previous sections.
When the wizard completes, it creates the new KPI configurations and update the Service-Assembly project (jbi.xml and pom.xml).
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the created artifacts can be edited using the JBI and XSL editors.
The Service Assembly project can be [packaged like any other Service Assembly project|Working with Service Assembly projects#Export for Petals].
h2. Deployment
The deployment of the created service assembly can be achieved with the Petals web console.
Or you can do it by dropping the service assembly in the install directory of your Petals installation.
This second option should only be used in development steps.
\\
Be careful, the [Petals KPI component|petalscomponents:Petals-SE-KPI] must be configured first.
This steps is described in details in the \[install guide of Petals View\|petalsview:InstallGuide\].