Service Orchestration Functional Specification - Orchestration Designer - Property Editors

$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

This document specifies the property editors which allow the user to modify attributes of activities and other process elements.
A link to use cases in the previous document would be nice.

2. Specification

The Property Editors are modal dialogs that can be brought up with a double click on the diagram element or by invoking the 'Edit' action of the element's contextual menu (in the diagram or Navigator).

TODO-1.0: In the future (post TPR3) we will extend the NetBeans notion of Properties Window with a rich editing capabilities. This Properties Window contains two tabs - Customizer and Properties. The Properties tab contains standard property sheet, whereas the newly introduced Customizer contains a panel with standard Swing components like text fields, pulldowns, etc. The Customizer allows the user to focus on important properties and provides a better user experience.

The name 'Customizer' should be improved.

Customizer Contents

The contents of the customizer panels is based on the previous design of property editors as modal dialogs. Some of the dialogs contain multiple tabs, however in the customizer, there is only the contents of the main tab. The contents of the other tabs can be managed in the Navigator Window.


TODO-TPR3: Is this problematic observability?
TODO: Should add links to use cases and scenarios.

Validation

The contents of the text fields is validated on focust lost. If the value is not valid validation message appears in the bottom of the dialog.

TODO-1.0: Once we proceed with Rich Properties Window - on error the focu will remain in the component and a validation message appears. And the user can rollback with ESC key to the last know valid value.TODO-TPR3: The validation mechanism for other components needs to be also mocked up.
Jirka (03/03/2006):This should be the result of the recent controversy around Apply/Cancel button etc.

General Design Rules

This section contains mockups of the property editors, however please note that in the final implementation, they should conform to the user interface design guidelines. The following rules should be kept in particular:

• The insets between the components and the boundary of the dialogs should be 12 px.'
• The insets between the components and the boundary of a tabbed pane should be 11 px from top and 8 px from left, right and bottom.
• There should be 17 px gap between the content of the dialog and bottom button group.
• Within the panels, there should be 5 px inset between related components, and 11 px between unrelated components.
• Scrollpanes should have a border.

Bellow the mockups there are also often refining directives.

2. Process Editor

Main

Figure - Process Editor - Main

• Mnemonics are assigned as follows:
  

• ^Name
• ^Target Namespace
• ^Query Language
• ^Expression Language
• ^Suppress Join Failure
• ^Enable Instance ^Compensation
• ^Abstract Process

Variables

Figure - Process Editor - Variables

• Missing mnemonics, suggesting:
  

• ^Add
• ^Edit
• ^Remove
  

Figure - Process Editor - Variables - Create New Variable

• Mnemonics is assigned as follows:
  

• ^Name
• ^Simple Type
  
• ^Message Type
• ^ Element Type
  

The content of the Name text field (the default value) is selected, in order to allow the user to immediately start typing a new name without the need to remove the content of the field first.

• This does not apply to the "Edit" dialog!
  

If the Name is empty, the OK button should be disabled and a validation message should appear, saying "Name is required."

If the Name is not unique or invalid identifier, a validation message "Name must be unique!" should appear.

 

Figure - Process Editor - Variables - Create New Varialbe - Simple Type

Design Details:

• The title should reflect the action that invoked the dialog; thus here it should be "Choose Simple Type"
• The label under the tree should be: "Simple Type:"
  
• First node should be selected, when the dialog appears, to announce that keyboard navigation is possible.
• Items should be ordered alphabetically.
  

QUESTION: Is this showing all simple types defined in various resources or just those defined in the XML Schema specification? Should show all.

• if it shows just the basic set, then the root node is not necessary, as there would be only one root node.

Figure - Process Editor - Variables - Create New Varialbe- Message Type

Design Details:

• The title should reflect the action that invoked the dialog; thus here it should be "Choose Message Type"
• The label under the tree should be: "Message Type:"
  
• Scrollpane should have a border.
• The focus should be on the first node of the tree when dialog appears.
• The root node "Message Types" is not neccesary, should be removed

Figure - Process Editor - Variables - Create New Varialbe- Element Type

Design Details:

• The title should reflect the action that invoked the dialog; thus here it should be "Choose Element Type"
• The root node "Element Types" is not neccesary, should be removed (not necessary). What about just having the schema and WSDL files as siblings, without any parent?
• Scrollpane should have a border.
• The focus should be on the first node of the tree when dialog appears.

Properties

Figure - Process Editor - Properties



Figure - Process Editor - Properties - Create New Correlation Properties

Property Aliases

Figure - Process Editor - Property Aliases




Figure - Process Editor - Property Aliases - Add New Property Alias

There should be two browse buttons instead of just one tall button

• Message Part Chooser appears with title "Choose Message Part"
  

Correlation Set

Figure - Process Editor - Correlation Sets

Assign Activity

TODO-TPR3: BPEL Mapper needs to be integrated here.
Figure - Assign Editor

Expression Builder

TODO-TPR3: BPEL Mapper needs to be integrated here.



Figure - Expression Builder

Notes:

• Variables root node not necessary.
  

Invoke Activity

 

Design Details:

• The focus should be in the tree when the dialog pops up.
  
• Create button should be enabled on the Process node as well as on Variables Container.
  
• There should be Expand/Collapse button on the Process node or it should not be possible to collapse it. (Ok, this is controversial as well, you may argue, and I would need to check guidelines). But makes sense, does it?
• The OK button should be disabled if any variable is not selected.
• Variables of compatible types should be highlighted and first should be preselected. Or maybe the dialog should show only variables of compatible types ...

Receive Activity

Reply Activity

Conditional Case of an If activity

Switch case editor is equal to expression editor - as there is only expression attribute on this element.

onMessage Editor

onAlarm Editor

Partner Link

no role items in the comboboxes should be more descriptive.

This is the original content - specification of the modal dialogs - very incomplete. Should be replaced with mockups for rich content of the properties window.

3.2. Element Editors

When an element of a diagram is selected, property sheet window is updated with the list of properties relevant to the selected element. The properties of some elements can be also edited in modal dialogs (element editors), which are invoked by the "Edit" contextual menu action or double-click on the element. The contents of the property sheet as well as the element editors are specified in this section.

3.2.1. Process

Property Sheet

• Name (Required)
  
• Target Namespace TODO: What is the use case? How does it fill to our XML tools story?
  
• Query Language TODO: Preset by default; Should not be exposed as the Query language is tool-defined?
  
• Expression Language TODO: dtto

Mike: Read-only for now

• Suppress Join Failure (Checkbox)
  
• Enable Instance Compensation (Checkbox)
  
• Abstract Process (Checkbox) TODO: Again - is it reasonable to set this true, as the Orchestration Designer UI exclusivly creates nonabstract processes?
  Mike: needs to be explored in the future.
  
• Additional namespaces - Mike:
  

TODO: Functional spec should say, where are these properties persisted.

Element Editor

TODO: If we decide to draw the process pool, then there should be an element editor for it. Otherwise, this information may be in a different view.

A multitab editor: Process | Variables | Correlation Sets

TODO: To be specified

3.2.2. Sequence

Property Sheet

• Name (Optional)
  

Element Editor

No provided.

3.2.3. Switch

Property Sheet

• Name (Optional)
  

Element Editor

No provided.

3.2.4. Case Branch

Property Sheet

• Name (Optional) - Functional spec: the name will be stored in the "implicit branch sequence" element (TODO: which is still an unresolved issue).
  
• Condition - Pops up the Condition Builder instead of default property editor

Element Editor

Brings up the Condition Builder.
TODO: The title of the dialog should be different; the Element Editor might also contain name.

3.2.5. Otherwise Branch

Property Sheet empty, no Element Editor.

3.2.6. Pick

Property Sheet

• Name (optional)
• Create Instance (checkbox)
  

Element Editor

None provided.

3.2.7. OnMessage Branch

TODO: To be specified later.

3.2.8. OnAlarm Branch

TODO: To be specified later.

3.2.9. Flow

3.2.10. Invoke Activity

Property Sheet

• Name (Optional)
  
• Partner Link (dropdown, containing all partnerLinks visible at the point of the activity)
  
• Operation (dropdown, containing all operations of the selected partner defined within partner's role)
  
• Input Variable (dropdown, containing all variables visible at the point of the activity)
• Output Variable (dtto)
  

TODO: Behaviour in regards to change of a property and consequent message flow rerouting.

Element Editor

A multitab editor: Recieve Activity (TODO: name to be polished) | Correleations
TODO: This could be also solved with multiple pop up dialogs, i.e. "Edit" & "Edit Correlations". - to be decided, based on use-cases & workflow

3.2.11. Recieve Activity

Property Sheet

• Name (Optional)
• Create Instance (checkbox)
  
• Partner Link (dropdown, containing all partnerLinks visible at the point of the activity)
  
• Operation (dropdown, containing all operations of the selected partner defined within partner's role)
  
• Input Variable (dropdown, containing all variables visible at the point of the activity)

TODO: Behaviour in regards to change of a property and consequent message flow rerouting.

Element Editor

A multitab editor: Recieve Activity (TODO: name to be polished) | Correleations
TODO: This could be also solved with multiple pop up dialogs, i.e. "Edit" & "Edit Correlations". - to be decided, based on use-cases & workflow

3.2.12. Reply Activity

Property Sheet

• Name (Optional)
• Partner Link (dropdown, containing all partnerLinks visible at the point of the activity)
  
• Operation (dropdown, containing all operations of the selected partner defined within partner's role)
  
• Output Variable (dropdown, containing all variables visible at the point of the activity)

TODO: Behaviour in regards to change of a property and consequent message flow rerouting.

Element Editor

A multitab editor: Recieve Activity (TODO: name to be polished) | Correleations
TODO: This could be also solved with multiple pop up dialogs, i.e. "Edit" & "Edit Correlations". - to be decided, based on use-cases & workflow

3.2.13. Assign Activity

Property Sheet

• Name

Element Editor

TODO: To be specified - Mike proposes "Copy Editor"

3.2.13. Empty Activity

Property Sheet

• Name

Element Editor

None provided.

3.2.14. Partner Link

Property Sheet

• Name (Required)
  
• WSDL File
• Partner Link Type
• My Role
• Partner Role
  

Element Editor

• Name
• ...
• Properties
  

TODO: Activities in general:

- name
- join condition (only if flow links are present)
- surpress join failure (only if flow links are present)

Variables Editor

Invoked by the "Edit Variables" action of process or scope contextual menu.

Assign Editor

Mockup

+-----------------------------------------------------+
| Edit(Add) Assign Activity                           |
+-----------------------------------------------------+
| Name: | assignPaymentLineItem                     | |
|                                                     |
| Copy Rules:                                         |
| |----------------------------------|  [    Add    ] |
| |       From       |       To      |  [    Edit   ] | 
| |----------------------------------|  [   Remove  ] |
| |                  |               |                |
| |                  |               |  [  Move Up  ] |
| |                  |               |  [ Move Down ] |
| |                  |               |                |
| |                  |               |                |
| |----------------------------------|                |
|                                                     |
|                       [  OK  ]  [ Cancel ] [ Help ] |
+-----------------------------------------------------+

Figure - Mockup of Edit Assign Activity Editor

Note: The title of the dialog is "Edit Assign Activity" or "Add Assign Activity" (in case of eager scenario).

Copy Rules Table Contents

The values in the cells are formatted in the following way:

Partner Link: $partnerLink.name ($partnerLink.role)
Variable: $variable.name
XML Fragment: $literalValue

TODO: We may want to reiterate on this design & implementation - we may want to have a richer table row rendering (with icons).

Behaviour

• Edit and Remove buttons are enabled only if a row is selected.
• Add and Edit dialog pop up a the "Copy Rule Editor"
• Remove button removes the selected row in the table
• Move up button is only enabled if non-first row is selected. If the button is pressed, selected rule is moved one level up and remains selected.
  
• Move down button is only enabled if non-last row is selected. If the button is pressed, selected rule is moved one level down and remains selected.
• OK button commits the changes and closes the window.
  
• Cancel button closes the window without commiting any changes.
  

Copy Rule Editor

TODO: The XML Literal (fragment) editing feature may reuse the XML tools capabilities. When the developer specifies the target variable of a certain type, the tool could assist in the creation of the "XML document".

Correlations Editors (& Property Editor)

Fault QName Editor (???)

Other Editors

Some notes for functional specification:

This is how the 'duration of for' and 'deadline of until' should be formatted.

http://www.w3.org/TR/xmlschema-2/#duration
http://www.w3.org/TR/xmlschema-2/#dateTime

---

1. General Comments

The following applies almost to all the dialogs.

Refresh button
    - what is the use case?

Insets

• in a dialog: 12 px from all sides (wrong everywhere)
  
• in a tabbed pane: 11 px from top, 8 px from left, right and bottom (wrong everwhere)
• 17 px between the content of the dialog and bottom button group (probably kept everywhere)
• between components:

• vertically: 5px if semantically close, 11 px if semantically distant
• horizontally: 11 px between label and component
  

Scrollpanes should have a border (missing everywhere).

Wording

• Instead of Delete there should be "Remove"
  

• (The guideline is to use Add with Remove or Create with Delete, whereas the former "Add/Remove" is prefered)

Instead of "..." there should be "Browse..." on the Browse buttons

Titled Border

• it is preffered not to use Titled Border (due to space consumption), it should be replaced with labels, the left inset of the related components should be 19 px then.
  

Choosers Summary

Type Chooser - Element Type

This chooser is invoked in the following scenarios:

• Add a Variable
  TODO-postTPR3: Also Add a Property

Mockup (example):

|---------------------------------------|
| Select Type                           |
|---------------------------------------|
| Select an element type:               |
| |-----------------------------------| |
| | -- [S] schema1.xsd                | |
| | |   -- [e] elementType1
| | |   -- [e] elementType2
| | -- [S] schema2.xsd
| | |   -- [e] elementType1
| | |   -- [e] elementType2
| | -- [W] wsdlfile1.wsdl
| | |   -- [e] elementType1
| | |   -- [e] elementType2
| | -- [W] wsdlfile2.wsdl
| | |   -- [e] elementType1
| | |   -- [e] elementType2
| | -- [S] folderA\schema3.xsd
| | -- [W] folderA\wsdlfile3.wsdl
| | |   -- [e] elementType1
| | |   -- [e] elementType2 
| | -- [W] folderA\folderB\wsdlfile3.wsdl
| | |   -- [e] elementType1
| | |   -- [e] elementType2
| | -- [S] folderA\folderB\zipcodes.xsd
| |     -- [e] elementType1
| |     -- [e] elementType2          | |
| |----------------------------------- |
| [ ] Show Imported Files Only         |
|                                      |
| Type: |                            | |
|                  [  Ok  ] [ Cancel ] |
|--------------------------------------|

Description, contents:

• The title of the window is "Select Type"
• The tree contains all the available web resources - see the section related to all choosers - and the element types that are defined in those resources.
  

TODO-TPR3: Improted files could be badged - but is the context of badging clear? I.e. the files won't be badged in the project tree, the badging in the choosers will change based on what process is being edited, etc.

Type Chooser - Simple Type

Same as Element Type chooser, just the contents and labels are changed appropriately.

Type Chooser - Message Type

Same as Element Type chooser, just the contents and labels are changed appropriately.

Property Chooser

This chooser is invoked by the "Add Property ..." contextual menu actions of the Correlation Set node in the Navigator window.

Mockup (example):

|---------------------------------------|
| Select a Property                     |
|---------------------------------------|
| Select a property:                    |
| |-----------------------------------| |
| | -- [W] wsdlfile1.wsdl
| | |   -- [p] property1
| | |   -- [p] property2
| | -- [W] wsdlfile2.wsdl
| | |   -- [p] property1
| | |   -- [p] property2
| | -- [W] folderA\wsdlfile3.wsdl
| | |   -- [p] property1
| | |   -- [p] property2 
| | -- [W] folderA\folderB\wsdlfile3.wsdl
| | |   -- [p] property1
| | |   -- [p] property2
| |----------------------------------- |
| [x] Show Imported Files Only         |
|                                      |
|                  [  Ok  ] [ Cancel ] |
|--------------------------------------|

Description, contents:

• The title of the window is "Select Property"
• The tree does not have a single root node.
• The tree contains avaialable WSDL files and properties defined in these files - see the section related to all choosers. The specification of the property node follows:
  

• [p] property
  - label: name of the property
  - tooltip: type of the property (fully qualified name)
  

TODO-postTPR3: We need a messagePart/query choose for creating a propertyAlias.
- see thread "Re: please see "Process “Property and Property Alias” tabs" section of TPR3 Features doc" on bpmn-dev mail alias.

3. Update on message part/query chooser related to change in BPEL 2.0
It seems that there are new attributes on the propertyAlias elements, which were not present before (type, element). See section "7.3 Defining Property Aliases" of http://www.oasis-open.org/committees/download.php/16525/wsbpel-specification-draft%20feb%2001%202006%20no%20tracking.htm
 

Shared Behaviour of All Choosers

This section describes the features, which are shared with all the choosers.

• The tree does not have a single root node.
• The tree contains:

• [S] Schema file and [W] WSDL file nodes
  - on top level all the available web resources (contained in or referenced by the project)
  - ordered alphabetically, whereas the structure is kept - i.e. first all the files from root are shown; then all the files from the first folder; then all the files from the first folder within the first folder, etc.
  - tooltip: target namespace of the web resource
  
• [e] Element Type
  - label: localname of the element type

The checkbox "Show Imported Files Only" is unselected by default. Its value is kept across invocations of the dialog and the IDE.
If it is selected, the tree does not contain all the available web resources but only those, which are being improted by the currently edited process.

If a type from file, which has not been imported yet, is chosen, the file is imported automatically, while the prefix is determined with an algorithm described in Add Import Dialog. If any acceptable prefix was not found, the Add Import Dialog pops up (with prefilled values) and the user is supposed to fill in the prefix manually.

• If the "Add Import" dialog is not confirmed, the focus goes back to the type chooser.
  

Add Import Dialog

#
This dialog may be invoked explicitly with the "Add Import ..." contextual menu action of the Imports node in the Navigator window, or in certain cases from a type chooser.

|----------------------------------------------|
| Add Import                                   |
|----------------------------------------------|
| File:      |                    | [ Browse ] |
| Namespace: |                    |            |
|                                              |
| <validation message>                         |
|                          [  Ok  ] [ Cancel ] |
|----------------------------------------------|

Description:

• File - editable text field

• If the dialog is brought up implicitly, the text field is preset with the relevevant file.
• Once the file is set (with a browse button or manually - on focus lost) the namespace and prefix text fields are filled out.
  

Browse button

• Brings up a file chooser allowing the user to pick a web resources available to the process.

Namespace - non editable text field

• The namespace is determined from the file.

Validation - if any of the following cases occurs, the Ok button is disabled and one of the following messages appear:

• If the file is not valid: "File is not valid."
• If the file does not exist: "File does not exist."

Once confirmed, the dialog will add <import> element into the BPEL process and namespace prefix definition in the the root node of the BPEL file. The prefix is unique and determined automatically, as most of the users probably don't care about prefixes much.

TODO-postTPR3: Jirka: What is the relationship of the <import> BPEL element and the catalog.
See "RE: <import> support in bpel" on jetstream mail alias.