Conversing with Other Systems
As a Commerce Server and BizTalk Server developer, your work with BizTalk adapters may include programming and configuration tasks in BizTalk Server and in the line-of-business (LOB) application with which you are sharing data. These programming and configuration tasks differ depending on which of the following types of operations you use:
Process messages exported from a server that is running Commerce Server based on a schedule that you configured in a receive adapter.
Initiate query or import operations with Commerce Server by using a send adapter.
This topic contains a high-level discussion of both scenarios.
To automatically export Commerce Server data to another system such as an LOB application, you may have to perform programming and configuration tasks in BizTalk Server and other systems. The following list contains a summary of these tasks:
Create and configure one or more BizTalk Server entities to subscribe to the export messages that are generated by the Commerce Server receive adapter endpoints that you have configured. These entities may be BizTalk orchestrations, send ports, and so on. You may handle export messages that originate from different Commerce Server systems by using different BizTalk Server entities. Each entity may subscribe to a different message type. You may even have to process messages from the same Commerce Server system in different ways. For example, send some orders to one warehouse application for fulfillment and send other orders to another warehouse application.
Consider the schema of the export messages that come from Commerce Server. Is it a schema that the message's destination application can consume? If not, BizTalk Server is the natural location to perform the transformations that are required to convert the message to another format. However, remember the performance implications of doing transformations on large messages, such as full catalog export messages. For more information about how BizTalk Server processes large messages, see http://go.microsoft.com/fwlink/?LinkId=82351.
A good example of potential message format incompatibility is purchase orders that are retrieved from Commerce Server for processing in BizTalk Server and then sent to an LOB application beyond BizTalk Server. The XML format of Commerce Server orders is structured as follows:
<Addresses> <Address ID=1 .../> <Address ID=2 .../> <Addresses/> <Order> <LineItem ID=1 ... ShipToID=1/> <LineItem ID=2 ... ShipToID=1/> ... <LineItem ID=n ... ShipToID=2/> <Order/>
The values of the ShipToID attributes in the LineItem elements refer to the values of the ID attributes in the Address elements.
The format earlier is not optimal for processing in BizTalk Server and typical LOB applications. The following format with structures that embed the address information in the line items works better:
<Order> <LineItem ID=1 ... > <Address Street = ... > <LineItem/> <LineItem ID=2 ... > <Address Street = ... > <LineItem/> ... <LineItem ID=n ... > <Address Street = ... > <LineItem/> <Order/>
You can use BizTalk Mapper to transform the former structure into a structure such as the structure shown in the latter example. For more information about how to integrate Commerce Server orders with BizTalk Server and LOB applications, see http://go.microsoft.com/fwlink/?LinkId=77515.
Consider how the export message from Commerce Server, transformed or not, will be routed through BizTalk Server to the destination application. How this occurs depends on the specific requirements of the destination application, although it is likely that a BizTalk Server send port of some kind is involved.
To automate query and import operations with Commerce Server, you may have to perform programming and configuration tasks in BizTalk Server and other systems. The following list contains a summary of these tasks:
Consider how the query and import messages to be sent to Commerce Server are originated. Do you construct them in an LOB application and submit them to BizTalk Server? If you do originate the messages in this manner, is it by using a send or receive adapter, one of the standard adapters provided by BizTalk Server, or a custom adapter designed for the LOB application? This last option resembles how the Commerce Server adapters handle a well-defined set of Commerce Server messages. Is the generation of these messages something that occurs on a schedule? Or is it driven by some event in the LOB application, such as a change being made directly by a user or the receipt of another message?
Consider the schema of the query and import messages that will be routed to one of the Commerce Server send adapters. Does the schema of the message already follow what is expected by the Commerce Server send adapter to which it will be routed? Messages that originate from another Commerce Server installation are a good example of messages that may already be expressed by using a compatible schema. These may require very little BizTalk Server processing. Messages that originate from a disparate LOB application may not be expressed by using a compatible schema. In these cases, you could use the advanced schema mapping capabilities of BizTalk Server to transform the message format from what is submitted by the LOB application into the format expected by the corresponding Commerce Server send adapter. However, remember the performance implications of doing transformations on large messages, such as full catalog import messages. For more information about how BizTalk Server processes large messages, see http://go.microsoft.com/fwlink/?LinkId=82351.
An exception to messages between two instances of Commerce Server not requiring manipulation by BizTalk Server is when one instance of Commerce Server is exporting orders in which there is a single order per message. The exported order messages have the element OrderGroups as their root element. Unless you use BizTalk Mapper to change this root element to OrderGroup (singular) before you import it into the second instance of Commerce Server, you will generate the following error:
"Specified Xml is invalid. The root node OrderGroups is not an OrderGroup derived type."
After a query or import message that is formatted correctly arrives in the BizTalk Server MessageBox Database, a Commerce Server send adapter endpoint that is configured correctly should receive the message and process it through the corresponding Commerce Server system Web service.
The Commerce Server send adapters use the solicit-response message model. Perform the programming and configuration tasks to process the response messages that the send adapters generate. If there are query operations, process response messages to request information with which you want to do something.
Processing response messages is equally important for import operations. Check the response messages to confirm whether the import operation was successful.
All the response messages that the Commerce Server send adapters generate include the context property CommerceServerCommandResults. This property will be set to one of the following string values:
The context property CommerceServerCommandResults is promoted so that you can route the response messages differently based on the value of this property. This enables you to configure different handling for success response messages than for failure response messages. Additionally, the message bodies of some response messages contain more information about errors that have occurred.
If you do not configure the handling of the response messages that may result from the solicit messages, you may generate exception messages from BizTalk Server in the event log. You may even leave BizTalk Server host instances running when they should have ended.