Saturday, November 14, 2009

Using the Covast ebMS Adapter (part 3)

In the previous posts (part1 and part2) i have described some features of the Covast ebMS Adapter and the usage of pipelines to set the message properties and destination.

When using orchestrations, the message can be sent directly to the message box because the message context properties can be set inside the orchestration. This approach can be used to implement additional requirements in inter party communication such as error handling, correlation and other implementations where more dynamic control is required beyond the static configuration of pipelines.

Let’s build an orchestration using the ebMS context properties to send message to a specific party and collaboration protocol agreement (CPA).

‘Building an orchestration for ebMS messaging’

The orchestration in this scenario used message context properties to ensure that the correct collaboration protocol agreement was used during processing. The following paragraph, will explain the construction of this Orchestration.

clip_image002

The figure below shows the message context properties used in the scenario. These properties are set in an expression in the sample orchestration.

clip_image004

1.1.1 Create the solution

First we must create a new solution project. This must be of the type BizTalk project ‘Empty BizTalk Server project’. Name the project ‘GettingStarted’.

clip_image006


1.1.2 Add reference to Covast ebXML Message Service Adapter propertyschema

This orchestration will set the message context properties to control routing of the message. To make these properties visible to the orchestration, add a reference to the property schema in the BizTalk project as shown in the figure below. The location of the property schema is ‘C:\Program Files\Covast\ebXML Message Service Adapter\Pipeline\CovastEbmsPropertySchema.dll’.

clip_image008


1.1.3 Create the orchestration

The next step is to actually create the orchestration. This orchestration will be created step by step. The figure below shows how to create the orchestration.

clip_image010

1.1.4 Define a message type

The test message content is Xml. To accommodate this we have to create a new message type. This can be done by creating a multipart message, containing 1 part of type System.Xml.Xmldocument. Select the orchestration and go to the Orchestration view, expand types and create a message type as shown in the figure below.

clip_image012

1.1.5 Create messages

After creating the message types, the messages themselves must be created. One that represents the incoming message and another that represents the outgoing message. Both messages are of the type GetingStarted.ebMxmlMessage.

clip_image014


1.1.6 Create receive port

The orchestration starts at the moment a message is received. In BizTalk terminology, it is described as ‘instance activated’. In order to send and receive messages, we must define ports. Right click on the port surface and click ‘New Configured port’. Use the configuration as shown in the figures below.

clip_image016

The next step is to define the message type used for the ports as shown in the figure below.

clip_image018

Note: perform this step for all the ports

1.1.7 Create receive shape

To connect the message to the port, we must to create a Receive shape. Right click on the orchestration and select Receive.

clip_image020

After this, we can assign a message and operation to the receive shape as shown in the figure below.

clip_image022

1.1.8 Create receive shape

After the receive shape is created, we must assign the message that will be submitted to the messagebox. This can be done using a Message Assignment shape. Right click below the receive shape and select ‘Message Assignment’.

clip_image024

Configure the ‘Assign message’ shape to construct the outgoing message ‘clientMessage’ as shown in the figure below.

clip_image026

In the next step we can implement the code to configure the correct CPA by setting the context properties. The code is shown in the figure below and can be copy-pasted.

//Precondition:

// CPA is imported from: CPA_gettingstarted_Orchestration.xml

clientMessage = clientRequest;

clientMessage(*) = clientRequest(*);

//configure the context properties based on the CPA

clientMessage(ebMSProperties.Action) = "RequestServiceOne";

clientMessage(ebMSProperties.Cpaid) = "urn:nl:covast:orchdemo:ebms";

clientMessage(ebMSProperties.PartyName) = "OtherParty";

clientMessage(ebMSProperties.ServiceName) =

"urn:nl:covast:orchdemo:ebms:ServiceOne:0:01";

//send the message to the retry orchestration

clientMessage(ebMSProperties.ToRetry) = true;

clip_image028


1.1.9 Create send port

To submit the message we must create a send port. This port is direct-bound to the BizTalk messagebox because the ebMS orchestrations must process this message later. Create the send port using the configuration steps shown in the figure below.

clip_image030

The next step is to define the message type used for the ports as shown in the figure below.

clip_image032

Note: assign the correct message type


1.1.10 Create correlation

Because the ebMS retry orchestration listens for messages using a direct-bound port with a filter on the property ‘ebMSProperties.ToRetry’, we need to ensure that the property is ‘promoted’ (the value of a property is present in the BizTalk message context at runtime).

We can ensure that this is the case by creating a correlation type and set using the aforementioned property. The configuration is shown in the figures below.

To create a correlation type, perform the following actions:

  • Go to the Orchestration view in the

clip_image034

  • Expand the ‘Types’ node
  • Right click the ‘Correlation Types’ node and click ‘New correlation type’
  • A Correlation properties dialog will appear. Expand the ebMSProperties node.

clip_image036

  • Select the ToRetry property and click Add

clip_image038

  • Click Ok
  • Select the created correlation type and change:
    • Identifier à ‘CorrelationType_ebMS’

To create the correlation set (this is an instance of the correlation type), perform the following actions:

  • Right click on Correlation Set and select ‘New correlation set’
  • Select the create correlation set and change the following information:
    • Identifier à ‘Correlation_ebMSRetry’
    • Correlation Type à select the create correlation type ‘CorrelationType_ebMS’

clip_image040


1.1.11 Create send shape

The final step is to link the port, correlation set and message together using a send shape. Right click on the last element in the orchestration and create a Send shape.

clip_image042

After this, we can assign a message, operation and correlation set to the send shape as shown in the figure below.

Actions:

  • Choose the initializing correlation Set ‘Correlation_ebMSRetry’
  • Choose the message ‘clientMessage’
  • Change the name to ‘SendToRetryOrchestration’

clip_image044


1.1.12 Deployment setting

After creating the solution, the orchestration must be deployed. Go to the solution properties and configure the deployment settings as shown in the figure below.

BizTalk requires that all assemblies are signed with a strong name. This can be generated, but the GettingStarted package already contains a strong name key. This can be found in:

C:\GettingStarted\Scenarios\Scenario with Orchestration context properties\Solution\ GettingStarted.snk

clip_image046

When the configuration is complete, the solution can be deployed. This will create the application if it did not already exist.

Note: it is recommended to close the BizTalk Administration console during deployment.

clip_image048

1.1.13 Configure the application

When the application is deployed, the orchestration is unbound. This means that the logical ports are not mapped to physical ports. This can be done by opening the orchestration properties in the BizTalk Administration console.

Select the correct receive location as shown in the figure below.

clip_image050


1.1.14 Starting the application

To start the application, perform the following actions:

  • Right click on the application ebMS.GettingStarted
  • Select ‘Start’ from the context menu

clip_image052

  • Select ‘Start’ in the popup dialog

clip_image054

No comments: