Chapter 2. Choreography Description Designer

2.1. Choreography Concepts

This section presents the different components that can be found in the Choreography Description. Although most of the concepts are very similar to their WS-CDL counterparts, some of the concepts are not directly related. Therefore, where necessary, the mapping between a Choreography Description component and its equivalent WS-CDL syntax will be explained.

Property	Description
Name	The name of the channel type
Description	Longer descriptive text to explain the purpose of the type within the choreography
Action	This property defines whether the channel type supports "request/response" or just "request" or just "response" messages
Role Type	This property identifies the destination role type associated with the channel type - this role type is effectively the provider of the service
Behavior	This field defines the optional behavior, within the identified role, that this channel type is associated with
Reference Token	This field identifies the type of the service endpoint reference
Usage	This field identifies the permitted usage pattern for the instances of this channel type - "once" means that only a single interaction can be performed on a channel instance, "unlimited" means that it can be used any number of times

Within a complex choreography, that has multiple channel instances (whether the same or different channel type), it is necessary to ensure they each have their own identity. It is also important to understand how these many channel instances relate to each other within a particular choreography session instance.

The information required to derive the identity of a channel instance is defined using the 'Identity' element(s) under the channel type. This mechanism is described further in another section.

The Channel Type can declare restrictions on the channels that are passed (within an interaction) across an instance of this channel type. These restrictions are defined by creating a 'Passed Channel Details' element under the channel type. The properties for this element are:

Property	Description
Name	The name of the channel type
Description	Longer descriptive text to explain the purpose of the passed channel restrictions
Action	This property defines whether the channel type can be passed within both a request/response, or only in either a request or a response
Channel	The channel type being passed
New	Whether the passed channel is being created, and the 'client' end of this new channel is being passed to enable the other end of the current channel instance to be able to 'callback' the participant sending the passed (newly created) channel instance

2.1.1.6. Information Type

The Information Type component is used to provide abstract data types that can be used by other elements of the choreography. Some examples being the declaration of variables, used to store messages being exchanged or state that is evaluated by expressions, and defining the type of tokens used for correlating messages to a choreography instance. The properties of this component are:

Property	Description
Name	The name of the information type
Description	Longer descriptive text to explain the purpose of the type within the choreography
Element Name	Refers to an XML Schema element
Type Name	Refers to an XML schema simple type, or a WSDL1.1 message type

2.1.1.7. Tokens and Locators

A Token is simply an alias for a piece of information of a particular type.

A Token Locator is a means of extracting a piece of information (aliased by a token), from a complex data type (e.g. a message).

We may have two or more data types that all contain a particular piece of information (such as an id). If we wish to refer to the piece of information in a consistent manner, regardless of the different data types, then we need a way to reference this field using an appropriate alias.

Therefore, the first step is to declare a token to represent the generic piece of information we are interested in. The Token element has a name property to uniquely identify the token, a description property and finally a reference to the Information Type appropriate for the Token.

The next step is to define a Token Locator to describe how the information related to the token can be extracted from an Information Type (representing the complex data type) that contains this field. One token locator would be required for each combination of token and data type that contains the token field. The locator has properties:

Property	Description
Description	Longer descriptive text to explain the purpose of the token locator
Information Type	The information type that is being examined to retrieve the information associated with the token
Part	If the information being examined to extract the token field is a WSDL1.1 message, then this optional part name can identify the appropriate part of a multipart message
Query	The XPath expression used to extract the field from the source information
Token	The token representing the data to be extracted

2.1.2. Activities

The list of activities within the choreography description are described in this section.

2.1.2.1. Assign

The Assign activity provides the mechanism for assigning values to one or more variables, within an atomic unit. This means that if a failure should occur during this assignment activity, then the activity will undo any work it has already done, leaving the state as it was prior to the activity commencing.

The result of an assignment, where the source information is unavailable (see isVariableAvailable function), is undefined. A Conditional or When activity, used in conjunction with the isVariableAvailable function,can be used to ensure this does not happen.

The Assign activity requires an associated role type. This role type indicates at which role the assignments are being performed. The role type can be selected from a dropdown list, which will contain any role types that have been defined within the Choreography Description:

The next step is to define the information associated with each variable that is being assigned. This is achieved by creating a new 'Copy Details' element, under the assign component, for each variable being assigned:

The properties for this 'Copy Details' element are described in the table below:

Property	Description
Name	Short name for this component
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Source Expression	The XPath expression used to derive the value that will be copied into the target variable - if a source expression is defined, then the following source variable field should not be specified (i.e. these fields are mutually exclusive)
Source Variable	The source variable whose value will be copied into the target variable - if a source variable is defined, then the source expression field should not be specified (i.e. these fields are mutually exclusive)
Source Variable Part	If a source variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
Target Variable	The target variable into which the copied value will be assigned
Target Variable Part	If a target variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
Cause Exception	If this field is specified, then this copy statement is intended to cause an exception (of the type defined by the value within this field) to be raised

2.1.2.2. Choice

The Choice activity provides the mechanism to enable a choreography to define two or more mutually exclusive paths. The path is selected based on the outcome of observable or non-observable situations. These situations may be related to the evaluation of observable expressions that operate on the state managed by the choreography (i.e. variables). They may relate to events (e.g. messages) that are being sent and received by the participants.

For example, a Choice construct is typically used to represent the alternate paths that may be enacted based on whether a normal or fault response is received following a request being sent. Therefore two paths may be declared, one with the interaction defined to exchange the normal response, and then other defined to exchange the fault response. From the perspective of the participant that is sending the normal or fault response, it could have a non-observable condition which may be internally evaluated (and therefore not defined within the choreography), to determine which path to take. The receiving participant equally does not have any observable expression to determine which path to take. It will use the type of the received message to determine which path is appropriate.

2.1.2.3. Conditional

The Conditional component within the Choreography Description is used to represent a decision point, where the path taken through a choreography is dependent upon the evaluation of an expression.

Property	Description
Name	Short name for this component
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Expression	The XPath expression representing the predicate

The Conditional component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:




    <workunit name="ncname"

                  guard="xsd:boolean XPath-expression"?

                  repeat="xsd:boolean XPath-expression"?

                  block="true|false"? >

              Activity-Notation

    </workunit>

The expression field of the Conditional component is mapped onto the guard attribute of the workunit. The semantics of the Conditional activity does not support repetition, and so the repeat attribute in the workunit is not set.

The block attribute on the workunit will be set to 'false', as the semantics for the Conditional activity does not support blocking.

2.1.2.4. Finalize

The Finalize activity is used to initiate the finalization handling for a choreography that has previously been performed (using the Perform activity).

The finalization details are defined with the following properties:

Property	Description
Name	Short name to identify the finalize activity
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Choreography	This property defines a reference to the enclosed choreography that is being finalized - and can be selected from a dropdown list
Choreography Instance Id	This property is an optional XPath expression, and can be used to identify a specific instance of the choreography to be finalized, in cases where multiple instances of this choreography have been performed
Finalizer	This property references the finalization handler that is to be used within the enclosing choreography

2.1.2.5. Interaction

The Interaction activity is the main activity that represents the communication between the various participants and roles defined within a choreography.

Unlike most business process specifications, which identify the act of communication from a particular endpoint's perspective using a send or receive primitive, the choreography is defined from the global perspective. Therefore the Interaction activity encapsulates both the sending of messages and the subsequent receiving of these messages as a single concept. This ensures that both endpoints nvolved in a communication are correctly synchronized.

The Interaction defines the following properties:

Property	Description
Name	A short name used to describe the interaction
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Align	This is a boolean property that indicates whether the result of this interaction should be aligned at the communicating endpoints - i.e. they both agree that they have the same resulting state before the interaction completes
Channel Variable	This is the reference to the variable that represents the channel instance on which to communicate
Initiate	This is a boolean property that indicates whether this interaction is responsible for initiating the choreography
Operation	The operation name, which should be valid for the receiving role type's behavior
Relationship	The relationship type associated with this interaction
Timeout "From" Role Type Record Details	Whenever a timeout occurs, the record details associated with this list will be performed at the 'from' role type
Timeout "To" Role Type Record Details	Whenever a timeout occurs, the record details associated with this list will be performed at the 'to' role type
Time To Complete	This field identifies the duration to wait for the interaction to complete, and if it does not complete during the specified time interval, then a timeout should occur

2.1.2.5.1. Exchange Details

Associated with the interaction is one or more exchange elements. These elements provide the details of the messages that will be exchanged between the two roles involved in the interaction. The properties associated with an 'Exchange Details' element are:

Property	Description
Name	A short name used to describe the exchange
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Action	This field identifies the direction of the message, whether it is a 'request' from the 'from role' to the 'to role', or a 'respond' message in the opposite direction, which may be a normal message or a fault
Fault Name	This optional field identifies the name of the fault associated with this exchange
Receive Cause Exception	This optional field is used to indicate the type associated with an exception that is raised at the receiving role, related to the direction of this exchange
Receive Record Details	This field provides a list of 'Record Details', associated with the same interaction, that are triggered in the receiving role
Receive Variable	This field identifies the optional variable that will contain the information received as part of the exchange
Receive Variable Part	If a receive variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
Send Cause Exception	This optional field is used to indicate the type associated with an exception that is raised at the sending role, related to the direction of this exchange
Send Record Details	This field provides a list of 'Record Details', associated with the same interaction, that are triggered in the sending role
Send Variable	This field identifies the optional variable that contains the information being sent as part of the exchange
Send Variable Part	If a send variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
Type	This field identifies the information type for the information being exchanged

2.1.2.5.2. Record Details

The 'Record Details' define information that must be assigned to variables as a result of an exchange occurring. The properties associated with this element are:

Property	Description
Name	A short name used to describe the exchange
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Cause Exception	This optional property indicates the type of exception that will be raised on the occurance of this record
Source Expression	This property defines the source XPath expression that will identify the value to be recorded. This field is mutually exclusive with the source variable field
Source Variable	The source variable whose value will be copied into the target variable. If a source variable is defined, then the source expression field should not be specified (i.e. these fields are mutually exclusive)
Source Variable Part	If a source variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
Target Variable	The target variable into which the copied value will be assigned
Target Variable Part	If a target variable is specified that represents a WSDL1.1 multipart message, then this field can be used to specify the relevant part name
When	This property identifies at what point the record statement should be performed in relation to the exchange it is associated with. It can have three values: before record before the exchange occurs, after record after the exchange occurs, or timeout record if a timeout occurs

2.1.2.6. NoAction

The NoAction activity defines that the participants involved within a choreography should not perform any internal tasks that would modify the observable behavior exhibited by those participants.

This means that the participant would not be able to perform any interactions, or modify state information that is defined within the choreography.

The primary purpose of this activity is to represent a NOP (no operation), to fill slots where an activity is mandatory, but where we don't actually wish to do anything. An example would be that we may wish to indicate that a choice construct should have an option to 'not do anything' and therefore be optional.

Property	Description
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Role Type	This field is optional - if specified, identifies the role at which this 'no action' should be handled

2.1.2.7. Parallel

The Parallel activity defines that the activities that it contains will all be performed concurrently.

The parallel activity will only complete once all of the contained activities have all completed.

2.1.2.8. Perform

The Perform activity is used to indicate that the activities within a referenced choreography should occur at this point.

This mechanism supports the modularization of choreographies into reusable entities. The perform activity can refer to choreographies that are either directly defined within the performing choreography, or that are defined at the top level of the Choreography Description.

To provide the greatest reuse of choreographies, the Perform activity provides the optionally capability to bind variables within the performing choreography with variables in the performed choreography. To achieve this binding, the variable in the performed choreography must be defined as a 'free' variable. This means that it has no direct storage of its own, but instead maps onto the storage of a variable contained within an enclosing choreography.

The properties associated with the Perform activity are:

Property	Description
Description	Descriptive text to explain the purpose of the activity within the choreography
Choreography	This property defines a reference to the choreography that is being performed - and can be selected from a dropdown list
Choreography Instance Id	This property is an optional XPath expression, and can be used to identify a specific instance of the choreography to be performed, in cases where multiple instances of this choreography will be performed and later finalized
Wait For Completion	This property determines whether the performing choreography should wait for the performed choreography to complete, before preceding to the next activity

The variable binding information is specified in an element contained within the Perform activity, called the 'Bind Details', with the following properties:

Property	Description
Name	Short name for this component
Description	Longer descriptive text to explain the purpose of the activity within the choreography
'This' Variable	This property defines the variable, within the performing choreography, that will be bound
'Free' Variable	This property defines the variable, within the performed choreography, that will be bound

2.1.2.9. Sequence

The Sequence activity specifies that the set of activities that are defined within the sequence construct should be performed one by one, in the order that they are specified.

The subsequent activity in the list can only be performed once its proceeding activity has completed. The sequence only completes when the final activity in its list has completed.

2.1.2.10. SilentAction

The SilentAction activity is similar in nature to the NoAction activity, with the difference that it indicates that the internal implementation of a participant (and role) should carry out some non-observable implementation specific tasks.

These internal tasks may modify the state information associated with the particular participant and role. However it will not be entitled to perform interactions, as this would interfere with the externally observable behavior of the role.

Properties associated with this component

Property	Description
Description	Longer descriptive text to explain the purpose of the activity within the choreography - could be used to define the requirements for the implementation of the 'silent' action
Role Type	This field is optional - if specified, identifies the role at which this silent action should be handled

2.1.2.11. When

The When component within the Choreography Description is used to describe a synchronization point where the choreography is dependent upon a predicate (condition) being true. If the information referenced within the condition is not available, then the condition will block until the information becomes available. At this point the predicate will be evaluated to determine if it is true, and if not the activity will continue to block until the predicate becomes true.

The When component has an optional 're-evaluation' condition, which is evaluated after all of the activities within the 'when' component have completed, to determine whether the conditional expression (associated with the 'when' component) should be evaluated again. This provides the ability for the When component to be repeated multiple times - each time being synchronized based on the expression associated with the 'when' component.

The semantics of the when component can be written as:

    when (C) {
        activities
    } [ until (!R) ]

where C represents the condition and R represents the optional 're-evaluation' expression. The activities in the body of the When component are only performed if the condition C evaluates to true. Then the condition is only re-evaluated if R is either not specified, or evaluates to true.

Properties associated with this component:

Property	Description
Name	Short name for this component
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Expression	The XPath expression representing the predicate on which this 'when' component is synchronized
Re-Evaluate Condition	The XPath expression to determine if the 'when' condition should be re-evaluated after the iteraction has completed

The When component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:




    <workunit  name="ncname"

                  guard="xsd:boolean XPath-expression"?

                  repeat="xsd:boolean XPath-expression"?

                  block="true|false"? >

              Activity-Notation

    </workunit>

The expression field of the When component is mapped onto the guard attribute of the workunit, and the re-evaluation condition is mapped onto the repeat attribute.

The block attribute on the workunit will be set to 'true', as the When semantics require the condition to block until all of its information is available, and the predicate evaluates to true. The non-blocking semantics are described by the While activity.

2.1.2.12. While

The While component within the Choreography Description is used to describe a repetition that is dependent upon a condition being true. The condition is evaluated prior to performing each iteration of the activities contained within the scope of the While component.

What makes the semantics of the while component slightly different from a normal 'while' construct in a programming language, is that after an iteration has been performed, an optional 're-evaluation' condition can also be specified, to determine whether the conditional expression (associated with the while component) should be evaluated again. This provides the ability to break out of the repetition without unnecessarily complicating the while condition.

The semantics of the while component can be represented using the following:

    while (C) {
        activities
    } [ until (!R) ]

where C represents the condition and R represents the optional 're-evaluation' expression. Each iteration only proceeds if the condition C evaluates to true, and the condition is only re-evaluated if R is not specified or also evaluates to true.

Properties associated with this component:

Property	Description
Name	Short name for this component
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Expression	The XPath expression to determine if the repetition should occur
Re-Evaluate Condition	The XPath expression to determine if the repetition condition should be re-evaluated after the iteraction has completed

The While component is mapped onto the WS-CDL workunit activity. The syntax of a workunit is:




    <workunit  name="ncname"

                  guard="xsd:boolean XPath-expression"?

                  repeat="xsd:boolean XPath-expression"?

                  block="true|false"? >

              Activity-Notation

    </workunit>

The expression field of the While component is mapped onto the guard attribute of the workunit, and the re-evaluation condition is mapped onto the repeat attribute.

The block attribute on the workunit will be set to 'false', as the While semantics do not wait for information to be available, or require the condition to be true before proceeding. The blocking semantics are described by the When activity.

2.1.3. Expressions

2.1.3.1. CDL Functions

Within expressions defined in a choreography, it is possible to make use of a set of pre-defined functions which are prefixed with the letters "cdl:". The list of these choreography description language functions are:

any getChannelIdentity(string varName)
        The function can be used to return the identity information associated with a channel instance.
 
 
any getChannelReference(string varName)
        The function can be used to return the endpoint reference information associated with a 
        channel instance.
 
 
date getCurrentDate(QName roleName)
        The function can be used to retrieve the current date. This function will be performed
    locally at the role identified by the roleName parameter.
 
 
dateTime getCurrentDateTime(QName roleName)
        The function can be used to retrieve the current date and time. This function will be
    performed locally at the role identified by the roleName parameter.
 
 
time getCurrentTime(QName roleName)
        function can be used to retrieve the current time. This function will be performed locally
    at the role identified by the roleName parameter.
 
 
any getVariable(string varName, string part, string documentPath, QName roleName?)
        The function can be used to obtain the information associated with a named variable. If the
    variable is a WSDL1.1 message, then it will also be necessary to identify the part of the message
    that should be retrieved.
 
 
boolean globalizedTrigger(string expression, string roleName, string expression2, string roleName2, ...)
        function provides a mechanism to describe, within a single activity expression, a list
    of distinct sub-expressions that should be projected to different roles associated with
    the activity. This enables the choreography designer to determine what relevant expression
    is required at the different roles, to ensure that those roles take the same path within
    the global choreography.
 
 
boolean hasDeadlinePassed(dateTime deadlineTime, QName roleName)
        The function can be used to determine whether a particular deadline time has passed.
    Generally this function will be used within the When activity as part of the blocking
    condition, to cause the choreography to wait for the impending deadline. It may also be
    used within the 'complete' condition for a choreography, to ensure that the choreography
    finishes before the specified time.
 
 
boolean hasDurationPassed(duration elapsedTime, QName roleName)
        The function can be used to determine whether a particular time interval has passed.
    Generally this function will be used within the When activity as part of the blocking
    condition, to cause the choreography to wait for the duration. It may also be used
    within the 'complete' condition for a choreography, to ensure that the choreography
    finishes within the specified duration.
 
 
boolean isVariableAvailable(string varName, QName roleName)
        The function is used to test whether a variable has been populated with some information.
    This is required to guard against the use of an unset variable in an invalid situation.
    If an unset variable is used within the When activity, the activity will block until the
    variable is set. However, in other cases the use of such a variable is undefined.
 
 
boolean variablesAligned(string varName, string withVarName, QName relationshipName)
        The function is used to determine whether two variables, at different roles (associated
    with a relationship), have 'aligned' values. Alignment means that there has been agreement
    that the two variables have the same value.
 
 
boolean hasExceptionOccurred(QName exceptionType)
        The function returns "true" if an exception of the type identified by the parameter
    exceptionType has occurred. Otherwise it returns "false".
 
 
boolean hasChoreographyCompleted(string choreoName, string choreoInstanceId?)
        The function returns true if the performed choreography associated with the parameter
    'choreoName' and OPTIONAL choreoInstanceId has a status of completed (whether successfully
    or not). If choreoInstanceId is not specified, the function will evaluate whether all
    performed choreographies, with the supplied name, have completed. If the named choreography
    has not been performed, prior to this function being called, it will return false.
 
 
string getChoreographyStatus(string choreoName, string choreoInstanceId?)
        The function returns the current status associated with the identified choreography and
    OPTIONAL choreoInstanceId . If choreoInstanceId is not specified, then there MUST only be
    a single instance of that performed choreography in the scope of the current choreography
    that is checking the status, otherwise a status of 'ambiguous' MUST be returned. The values
    of the status can be 'enabled', 'completed-successfully', 'completed-unsuccessfully',
    'closed', 'ambiguous', or 'instance-unknown'. The 'instance-unknown' status is encountered
    when this function is invoked and when the choreography has not been enabled.

2.1.3.2. XPath Expressions

XPath is a standard notation for querying information in an XML document. Although XPath defines many constructs for accessing this information, we have introduced the most useful features below.

If you would like to read more information about XPath, then the specification can be found at: http://www.w3.org/TR/xpath.

2.1.3.2.1. Invoking a choreography function

Functions are simply invoked by expressing the function name (including the namespace) and the set of comma separated parameters within the following brackets.

For example,


    cdl:getVariable('myVar','','/order/@id','myRole')

In this example, the parameters are supplied as a set of text strings.

2.1.3.2.2. Boolean operators

The list of boolean operators, in precedence order, is:


    or
    and
    = !=
    <= < >= >

For example,


    cdl:isVariableAvailable('myVar') and cdl:getVariable('myVar','','') > 5

XPath also supports some boolean functions:


boolean not(boolean)
    The not function returns true if its argument is false, and false otherwise
 
 
boolean true()
    The true function returns true
 
 
boolean false()
    The false function returns false

2.1.3.2.3. Arithmetic operators

The list of Arithmetic operators is:


    +
    -
    *
    div
    mod

For example,


    cdl:getAvailable('myVar','','') + 1

2.1.3.2.4. String manipulation

Text strings can be defined within an XPath expression as literals within single or double quotes (depending on the context).

XPath provides a set of built-in functions for manipulating strings, which include:


string string(object?)
        Converts the supplied value to a string representation
 
 
string concat(string, string, string*)
        The concat function returns the concatenation of its arguments
 
 
boolean starts-with(string, string)
        The starts-with function returns true if the first argument string starts
    with the second argument string, and otherwise returns false
 
 
boolean contains(string, string)
        The contains function returns true if the first argument string contains
    the second argument string, and otherwise returns false
 
 
string substring(string, number, number?)
        The substring function returns the substring of the first argument
    starting at the position specified in the second argument with length
    specified in the third argument. For example, substring("12345",2,3)
    returns "234". If the third argument is not specified, it returns the
    substring starting at the position specified in the second argument and
    continuing to the end of the string. For example, substring("12345",2)
    returns "2345"

2.1.3.2.5. Location paths

Primarily, XPath is an expression language for locating information within an XML document. Therefore the language provides a way to describe how to navigate the hierarchical nodes and determine which attribute, text field or node-set should be returned. The following table provides a subset of the possible accessors that can be used - refer to the XPath specification for more details. This table describes the abbreviated form of the locators, as this form is more compact:


para
        Selects the para element children of the context node,
    e.g. /order/item, would select all 'item' nodes that were contained
    within the 'order' node
 
 
\*
        Selects all child nodes of the current context, e.g. /order/*,
    would select all nodes contained under the 'order' node
 
 
text()
        Selects all text nodes under the current context, e.g. /order/text(),
    would return any text nodes contained by the 'order' node
 
 
@name
        Selects the name attribute of the context node, e.g. /order/@id would
    return the id attribute from the 'order' element
 
 
para[1]
        Selects the first para child of the context node, e.g. /doc/chapter[5]/section[2]
    selects the second section of the fifth chapter of the doc node
 
 
para[@type="warning"]
        Selects all para children of the context node that have a type attribute
    with value 'warning'
 
 
chapter[title]
        Selects the chapter children of the context node that have one or more
    title children
 
 
employee[@secretary and @assistant]
        Selects all the employee children of the context node that have both a
    secretary attribute and an assistant attribute

2.1.4. Choreography Session Identity

This section discusses how channel instances are identified within the context of a choreography session.

This is important, as it enables messages to be correctly associated with the appropriate choreography session and channel instance, and it also enables an association to be established between multiple independent channel instances, to correlate them to the same session.

The Identity element is created as a child element of a Channel Type. The identity consists of one or more Token elements, which locate the specific parts of the composite identity information from a particular message (using Token Locators where appropriate).

The identity element has an associated type, which indicates its purpose in relating instances of the channel type to the choreography session. These types are:

Primary
This identity provides the primary key for the channel type. Only one instances of a channel type can have the same value for a particular identity. Only one primary identity can be associated with a channel type.
Alternate
As each message exchanged on an instance of a channel type will generally not have the same (primary) key value as part of its data, we need to provide alternative identity fields that can be used in place of the primary identity. To ensure that an alternate identity is associated with the appropriate channel instance, it must first occur in a message that is associated with the channel instance due to the fact that it contains either the channel instance's primary identity, or another one of its alternate identities that had previously been associated with the channel instance.
Derived
The previous two identity types were concerned with correlating messages to a particular instance of the channel type. The derived identity type concerns establishing a correlation between channel instances, to ensure that are bound to the same choreography session. When the derived identity is specified on a channel type, it means that if a message is exchanged on an instance of that channel type, that contains the appropriate information for the derived identity, then the identity will be associated with the choreography session. It is then possible to define another Channel Type that has the same identity information, but being classified as the primary identity for this other Channel Type. When a new instance of this Channel Type is created, based on the identity value previously derived from the other channel instance, then this will automatically correlate the new channel instance to the same choreography session as the previous channel instance.
Association
The association identity type is similar in purpose to the previous derived identity type, in that it is used to correlate channel instances to a choreography session. However the difference between these two identity types is that the derived identity type can be considered equivalent to a forward reference, and the association identity type can be considered equivalent to a backward reference. With an association identity, the initial channel type only defines its own identity information, and the subsequent channel type (that needs to be correlated to the initial channel type) provides the association identity element with the information necessary to map onto one of the primary or alternate identity values in the initial channel type.

2.1.5. Structure

2.1.5.1. Choreography

The choreography is the main construct that groups a set of interactions into a meaningful business transaction. Choreographies represent a module that can be reused by other choreographies, using the Perform activity, enabling more comprehensive business protocols to be assembled from simplier protocol units.

The choreography has the following properties:

Property	Description
Name	Short name for the choreography
Description	Longer descriptive text to explain the purpose of the choreography
Completion Condition	The optional XPath expression used to determine when this choreography can be prematurely completed in a successful state
Coordinated	When set to true, this property indicates that all participants involved in the choreography will be coordinated so that they all complete at the same time, and with the same status
Isolation	When this boolean property is set to true, it means that modifications made within the scope of this choreography, to bound variables in the performing choreography, will not be made visible until this choreography has successfully been completed - it also means that the enclosing and sibling choreographies will block when accessing those variables, until the isolated choreography has completed
Relationships	The optional list of relationship types that are associated with the choreography - if not defined, then the choreography will be implicitly associated with all relationship types
Root	This boolean property identifies whether this is the root choreography - only one top level choreography can be declared as root, which identifies it as the entry point into the set of choreographies included in the CDL package

2.1.5.2. Variables

Variables are used by a choreography to represent state information and channel instances. A choreography may require state information to be explicitly modeled and recorded in order to make a decision as to which path to take. A choreography that models only the observable interactions, without making any internal state visible, still needs to represent the channel instances on which interactions are performed.

The properties associated with a variable declaration are:

Property	Description
Name	The variable name
Description	Longer descriptive text to explain the purpose of the activity within the choreography
Free	When set to "true", specifies that the Variable must be bound to an equivalent (i.e. same type) variable within an enclosing choreography - this variable cannot be used in its own right without being bound
Mutable	When set to "false", specifies that the Variable information cannot change once initialized
Role Types	This property represents the optional list of role types associated with the variable - if no list is provided, then the variable will be declared at all roles associated with the choreography
Silent	This property, if set to "true", indicates that the manipulation of the value associated with this variable is non-observable, i.e. it is modified within the internal implementation of the respective choreography participants
Type	This property identifies the type of the variable - either an information type or channel type

Free variables can simply be thought of as links to real variables that have been declared in an enclosing (performing) choreography. This link is established when the enclosing choreography performs the current choreography and provides the necessary binding details to link the concrete variable with the free variable. These bound variables must be compatible in terms of type.

Silent variables can be used to define an expression in the choreography description that is based on information whose value is only known to the implemented endpoints. These variables will have their values modified by the internal implementation of an endpoint, and therefore it cannot be expressed in observable activities within the choreography.

2.1.5.3. Exception Handling

Exception handling provides a mechanism to enable a choreography to terminate based on the occurence of a situation. The exception is raised based on a piece of information, of a particular type, being recorded in a participant.

Some of the choreography activites have a property, called cause exception, to indicate that when the activity is performed, then an exception of the type associated with the activity should be raised. If a choreography is coordinated, then all of the participants within the choreography should enter the same exception handler. For non-coordinated choreographies, the interactions will need to be defined in such a way to cause the same exception to be raised at each participant.

To define an exception handler, press the 'add exception handler' button at the top of the choreography flow page, as show here:

This will create a new exception handler within the sub-choreography:

The exception handler (i.e. Exception Work Unit) element has properties to define the name and description of the exception handling activity. It also has a property to select the information type associated with the exception to be handled. If an exception information type is not specified, then the associated exception workunit will become the default exception handler to catch any exception information type that has no explicit handler - only one default exception work unit can be defined for a choreography.