Using IFR-XML Format with Adapter for SAP

Overview

With the XML format defined in the Interface Repository, SAP establishes a standardized exchange of business management data on a semantic level across the web. XML documents which are generated according to the XML format and defined in the Interface Repository are called business documents.

The number of business documents exchanged between two partners to invoke a business management function depends on the underlying interface type and the usage scenario. During a synchronous call of a BAPI or RFC, two business documents (request and response document) are exchanged. During an asynchronous call, only a request document is exchanged.

Characteristics of business documents are:

  • Use of XML envelopes.
  • Common structure for request and response documents.
  • Common way of representing parameters.
  • Common error handling concepts.
Note: IDocs do not support all of these features.

Use of XML Envelopes

Business documents are transmitted within an XML envelope. Due to the fact that they only contain business management data they can be transmitted via arbitrary XML standard envelopes (e.g. BizTalk, SOAP, …).

Adapter for SAP supports the transport of business documents within the BizTalk envelope. More details concerning the use of the BizTalk envelope for the transport of business documents can be found in Using BizTalk Envelopes with Adapter for SAP.

Common Structure of Request and Response Documents

To ensure a standardized exchange of business management data the overall structure of request and response documents is the same regardless of which interface type is called. Generally three different types of business documents can be distinguished:

  • Request business documents that are identified by a root element that has the same name as the corresponding interface.

    Example: 

    <doc:InterfaceName xmlns:doc="urn:…">  
   <!-- request specific data -->  
     …  
</doc:InterfaceName>
  • Response business documents that are sent back from the server if the request has been correctly executed. They are identified by a root element that has the concatenation of the interface name and the suffix .Response as its name.

    Example: 

    <doc:InterfaceName.Response xmlns:doc="urn:…">  
   <!-- response specific data -->  
     …  
</doc:InterfaceName.Response>
  • Exception business documents that are sent back from the server if application errors occurred during the execution of the request. They are identified by a root element that carries the concatenation of the interface name and the suffix .Exception as its name.

    Example: 

    <doc:InterfaceName.Exception xmlns:doc="urn:…">  
   <!-- exception specific data -->  
     …  
</doc:InterfaceName.Exception>

Common Way of Representing Parameters

Parameters are generally represented as child elements of the business document root element. What parameter names are used as element names within the business document depends on the underlying interface type:

  • In business documents for RFCs, the names of the parameters of the function module interface are used in the XML document.
  • Business documents for BAPIs contain the parameter names as they are defined in the business object Repository (BOR).

The SAP-internal data structures of the parameters are displayed in a serialized form within the parameter element in accordance with the SAP specification Serialization of ABAP Data in XML.

Common Error Handling Concepts

The different error handling concepts of BAPIs and RFCs are presented at the XML level in a uniform way.

Generally, exception business documents are structured as serialized ABAP OOExceptions which are passed within the root element (InterfaceName.Exception) of the exception document. These serialized exceptions are flexible enough to contain different kinds of error information. Consequently, both BAPI return parameters and function module exceptions are mapped to the representation of serialized exception objects.

The serialized ABAP-OO exception consists of the following XML elements:

XML Element Description 
<Name>
 Identifies the exception. Normally a global name.
<Message> (optional) sub-elements:

  <ID>

  <Number>

  <Text> (optional)

The <Message> element references an SAP message that describes the error situation.

Message class

Message number

Error description

<Attributes> (optional) sub-elements:

  <Collection> (optional) 

  
  
  <AttributenameX>     
(multiplicity: 0..*)
 The <Attributes> element contains additional application specific information.

Table with serialized exceptions that represent single error messages, if error collections have to be returned. Each serialized exception within the <Collection> element has the same structure as the wrapper exception.

Named attributes (AttributenameX = Name of Attribute) in which additional application specific information can be returned.

More detailed information about the XML format defined in the Interface Repository can be found at http://ifr.sap.com.

XML Format for BAPIs

For each BAPI, three different types of business documents exist:

  • A request business document.
  • A response business document (in case of a correct execution of the BAPI call).
  • An exception business document (in case of an incorrect execution of the BAPI call).

The following sections describe these three types of business documents in more detail.

Structure of Request Business Documents for BAPIs

This is the general structure of request business documents for BAPIs: 

<doc:BusinessObjectName.MethodName  
     xmlns:doc="urn:sap-com:document:sap:business"  
     [Key1="…", Key2="…", …]>  
    <BOR_Parameter1>...</BOR_Parameter1>  
        ...  
</doc:BusinessObjektName.MethodenName>

Additionally, consider the following:

  • The arrangement of BAPIs according to a business object is directly reflected by the element names of the business document. The root element that identifies the Request business document carries the concatenation of the business object name and the BOR method name as its name. The root element has the following characteristics:
    • It contains the namespace reference of business documents that refer to BAPIs ("urn:sap-com:document:sap:business").
    • If the BAPI is an instance method, the root element contains an attribute for each key field of the corresponding business object that is named like the key field.
      Note: If the business object has more than one key field, the corresponding attributes should appear in the same sequence as the key fields defined in the BOR.
  • Import parameters of the BAPI appear as sub-elements of the root element. These sub-elements are named like the parameters as they are defined in the BOR. Within these elements, the SAP-internal data structures are represented in a serialized form in accordance with the specification Serialization of ABAP Data in XML.

Structure of Response Business Documents for BAPIs

A response business document is returned to the sender if the BAPI call could be processed without application errors. This means that the BAPI-return parameter only contains messages of the type S, I, or W. In that case, the Response business document contains the export parameters of the BAPI call.

This is the structure of response business documents for BAPIs: 

<doc:BusinessObjektName.MethodenName.Response  
     xmlns:doc="urn:sap-com:document:sap:business"  
     [Key1="…", Key2="…", …]>  
    <BOR_Parameter1>...</BOR_Parameter1>  
        ...  
</doc:BusinessObjektName.MethodenName.Response>

Additionally, consider the following:

  • The arrangement of BAPIs according to a business object is directly reflected by the element names of the business document. The root element that identifies the request business document carries the concatenation of the business object name, the BOR method name and the suffix .Response as its name. The root element has the following characteristics:
    • It contains the namespace reference of business documents that refer to BAPIs ("urn:sap-com:document:sap:business").
    • If the BAPI is an instance method or a factory method, the root element contains an attribute for each key field of the corresponding business object that has the same name as the key field.
      Important: If the business object has more than one key field, the corresponding attributes should appear in the same sequence as the key fields defined in the BOR.
  • Export parameters of the BAPI appear as sub-elements of the root element. These sub-elements have the same name as the parameters defined in the BOR. Within these elements, the SAP-internal data structures are presented in a serialized form in accordance with the specification Serialization of ABAP Data in XML.
  • If the BAPI is a factory method, possibly only the key fields of the created instance will be returned to the client. In this case, the response business document only consists of attributes.

Structure of Exception Business Documents for BAPIs

An exception business document is returned to the sender if the BAPI call could not be processed without application errors. This means that the BAPI return parameter contains at least one message of type E (error) or A (abort). In this case, the exception business document contains only the error descriptions.

These error descriptions have the following characteristics:

  • Error messages of the BAPI return parameter are displayed as serialized exception objects on XML level. So the representation of the error description in the exception business document differs from the original BAPI return structure. Messages of type E are represented as exceptions with name BapiError. Messages of type A are represented as exceptions with the name BapiAbort.
  • Status messages (messages of the type S, I, or W) that are also part of the Return parameter are still returned as the return parameter structure.
    Important: All status messages will be mapped to the BAPIRET2 structure.
  • The export parameters of the BAPI are not taken into account.

The detailed structure of the Exception business documents depends on whether the return parameter is a structure or a table.

Exception Document for Return Structures

If the return parameter is a structure, the exception business document contains one single exception that is created from the information of the return message. The exception is named BapiError or BapiAbort depending on whether the return message is of type E or A.

The XML representation of a return structure consists of following sub-elements:

XML Element Corresponding Information from the Return Parameter
<Name> „BapiError", if value of field TYPE is „E".

„BapiAbort", if value of field TYPE is „A".

<Message> (0..1)

  <ID>

  <Number>

  <Text>

Value of the ID field.

Value of the NUMBER field.

Value of the MESSAGE field.

<Attributes> (optional)

  <MESSAGE_V1> (optional)

  <MESSAGE_V2> (optional)

  <MESSAGE_V3> (optional)

  <MESSAGE_V4> (optional)

  <LOG_NO> (optional)

  <LOG_MSG_NO> (optional)

  <PARAMETER> (optional)

  <ROW> (optional)

  <FIELD> (optional)

  <SYSTEM> (optional)

The <Attributes> element contains the information of BARIRET2 as sub-elements that have the same names as the corresponding fields of the BARIRET2 structure.

Exception Document for Return Tables

Return tables consist of one or more rows that have the same structure as a return structure. If the return table contains at least one message of type E (error) or A (abort), an exception business document is returned to the client that has the structure of a collection exception. This exception is named BapiError or BapiAbort depending on whether the most critical message in the return table is of type E or A.

The collection exception is identified by a standardized message which is similar for all return tables. The messages of the return table are displayed within the <Collection> element of the collection exception, which is a sub-element of the <Attributes> element.

Each single message of type E or A is displayed as an exception that is grouped within the <Collection> element in the form of a table. Single messages are displayed as exceptions in an exception table in accordance with the specification Serialization of ABAP Data in XML. Consequently, each exception is encapsulated in an <item> element that contains the exception data.

If, despite the error messages, the return table contains additional messages of type S, I, or W, these messages are displayed in a table of row type BAPIRET2 within a <Status> element, which is a sub-element of the <Attributes> element.

If a BAPI return table contains error messages, the following XML-elements comprise the resulting exception business document:

XML Element Corresponding Information from the Return Parameter
<Name> „BapiError", if value of field TYPE is „E". „BapiAbort", if value of field TYPE is „A".
 <Message>

  (0..1)

   <ID>

  <Number>

   <Text>

The three sub-elements contain a generic message that is used for all return tables (for example: "During the execution of the BAPI one or more errors occurred"). 
 <Attributes>  
   <Collection>  
    <item>  
      <Name>…</Name>  
      <Message>…</Message>  
      <Attributes> (optional)  
       ...  
      </Attributes>  
    </item>  
    <item> (optional)  
     ...  
    </item>  
    ...  
   </Collection>
 XML representation of each error message within the return table. Within the <item> elements, the data of a single return message is displayed as a serialized exception object. 
   <Status> (optional)  
    <item>  
     <ID> (optional)  
     <TYPE> (optional)  
     <NUMBER> (optional)  
     <MESSAGE> (optional)  
     <MESSAGE_V1> (optional)  
     <MESSAGE_V2> (optional)  
     <MESSAGE_V3> (optional)  
     <MESSAGE_V4> (optional)  
     <LOG_NO> (optional)  
     <LOG_MSG_NO> (optional)  
     <PARAMETER> (optional)  
     <ROW> (optional)  
     <FIELD> (optional)  
     <SYSTEM> (optional)  
    </item>  
    <item> (optional)  
     …  
    </item>  
     …  
   </Status>
 The <Status> element contains a serialized table with row type BAPIRET2. Within the <Status> element, all return messages of type S, I, or W that are also returned in the BAPI return parameter are displayed.

XML Format for RFCs

Just as for BAPIs, there are three different types of business documents for each RFC:

  • A request business document.
  • A response business document, if the RFC call has been successfully executed.
  • An Exception business document, if the RFC call failed.

The following sections describe these three types of business documents in more detail.

Structure of Request Business Documents for RFCs

This is the general structure of request business documents for RFCs: 

<doc:FunctionModuleName  
           xmlns:doc="urn:sapcom:document:sap:business:rfc:functions">  
     <FuMod_Parameter1>...</FuMod_Parameter1>  
        ...  
</doc:FunctionModuleName>

Additionally, consider the following:

  • The root element that identifies the request business document has the same name as the corresponding function module. It contains the namespace reference of business documents that refer to RFCs ("urn:sap-com:document:sap:business:rfc").
  • Import parameters of the RFC appear as sub-elements of the root element. These sub-elements have the same name as the parameters as they are defined in the function module interface. Within these elements, the SAP-internal data structures are represented in a serialized form in accordance with the specification Serialization of ABAP Data in XML.
  • Because it is not possible to distinguish tables in the function module interface in import tables and export tables, all tables that should be taken into account have to be represented as sub-elements.

Structure of Response Business Documents for RFCs

If the RFC can be executed without getting an exception, a response business document is returned to the sender. It contains the export data of the function module.

This is the structure of response business documents for RFCs: 

<doc:FunctionModuleName.Response  
           xmlns:doc="urn:sapcom:document:sap:business:rfc:functions">  
     <FuMod_Parameter1>...</FuMod_Parameter1>  
        ...  
</doc:FunctionModuleName.Response>

Additionally, consider the following:

  • The name of the root element that identifies the response business document is defined as the concatenation of the name of the corresponding function module and the suffix .Response. It contains the namespace reference of business documents that refer to RFCs ("urn:sap-com:document:sap:business:rfc").
  • Export parameters and tables of the RFC appear as sub-elements of the root element. These sub-elements have the same name as the parameters defined in the function module interface. Within these elements, the SAP-internal data structures are presented in a serialized form in accordance with the specification Serialization of ABAP Data in XML.

Structure of Exception Business Documents for BAPIs

If the function module cannot be executed, the execution ends with a function module exception and an exception business document is returned to the client. It describes only the error situation. In this case, export parameters of the function module are not included.

This is the structure of exception business documents for RFCs: 

<doc:FunctionModuleName.Response  
         xmlns:doc="urn:sap-com:document:sap:business:rfc">  
     <!--Representation of the serialized exception-->  
        ...  
</doc:FunctionModuleName.Response>

The representation of the function module exception as a serialized exception consists of the following XML elements:

XML Element Description
<Name> Name of the exception as defined in the function module interface.
<Message>

(0..1) 

  <ID>  
  <Number>  
  <Text>
 The <Message> element contains information from the SY fields. Could be empty if the mapping was performed on an external middleware system.

SY-MSGID

SY-MSGNO

Message text, which is defined for ID and number. In ABAP, evaluated with „message id... into.."

<Attributes> (optional)

  <V1> (optional)

  <V2> (optional)

  <V3> (optional)

  <V4> (optional)

Contains list of SY fields, which represent the variables of an error message.

SY-MSGV1

SY-MSGV2

SY-MSGV3

SY-MSGV4

XML Format for IDocs

To create an asynchronous communication, IDocs are exchanged between two SAP systems. There are two ways to define concrete IDocs to communicate asynchronously:

  • As of Release 4.0, generate an IDoc from an existing BAPI.
  • Create IDocs manually.

Therefore, two different ways of representing IDocs in XML can be distinguished:

  • If the IDoc was generated from an existing BAPI, the asynchronous communication is performed by using the BAPI interface. Consequently, the exchanged business documents are created from the corresponding BAPI. The IDoc itself is not visible at XML level.
  • IDocs that were defined manually and not generated from BAPIs require a separate XML representation. This representation is described in detail below.

XML Format for Manually Defined IDocs

This is the structure of business documents for manually defined IDocs: 

<doc:IdocTypeName>  
   <IDOC BEGIN="1">  
     <EDI_DC40 SEGMENT="1">...</EDI_DC40>  
     <E1SEGMENT1 SEGMENT="1">...</E1SEGMENT1>  
        ...  
   </IDOC>  
</doc:IDocTypeName>

Additionally, consider the following:

  • The root element, which identifies the business document for an IDoc, has the same name as the corresponding IDoc type.
  • The IDoc itself is encapsulated by the element <IDOC BEGIN="1"> ...</IDOC>.The element contains the attribute BEGIN with the fixed value "1".
  • The IDoc control record is defined through the element <EDI_DC40 SEGMENT="1">...</ EDI_DC40>.
  • Each IDoc segment is represented as a separate element that has the same name as corresponding IDoc segment. SAP segments usually have the prefix E1. These elements contain the attribute SEGMENT with the fixed value "1", which defines the beginning of the segment.

    The element name for the fields within one segment are given by the name of the corresponding field. An XML document for an IDoc may contain empty fields. These fields are displayed as elements with the form <FieldName/>.

  • The hierarchical structure of IDocs is represented by the structure of the XML document.
  • The IDoc control record is handled in the XML document as a common segment.