Implementing a New PIP

Accelerator for RosettaNet documentation includes an end-to-end tutorial explaining PIP implementation. This chapter does not repeat the tutorial included in the product documentation. Instead, we will concentrate on the logical flow of a message within Accelerator for RosettaNet and how all components relate to each other. Also, the product tutorial assumes that the corresponding document schemas (DTDs) have already been downloaded (from www.rosettanet.org) and applied to the consolidated message schema. Later in this chapter we will describe how to apply a schema to the consolidated schema. In this section, we will describe what differs if you want to implement a completely new PIP.

Overview of Implementing a New PIP

Assume that we will implement the PIP 3A8: Request Purchase Order Change process, between the Home Organization and Destination Organization, where Home Organization has the initiator role.

To make it easier to understand what needs to be implemented, let's have a look at the PIP implementation overview as shown in Figure 25.8. This figure illustrates the flow of a message from initiator, to responder, and back to initiator. With this overview, it is clear that for either side we have to think of the following six factors: LOB, XLANG schedule, application adapter, PIP registration, channels and ports, and the Universal Message Schema.

To implement this process, Home Organization, the initiator role, needs to complete the following six steps:

To implement this process, the Destination Organization, the responder role, also needs to do the exact same steps as Home Organization, but with some minor differences:

Implementing the Initiator

Now we will go into the details of how to implement the initiator side. In our example, Home Organization is the initiator and would like to implement the 3A8 process with Destination Organization.

Creating the Schema

To initiate the process, as described in the PIP 3A8 specification, the Home Organization needs to perform the Purchase Order Change Request Action. This corresponds to sending a Purchase Order Change Request document to the Destination Organization. We first need to create the document schema for this action. Following steps describe how to do that:

Implementing the Initiator Application

To deliver the request message, the initiator application makes two calls to the CPIPAdapterManager interface of the PIPAdapterSDK component:

CPIPAdapterManager::StartActivity 
CPIPAdapterManager::DeliverInitiationMessage

Listing 25.3 shows a simplified piece of code showing the general structure of the initiator application.

Listing 25.3. Initiator Application

Dim PIPAdapterManager As PIPAdapterSDK.CPIPAdapterManager
    Dim strFlowID, strDocument As String


    Set PIPAdapterManager = CreateObject("PIPAdapterSDK.CPIPAdapterManager")

    'Initiate orchestration
    strFlowID = PIPAdapterManager.StartActivity( _
        "3A8", "Purchase Order Change Request", _
        "Request", "Production", _
        "Purchase Order Change Request", _
        False, _           GenerateUniqueID(), _
        GetDUNSNumber('Home'), GetDUNSNumber('Destination'), _
        strDocument)

    'strFlowID is now a moniker to the orchestration instance

    'strDocument includes skeletal consolidate message with Preamble and
    'Service Header elements filled. Service Content is left empty
    '>>> fill the Service Content in strDocument

    'Deliver Message
    PIPAdapterManager.DeliverInitiationMessage strFlowID, _ "NoCertificate", strDocument

    Set PIPAdapterManager = Nothing

The StartActivity method call initiates a BizTalk Orchestration and returns the BizTalk Orchestration moniker to strFlowId. We will use this moniker to hold the correspondence to the BizTalk Orchestration. The StartActivity method call will also fill the strDocument variable with a skeletal consolidated message. A consolidated message is an XML message stream consisting of three main elements of a RosettaNet message: namely, Preamble, Service Header, and Service Content. The StartActivity method fills the Preamble and Service Content sections automatically, but leaves the Service Content empty. We need to fill the Service Content section in the code. When the Service Content section is completed, the initiator application calls DeliverInitiationMessage. At this call, strDocument is the message to be sent. The strFlowID parameter corresponds to the previously initiated BizTalk Orchestration so that the SDK knows where to pass the message.

Implementing the Initiator Adapter

For the initiator adapter, you need to implement the IPIPInitiatorApplication interface. You will need to reference to the following type library to have this interface known by Visual Basic:

Microsoft BizTalk Server Accelerator for RosettaNet PIP Application Interfaces 
        1.0 Type Library

This interface exposes nine methods. Listing 25.4 shows the skeleton of an example code using Visual Basic. The method parameters are not shown in this example.

Listing 25.4. IPIPInitiatorApplication Interface Implementation

Implements IPIPInitiatorApplication

Private Sub IPIPInitiatorApplication_HandleError(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleResponseMessage(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleRNException(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleRNReceiptAcknowledgementException_(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleRNReceiptAcknowledgment(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleUnexpectedResponse(parameters)
End Sub

Private Sub IPIPInitiatorApplication_HandleUnexpectedSignal(parameters)
End Sub

Private Sub IPIPInitiatorApplication_InitializeRequestMessage(parameters)
End Sub

Private Sub IPIPInitiatorApplication_ValidateResponseMessage()
End Sub

IPIPInitiatorApplication provides a single interface to the BizTalk Orchestration schedule to interact with the back-end Line of Business application.

At the minimum, the interface must implement the HandleResponseMessage method. After the response comes back from the Destination Organization, the BizTalk Orchestration calls this method and passes along the response message. At this point, you may ask how the Destination Organization sends the message back. It should not really matter how the Destination Organization does this. The only thing we need to know is that the response comes through our transport layer (ReceiveRNO.ASP), then goes through the messaging components, and eventually finds its way to the Initiator Adaptor. HandleResponseMessage is the place where you need to capture the response. The example shown in Listing 25.5 saves the response message as ResponseMessage.XML into the application working folder.

Listing 25.5. HandleResponseMessage Implementation Example

Private Sub IPIPInitiatorApplication_HandleResponseMessage(p_strFlowID _ As String, _
p_strRequestMessage As String, _
           p_strResponseMessage As String, _
           p_strErrDesc As String)
    Dim XMLDOM As New DOMDocument

    'load the response into XMLDOM
    XMLDOM.loadXML p_strResponseMessage
    'save the response into the applicatio folder
    XMLDOM.save "ResponseMessage.XML"
End Sub

As such, you will need to implement all other methods—for example, HandleRNException to catch exceptions, ValidateResponseMessage if you want to do an extra validation on the response message before passing it to your backend system, or HandleRNReceiptAcknowledgement to get a handle to the acknowledge signal sent by the Destination Organization.

Initiator Orchestration

3A8 is a transaction type process—in other words, it defines a request and the corresponding response message. Therefore, for the initiator side, we should use a Transaction Initiator type of BizTalk Orchestration.

BizTalk Orchestration templates are located under the Accelerator for RosettaNet installation folder, in the PIP SDKPIP Patterns folder. To create a new BizTalk Orchestration for 3A8 initiator, do the following:

(You can find a detailed description of these steps in Accelerator for RosettaNet documentation in the Binding the Application Adapter to the XLANG Schedule page.)

Bind the schedule to SendRNMessage method as follows:

Change the data page so that it reflects the change we have just made:

Save the file and compile it into an executable XLANG schedule by selecting File, Make from the menu.

Register the BizTalk Orchestration Schedule

Next step is to let the Accelerator for RosettaNet know about this new BizTalk Orchestration schedule, so that when it needs to send a 3A8 request message, it will know which BizTalk Orchestration schedule to use. For that, we will use PIP Administrator.

Start PIP Administrator and select the Register New XLANG Schedule action. Complete the registration with the entries as shown in Table 25.4.

Messaging Components

The Messaging Configuration Wizard is a useful tool for automatically creating all necessary messaging components. For each partner pair, the wizard just needs to be run once.

To create the necessary channels, ports, organization definitions, and related settings between the Home and Destination Organizations, you will need to provide the information shown in Table 25.5.

After the wizard is complete, running it creates all necessary messaging components for the Home and Destination Organizations to talk to each other. Basically, this script creates the channels and ports as described earlier in Table 25.1.

Implementing the Responder

As described earlier in the “Overview of Implementing a new PIP” section, the responder implementation requires the same steps as the initiator implementation but with some minor differences. The differences are due to the fact that responder needs to wait for a document and then send a response. In conjunction, the back-end integration also needs to be slightly different.

Creating the Schema

To respond to a 3A8 request, the Destination Organization needs to perform the Purchase Order Change Confirmation Action. This action corresponds to replying with a Purchase Order Confirmation Request document. For that, a 3A8 response consolidated schema needs to be created and merged into the Universal Message Schema.

The necessary steps for doing this are exactly the same with what we did for the initiator. We will not repeat the steps here. The only difference is the DTD file that is being merged.

For the responder side, we will be using the DTD for 3A8 Purchase Order Confirmation Request document. As are all PIP DTDs, this one is also available for download from RosettaNet.org.

Implementing the Responder Adapter

The responder application adapter must implement the IPIPResponderApplication interface. You will need a reference to the following type library to have this interface known by VB:

Microsoft BizTalk Server Accelerator for RosettaNet PIP Application Interfaces 
        1.0 Type Library

This interface exposes six methods. Listing 25.6 shows the skeleton of an example using Visual Basic. The method parameters are not shown in this example.

Listing 25.6. IPIPResponderApplication Interface Implementation

Implements IPIPResponderApplication

Private Sub IPIPResponderApplication_HandleError(parameters)
End Sub

Private Sub IPIPResponderApplication_HandleRNReceiptAcknowledgementException _ (parameters)
End Sub

Private Sub IPIPResponderApplication_HandleRNReceiptAcknowledgment(parameters)
End Sub

Private Sub IPIPResponderApplication_HandleUnexpectedSignal(parameters)
End Sub

Private Sub IPIPResponderApplication_StartRequestHandling(parameters)
End Sub

Private Sub IPIPResponderApplication_ValidateRequestMessage(parameters)
End Sub

At a minimum, the interface must implement the HandleResponseMessage method. BizTalk Orchestration calls this method and passes along the response message. This is the place where you need to capture the message. Listing 25.7 shows an example of how to do that. In this example, we save the p_strFlowID, p_strRequestMessage, and p_strSkeletalResponseMessage parameters.

• p_strFlowID is the moniker to the responder schedule, which invoked this method. The responder application will have to use this moniker when replying back.

• p_strRequestMessage is the incoming message in its XML form.

• p_strSkeletalResponseMessage is a RosettaNet Message XML stream with the Preamble and Service Header already filled in for you. The Service Content area is left blank.

The responder application needs to pick up these three files, generate a response message, and deliver it back to the BizTalk Orchestration with the p_strFlowID unique moniker.

In this chapter, we are not going into the gory details of how to implement the rest of the methods exposed with this interface. It is straightforward. You will have to implement all these methods for a correct implementation.

Listing 25.7. Handling Requests in the Responder Adapter

Private Sub IPIPResponderApplication_StartRequestHandling _ (p_strFlowID As String, _
p_strRequestMessage As String, _
          p_strSkeletalResponseMessage As String, _
          p_strErrDesc As String)

       StrToFile "<FlowID>" & p_strFlowID & "</FlowID>", "FlowID.XML"
    StrToFile p_strRequestMessage, "RequestMessage.xml"
    StrToFile p_strSkeletalResponseMessage, "SkeletalResponseMessage.xml"
End Sub

Private Sub StrToFile(strStr as String, strFName as String)
    save strStr as strFName
End Sub

Implementing the Responder Application

The responder application needs to pick up the three files dropped by the responder adapter, generate a valid response document, and deliver it back to the responder BizTalk Orchestration.

To deliver the response message back to the BizTalk Orchestration, the responder application makes one method call CPIPAdapterManager interface of the PIPAdapterSDK component:

CPIPAdapterManager::DeliverResponseMessage 

Listing 25.8 is an example of a simple response application. The Preamble and Service Header nodes of the skeletal message were already completed automatically by Accelerator for RosettaNet at the time the responder adapter saved the SkeletalResponseMessage.XML. The application needs to fill the Service Content and call the DeliverResponseMessage method to send the response back.

To fill the Service Content, though, you will have to do some coding. One recommendation would be having a template 3A8 Service Content ready. You can then paste this template into the skeletal message and then fill in the XML element values as you want.

Listing 25.8. Response Application Example

Private Sub cmdDeliverResponse_Click(Index As Integer)
    Dim XMLDOM As New DOMDocument
    Dim PIPAdapterManager As PIPAdapterSDK.CPIPAdapterManager
    Dim FlowID As String
    Dim SkeletalMessage As String

    Set PIPAdapterManager = CreateObject("PIPAdapterSDK.CPIPAdapterManager")

    XMLDOM.async = False

    'get the flow ID
    XMLDOM.Load "FlowID.xml"
    FlowID = XMLDOM.documentElement.Text

    'get the skeletal message
    XMLDOM.Load "SkeletalResponseMessage.xml"
    SkeletalMessage = XMLDOM.xml

    Fill in the Service Content node of the skeletal message

    Call PIPAdapterManager.DeliverResponseMessage(FlowID, SkeletalMessage)

    Set PIPAdapterManager = Nothing
    Set XMLDOM = Nothing
End Sub

Responder Orchestration

As discussed before, 3A8 is a Transaction type process. Therefore, for the responder side, we will be using a Transaction Responder type of BizTalk Orchestration here.

Create a copy of the TransactionResponder.SKV file and rename it 3A8Responder.SKV. Just as we did for the initiator BizTalk Orchestration, change the stub adapter with your adapter.

Bind the schedule to SendRNMessage method. This procedure is little bit different from the initiator. The difference is the name of the MSMQ port.

Change the data page so that it reflects the change we have just made:

Save the file and compile it into an executable XLANG schedule by selecting File, Make from the menu.

Register the orchestration

The next step is to register the 3A8 responder BizTalk Orchestration using the PIP Administrator utility.

Start the PIP Administrator and select Register New XLANG Schedule action. Complete the registration with the entries as shown in Table 25.6.

Messaging Components

We will need to run the Messaging Configuration Wizard once again, this time to create the messaging components where the Destination Organization is the source organization. We will select Destination as the source organization and Home as the destination organization. Complete the wizard and run the script generated. The script creates the channels and ports listed in Table 25.7-just like the initiator side, but this time in the opposite direction.

Sending and Receiving Signals

Accelerator for RosettaNet handles signals automatically from within the BizTalk Orchestrations. As examined earlier, both initiator and responder adapter interfaces include methods for handling acknowledgements. There are three obvious questions here:

• Timing—How does the Accelerator for RosettaNet know when to send them?

• Message composition—How do the signal messages get composed?

• Messaging—How are the signals sent?

The Accelerator for RosettaNet uses BizTalk Orchestration schedules to handle message flow and state. When a message is received, the BizTalk Orchestration schedule describes how to send an acknowledgement. For example, have a look at the beginning of a Transaction Responder orchestration in Figure 25.9. After the activation message arrives, the schedule calls the CreateReceiptAcknowledgementMessage method. This method takes the inbound message and runs it through the RNMsgToAckAll.xml map to generate the corresponding acknowledgement message. This map and all others are installed to the following location:

<Accelerator for RosettaNet installation folder>PIP SDKSDK RepositoryMaps 

Just like this example, there are several other places in the BizTalk Orchestration schedule where CPIPAdapter gets called to create a signal message. All these calls will use the maps located in the location given previously. Therefore, if a signal pattern needs to change, modifying the corresponding map in the said repository will be sufficient.

After the signal message is built, the BizTalk Orchestration schedule asks the CPIPAdapter to send it. This will be done by a normal Submit call to BizTalk Server. Just as with any other message, BizTalk Server will match the signal message to one of the channels. In this case, the channel will be one of the signal channels created by the Messaging Configuration Wizard. The channel will receive and forward the signal message to the corresponding partner URL.

This is a fairly easy process, and you do not really have to modify anything about it. Knowing how the signals are sent is a good piece of information, though.

Content Validation

The Accelerator for RosettaNet uses a Universal Message schema for validating all messages going through its channels. This Universal Message schema contains document validation information for Service Content of all PIP action documents and Preamble and Service Header parts.

Figure 25.10 shows how the Universal Message Schema looks like when opened with BizTalk Schema Editor. Universal Message is a single <RosettaNet> node, which has three sub nodes <Preamble>, <Service Header>, and <Service Content>. The Preamble and Service Header are generic between processes. However, Service Content varies between different actions. For that reason, the Service Content node includes several subnodes, each describing the service content of a particular document, literally the DTD of the corresponding document described by RosettaNet.org.

This approach has advantages and disadvantages. Perhaps the biggest advantage is the capability to use only one schema for all actions. On the other hand, there is one disadvantage, which is a result of merging all Service Content DTDs into one big schema—that is, losing validation strength as you add more document schemas into the Universal Message Schema. The reason is simple. In a BizTalk document schema definition, each element is represented by a single top-level node, such as:

<ElementType name="myelement" content="eltOnly" model="closed"> 
  <b:RecordInfo />
  <element type="FreeFormText" maxOccurs="1" minOccurs="1" />
</ElementType>

The Element Type name must be unique in the schema. This means that myelement cannot be used in more than one document in a different way. All documents using myelement will have to use it as described in the preceding example.