Using BizTalk Envelopes with Adapter for SAP

Overview

Adapter for SAP uses the BizTalk XML envelope as the transport envelope for the transmission of XML business documents. The BizTalk envelope is implemented on Adapter for SAP in accordance with the BizTalk Framework 1.0a Independent Document Specification of January, 7th 2000.

As BizTalk specifications are open to implementation specific interpretations of some of the provided XML elements, this chapter describes how Adapter for SAP copes with BizTalk envelope tags that are not specified clearly enough. BizTalk strongly differentiates between a transport header and an application specific body, which results in the following overall structure of the BizTalk envelope: 

<biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml">  
   <header>  
     <!-- Header and processing information is contained here -->  
   </header>  
   <body>  
     <!-- Business transaction information is contained here -->  
   </body>  
</biztalk_1>

The BizTalk document header information is contained within the <header> element. This header contains information used for handling and processing the document. The business document passed in the message is contained within the <body> element. For more details concerning the standard BizTalk envelope refer to the BizTalk Framework 1.0a Independent Document Specification.

Use of the BizTalk Header

Introduction to Standard BizTalk Header Fields

BizTalk defines some standard XML elements for using with its envelope. The most important are:

  • The <message> element with its sub-elements <messageID>, <sent>, <subject> can be used to identify a message.
  • The <to> and <from> elements can be used to identify the sender and receiver in a communication process. Both may contain the sub-elements <address> and <state>.
  • The <manifest> element can be used to describe the business documents delivered in the body.

A full BizTalk XML header may look like this (taken from the Microsoft BizTalk specification): 

<?xml version='1.0' ?>  
<biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml">  
  <header>  
   <delivery>  
    <message>  
      <messageID>xyzzy:8</messageID>  
      <sent>1999-01-02T19:00:01+02:00</sent>  
      <subject>Purchase Order</subject>  
    </message>  
    <to>  
      <address>http://www.fabrikam.com/recv.asp</address>  
      <state>  
        <referenceID/>  
        <handle/>  
        <process/>  
      </state>  
    </to>  
    <from>  
      <address>mailto:foo@contoso.com</address>  
      <state>  
        <referenceID>123</referenceID>  
        <handle>7</handle>  
        <process>myprocess</process>  
      </state>  
    </from>  
   </delivery>  
   <manifest>  
    <document>  
       <name>PO</name>  
       <description>Purchase Order</description>  
    </document>  
   </manifest>  
  </header>  
  <!-- body definition here -->  
<biztalk_1>

For further details of the BizTalk XML envelope, refer to the BizTalk Framework 1.0a Independent Document Specification.

Adapter for SAP only uses a subset of these available header elements, which is described in the following chapters.

Representation of Routing and Address Information

Adapter for SAP needs to identify the sender and receiver of an XML message. Usually, these are logical systems, as defined inside the SAP system.

This information is transported by the BizTalk header element <delivery>. Within this element, the two sub-elements <to> and <from> can be defined.

These elements are used to exchange the routing information needed by Adapter for SAP. The names of the partners are put into the sub-element <address> of the <to> or <from> element.

BizTalk requires an URI as the content of the address element. The names of the SAP logical systems are encoded as a Universal Resource Name (URN) by putting the prefix urn:sap-com:logical-system: in front of the logical system identifier. For example: The logical system SAPCLNT001 would be represented as urn:sap-com:logicalsystem:SAPCLNT001.

Note: Although these identifiers are expressed as URNs, they are not globally unique; the names of logical systems can be setup freely for each SAP System domain.

This results in an XML document like the following: 

<?xml version="1.0" encoding="iso-8859-1"?>  
<biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml">  
  <header>  
   <delivery>  
    <message>  
      <messageID>0A125F1315B3A11B00000035</messageID>  
      <sent>2000-06-07T09:22:40</sent>  
    </message>  
    <to>  
      <address>urn:sap-com:logical-system:SAPCLNT001</address>  
    </to>  
    <from>  
      <address>urn:sap-com:logical-system:SAPADA0001</address>  
    </from>  
   </delivery>  
  </header>  
  <!-- Body definition here -->  
</biztalk_1>

Representation of SAP Transactions

When using tRFC or IDocs, you have to specify a unique SAP transaction ID for each call to ensure delivery. This transaction ID can be either resolved from an SAP system as described in this guide or built locally. It should always consist of 24 hexadecimal characters and be globally unique.

Because BizTalk does not support transaction IDs (TIDs), Adapter for SAP uses the <referenceID> element, which is a sub element of the <state> element.

Note: The <state> element can also be a sub-element of the <to> or <from> element.

Transaction IDs must be put in the <referenceID> element that belongs to the receiver's address information.

For example: 

<?xml version="1.0" encoding="iso-8859-1"?>  
<biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml">  
  <header>  
   <delivery>  
    <message>  
      <messageID>0A125F1315B3A11B00000035</messageID>  
      <sent>2000-06-07T09:22:40</sent>  
    </message>  
    <to>  
      <address>urn:sap-com:logical-system:SAPCLNT001</address>  
      <state>  
        <referenceID>120A135FB315A11B00003500<referenceID>  
      </state>  
    </to>  
    <from>  
      <address>urn:sap-com:logical-system:SAPADA0001</address>  
    </from>  
   </delivery>  
  </header>  
  <!-- Body definition here -->  
</biztalk_1>

Further BizTalk Header Fields

BizTalk requires the use of the XML element <message> to identify a single message. It defines the following sub-elements:

XML Element Description
<messageID> A unique identifier, generated for each exchanged document. Adapter for SAP will always generate a new message ID for both request and response messages.
<sent> Timestamp of the message creation. When using BAPIs with ALE, this timestamp is used to build the serialization ID of the IDoc control block. The element must contain date and time formatted according to ISO 8601 (first edition June 15, 1988). The format to use is Calendar date and local time of the day. The syntax is: CCYY-MM-DDThh:mm:ss.

For example:

2000-06-19T18:59:02describes June 19, 2000 18 hours 59 minutes 2 seconds.

<subject> May be used to specify an additional description for the message.
Important: This element is not used by Adapter for SAP.
Important: BizTalk provides the possibility to exchange manifest information in the header. This feature is not used by Adapter for SAP.

Error Handling

BizTalk does not describe its own error handling concept in its current specification. However, it recommends that you define application-specific error documents to handle application errors. For server-related errors, it describes using standardized XML exception descriptors.

Adapter for SAP distinguishes between two major groups of errors:

  • Errors in the XML processing and conversion layers of Adapter for SAP, and critical errors in the SAP systems that cause a termination of the connection.
  • Application-specific errors such as errors that were foreseen by the application developers and therefore defined at the interface definition in the SAP system. For example: a receipt could not be processed because of business-level problems.

This section includes the following topics:

Representation of Communication and Processing Errors

Errors which are caused inside Adapter for SAP or by the technical layers in the SAP system are represented by a uniform XML fault-descriptor element. This fault element has been defined following the design principles used for SOAP and SAP XRFC error handling.

This fault element is transferred in the body of a BizTalk XML envelope and introduced by the fault-XML element (which is defined in the namespace urn:sapcom: document:sap:business by applying a specific prefix).

This fault element has the following sub-elements:

XML Element Description
<faultcode> A number specifying the class of error. Compatible with the Microsoft SOAP XML framework specification. Adapter for SAP always sets this value to 401 to indicate an application-specific error.
<faultstring> Internal Adapter for SAP code for this exception.
<detail> Details of the specified sub-elements <name> and <message>
<name> Name of an exception to use with the SAP system as the ABAP exception identifier.
<message> Error message with the specified sub-element <text>. (Optional; this is not always fully specified).
<text> The text of the error message.

An example of an exception document: 

<?xml version="1.0" encoding="iso-8859-1"?>  
 <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1">  
  <header>  
   <delivery>  
    <message>  
      <messageID>0A125F1315B39EDB00000013</messageID>  
      <sent>2000-06-19T18:59:02</sent>  
    </message>  
    <to>  
       <address>urn:sap-com:logical-system:SAPCLNT001</address>  
    </to>  
    <from>  
      <address>urn:sap-com:logical-system:SAPADA0001</address>  
    </from>  
   </delivery>  
  </header>  
  <body>  
   <sap:Fault xmlns:sap="urn:sap-com:document:sap:business"  
          xmlns="">  
    <faultcode>401</faultcode>  
    <faultstring>  
       com.wm.adapter.sap.error.SAPBasicException  
    </faultstring>  
    <detail>  
     <name>SBC_EXCEPTION</name>  
     <message>  
       <text>Business object named Bank2 does not exist in SAP  
             System U9C</text>  
     </message>  
    </detail>  
   </sap:Fault>  
  </body>  
 </biztalk_1>

Representation of Application Errors

Application specific errors are always described as application specific XML business documents.

These exception documents are described in Using IFR-XML Format with Adapter for SAP. For SAP's standard interfaces, the relevant exception documents are provided in the SAP interface repository as part of the XML schema for response documents.

Note: These response documents are always exchanged as business documents that are part of the BizTalk body.