{section}
{column}
h1. Summary
This tutorial explains how you can invoke a Petals service when a file is added in a directory.
Such a service will either send the dropped file as an attachment to the invoked service, or load it and send its content in the message body.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component in *consumes* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 4 minutes then
*Expected skills:* know the basics about WSDL and XML
{info}
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}
h1. Creating the Service-Unit project
h2. Getting started
Start Petals Studio.
In the menu, select *File > New > Service-Unit Project*.
If you do not see it, go into *File > New > Other...* Then, select *Service-Unit Project* under the *Petals* category.
\\
A wizard opens, showing three drop-down lists.
In the *Use Case* list, select *Consume or Call a Petals service*.
In the *Petals Component* list, select *File Transfer // petals-bc-filetransfer*.
In the *Component Version* list, select the version of the Petals-BC-FileTransfer that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 3.0 of the File Transfer component.
Which gives us:
!petals-studio-tuto-consumes-ft-1.jpg!
\\
Click *Next*.
h2. Identifying the target service
The current page requires you to fill-in the base information to put in the JBI descriptor (*META-INF/jbi.xml*).
In particular, it defines the interface, service and end-point names of the service that will be invoked when a file is added in the watched directory.
You can obviously fill-in these fields by hand.
However, the most efficient way is to use the [Petals Services explorer|Getting familiar with the Petals Services view] (provided it was populated).
Click *Select a service*. A selection dialog shows up, providing filtering assistance.
!petals-studio-tuto-consumes-ft-2.jpg!
\\
When you have selected your service, click *OK*.
The wizard fields are filled-in automatically.
!petals-studio-tuto-consumes-ft-3.jpg!
\\
{note}
The values for the interface, service and end-point names must match the values defined in the jbi.xml of the invoked service.
Indeed, this service must be a Petals service, and thus be described in a jbi.xml.
As a reminder, the jbi.xml values and the WSDL values (if the WSDL exists) of the invoked service must be exactly the same.
For this reason, filling-in the information by hand or modifying it is discouraged.
{note}
\\
Click *Next*.
h2. Defining the project name
This page defines the name and the location of the project that will be created.
Indeed, this wizard will result in the creation of a project containing all the required elements for a File Transfer service-unit.
\\
Enter a project name for your project.
If you do not want your project to be created in the default workspace, uncheck *Use default location*.
Then click *Browse...* and select the location where the project will be created.
!petals-studio-tuto-consumes-ft-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which consumes (calls) a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-consume*
{note}
\\
Then, click *Next*.
h2. Specifying the File Transfer parameters
This page defines information which are specific to the Petals File Transfer component.
There are three parameters to take care of here:
* The first one is the *directory* that will be polled regularly.
* The second parameter is the *name pattern* of the file that must be sent to the invoked service.
* The third one is the *polling period*, i.e. the time interval between each polling of the read directory.
The other displayed parameters are optional.
There is still one to configure manually after the jbi.xml is created.
The meaning of all the parameters can be read in the documentation of the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component.
\\ !petals-studio-tuto-consumes-ft-5.jpg!
\\
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-FileTransfer component was developed with this framework.
This page requires information related to the CDK.
You have three parameters to complete here (others are optional or have default values):
* The name space of the invoked operation's name (WSDL operations are QNames).
* The local part of the invoked operation's name (WSDL operations are QNames).
* The Message Exchange Pattern (MEP).
The meaning of all the CDK parameters for File Transfer can be found in the documentation of the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component.
\\ !petals-studio-tuto-consumes-ft-6.jpg!
\\
Click *Finish* to complete the wizard.
h2. Checking the result
When the wizard has completed, a new project has been created and is visible in your workspace.
It contains a jbi.xml file, located under *src/main/jbi*.
This hierarchy allows you to work with Apache Maven then (a pom.xml was also created at the root of the project).
There is nothing else in the project.
\\ !petals-studio-tuto-consumes-ft-7.jpg!
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the newly created jbi.xml file has been open in the Service-Unit editor.
Regarding File Transfer configurations, the wizards are *almost* complete.
\\
However, from the version 3.0 of this component, there is an additional parameter that cannot be fill-in in the wizard.
This parameter is called *base-message* and needs to be set in the jbi.xml.
\\
As explained in the documentation of [the version 3.0 of the File Transfer component|petalscomponents:Petals-BC-Filetransfer], *base-message* defines a message skeleton that will be sent to the invoked message. The principle is the same one than [the Quartz component|petalscomponents:Petals-BC-SE-Quartz].
\\
To define the base message, update the jbi.xml manually. Be careful, the XML message must be contained in a CDATA section.
Here is a sample configuration of the File Transfer component.
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<!--
JBI descriptor for the Petals' "petals-bc-filetransfer" component (FileTransfer).
Originally created for the version 3 of the component.
-->
<jbi:jbi version="1.0"
xmlns:filetransfer="http://petals.ow2.org/components/filetransfer/version-3"
xmlns:gen0="http://petals.ow2.org/talend/"
xmlns:generatedNs="http://petals.ow2.org/talend/"
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">
<!-- Import a Service into Petals or Expose a Petals Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Expose a Petals Service => consumes a Service. -->
<jbi:consumes
interface-name="generatedNs:CommandsCollectorServicePortType"
service-name="generatedNs:CommandsCollectorService"
endpoint-name="CommandsCollectorEndpoint">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:operation>gen0:executeJobOnly</petalsCDK:operation>
<petalsCDK:mep>InOnly</petalsCDK:mep>
<!-- Component specific elements -->
<filetransfer:read-directory>${DropInDirectory}</filetransfer:read-directory>
<filetransfer:transfer-mode>content</filetransfer:transfer-mode>
<filetransfer:file-pattern>*.csv</filetransfer:file-pattern>
<filetransfer:polling-period>5000</filetransfer:polling-period>
<filetransfer:base-message>
<![CDATA[<tal:executeJob xmlns:tal="http://petals.ow2.org/talend/">
<tal:contexts />
<tal:in-attachments>
<tal:fileLocation>
<tal:fileContent>$attachment</tal:fileContent>
</tal:fileLocation>
</tal:in-attachments>
</tal:executeJob>]]>
</filetransfer:base-message>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}
\\
After generation and a possible edition, the project contains everything the File Transfer component needs.
You can now package it before deploying it.
\\
The created project being a [Service-Unit project|Working with Service-Unit projects], you can [package it as any Service-Unit project|Working with Service-Unit projects#Export for Petals].
It results in the creation of a Service Assembly for the Petals-BC-FileTransfer component. Its location depends on your export choices.
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.
\\
First, make sure the Petals-BC-FileTransfer is installed in your Petals environment.
Then, install the service assembly in your Petals, using one of the two ways indicated above.
\\
There is no need to update configuration of the File Transfer component to make it work.
Using the default settings is enough to make the service-unit work.
{column}
h1. Summary
This tutorial explains how you can invoke a Petals service when a file is added in a directory.
Such a service will either send the dropped file as an attachment to the invoked service, or load it and send its content in the message body.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component in *consumes* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 4 minutes then
*Expected skills:* know the basics about WSDL and XML
{info}
{column}
{column:width=350px}
{panel:title=Table of contents}{toc}{panel}
{column}
{section}
h1. Creating the Service-Unit project
h2. Getting started
Start Petals Studio.
In the menu, select *File > New > Service-Unit Project*.
If you do not see it, go into *File > New > Other...* Then, select *Service-Unit Project* under the *Petals* category.
\\
A wizard opens, showing three drop-down lists.
In the *Use Case* list, select *Consume or Call a Petals service*.
In the *Petals Component* list, select *File Transfer // petals-bc-filetransfer*.
In the *Component Version* list, select the version of the Petals-BC-FileTransfer that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 3.0 of the File Transfer component.
Which gives us:
!petals-studio-tuto-consumes-ft-1.jpg!
\\
Click *Next*.
h2. Identifying the target service
The current page requires you to fill-in the base information to put in the JBI descriptor (*META-INF/jbi.xml*).
In particular, it defines the interface, service and end-point names of the service that will be invoked when a file is added in the watched directory.
You can obviously fill-in these fields by hand.
However, the most efficient way is to use the [Petals Services explorer|Getting familiar with the Petals Services view] (provided it was populated).
Click *Select a service*. A selection dialog shows up, providing filtering assistance.
!petals-studio-tuto-consumes-ft-2.jpg!
\\
When you have selected your service, click *OK*.
The wizard fields are filled-in automatically.
!petals-studio-tuto-consumes-ft-3.jpg!
\\
{note}
The values for the interface, service and end-point names must match the values defined in the jbi.xml of the invoked service.
Indeed, this service must be a Petals service, and thus be described in a jbi.xml.
As a reminder, the jbi.xml values and the WSDL values (if the WSDL exists) of the invoked service must be exactly the same.
For this reason, filling-in the information by hand or modifying it is discouraged.
{note}
\\
Click *Next*.
h2. Defining the project name
This page defines the name and the location of the project that will be created.
Indeed, this wizard will result in the creation of a project containing all the required elements for a File Transfer service-unit.
\\
Enter a project name for your project.
If you do not want your project to be created in the default workspace, uncheck *Use default location*.
Then click *Browse...* and select the location where the project will be created.
!petals-studio-tuto-consumes-ft-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which consumes (calls) a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-consume*
{note}
\\
Then, click *Next*.
h2. Specifying the File Transfer parameters
This page defines information which are specific to the Petals File Transfer component.
There are three parameters to take care of here:
* The first one is the *directory* that will be polled regularly.
* The second parameter is the *name pattern* of the file that must be sent to the invoked service.
* The third one is the *polling period*, i.e. the time interval between each polling of the read directory.
The other displayed parameters are optional.
There is still one to configure manually after the jbi.xml is created.
The meaning of all the parameters can be read in the documentation of the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component.
\\ !petals-studio-tuto-consumes-ft-5.jpg!
\\
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-FileTransfer component was developed with this framework.
This page requires information related to the CDK.
You have three parameters to complete here (others are optional or have default values):
* The name space of the invoked operation's name (WSDL operations are QNames).
* The local part of the invoked operation's name (WSDL operations are QNames).
* The Message Exchange Pattern (MEP).
The meaning of all the CDK parameters for File Transfer can be found in the documentation of the [Petals-BC-FileTransfer|petalscomponents:Petals-BC-Filetransfer] component.
\\ !petals-studio-tuto-consumes-ft-6.jpg!
\\
Click *Finish* to complete the wizard.
h2. Checking the result
When the wizard has completed, a new project has been created and is visible in your workspace.
It contains a jbi.xml file, located under *src/main/jbi*.
This hierarchy allows you to work with Apache Maven then (a pom.xml was also created at the root of the project).
There is nothing else in the project.
\\ !petals-studio-tuto-consumes-ft-7.jpg!
h1. Updating, packaging and deploying
h2. Further edition and packaging
After completion, the newly created jbi.xml file has been open in the Service-Unit editor.
Regarding File Transfer configurations, the wizards are *almost* complete.
\\
However, from the version 3.0 of this component, there is an additional parameter that cannot be fill-in in the wizard.
This parameter is called *base-message* and needs to be set in the jbi.xml.
\\
As explained in the documentation of [the version 3.0 of the File Transfer component|petalscomponents:Petals-BC-Filetransfer], *base-message* defines a message skeleton that will be sent to the invoked message. The principle is the same one than [the Quartz component|petalscomponents:Petals-BC-SE-Quartz].
\\
To define the base message, update the jbi.xml manually. Be careful, the XML message must be contained in a CDATA section.
Here is a sample configuration of the File Transfer component.
{code:lang=xml}
<?xml version="1.0" encoding="UTF-8"?>
<!--
JBI descriptor for the Petals' "petals-bc-filetransfer" component (FileTransfer).
Originally created for the version 3 of the component.
-->
<jbi:jbi version="1.0"
xmlns:filetransfer="http://petals.ow2.org/components/filetransfer/version-3"
xmlns:gen0="http://petals.ow2.org/talend/"
xmlns:generatedNs="http://petals.ow2.org/talend/"
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">
<!-- Import a Service into Petals or Expose a Petals Service => use a BC. -->
<jbi:services binding-component="true">
<!-- Expose a Petals Service => consumes a Service. -->
<jbi:consumes
interface-name="generatedNs:CommandsCollectorServicePortType"
service-name="generatedNs:CommandsCollectorService"
endpoint-name="CommandsCollectorEndpoint">
<!-- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:operation>gen0:executeJobOnly</petalsCDK:operation>
<petalsCDK:mep>InOnly</petalsCDK:mep>
<!-- Component specific elements -->
<filetransfer:read-directory>${DropInDirectory}</filetransfer:read-directory>
<filetransfer:transfer-mode>content</filetransfer:transfer-mode>
<filetransfer:file-pattern>*.csv</filetransfer:file-pattern>
<filetransfer:polling-period>5000</filetransfer:polling-period>
<filetransfer:base-message>
<![CDATA[<tal:executeJob xmlns:tal="http://petals.ow2.org/talend/">
<tal:contexts />
<tal:in-attachments>
<tal:fileLocation>
<tal:fileContent>$attachment</tal:fileContent>
</tal:fileLocation>
</tal:in-attachments>
</tal:executeJob>]]>
</filetransfer:base-message>
</jbi:consumes>
</jbi:services>
</jbi:jbi>
{code}
\\
After generation and a possible edition, the project contains everything the File Transfer component needs.
You can now package it before deploying it.
\\
The created project being a [Service-Unit project|Working with Service-Unit projects], you can [package it as any Service-Unit project|Working with Service-Unit projects#Export for Petals].
It results in the creation of a Service Assembly for the Petals-BC-FileTransfer component. Its location depends on your export choices.
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.
\\
First, make sure the Petals-BC-FileTransfer is installed in your Petals environment.
Then, install the service assembly in your Petals, using one of the two ways indicated above.
\\
There is no need to update configuration of the File Transfer component to make it work.
Using the default settings is enough to make the service-unit work.