This is the third post in my Commerce Server 2007 B2B Solution Development series and if you've been following the first two posts (1, 2), you'll remember that I like to "begin with the end in mind". In Commerce Server 2007 terms, this means figuring out how to map the XML produced by the Orders Receive Adapter (OrderGroupCollection schema) to something a little easier to work with as you integrate your Commerce Server orders into your ERP system.
BTW, this is one of the most widely asked questions I've seen in the past year and there's nothing in the Commerce Server docs to suggest how to use the XML produced by the Orders adapter.
The new Orders Receive Adapter produces a single message type which is used to periodically export order information from the Commerce Server Orders subsystem. This adapter is unique among the four new adapters in that it performs everything within a transaction, which allows roll-back in case of an error. The Orders adapter produces an XML document which conforms to the OrderGroupCollection schema as shown below from the BizTalk Schema Editor.
Since this schema was developed to match the Commerce Server Orders subsystem it’s unlikely that you’ll be able to use the XML produced by it “as is.” This is where the BizTalk Map comes in to play. In most cases, you’ll want to “normalize” the XML documents received from the Orders Adapter by mapping to some standard XML schema used by your organization. In our case, we normalize all inbound purchase orders (whether from an external trading partner or from Commerce Server) to an internal format that’s easier to work with and one which “fits” better into our existing BizTalk applications. This normalized XML sales order schema is shown below.
One of the challenges in mapping from the OrderGroupCollection schema is how to map weakly-typed (indexer) properties found in the various elements within the schema. Luckily, the BizTalk Mapper tool includes several functoids that make this process pretty simple. In the example below, the Equal functoid returns true if it finds a certain string in the WeaklyTypedProperty element’s Name attribute and the Value Mapping (Flattening) functoid will then map the Value attribute to the shipping_method_name attribute in the outbound schema. Using these two functoids, you can “look up” all the weakly-typed properties used in your Commerce Server application by their name and map them as needed.
Another challenge in mapping from the OrderGroupCollection schema is how to map the correct OrderAddress attributes, since the OrderAddress elements are located on the same level as the OrderForm they correspond to in the schema. This makes mapping using standard techniques very difficult but thankfully, BizTalk Server includes some advanced functoids created for just this kind of mapping challenge.
In the sample shown below, I’ve used the Database Lookup and Value Extractor functoids linked to the ShippingAddressId attribute to lookup all the required address information directly from the Commerce Server “transactions” database. Since the ShippingAddressID property is set in the Commerce Server web application and persisted to the “transactions” database, it should be present in all saved orders. A word of caution should be noted however. The Database Lookup and Value Extractor functoids call the database directly from the BizTalk map and as such, they could cause performance issues when used in a high volume scenario. Always test your BizTalk applications thoroughly before deploying into your production environment.
Obviously, mapping from the Commerce Server OrderGroupCollection schema directly to the schema used by your ERP system is "possible" but in my experience, mapping to a simpler XML schema (normalizing) and then to your final schema is much more effective. Remember, in BizTalk Server you can map on a Receive Port, a Send Port, in an Orchestration or in any combination of the three. This flexibility makes it possible to map from the OrderGroupCollection schema to just about any schema you require.