Service Orchestration Functional Specification - Orchestration
Project
$Revision: 1.1.1.1 $
$Date: 2009/10/29 16:50:04 $
Note: This document contains hidden
sections. You may show them
using the following links: Reader Notes: Hide
/ Show
| Author Notes: Hide / Show
1. Introduction
An Orchestration project is primarily a design time construct. There is no exact equivalent in the BPEL runtime. An Orchestration project is first and foremost an IDE centric metaphor for Orchestration Designers to organize their business process development into a collection of design time artifacts. The Orchestraton project will also provide the user with a logically consistent development environment for the full development cycle. The full cycle consists of authoring BPEL processes, deploying BPEL processes, test running BPEL processes, and debugging BPEL processes. The Orchestration project must enable each of these aspects of the development cycle in a RAD fashion.
2. Use Cases and Scenarios
Use Case Assumptions
This functional specification makes some fundamental assumptions about Orchestration project to BPEL process cardinality. These assumptions are not easy ones, as there are pro and con arguments. The current working assumption is that, all things being equal, our customers will prefer the ability to create multiple bpel processes within a single Orchestration project. The difficult part of that statement is "all things being equal" as all things are never equal. For one, our project implementation and our project user interface will have to be more complex to handle the 1:n project:process cardinality. We hope that this will be marginally additional complexity and not overwhelming additional complexity. If it turns out to be ovewhelming additional complexity we will have to revise our plans and scale back to a 1:1 cardinality.
The primary driver in favor of 1:n cardinality is the assumption that there is substantial and perceivable benefit to, at least, some users in having the freedom to author a collection of bpel processes in a single project and deploy them within a single logical deployment unit. There is a position which suggests this logical "collection" could still be supported even if we opted to restrict each Orchestration project to a single process (i.e. 1:1 cardinality), by eventually providing an additional "Composite Application project" which would aggregate the individual processes into the desirable logical collection. That would be a fallback strategy if we back away from our current 1:n cardinality proposal.
An auxilliary assumption of this 1 Project : n Process cardinality
is that the collection of processes within a project must form a single
logical deployment unit. In some respects, this is a user decision. If
the user does not intend for their n .bpel processes to comprise a
single logical deployment unit, then the user should not add > 1
process to a particular Orchestration Project.
Process and Partner Links - Technical Background
Process - A BPEL process being designed by the user within the Orchestration Designer
Partner - A web service or
a
BPEL process (exposed as a web service) that interacts with the process being designed.
Partner WSDL - A WSDL file
describing the partner service and the interaction with its
environment. In most cases obtained from a running server or registry.
Port Type - A set of
operations (defined in a WSDL); this element is also defined in WSDL.
The WSDL may contain more then one port type. Certain port types may be
implemented by the service (provided
port type) whereas others may be required to be implemented by
the partners of the service (consumed
port types).
Partner Link Type - Defines a pair of Port Types - two sides of
conversations, each side assigned a different role name. In a more
simple case, there may be only one role defined (i.e. one port type).
This element may be predefined in a partner WSDL as well as in a
separate WSDL (wrapper WSDL), created within the Orchestration
Designer. Usually one of the port types will be provided by partner and
consumed by the process, whereas the other will be provided by process
and consumed by partners.
Partner Link - Defines a
usage of a Partner Link Type in a process; specifies the roles for
process and partner.
Note to process creation use cases: The
essential part of a process is the communication with one or more
partners. In most cases, these partners are well known in advance;
however the author may also open the process for the communication with
an unknown partner. The latter case is achieved by creating one or more
Port Types and exposing them in the process WSDL.
UC-PR-1: Create a new Orchestration Project with no pre-existing sources
User wants to create a new orchestration project.
Scenario:
- User invokes the New Orchestration Project wizard
- Enters the name of the new project
- Enters the location of the new project
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure and then the user continues his work on this new project.
Use Cases related to multiple procesess
Jirka (24/02/2006) Use Cases related to multiple processes in a project need to be revised. Let's discuss this with Loren, as the SeeBeyond team will be probably responsible for this part.
UC-PR-2: Create a blank process
User wants to create a blank process.
Scenario:
- User invokes the New Process wizard
- Specifies the name of the process
- Clicks Finish
- New process is created and opened in the editor.
TODO: Is this reasonable use-case? I.e. creation of blank project without any partner link?
(Optional) UC-PR-2.1: Create a new process with a partner link refering to a new port type
In this case the partner of the communication is not known in advance, or it does not define any requirements on the communication (i.e. port type to be provided by the process and/or port type to be consumed by the process). The author of the process is supposed to define new port types and expose them with the process (along with partner link types). The resulting WSDL would be then used in the development of other services or processes (the operations of the provided port types may be called by the partner, the operations of the consumed port types have to be implemented by the partner).
The author of the process may know in advance that the process will expose some functionality in one or more new partner link types, however he or she may discover this fact later.
Scenario:
- User invokes the New Process wizard (overlaps with UC-PR-2)
- Specifies the name of the process (overlaps with UC-PR-2)
- User declares that a new port type should be created and provides
necessary information
- User follows the steps of "UC-PR-2: Create a blank process"
- User follows the steps of "UC-DIAG-1: Add a new partner link to a
new port type"
(Optional) UC-PR-2.2: Create a new process with one or new partner
links refering to one or more existing partners
In this case, there is one or more known partners which define some requirements on the communication. They may expose one or more provided port types and one or more consumed port types. In this case, only Partner Links to existing Partner Link Types (and port types) are created.
The author of the process may know in advance with what partners will the process communicate ("Now I want create a TravelIterinary process which will communicate with HotelReservation and CarRental partners."), however he or she may come up with additional partners during the development ("Now I want to add FlightReservation partner.").
Scenario:
- User invokes the New Process wizard (overlaps with UC-PR-2)
- Specifies the name of the process (overlaps with UC-PR-2)
- Specifies the set of partners for which the partner links should
be created and provides also necessary information.
TODO: The UI for this step might be very heavy; the use-case might be fulfilled by an alternative scenario:
- User follows the steps of "UC-PR-2: Create a blank process"
- User follows the steps of "UC-DIAG-2: Add a new partner link to an existing partner"
Use Cases related to Importing from Existing Sources
Jirka (24/02/2006): In January'06 me and Mike agreed that these use cases have lower priority and that we probably won't cover them in Coke 1.0.
* This needs to be further discussed with SeeBeyond team - what is their target - as project system is their responsibility.
Create an Orchestration Project from pre-existing sources
User wants to create a new Ochestration Project, but wishes to use pre-existing orchestration sources. The pre-existing orchestration sources must minimally include 1-n .bpel files, and may include other orchestration resources. The other pre-existing orchestration resources could consist of the following artifacts:
.wsdl for each .bpel process
1 .wsdl for the collection of related processes (i.e. the "main.wsdl" that is referenced by the pxe-system.xml )
1 pxe-system.xml (i.e. the PXE System deployment descriptor)
1 PXE RR file (i.e. the PXE System reference resolver descriptor)
0-n partner .wsdl files
0-n .xsd files
It is probably too compicated to support new project from any combination of possible existing sources. There are too many possible sources which are fragmentary or require some contextual understanding before being useful. For instance, a wsdl file may be a bpel process wsld or it may be a partner wsdl file. The IDE does not necessarily know which context applies unless the selection is made in context. Therefore, the IDE will support two basic "from existing sources" cases. The other sources may be used post project construction.
Create an Orchestration Project from pre-existing BPEL file
User wants to create a new Ochestration Project, but wishes to use exactly one pre-existing BPEL file.
Scenario:
- User invokes the New Orchestration Project from Existing Sources wizard.
- Enters the name of the new project
- Enters the location of the new project
- User selects a single pre-existing .bpel file
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure and then the user continues his work on this new project.
Create an Orchestration Project from pre-existing WSDL file
User wants to create a new Ochestration Project, but wishes to use a pre-existing WSDL file. There is no pre-existing BPEL, only an interface definition for the process in the WSDL file.
Scenario:
- User invokes the New Orchestration Project from Existing Sources wizard.
- Enters the name of the new project
- Enters the location of the new project
- User selects the corresponding process WSDL file
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure and then the user continues his work on this new project.
Issues: On what basis should the IDE name the process file? Should it name it after the WSDL file? Should it name it after the project name? Or should the wizard have a separate field for "Proces Name" which defaults to the Project name but can be overriden?
Create an Orchestration Project from pre-existing BPEL file and corresponding WSDL file
User wants to create a new Ochestration Project, but wishes to use exactly one pre-existing BPEL file and a pre-existing WSDL file.
Scenario:
- User invokes the New Orchestration Project from Existing Sources wizard.
- Enters the name of the new project
- Enters the location of the new project
- User selects a single pre-existing .bpel file
- User selects the corresponding process wsdl file
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure and then the user continues his work on this new project.
Create an Orchestration Project from > 1 pre-existing BPEL files
User wants to create a new Ochestration Project, but wishes to use > 1 pre-existing BPEL file.
There are several scenarios that could satisfy this use case. Here are two. The implementation question is how far should the new project wizard go to satisfy this use case, when there may be actions available to the user after project construction which can be invoked to satisfy the use case.
Scenario:
- User invokes the New Orchestration Project from Existing Sources wizard.
- Enters the name of the new project
- Enters the location of the new project
- User selects a single pre-existing .bpel file
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure
- User repeatedly invokes the "Add BPEL process to project" action for each additional BPEL process.
Scenario:
- User invokes the New Orchestration Project from Existing Sources wizard.
- Enters the name of the new project
- Enters the location of the new project
- User selects > 1 pre-existing .bpel files from a single folder
- Clicks Finish
- User waits until the Wizard completes the construction of the new project structure
- User repeatedly invokes the "Add BPEL process to project" action for each additional BPEL process which was not located in the source folder that was selected at
Create an Orchestration Project from > 1 pre-existing WSDL files
User wants to create a new Ochestration Project, but wishes to use > 1 pre-existing BPEL file and their corresponding WSDL files.
Issue: There are several scenarios that could satisfy this use case. The implementation question is how far should the new project wizard go to satisfy this use case, when there may be actions available to the user after project construction which can be invoked to satisfy the use case.
Create an Orchestration Project from > 1 pre-existing BPEL and pre-exising WSDL files
User wants to create a new Ochestration Project, but wishes to use > 1 pre-existing BPEL file.
Issue: There are several scenarios that could satisfy this use case. The implementation question is how far should the new project wizard go to satisfy this use case, when there may be actions available to the user after project construction which can be invoked to satisfy the use case.
3. Specification
Wizard: New
Orchestration Project
#This is a New Project wizard.
Category: SOA
Name: Orchestration Project
Description: Creates a new web service orchestration project which supports the authoring of a single BPEL process. The project also provides an IDE-generated Ant build script to build, run, and debug your project.
Title (starting step #2): New Orchestration Project
Mockup

Note: This is juck a mockup. Insets, certain labels and the content of description label may be different from implementation. Also the Process Name text field is not present in the implementation of TPR2.
Functional Specification
AI: Fill this in.
Then optionaly also add a wizard for creation of New Processes.
Wizard: New Orchestration Project from pre-existing BPEL file
TODO: Add images of New Orchestration Project from pre-existing BPEL file Wizard
Wizard: New Orchestration Project from pre-existing WSDL file
TODO: Add images of New Orchestration Project from pre-existing WSDL file Wizard
Wizard: New Orchestration Project from pre-existing BPEL file and pre-existing WSDL file
TODO: Add images of New Orchestration Project from pre-existing BPEL file and pre-existing WSDL file Wizard
Project Folders Layout
The goal of this chapter is to describe the layout of the project folder and its contents. The project folder is created with the New Orchestration Project Wizard on the finish step. It creates a filesystem that contains a collection of folders and artifact files. All of the appropriate folders should be created by the wizard. Some of the artifacts will be created by the wizard and other artifacts will be created in an as needed fashion as the developer modifies the project interactively.
Synchronous Process
For TPR2, the structure of a synchronous process project goes as follows:
[Project Name]/The process file contains a recieve and reply for a synchronous operation, which is defined in the generated wsdl file. A couple of simple types used by the operations are defined in the generated XML Schema file.
[Project Name]/build.xml
[Project Name]/build
[Project Name]/nbproject
[Project Name]/nbproject/*
[Project Name]/references
[Project Name]/references/[processName].xsd
[Project Name]/src
[Project Name]/src/[processName].bpel
[Project Name]/src/[processName].wsdl
[Project Name]/src/pxe-system.xml
[Project Name]/test
The ./test folder contains test messages that are exposed under the Test Scenarios logical node in the Project Window.
Asynchronous Process
If the user chooses to create an asynchronous project, actually two projects are created. The main process project contains a BPEL file with a recieve and invoke activities (callback) for the asynchronous operation. In fact, these correspond to two operations defined in the WSDL file within the port types. And then a client project may be also created based on the user choice. The name of that project is "[Project Name]Client".
TravelReservationSample Project
We may also want to specify the files that are created with the TravelReservationService sample project wizard.Issue: The primary issue is the location of sources. Should the project be flexible or prescriptive when it comes to physical layout? In order to readily import pre-existing orchestration sources, the project might need to be very flexible in regard to source location.
The proposed filesystem view of the Orchestration project structure is as folllows (Subject to revisions, particularly re granularity:
[Project Name]/
[Project Name]/nbproject
[Project Name]/src
[Project Name]/references
[Project Name]/test
[Project Name]/build
TODO – review above list compare to current J1 prototype (below). Above
list is more consistent with NB Jakarta style organization. Below list
is particular to BPEL. It was created for J1 without review.
[Project Name]/
[Project Name]/nbproject
[Project Name]/build
[Project Name]/dist
[Project Name]/bpel
[Project Name]/bpeltest
[Project Name]/pdd
[Project Name]/wsdl
Breakdown of project filesytem substructure:
[Project Name]/
[Project Name]/build.xml
TODO: Describe contents of wizard generated
build.xml
[Project Name]/nbproject
[Project Name]/nbproject/project.properties
[Project Name]/nbproject/project.xml
[Project Name]/nbproject/build-impl.xml
[Project Name]/nbproject/private/
[Project Name]/nbproject/private/private.properties
TODO: Describe contents of wizard generated project.properties
TODO: Describe contents of wizard generated project.xml
TODO: Describe contents of wizard generated buld-impl.xml
TODO: Describe contents of wizard generated private.properties
[Project Name]/src
[Project Name]/src/[processName].bpel
[Project Name]/src/[processName].wsdl
[Project Name]/src/pxe-system.xml
[Project Name]/src/rr.xml
TODO - consider using [Project Name]/src/ directory to house process wsdl, pxe-system.xml and rr.xml as a src artifact
TODO: Describe contents of wizard generated [processName].bpel
TODO: Describe contents of wizard generated [processName].wsdl
TODO: Describe contents of wizard generated pxe-system.xml
TODO: Describe contents of wizard generated rr.xml
[Project Name]/references
[Project Name]/references/wsdl/
[Project Name]/references/wsdl/*.wsdl
[Project Name]/references/schema/
[Project Name]/references/schema/*.xsd
[Project Name]/test
TODO - This folder is meant to hold the unit test file substructure. This may be quite complex.
[Project Name]/build
TODO - complete structural description of this folder
Project Explorer
+-----------------------------------------------------+Figure: Logical View of Orchestration Project
| Projects |
+-----------------------------------------------------+
| [O] OrchestrationProject1
| -- [P] Processes
| | -- [p] travel
| | -- [T] Test Scenarios
| | -- [t] testRequestA [1 running, 0 completed]
| | -- [r] Tue, 21 Feb 11:23:41
| | -- testRequestB [0 completed]
| | -- [w] travel.wsdl
| | -- [D] pxe-system.xml
| | +- [p] loan
| -- [R] Web References
| | -- [S] XML Schema Files
| | | -- [s] ota_types.xsd
| | -- [W] WSDL Files
| | -- [w] partner.wsdl
|
Node: Orchestration Project [O]
This is the root node of the Orchestration Project.
- Name: <project-name>
- Tooltip: none
- Contextual menu:
New Not for TPR2
--------------
Build Project
Clean and Build Project
Clean Project
--------------
Run Project
Debug Project
Deploy
--------------
Set Main Project
Open Required Projects
Close Project
---------------
Rename Project
Move Project
Copy Project
Delete Project Delete Not for TPR2
---------------
Find ...
---------------
CVS >
---------------
Properties Not be TPR2
Node: Processes [P]
This is a folder-node for all processes within the project.
- Name: <project-name>
- Tooltip: none
- Contextual menu: none
New >
[ ] Orchestration Process ...
Then there is also BUG in current implementation - there is a tooltip "src" on this node.
Node: Process [p]
The node represents an individual process within the project.
- Name: <process-bpel-filename.bpel>
- Tooltip: None
- Double click: Opens the Process
Editor
- Contextual menu:
Open
Check XML
Validate XML
--------------------
CVS >
--------------------
Save As Template...
--------------------
Tools >
--------------------
Properties
All the actions in the contextual menu equals to those exposed on a generic XML file, except Open which opens the Process Editor.
Node: Test Scenarios [T]
This node is a container for test messages that can be send to the
users. In TPR2 there is no UI for adding new messages, they need to be
managed manually from the Files window. The test messages (xml files)
are stored in the ./test
folder.
- Name: Test Scenarios
- Tooltip: None
- Contextual menu:
Properties
The Properties action brings up a Properties Window, where the URL for sending the messages can be specified. However, this should not be necessary, as the Test Scenarios should work out of the box.
Node: Test Message [t]
Represents a test SOAP message that may be send to a deployed
business process. This node basicly represents an XML file in the ./test project folder.
- Name: <file-name without
extension> [ $n running, $m completed]
$n is replaced with the count of messages that were send but the test wasn't finished yet (i.e. HTTP connection is still pending).
$m is replaced with the count of messages that were send and the test was finished (i.e. HTTP connection was closed). Note that this may also include unsuccessfull atempts to send the message.
If there are no "running" tests, the section "$n runninng" is ommited.
- Tooltip: BPEL Test Case
- Contextual menu:
Run
The Run and and Default Test actions are only visible if the test is not pending. These two states are also distinguished with different icons.
Default Test
--------------------
...
<generic XML file actions>
...
- Run action - runs an Ant target that sends the message to the process.
- Default Test - sets this test message as default (this message
is then sent on Run and Debug)
Node: Test Result [r]
Represents a response of an attempt to send a test message. This
response is a text or XML document stored in "<test file-name without
extension>_results" folder. The name of this file is encoded
with a timestamp, however the logical node in the Project window
contains a decoded date and time of the test attempt.
- Name: <Day-of-week,
Day-of-month Month Hour:Minute:Second>
- Tooltip: BPEL Test Case Result
- Contextual menu is equal to the contextual menu of a generic XML file
Node: Web References [R]
This node is a container for references to external XML Schema and
WSDL files (i.e. those stored in ./references
project folder). Here, external only reflects the fact that the
WSDL file of the main process is not exposed here but as a child of the
process node.
- Name: Web References
- Tooltip: Reference to a schema/wsdl file
- Contextual menu:
New > File/Folder
The second item pops up the "Retrieve Schema and WSDL Documents" provided by XML Tools.
----------------
Retrieve Schema and WSDL Documents...
Node: XML Schema Files [S]
Contains all .XSD files contained in ./references folder. The .xsd file nodes will be automatically added by the IDE based on a discovery algorithm. The IDE will introspect the file system below [Project Name]/references and for any .xsd files that it finds it will create and add an .xsd file node child to the XML Schemas logical node. The .xsd file nodes will be presented in a flat, non-hierarchical fashion, irrespective of their physical location under the [Project Name]/references directory
- Name: XML Schema Files
- Tooltip: Contains all schema documents
- Contextual menu: None
Node: WSDL Files [W]
Contains all .WSDL files contained in ./references folder. # The
.wsdl file nodes will be automatically added by the IDE based on a
discovery algorithm. The IDE will introspect the file system below
[Project Name]/references and for any .wsdl files that it finds it will
create and add an .wsdl file node child to the XML Schemas logical
node. The .wsdl file nodes will be presented in a flat,
non-hierarchical fashion, irrespective of their physical location under
the [Project Name]/references directory.
- Name: WSDL Files
- Tooltip: Contains all WSDL documents
- Contextual menu: None
Node: XML Schema File [s]
The appearance and behaviour of this node is identical to a common XML file in NetBeans.
Node: WSDL File [w]
The appearance and behaviour of this node is identical to a common WSDL file in NetBeans or Alaska; however there is an added functionality.
DnD behavior
When the user DnDs a WSDL file node from the project explorer to the
Design View of the Orchestration Editor, an <import> element is
added to the BPEL process and a partner link may be created. If the
partner link is created depends on the inner
settings of the WSDL file.
Wizard: New Orchestration Process
Jirka (24/02/2006):
This depends on the direction we set out for TPR3.
TODO – should we place the emphasis in the New
actions on
“Business Process” or “BPEL process”? Again,
the diagram cardinality issue surfaces here.
- basically a wording issue
TODO: If we limit a project to
only 1 business process diagram then we do not need and should not
have a “New” action. - IS THIS QUESTION ALREADY RESOLVED (i.e. multiple
processes, multiple BPEL files)?
TODO: Update the following paragraph into
NetBeans wording
One can create a new Business process diagram via the top level menu "File : New : BPEL Process" menu or file node context menu "New : BPEL Process". Both actions bring up the New BPEL wizard, which consists of a single panel. The only provided context is the pre-selection of the parent folder, which may be overridden by wizard user. When the wizard completes, a skeleton BPEL file is created on disk in the specified location.

Wizard: Add Orchestration Process
TODO: Describe the Add process UI. Is this a wizard or not?