What Changes the Interface Using the Contract Last Approach

If a process uses a generated WSDL, making any of the changes described in this topic will result in changes to the generated WSDL, meaning that the application cannot be upgraded.

Any Contract Last process that contains a task or a service that can expose a web service can be affected by changes in its interface. Projects containing the following tasks or events can be affected:

 Receive tasks
Start Message events
Intermediate Catch Message events
Error End events

Even though throw message events (intermediate and end) may be used as a reply to an incoming message activity, when it is used as such no configuration is made on the send task that affects the interface (it is wholly derived from the incoming message activity is is associated with).

For throw error events, the associated parameters form the content of the fault message.

If your Contract Last Process As A Service (PAAS) project contains any of these objects, it will include one or more generated WSDLs. It is only if your project has a generated WSDL (not an imported WSDL) that any changes that you make to the project are at risk of automatically altering the service interface. If so, the folder Generated Services will exist in Project Explorer, under the relevant project.

In this folder are one or more generated WSDLs - in this illustration, ProcessPackage.wsdl. You can open this WSDL in order to see its contents.

You can upgrade the application as long as the WSDL, or WSDLs, do not change.

The following process changes can trigger a change in a generated WSDL:

Changing Tasks or Events

If any of the incoming message activities or message events listed in What Changes the Interface Using the Contract Last Approach? change, the service interface changes. Changes that have that effect include:

  • Removing such a task or event.
  • Changing the name of a task or event.

    Changing the label without changing the name is permitted because the label is for users’ convenience and is not used by the code, it does not affect the interface).

These items and their names are used to automatically generate the operations within the WSDL and therefore will trigger a WSDL change if they are changed.

You can add other kinds of tasks or events to the process without the interface being affected, and will still be able to upgrade the application.

Best Practice

If you expect these items to change then use the Contract First approach to define the service, including the operations and map from the supplied WSDL to the process definition.

Changing the Name of the Process

If you change the name of an application or of a process, its service interface changes. The port type it represents will no longer be available.

Retaining Previous WSDL Versions

It is recommended that all previous deployed generated WSDL versions are source controlled along with the process artifacts, so that you can subsequently compare them with the latest WSDL version being deployed.

Changing Parameters

If you change any of the parameters used by a Message Start event, Message Error End event, Intermediate Catch event, or a Receive task, used to expose a web service operation, the change will change the WSDL and the interface that it defines. This applies if you:

  • Add a parameter,
  • Delete a parameter,
  • Rename a parameter,
  • Change the name of a type referenced by a parameter,
  • Change the type of a parameter
    Note: When the BOM data type is used, then the referenced BOM data type and any other BOM data types that it references, directly or indirectly, must remain unchanged. This check is restricted to only this set of BOM types and other BOM types defined in the same BOM packages that are not referenced via incoming message activity parameters can be changed.
  • Change the length of a parameter.

Best Practice

Changing an interface is changing a contract and therefore will prevent application uprade. Due attention should be paid to ensuring that the interface design takes account of the foreseeable future design requirements of the interface. The Contract First approach will naturally drive towards taking this into account.

There are a number of data-related changes which one might normally want to make to an interface which are compatible with the existing deployed clients using this interface. However, this is not allowable for application upgrade because in that circumstance there is only a single end-point for the service but incoming requests may be directed towards existing process instances from older versions of the application that are developed with the old data models and service operations. Such changes would therefore be incompatible with the existing process instances that would be using the new interface.

These include (but are not necessarily limited to):

  • Lengthening of a parameter, for example changing a string(10) to string(20), int to bigint, and so on.
  • Addition of optional parameters.

Depending upon your use case, you may be able to use Mediation to wrap the different interface implementations that need to be active at the same time.

Adding a new operation to existing port type that uses a Contract First approach: Recommended approach

The following procedure applies when it is necessary to add a new operation to existing port type that uses a Contract First approach.

Take all these actions in the context of the Best Practice guidelines given in Changing Parameters.

  1. Add operation to the WSDL.
  2. Add an incoming message activity to the process for a new operation (using the existing participant).