Visitor

Resources Tools Microsoft XML Parser 3rd Party Vendors White Papers Specifications Links   Find out what Biztalk.org's users are saying in Community.

BizTalk™ Framework Document Design Guide Creating Extensible Markup Language (XML) document schemas and instances from data contained within existing systems or that meet a user’s application needs is complicated, in part because of the many different ways to express the same thing. Furthermore, inconsistent message construction will make the process of integration more difficult. This document provides a set of design guidelines for Microsoft® BizTalk™ Framework documents that can easily be implemented by application developers. The BizTalk Framework is an XML framework for application integration and e-commerce. It includes a design framework for implementing an XML schema and a set of XML tags used in messages sent between applications. Microsoft Corp., other software companies and industry standards bodies will use the BizTalk Framework to produce XML schemas in a consistent manner. Creating Extensible Markup Language (XML) document schemas and instances from data contained within existing systems or that meet a user’s application needs is complicated, in part because of the many different ways to express the same thing. Furthermore, inconsistent message construction will make the process of integration more difficult. This document provides a set of design guidelines for Microsoft® BizTalk™ Framework documents that can easily be implemented by application developers. The BizTalk Framework is an XML framework for application integration and e-commerce. It includes a design framework for implementing an XML schema and a set of XML tags used in messages sent between applications. Microsoft Corp., other software companies and industry standards bodies will use the BizTalk Framework to produce XML schemas in a consistent manner. Mandatory Requirements Tags There are three essential rules for the creation of BizTalk Framework documents and messages: define schemas using XML-Data, use BizTalk Framework tags, and document schemas so they can be catalogued automatically. Define Schemas Using XML-Data Business message documents are described by schemas, a listing of which elements and attributes may appear in the message and in which combinations. There are several formats available for writing a schema. The BizTalk Framework requires a specific format: XML-Data. Briefly, XML-Data is a vocabulary (schema) of XML elements and attributes designed for describing other classes of XML documents. It describes what elements may be used in a document, what attributes may appear, and what combinations of elements and attributes are valid. To this degree, XML-Data performs the same function as the XML standard format known as "DTD." However, XML-Data goes beyond DTD in four important respects: it describes datatypes (number, date, etc.),; it supports the XML namespaces specification, it allows open content models, and it is itself extensible because it is written in XML. Defining which elements in a document are numbers, which are dates and so forth is key to improving the reliability, automatic validation and programmatic access of business messages. If datatypes are used, numbers and dates must be formatted in specific ways based on international standards. These are documented more fully at http://msdn.microsoft.com/xml/xmlguide/schema-datatypes.asp and also at http://msdn.microsoft.com/xml/reference/schema/datatypes.asp. Supporting the namespaces specification allows users to compose messages using parts drawn from several schemas. Namespaces give universally recognizable identifiers to elements and are fundamental to the interoperability of Web documents. The BizTalk Framework requires the documentation of messages using XML-Data, and use of the features of datatypes and namespaces. Full details on XML-Data are available from http://msdn.microsoft.com/xml. Use BizTalk Framework Tags Certain information, such as routing numbers, addresses and so forth, constitutes protocol-level information common to all business messages. The BizTalk Framework defines a set of standard tags for this purpose that is mandatory in every BizTalk Framework document. These tags are defined in the BizTalk Framework tags specification document available on http://www.biztalk.org/. Document and Classify Schema BizTalk provides a set of standard elements to document and classify schemas. With these, users can indicate the owner, author, intended use and various other categorizations of schema, as well as provide key words and other taxonomic classifiers to make it easier for other businesses to discover and put into practice a user’s schema. Style Guidelines Names and Cases Names should use the style called "CamelCase." If an element reflects a thing (an object, a class or a table name), use UpperCamelCase; if it is a property, a reference, etc., use lowerCamelCase. UpperCamelCase example: <PurchaseOrder> lowerCamelCase examples: <dateTaken>1997-05-04</dateTaken> <dateDue>1998-05-03</dateDue> Use Meaningful Names People are sometimes over-economical with the letters they are willing to spend on a tag name, omitting vowels and other expendable parts. This made good sense in the days when a few letters consumed a significant fraction of the space available on a computer or a phone line. However, XML compresses very well. Computers are becoming cheaper; humans are not. Keep the few extra letters to make sure that humans can read messages more easily. <shp2> Don’t do this. <shipTo> Write it this way. Name by Function, Not Location Do not name elements by their location. In addition to the resulting illegibility, this practice is unreliable because variations in messages tend to shift element positions. It also encourages overloading the same element name to hold different information items at different times. <field_34>Don’t do this. <shipTo> Write it this way. Don’t Use Private Encodings When practical, use distinct elements to separate parts of data. With a data item that has internal structure, separating the parts with tags allows the XML parser to do the work of distinguishing them, saving the cost of writing a custom parser. In addition, the structure will then be publicly readable and thereby available to standard tools such as XSL style sheets and query languages. If something has more than one part, it is likely that it will gain more parts in the future; using tags upfront means easier extension later. <price>12.5AUS</price>Don’t do this. <price>Write it this way. <currency>AUS</currency> <quantity>12.50</quantity> </price> Practical Applications The message body of a BizTalk Framework document contains the real data of the interchange, the information that the receiving application will consume, rather than the BizTalk Framework infrastructure. This section provides examples of how to design the structure of a BizTalk Framework message body from an application developer perspective. Expressing Data All simple data — trees, columns, rows, objects, properties, etc. — should be expressed as elements and subelements, not attributes. The XML Canonical Form Document available at http://www .biztalk.org/ defines the approach for expressing more complex data structures and relationships. For example, the simplified BizTalk Framework message shown below represents a purchase order: <BizTalk xmlns= "urn:schemas-biztalk-org:biztalk-0.81.xml"> <Route> . . . see above . . . </Route> <Body> <PurchaseOrder xmlns= "urn:schemas-biztalk.org:your-namespace/purchaseorder.xml"> <POHeader> <PONumber>12345</PONumber> <PaymentType>INVOICE</PaymentType> <POShipTo> <street1>Your Street 1</street1> <street2>Your Street 2</street2> <city>Your City</city> </POShipTo > <POBillTo> <street1>Your Street 1</street1> <street2>Your Street 2</street2> <city>Your City</city> </POBillTo > </POHeader> <POLines> <Item> <partno>ikypop1</partno> <quantity>1</quantity> <unitPrice>14.00</unitPrice> </Item> </POLines> </PurchaseOrder> </Body> </BizTalk> Since this generally will not be the way the data is actually stored on any system, it needs to be mapped from the native form to the BizTalk Framework form. Mapping From Database Tables Records should be represented as an element containing subelements for each field. Where a field is a foreign key, that element will be a container for the subelements representing the foreign record. For example, the source database tables for the above example might have the following schema: PURCHASE_ORDERS po_number (primary key) payment_type ship_to (foreign key -> DEPARTMENTS) bill_to (foreign key -> DEPARTMENTS) DEPARTMENTS department_id (primary key) street1 street2 city LINE_ITEMS po_number part_number quantity unit_price Mapping From Objects Objects should be represented as elements containing a nested element for each property. Where a property is a reference to another object, the nesting is extended to include the properties of the referenced object. For example, the XML above might be derived from a set of objects with the following classes: PurchaseOrder .OrderID .PaymentType .ShipTo .BillTo .Items() Department .DepartmentName .Street .City .PostalCode Item .PartNumber .Quantity .UnitPrice ######### Microsoft and BizTalk are either registered trademarks or trademarks of Microsoft Corp. in the United States and/or other countries. Other product and company names herein may be trademarks of their respective owners. © BizTalk 1999. All rights reserved.