SAP XI Adapter

How the SAP XI Adapter Works

The SAP XI adapter integrates Sterling B2B Integrator with SAP NetWeaver through the XI Adapter Framework (AF) of the SAP XI 3.0 component of SAP NetWeaver. SAP recommends SAP XI as the component for exchanging data with external applications on either SAP or non-SAP systems.

SAP XI Messages

Messages consist of a message payload and, optionally, one or more attachments. The content of the message may be XML or binary. If the content is binary, the message cannot be routed dynamically within SAP XI. The content of the attachments is arbitrary. Attachments are passed to the receiving partner in SAP XI without being opened or parsed. Messages can be sent in synchronous mode only.

Inbound Messages

Messages sent from Sterling B2B Integrator to SAP XI are called inbound messages. The message payload is passed as a primary document in the root of the process data. One or more attachments can also be sent with the message in an attachments structure.

Input Message

The BPML format for the message is:

<PrimaryDocument SCIObjectID=id/>

The optional attachments structure includes a list of attachment nodes:

<attachments>
  attachment_1
  ...
  attachment_n 
</attachments>

This allows for multiple attachments. The attachment numbers increment by one for each attachment and n is the number of the final attachment.

The structure for a single attachment is:

<attachments>
  attachment_1 
</attachments>

Each attachment consists of a document node and an optional body property part. The document node contains a primary document with the attachment contents. You can specify an optional index attribute to define the order of attachments in the message. If the index attribute is omitted, attachments are processed in the specified order.

The structure for a basic document node without optional index attributes or body properties is:

<attachment_n>
  <document>
    PrimaryDocument
  </document> 
</attachment_n>

The structure for a document node with optional index attributes is:

<attachment_n>
  <document index=n>
    PrimaryDocument
  </document>
  <properties index=n>
    BodyProperties
  </properties> 
</attachment_n>

Body properties describe details of a payload message or attachment message. The structure for body properties is:

<BodyName>name</BodyName> 
<BodyDescription>description</BodyDescription> 
<BodyVersion>version</BodyVersion> 
<BodySchema>schema</BodySchema> 
<BodyEncoding>encoding</BodyEncoding> 
<BodyContentType>type</BodyContentType> 
<IsXMLContent>true or false</IsXMLContent>

Response Message

The response message consists of the response payload in the primary document and the SAPXIResponse structure which contains header and body details of the payload and an optional attachments part.

PrimaryDocument 
<SAPXIResponse>
  HeaderDetails
  <properties>
    BodyProperties
  </properties>
  Attachments (optional) 
</SAPXIResponse>

Header Details

<Header>
  <ToService>detail</ToService>
  <FromService>detail</FromService>
  <ToParty>detail</ToParty>
  <FromParty>detail</FromParty>
  <MessageID>detail</MessageID>
  <Action>detail</Action>
  <ActionNS>detail</ActionNS> 
</Header>

Outbound Messages

Messages sent from SAP XI to Sterling B2B Integrator are called outbound messages. For outbound messages, a business process is specified in an SAP XI adapter configuration. This business process is bootstrapped when a message is received from SAP XI. The Output Message is returned in the process data of the business process.

Output Message

The output message consists of the contents of the primary document, an SAP XI outbound structure and an originator ID.

The BPML format for the message is:

PrimaryDocument 
SAP XI Outbound Structure 
<OriginatorID>id</OriginatorID>

The SAP XI Outbound structure is:

<SAPXIOutbound>
  Header
  <properties>
    BodyProperties
  </properties>
  Attachments (Optional) 
</SAPXIOutbound>

Response Message

The bootstrapped business process can return a synchronous response to the sender in the same call passing the Originator ID to the outbound adapter configuration.

The Response message consists of the contents of the primary document, and optionally, attachments.

See Business Process Examples for more information.

Implementing the SAP XI Adapter

Installing the SAP XI Library Files

The SAP XI adapter requires three third-party libraries. Obtain the necessary .jar files from your SAP XI installation and install them on your Sterling B2B Integrator system.

Configuring the SAP XI Adapter

You must specify field settings in Sterling B2B Integrator, using the Admin Console, and in the GPM.

Creating or Setting Up an SAP XI Adapter Configuration in the Admin Console

Use the field definitions in the following table to create a new configuration of the SAP XI adapter, or to set up the configuration provided with Sterling B2B Integrator. Some fields are available in both the Admin Console and in the GPM. For the fields that are available in both, the GPM field name is shown in parentheses in the table below.

Setting Up the SAP XI Adapter in the GPM

Use the field definitions in the following table to set up the adapter configuration in the GPM:

Global Properties for the SAP XI Adapter

There are optional global properties that can be configured for the SAP XI adapter. For information, see sapxi.properties in the Sterling B2B Integrator online documentation.

Installing and Configuring the GIS Resource Adapter within SAP XI

The SAP XI Resource Adapter (GIS RA) is packaged in an SAP-specific installation called a Software Delivery Archive (SDA). This single SDA file (gis_xi_adapter_version.sda) contains all the files necessary to deploy the GIS RA in SAP NetWeaver.

Deploying the SDA in SAP NetWeaver

Adding the RA to the System Landscape Directory

After the SDA is deployed, the GIS RA must be added to the System Landscape Directory (SLD). You must define the RA as a software unit in SAP NetWeaver.

Creating a Repository Namespace

After creating the product and software component, you must create a namespace in the integration repository using the SAP Integration Builder.

Creating an Adapter Object

After creating the repository namespace, you must create an adapter object that defines an adapter type for the GIS RA. An adapter object is comprised of adapter metadata that defines configuration data for the adapter type and one or more communication channels. The adapter metadata defines the portion of a communication channel that is unique to the adapter type. A communication channel defines the rules for handling messages during inbound or outbound processing.

Setting Up the Adapter Metadata

Creating Communication Channel Templates

Communication channels define rules for handling messages during inbound or outbound processing. Depending on the direction of message processing, you require either a sender or a receiver channel. Therefore, you must create two communication channel templates, one for sending and one for receiving.

The GIS RA is now set up as a standard SAP XI resource adapter and can be used with the communication channel templates in SAP integration scenarios. See the SAP documentation for more information.

Business Process Examples

The following examples illustrate how the SAP XI adapter can be used in a business process for both inbound and outbound message processing:

Inbound Message Processing (Sterling B2B Integrator to SAP XI):

In this example, the input is the primary document containing the message. The sapxiinbound process sends a message to SAP XI. The message consists of the content from the primary document, the header from workflow parameters, and two attachments.

Process data contents before call

<ProcessData>
 <PrimaryDocument SCIObjectID="serverNode:169ca65:109f0bef19c:2f04"/>
 <att1>
    <message>This is my attachment 1 message</message>
  </att1>
 <doc1>
    <PrimaryDocument SCIObjectID="serverNode:169ca65:109f0bef19c:2f25"/>
 </doc1>
  <att2>
   <message>This is my attachment 2 message</message>
 </att2>
  <doc2>
   <PrimaryDocument SCIObjectID="serverNode:169ca65:109f0bef19c:2f47"/>
 </doc2>
  <attachments>
   <attachment_1>
      <document index="1">
       <PrimaryDocument SCIObjectID="serverNode:169ca65:109f0bef19c:2f25"/>
     </document>
      <properties>
       <BodyName>BodyName1</BodyName>
       <BodyDescription>BodyDescription1</BodyDescription>
       <BodyVersion>BodyVersion1</BodyVersion>
       <BodySchema>BodySchema1</BodySchema>
       <BodyEncoding>UTF-8</BodyEncoding>
       <BodyContentType>text/xml</BodyContentType>
       <IsXMLContent>true</IsXMLContent>
     </properties>
    </attachment_1>
   <attachment_2>
      <document index="2">
       <PrimaryDocument SCIObjectID="serverNode:169ca65:109f0bef19c:2f47"/>
     </document>
      <properties>
       <BodyName>BodyName2</BodyName>
       <BodyDescription>BodyDescription2</BodyDescription>
       <BodyVersion>BodyVersion2</BodyVersion>
       <BodySchema>BodySchema2</BodySchema>
       <BodyEncoding>UTF-8</BodyEncoding>
       <BodyContentType>text/xml</BodyContentType>
       <IsXMLContent>true</IsXMLContent>
     </properties>
    </attachment_2>
 </attachments> 
</ProcessData>

Message To Service

<SAPXIOut>
 <LocalPassword>********</LocalPassword>
 <RemotePassword>********</RemotePassword>
 
<JNDILocalAddress>serverNode:50004</JNDILocalAddress>
 <RemoteJNDIContext>com.sap.engine.services.jndi.InitialContextFactoryImpl
 </RemoteJNDIContext>
 <ServiceType>Inbound</ServiceType>
 <LocalJNDIContext>com.sap.engine.services.jndi.InitialContextFactoryImpl
 </LocalJNDIContext>
 <JNDIRemoteAddress>serverNode:50004</JNDIRemoteAddress>
 <LocalRegistryType>EXTERNAL_REG</LocalRegistryType>
 <RemoteUser>userName</RemoteUser>
 <LocalUser>userName</LocalUser>
 <JNDILocalKey>com.sterlingcommerce.woodstock.services.sapxiga</JNDILocalKey>
 <XMLVersion>1.0</XMLVersion>
  <JNDIRemoteKey>com.sterlingcommerce.woodstock.services.sapxira
  </JNDIRemoteKey>
 <XICallType>SYNCHRONOUS</XICallType>
 <AttachmentRoot>attachments</AttachmentRoot>
 <ToParty/>
  <FromParty/>
 <ToService>I03_OutboundToGIS</ToService>
 <FromService>I03_InboundFromGIS</FromService>
 <Action>CarstensMessageInterfaceSync</Action>
 <ActionNS>http://stercomm.com/adapter/gis</ActionNS>
 <MessageID>MSG_DV_001</MessageID>
 <MessageDescription>This is a test message description</MessageDescription>
 <BodyName>BodyName</BodyName>
  <BodyDescription>BodyDescription</BodyDescription>
 <BodyVersion>BodyVersion</BodyVersion>
 <BodySchema>BodySchema</BodySchema>
 <BodyEncoding>UTF-8</BodyEncoding>
 <BodyContentType>text/xml</BodyContentType>
 <IsXMLContent>true</IsXMLContent> 
</SAPXIOut>

BPML Business Process (Inbound)

<process name="callXI">
 <sequence name="sap">
    <!-- create two attachments -->
    <assign to="att1/message" from="'This is my attachment 1 message'">
    </assign>
   <operation name="XML Encoder">
     <participant name="XMLEncoder"/>
     <output message="XMLEncoderTypeInputMessage">
       <assign to="mode">process_data_to_document</assign>
       <assign to="root_element">att1</assign>
       <assign to="xPath" from="'att1/node()'"></assign>
       <assign to="att1" from="att1/node()"></assign>
     </output>
      <input message="inmsg">
       <assign to="doc1" from="*"></assign>
     </input>
    </operation>
   <assign to="att2/message" from="'This is my attachment 2 message'"></assign>
   <operation name="XML Encoder">
     <participant name="XMLEncoder"/>
     <output message="XMLEncoderTypeInputMessage">
       <assign to="mode">process_data_to_document</assign>
       <assign to="root_element">att2</assign>
       <assign to="xPath" from="'att2/node()'"></assign>
       <assign to="att2" from="att2/node()"></assign>
     </output>
      <input message="inmsg">
       <assign to="doc2" from="*"></assign>
     </input>
    </operation>
    <!-Create attachment structure with two attachments -->
    <assign to="attachments/attachment_1/document" from="doc1/node()"></assign>
   <assign to="attachments/attachment_1/document/@index" from="'1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyName"
         from="'BodyName1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyDescription" 
         from="'BodyDescription1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyVersion" 
         from="'BodyVersion1'"></assign>
    <assign to="attachments/attachment_1/properties/BodySchema" 
          from="'BodySchema1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyEncoding" 
         from="'UTF-8'"></assign>
    <assign to="attachments/attachment_1/properties/BodyContentType" 
          from="'text/xml'"></assign>
   <assign to="attachments/attachment_1/properties/IsXMLContent" 
         from="'true'"></assign>
    <assign to="attachments/attachment_2/document" from="doc2/node()"></assign>
   <assign to="attachments/attachment_2/document/@index" from="'2'"></assign>
   <assign to="attachments/attachment_2/properties/BodyName" from="'BodyName2'">
   </assign>
   <assign to="attachments/attachment_2/properties/BodyDescription" 
         from="'BodyDescription2'"></assign>
   <assign to="attachments/attachment_2/properties/BodyVersion" 
         from="'BodyVersion2'"></assign>
    <assign to="attachments/attachment_2/properties/BodySchema" 
          from="'BodySchema2'"></assign>
   <assign to="attachments/attachment_2/properties/BodyEncoding" 
         from="'UTF-8'"></assign>
    <assign to="attachments/attachment_2/properties/BodyContentType" 
          from="'text/xml'"></assign>
   <assign to="attachments/attachment_2/properties/IsXMLContent" 
         from="'true'"></assign>
   <!-- Now send message to SAP XI system -->
   <operation name="callsapxi">
      <participant name="SendToXI"/>
      <output message="SAPXIOut">
       <assign to="XICallType" from="'SYNCHRONOUS'"></assign>
       <assign to="AttachmentRoot" from="'attachments'"></assign>
       <assign to="ToParty" from="''"></assign>
       <assign to="FromParty" from="''"></assign>
       <assign to="ToService" from="'I03_OutboundToGIS'"></assign>
       <assign to="FromService" from="'I03_InboundFromGIS'"></assign>
       <assign to="Action" from="'CarstensMessageInterfaceSync'"></assign>
       <assign to="ActionNS" from="'http://stercomm.com/adapter/gis'"></assign>
       <assign to="MessageID" from="'MSG_DV_001'"></assign>
       <assign to="MessageDescription" 
             from="'This is a test message description'"></assign>
        <assign to="BodyName" from="'BodyName'"></assign>
       <assign to="BodyDescription" from="'BodyDescription'"></assign>
       <assign to="BodyVersion" from="'BodyVersion'"></assign>
       <assign to="BodySchema" from="'BodySchema'"></assign>
       <assign to="BodyEncoding" from="'UTF-8'"></assign>
       <assign to="BodyContentType" from="'text/xml'"></assign>
       <assign to="IsXMLContent" from="'true'"></assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="SAPXIIn">
       <assign to="." from="*"></assign>
     </input>
    </operation>
 </sequence> 
</process>

Outbound Message Processing (SAP XI to Sterling B2B Integrator):

In this example, the input is an SAP XI message with two attachments and the output is a response message with one attachment. The sapxiout_response process receives a message from SAP XI. The message consists of the message content and two attachments. Within the business process, a response message is created and passed back synchronously to the SAP XI system in the same call.

Process data directly after the business process is bootstrapped:

<?xml version="1.0" encoding="UTF-8"?> 
<ProcessData>
 <PrimaryDocument SCIObjectID="serverNode:169ca65:109de7de0fd:-5612"/>
 <SAPXIOutbound>
    <Header>
     <ToService>I03_OutboundToGIS</ToService>
     <FromService>I03_InboundFromGIS</FromService>
     <FromParty/>
      <MessageID>c41268c0-af56-11da-b4bc-0003ba783746</MessageID>
     <ToParty/>
    </Header>
   <attachments>
      <attachment_1>
       <document index="1">
          <PrimaryDocument SCIObjectID=
           "serverNode:169ca65:109de7de0fd:-560c"/>
       </document>
        <properties index="1">
          <BodyVersion>undef</BodyVersion>
         <BodyEncoding>UTF-8</BodyEncoding>
         <BodyName>BodyName1</BodyName>
         <IsXMLContent>false</IsXMLContent>
         <BodyDescription>BodyDescription1</BodyDescription>
         <BodyContentType>text/xml</BodyContentType>
       </properties>
      </attachment_1>
     <attachment_2>
        <properties index="2">
          <BodyDescription>BodyDescription2</BodyDescription>
          <BodyContentType>text/xml</BodyContentType>
          <BodyEncoding>UTF-8</BodyEncoding>
          <BodyName>BodyName2</BodyName>
          <IsXMLContent>false</IsXMLContent>
          <BodyVersion>undef</BodyVersion>
        </properties>
        <document index="2">
          <PrimaryDocument SCIObjectID=
           "serverNode:169ca65:109de7de0fd:-560a"/>
       </document>
      </attachment_2>
   </attachments>
    <properties>
     <BodyVersion/>
      <BodyName>BodyName</BodyName>
     <BodyDescription>BodyDescription</BodyDescription>
     <IsXMLContent>true</IsXMLContent>
     <BodyContentType>text/xml</BodyContentType>
     <BodyEncoding>utf-8</BodyEncoding>
     <BodySchema/>
    </properties>
 </SAPXIOutbound>
  <OriginatorID>serverNode.169ca65.109de7de0fd.F5647</OriginatorID> 
</ProcessData>

Additional Process data before response call:

... following process data is added by the business process to prepare the 
    response… 
<ResponseAttach>
   <Result>This is my response attachment message</Result>
 </ResponseAttach>
  <doc1>
   <PrimaryDocument SCIObjectID="serverNode:169ca65:109de7de0fd:-26e9"/>
 </doc1>
  <attachments>
   <attachment_1>
      <document index="1">
       <PrimaryDocument SCIObjectID="serverNode:169ca65:109de7de0fd:-26e9"/>
     </document>
      <properties>
       <BodyName>BodyName1</BodyName>
       <BodyDescription>BodyDescription1</BodyDescription>
       <BodyVersion>BodyVersion1</BodyVersion>
       <BodySchema>BodySchema1</BodySchema>
       <BodyEncoding>UTF-8</BodyEncoding>
       <BodyContentType>text/xml</BodyContentType>
       <IsXMLContent>true</IsXMLContent>
     </properties>
    </attachment_1>
 </attachments>

Message To Service:

<SAPXIOut>
 <SyncWaitTimeout>60</SyncWaitTimeout>
 <BootstrapBP>sapxiout_response</BootstrapBP>
 <LocalPassword>********</LocalPassword>
 <RemotePassword>********</RemotePassword>
 <JNDILocalAddress>serverNode:50004</JNDILocalAddress>
 <RemoteJNDIContext>com.sap.engine.services.jndi.InitialContextFactoryImpl
 </RemoteJNDIContext>
 <ServiceType>Outbound</ServiceType>
 <LocalJNDIContext>com.sap.engine.services.jndi.InitialContextFactoryImpl
 </LocalJNDIContext>
 <JNDIRemoteAddress>serverNode:50004</JNDIRemoteAddress>
 <LocalRegistryType>EXTERNAL_REG</LocalRegistryType>
 <RemoteUser>userName</RemoteUser>
 <SyncWait>Yes</SyncWait>
  <LocalUser>userName</LocalUser>
 <JNDILocalKey>com.sterlingcommerce.woodstock.services.sapxigareturn
 </JNDILocalKey>
 <XMLVersion>1.0</XMLVersion>
  <JNDIRemoteKey>com.sterlingcommerce.woodstock.services.sapxirareturn
  </JNDIRemoteKey>
 <XICallType>SYNCHRONOUS_RESPONSE</XICallType>
 <OriginatorID>serverNode.169ca65.109de7de0fd.F5647</OriginatorID>
 <AttachmentRoot>attachments</AttachmentRoot>
 <FromParty/>
  <FromService>I03_OutboundToGIS</FromService>
 <ToParty/>
  <ToService>I03_InboundFromGIS</ToService>
 <Action>CarstensMessageInterfaceSync</Action>
 <ActionNS>http://stercomm.com/adapter/gis</ActionNS>
 <BodyName>BodyName</BodyName>
  <BodyDescription>BodyDescription</BodyDescription>
 <BodyVersion/>
  <BodySchema/>
 <BodyEncoding>utf-8</BodyEncoding>
 <BodyContentType>text/xml</BodyContentType>
 <IsXMLContent>true</IsXMLContent> 
</SAPXIOut>

BPML Business Process (Outbound):

<process name="sapxiout_response">
 <sequence name="sap">
    <assign to="ResponseAttach/Result" 
          from="'This is my response attachment message'" />
   <operation name="XML Encoder">
      <participant name="XMLEncoder" />
      <output message="XMLEncoderTypeInputMessage">
         <assign to="mode">process_data_to_document</assign>
         <assign to="root_element">ResponseAttach</assign>
         <assign to="xPath" from="'ResponseAttach/node()'"/>
         <assign to="ResponseAttach" from="ResponseAttach/node()"/>
      </output>
       <input message="inmsg">
         <assign to="doc1" from="*" />
      </input>
    </operation>
   <!-- Create Response Payload (overwrite Prim. Doc.) -->
   <assign to="ResponsePay/Result" from="'This is my response payload 
                                          message'" />
   <operation name="XML Encoder">
      <participant name="XMLEncoder" />
      <output message="XMLEncoderTypeInputMessage">
         <assign to="mode">process_data_to_document</assign>
         <assign to="root_element">ResponsePay</assign>
         <assign to="xPath" from="'ResponsePay/node()'"/>
         <assign to="ResponsePay" from="ResponsePay/node()"/>
      </output>
       <input message="inmsg">
         <assign to="." from="*" />
      </input>
    </operation>
   <!-- Create Response Attachment structure -->
   <assign to="attachments/attachment_1/document" from="doc1/node()">
   </assign>
   <assign to="attachments/attachment_1/document/@index" from="'1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyName"
         from="'BodyName1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyDescription" 
         from="'BodyDescription1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyVersion" 
         from="'BodyVersion1'"></assign>
    <assign to="attachments/attachment_1/properties/BodySchema" 
          from="'BodySchema1'"></assign>
   <assign to="attachments/attachment_1/properties/BodyEncoding" 
         from="'UTF-8'"></assign>
    <assign to="attachments/attachment_1/properties/BodyContentType" 
          from="'text/xml'"></assign>
   <assign to="attachments/attachment_1/properties/IsXMLContent"
           from="'true'">
   </assign>
    <!-Now send back response with outbound adapter -->
   <operation name="SAPXI_DeliveryResponse">
     <participant name="GetFromXI"/>
     <output message="SAPXIOut">
      	<assign to="XICallType" from="'SYNCHRONOUS_RESPONSE'"></assign>
     	<assign to="OriginatorID" from="OriginatorID/text()"></assign>
     	<assign to="AttachmentRoot" from="'attachments'"></assign>
     	<assign to="FromParty" from="SAPXIOutbound/Header/ToParty/text()"/>    
      	<assign to="FromService" from="SAPXIOutbound/Header/ToService/text()"/>
      	<assign to="ToParty" from="SAPXIOutbound/Header/FromParty/text()"/>
      	<assign to="ToService" from="SAPXIOutbound/Header/FromService/text()"/>
        <assign to="Action" from="'CarstensMessageInterfaceSync'"></assign>
       <assign to="ActionNS" from="'http://stercomm.com/adapter/gis'"></assign>
      	<assign to="BodyName" from="SAPXIOutbound/properties/BodyName/text()">
       </assign>
       <assign to="BodyDescription" 
             from="SAPXIOutbound/properties/BodyDescription/text()"></assign>
       <assign to="BodyVersion" 
             from="SAPXIOutbound/properties/BodyVersion/text()"></assign>
       <assign to="BodySchema" 
             from="SAPXIOutbound/properties/BodySchema/text()"></assign>
       <assign to="BodyEncoding" 
             from="SAPXIOutbound/properties/BodyEncoding/text()"></assign>
       <assign to="BodyContentType" 
             from="SAPXIOutbound/properties/BodyContentType/text()"></assign>
       <assign to="IsXMLContent" 
             from="SAPXIOutbound/properties/IsXMLContent/text()"></assign>
       <assign to="IsXMLContent" from="'true'"></assign>
       <assign to="AttachmentRoot" from="'attachments'"></assign>
     	<assign to="." from="*"></assign>
	 </output>
      <input message="SAPXIResponse">
       <assign to="." from="*"></assign>
     </input>
    </operation>
 </sequence> 
</process>

Parameters Passed From Business Process to Adapter

The following table contains the parameters passed from the business process to the SAP XI adapter: