{section}
{column}
h1. Summary
This tutorial explains how you can make a Web Service visible inside Petals ESB.
Generally, we say we *import a Web Service* into Petals.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component in *provides* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 1 minute then
*Expected skills:* be able to locate a WSDL interface
{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 *Provide or Import a Service into Petals*.
In the *Petals Component* list, select *SOAP // petals-bc-soap*.
In the *Component Version* list, select the version of the Petals-BC-SOAP that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 4.0 of the SOAP component.
Which gives us:
!petals-studio-tuto-import-ws-1.jpg!
\\
Click *Next*.
h2. Identifying the 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 is imported.
When working with Web Services, these fields can generally be filled-in automatically, by providing a WSDL file.
\\
If the WSDL interface is accessible through an URL, then copy its URL in the *WSDL file* field.
If you only have the Web Service address, the WSDL address can generally be found by appending "?wsdl" to the Web Service's address.
!petals-studio-tuto-import-ws-2.jpg!
\\
If the WSDL interface of the Web Service is located on the local disk, click *Browse...* and select your WSDL on the disk.
!petals-studio-tuto-import-ws-3.jpg!
\\
In any case, the other fields will be automatically filled-in.
If the WSDL interface describes several services, then all these services are available in the drop-down lists.
The service which is selected in the drop-down lists is the one that will be exposed inside Petals.
\\
{note}
The values for the interface, service and end-point names must match the WSDL interface.
That is to say there must be a service with this name, implementing the so-called interface at this end-point.
For the same reasons, filling-in the information by hand or modifying it is discouraged.
*Sticking to a WSDL interface always ensures this information is valid.*
{note}
{note}
The auto-generation of the end-point means the service end-point is generated at deployment time.
By deploying a such service-unit on n Petals nodes, you would have n times the same service, implementing the same interface, but available at n different locations.
{note}
\\
Once the WSDL location and the fields have been filled-in, 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 SOAP 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-import-ws-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which provides a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-provide*
{note}
\\
Then, click *Next*.
h2. Specifying the SOAP parameters
This page defines information which are specific to the Petals SOAP component.
Generally, you will not have to complete anything here (except if you are using a *proxy*).
The Web Service *address* and the *SOAP version* were retrieved during the WSDL parsing performed in the previous pages.
The meaning of all the parameters can be read in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
\\ !petals-studio-tuto-import-ws-5.jpg!
\\
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-SOAP component was developed with this framework.
This page requires information related to the CDK.
By default, you have nothing to do here.
The meaning of all the CDK parameters for SOAP can be found in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
\\ !petals-studio-tuto-import-ws-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).
In the same directory, you can see your WSDL interface, which was imported with all its dependencies (e.g. referenced XML schemas or other WSDL interfaces).
\\ !petals-studio-tuto-import-ws-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 SOAP configurations, the wizards are complete and provide all the options.
Thus, you do not need to edit the jbi.xml.
\\
The project contains everything the SOAP 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-SOAP 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-SOAP 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 SOAP 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 make a Web Service visible inside Petals ESB.
Generally, we say we *import a Web Service* into Petals.
\\
Technically, this tutorial shows the creation of a service-unit for the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component in *provides* mode.
{info}
*Level:* Easy
*Estimated time:* 10 minutes the first time, 1 minute then
*Expected skills:* be able to locate a WSDL interface
{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 *Provide or Import a Service into Petals*.
In the *Petals Component* list, select *SOAP // petals-bc-soap*.
In the *Component Version* list, select the version of the Petals-BC-SOAP that you are using in Petals.
\\
In the scope of this tutorial, we are going to work with the version 4.0 of the SOAP component.
Which gives us:
!petals-studio-tuto-import-ws-1.jpg!
\\
Click *Next*.
h2. Identifying the 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 is imported.
When working with Web Services, these fields can generally be filled-in automatically, by providing a WSDL file.
\\
If the WSDL interface is accessible through an URL, then copy its URL in the *WSDL file* field.
If you only have the Web Service address, the WSDL address can generally be found by appending "?wsdl" to the Web Service's address.
!petals-studio-tuto-import-ws-2.jpg!
\\
If the WSDL interface of the Web Service is located on the local disk, click *Browse...* and select your WSDL on the disk.
!petals-studio-tuto-import-ws-3.jpg!
\\
In any case, the other fields will be automatically filled-in.
If the WSDL interface describes several services, then all these services are available in the drop-down lists.
The service which is selected in the drop-down lists is the one that will be exposed inside Petals.
\\
{note}
The values for the interface, service and end-point names must match the WSDL interface.
That is to say there must be a service with this name, implementing the so-called interface at this end-point.
For the same reasons, filling-in the information by hand or modifying it is discouraged.
*Sticking to a WSDL interface always ensures this information is valid.*
{note}
{note}
The auto-generation of the end-point means the service end-point is generated at deployment time.
By deploying a such service-unit on n Petals nodes, you would have n times the same service, implementing the same interface, but available at n different locations.
{note}
\\
Once the WSDL location and the fields have been filled-in, 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 SOAP 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-import-ws-4.jpg!
\\
{note}
Petals service-units have a naming convention.
For a service-unit which provides a service, the convention is *su\-*_<Protocol or Technology>_*\-*_<Service name>_*\-provide*
{note}
\\
Then, click *Next*.
h2. Specifying the SOAP parameters
This page defines information which are specific to the Petals SOAP component.
Generally, you will not have to complete anything here (except if you are using a *proxy*).
The Web Service *address* and the *SOAP version* were retrieved during the WSDL parsing performed in the previous pages.
The meaning of all the parameters can be read in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
\\ !petals-studio-tuto-import-ws-5.jpg!
\\
Click *Next*.
h2. Specifying the CDK parameters
The CDK is the Petals framework to develop JBI components.
The Petals-BC-SOAP component was developed with this framework.
This page requires information related to the CDK.
By default, you have nothing to do here.
The meaning of all the CDK parameters for SOAP can be found in the documentation of the [Petals-BC-SOAP|petalscomponents:Petals-BC-SOAP] component.
\\ !petals-studio-tuto-import-ws-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).
In the same directory, you can see your WSDL interface, which was imported with all its dependencies (e.g. referenced XML schemas or other WSDL interfaces).
\\ !petals-studio-tuto-import-ws-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 SOAP configurations, the wizards are complete and provide all the options.
Thus, you do not need to edit the jbi.xml.
\\
The project contains everything the SOAP 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-SOAP 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-SOAP 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 SOAP component to make it work.
Using the default settings is enough to make the service-unit work.