HOME > Community > Projects > enterprise

Service Orchestration Functional Specification - Orchestration Project

$Revision: 1.3 $
$Date: 2006/06/20 10:34:50 $

Note: This document contains hidden sections. You may show them using the following links: Reader Notes: Hide / Show | Author Notes: Hide / Show

Author Notes:
Jirka (24/02/2006)

* This specification needs to be cleared out.
   * Use-cases could be polished.
   * New Project Wizards from existing sources may be considered and specified.
   * More could be said in terms of functional specification of project file system and TravelReservationSample.
   * Test Ecology nodes should be respecified if we improve that area for TPR3.
   * XML Tools integration needs to be also respecified in respect to what will be done for TPR3.
   * New Orchestration Process wizard should be specified if we go that direction.

* We also need to add a section on Help System integration.

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

TODO: This section is meant to be an "technical glossary"of the terms being used in the further text. It may be usefull for the readers; it may be also removed. However, the language would have to be precised then.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.
TODO: Should add motivation for the creation of the project (e.g. process agregation, ...).

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: The newly created process will probably contain an empty sequence.
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

Alternative scenario (composite of "UC-PR-2: Create a blank process" and "UC-DIAG-1: Add a new partner link to a new port type"):

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:

Alternative scenario (composite of "UC-PR-2: Create a blank process" and "UC-DIAG-2: Add a new partner link to an existing partner"):

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.

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.

Jirka (24/02/2006):
Process Name text field may be present if we allow more processes in one project. This needs to be discussed with Loren.
Also the default contents of Namespace text field needs to be reconsidered.

Jirka (24/02/2006): Functional Specification should be filled in here. Maybe a functional specification of the current implementation, maybe the functional specification of what will be done by SeeBeyond team.

Functional Specification

AI: Fill this in.

Then optionaly also add a wizard for creation of New Processes.

Jirka (24/02/2006):
Wizards for creating a new process with existing sources may be considered here. See also Use-cases section.
Again - in responsibility of SeeBeyond team.

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]/
[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 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.

The ./test folder contains test messages that are exposed under the Test Scenarios logical node in the Project Window.

We may to specify the details of all the files. And also talk more about the *_results folders in the ./test folder.

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".

Jirka (24/02/2006): Concern: Currently, the client project contains two wsdl files: "[Project Name].wsdl" and "[Project Name]Client.wsdl". The main process WSDL is identical to the one in the main process project. The client wsdl file contains import of the main process wsdl file and then a (probably) redundant copy of simple type, message type, port type and partner link type definitions.

This needs to be cleared out, probably by the SeeBeyond team, which will take over of this part.

TravelReservationSample Project

We may also want to specify the files that are created with the TravelReservationService sample project wizard.

Jirka (24/02/2006): These are original notes, serving as source of data for the polished spec. Maybe removed when this section is done.

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

The project explorer contains a logical view of the 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
|

Figure: Logical View of Orchestration Project

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

Jirka (24/02/2006): There is a couple of actions here which need to be designed and implemented in order to provide consistent user experience with other NetBeans projects.
This needs to be consulted with Loren Mack, as the Project UI will be in SeeBeyond team responsibility.

Node: Processes [P]

This is a folder-node for all processes within the project.

Name: <project-name>
Tooltip: none
Contextual menu: none

Jirka (24/02/2006):
If we go for multiple process projects, there should be at least "New > Orchestration Process" action. But maybe also entry points for other related templates, such as XML Schema and WSDL files.

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.

Jirka (24/02/2006): We may want to improve this UI for TPR3, along with the rest of the test-ecology feature

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
Default Test
--------------------
...
<generic XML file actions>
...
```
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.

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)

Jirka (24/02/2006): We may want to improve this UI for TPR3, along with the rest of the test-ecology feature.
BUG: Definetely the "Default Test" action should be renamed to something like "Set as Default".
And also the tooltip should be revised.

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
                       ----------------
                       Retrieve Schema and WSDL Documents...

The second item pops up the "Retrieve Schema and WSDL Documents" provided by XML Tools.

Jirka (24/02/2006):
* This node may be improved along with other improvements in project infrastructure and closer integration with XML tools infrastructure. And that seems to be a shared responsibility of XML-tools and SeeBeyond teams.

* Tooltip should be changed to something more reasonable or removed (prefered).

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.

Jirka (24/02/2006):
BUG: Currently the user can DnD any WSDL file from any project to the Process Editor. However, the WSDL file is not added to the project. This is a bad behaviour. It needs to be precisly specified and implemented.

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.