====== How to write a jSeduite BPEL Process ======

===== Step #1: Creating a BPEL module =====

  - Right click on the //projects// panel
    * Choose ''New Project ...'', ''SOA'' category and ''BPEL Module'' project.
    * Click the ''Next'' button.
  - Choose a meaningful name as ''Project Name'', 
    * Use the ''$JSEDUITE_HOME/orchestrations'' folder as ''Project Location''
    * Click the ''Finish'' button.

==== Step #1.1: Adding Partners contracts ====

  - Right click on the ''Process Files'' directory, and choose ''New'', ''Folder ...''
    * Name it ''Partners''
  - Right click on this newly createdfolder, and choose ''New'' / ''External WSDL Document ...''
    * Select the ''From Local File System'' option, and browse to the ''$JSEDUITE_HOME/architecture/contracts'' directory
    * Pick up all WSDL interface description you'll need as partner of this orchestration
    * //Tips:// Even if it's not mentioned, you can pick up a set of file in this wizard

==== Step #1.2: Design your orchestration ====

This section assumes you're familiar with [[http://www.netbeans.org/kb/61/soa/synchsample.html|BPEL process development]] using the Netbeans environment. It essentially focuses on expressing naming conventions. 
  * Important readings: [[http://www.netbeans.org/kb/trails/soa.html]]

=== Data Model: XSD schema ===

  - Right click on the ''Process Files'', and choose ''New'' / ''Xml Schema ...''
    * Use ''OrchestrationName'' as ''FileName''
    * Edit the ''Target Namespace'' to match the following naming convention: 
      * ''http:%%//%%**provider**/jSeduite/orchestrations/schema/**OrchestrationName**''
      * //e.g.// ''http:%%//%%**modalis.i3s.unice.fr**/jSeduite/orchestrations/schema/**WeatherProxy**''
  - Switch to the ''Design'' view, and add: 
    * If you're manipulating complex data structures: ''Complex Types'' describing such structures
    * Invocation message: 
      * Define an ''OperationName**In**'' complex type which represents the structure of expected input messages
      * Replace ''In'' by ''Out'' in the previous sentence to describe expected output messages.
    * Invocation elements: Following the ''Document Literal'' standard, request and response message **MUST** be defined as ''elements''/
      * Define an ''OperationName**Request**'' element, of type ''OperationName**In**''.
      * Replace ''Request'' by ''Response'' and ''In'' by ''Out'' LOL
  - You newly created data model should be ok
    * Choose the ''Run'' menu, and then ''Validate XML''
    * The ''XML Check'' window will pop, and **must** say ''0 Error(s)''.

=== Interface: WSDL contract ===

  - Right click on the root project, and choose ''New'', ''WSDL Document ...''
    * **Warning** : ''WSDL Document ...'' is a definitively different wizard than the  ''External WSDL Document(s) ...'' one.
    * Choose ''OrchestrationName'' as ''File Name''
    * Edit the ''Target Namespace'' to match the following naming convention: 
      * ''http:%%//%%**provider**/jSeduite/orchestrations/wsdl/**OrchestrationName**''
      * //e.g.// ''http:%%//%%**modalis.i3s.unice.fr**/jSeduite/orchestrations/wsdl/**WeatherProxy**''
    * Tick the ''Import XML Schema File(s)'' check box, and load the ''OrchestrationName.xsd'' file.
    * Click on the ''Next'' button.
  - Customize the ''Abstract Configuration'': 
    * Replace the ''Operation Name'' by a meaningful name (CamelCase convention, first letter in upper case).
    * Edit the ''Input'' part:
      * Rename ''part1'' as ''in''
      * Change its ''element'' to the ''OperationName**Request**'' one.
    * Edit the ''Output'' part: (replace ''in'' by ''out'' and ''request'' by ''response'').
  - Customize the ''Concrete Configuration'': 
    * Select the ''Document Literal'' binding subtype

=== Behaviour: BPEL process ===

  - Right click on the project root, and choose ''New'', ''BPEL Process ...'' 
    * Use ''OrchestrationName'' as ''File Name''.
    * Change the ''Target Namespace'' to match the following naming convention:
      * ''http:%%//%%**provider**/jSeduite/orchestrations/bpel/**OrchestrationName**''
      * //e.g.// ''http:%%//%%**modalis.i3s.unice.fr**/jSeduite/orchestrations/bpel/**WeatherProxy**''
  - Import the public interface: 
    * Just drag'n drop the WSDL file on the left part of the designer
    * Rename the partner link as ''external'' (instead of ''PartnerLink1'' or whatever)
  - Import all partners inside the process
    * For each partner, drag'n drop ots WSDL file on the right part of the designer
    * Use an explicit ''Name'' (//i.e.// partner's name)
  - Implements your BPEL process !!
{{  :cookbook:bpel_designer.png?250x250  |}}

===== Step #2: Build a JBI Component =====

  - Right click on the left panel, and chosse ''New'' / ''SOA'', ''Composite Application Project''.
    * Use the ''OrchestrationName**Component**'' naming convention
    * Be sure that ''Project Folder'' is under ''orchestrations'' folder.
  - Once finished, right click on the project root, and choose ''Add JBI Module ...''
    * Select the ''OrchestrationName'' project
    * Click on the ''Add Project JAR Files'' button to wrap the process into a JBI Module
  - Right click on the project root, and choose the ''Clean And Build'' action
  - Right click on the ''Test'' folder, and add a ''New Test case''.
    * The name will be ''Invoker'' (as we'll use it to invoke the process), click ''Next''.
    * Choose ''OrchestrationName.wsdl'' from the ''OrchestrationName'' folder, click ''Next''
    * Select the ''OperationName'' binding operation, click finish 
  - Edit the XML ''Input'' message to send meaningful data
  - Right click on the ''Invoker'' test case, end choose ''Run'' !

<note tuyau>
Basically, the test case will more or less fail, as it's a simple textual comparison (equality) between the expected message and the returned one. As information are different following time concerns, such test policy will never match !
</note>



===== Step #3: Share your work ! =====

==== Public contract ====

You'll have to publish your WSDL contract (and XSD data model) into the ''$JSEDUITE_HOME/architecture/contracts'' folder. 
<note bloquante>
**Warning**: The WSDL file cannot be used for free without a little modification ! 
  * You'll have to replace the ''${HttpDefaultPort}'' string by ''9080''.
  * You'll have to retracts the ''Partners'' folder indication for embedded schemas
</note>

  * A script called ''add_bpel_contract.sh'' can help you to perform such a task: 
<code bash>
mosser@asmodeus:$JEDUITE_HOME/architecture$ ./add_bpel_contract.sh FeedReader
# Retrieving XSD data model [Partners => '']
../orchestrations/FeedReader/src/FeedReader.xsd -> contracts/FeedReader.xsd
# Retrieving WSDL descripton [HttpDefaultPort => 9080]
../orchestrations/FeedReader/src/FeedReader.wsdl -> contracts/FeedReader.wsdl 
mosser@asmodeus:$JEDUITE_HOME/architecture$ svn add contracts/FeedReader.*
A         contracts/FeedReader.wsdl
A         contracts/FeedReader.xsd
mosser@asmodeus:$JEDUITE_HOME/architecture$
</code>

==== Subversion commit ====

  - Select all the relevant projects  
    * //i.e.// ''OrchestrationName'' and ''OrchestrationName**Component**''
    * right click and select ''Subversion'' / ''Commit ...''
  - Enter a commit log message describing the orchestration

  

==== Public download ====