RosettaNet is a non-profit organization whose goal is to standardize on open e-business processes for document interchange. The organization consists of the world's leading information technology (IT), electronic components (EC), semiconductor manufacturing (SM), and solution provider (SP) companies. XML is used as the core technology to provide a common medium of business-to-business communication between organizations, departments, and trading partners.

Microsoft BizTalk Server 2004 helps companies efficiently and effectively integrate systems, employees, and trading partners through manageable business processes, enabling them to automate and orchestrate interactions in a highly flexible and highly automated manner.

Microsoft BizTalk Accelerator for RosettaNet (BTARN) 3.0 combines prebuilt support for all current RosettaNet Partner Interface Processes (PIPs) with a suite of development, testing, management, and rapid deployment tools to significantly reduce the time and resources required to build, deploy, and manage RosettaNet-based integration with trading partners.

The Microsoft BizTalk Adapter v2.0 for mySAP Business Suite provides the means to enumerate all IDoc, BAPI, and RFC calls (including customized IDocs) and allows the user to select multiple IDocs, BAPIs, and RFCs for each adapter instance. It also provides the means to enumerate IDoc, BAPI, and RFC schemas and convert these schemas into BizTalk Server 2004-compatible XSD schemas.

BizTalk Server 2004, along with BTARN, provides a business process platform for implementing the RosettaNet standard and includes the capability to integrate messages between companies from various industries who are involved in using heterogeneous back-end systems. The PIPs are XML-based RosettaNet document specifications (or schemas) that are used as a core to mapping messages between a RosettaNet document and other system formats such as those used by SAP and Siebel systems.

Throughout this document, we use a RosettaNet 3A4 Purchase Order Request document and an SAP ORDERS05 IDoc. BizTalk Server is used to integrate and map between these two formats. This sample extends the capability of the Microsoft BizTalk Server 2004 solution and provides an example of message exchanges by integrating RosettaNet transactions interfacing with the SAP systems using Microsoft BizTalk Accelerator for RosettaNet 3.0 and the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite.

The RosettaNet Partner Interface Processes (PIPs) are business processes between trading partners. The processes are specialized system-to-system XML-based messages that include the terms and conditions associated for document exchanges. A message generally covers many scenarios that may occur during the exchange of dialogs between two or more systems. For example, if a message is transmitted from one system to the next and an error occurs, we can find a set of schemas defined to handle such error conditions. The RosettaNet PIPs contain a set of schemas that define various scenarios of message exchanges.

RosettaNet categorizes the PIPs by high-level business functions called clusters and subfunctions known as segments. Each PIP defines how a document is packaged and processed. The PIPs come in seven clusters, or groups of core business processes, and each cluster is divided into segments. For a complete list of clusters and segments, visit http://go.microsoft.com/fwlink/?LinkId=56832. For this document, we focus on the 3A4 PIP. The 3A4 can be broken down into Cluster 3 as Order Management, Segment A as Quote and Order Entry, and Process 4 as Manage Purchase Order for the 3, A, and 4 representations. We cover more on the 3A4 schema later in this document.

When BizTalk Server 2004 and the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite are installed together, BizTalk Server can seamlessly establish a connection with an SAP R/3 4.x or R/3 6.20 (Enterprise) system. The Add Generated Items Wizard provides a "no-code" connectivity solution for integrating SAP data.

Prior to generating schemas through the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite, we create a send port by using BizTalk Explorer. The send port is mainly used as a means to access the metadata located in the SAP Business Object Repository (BOR). Figure 1 shows a window to create a new one-way static send port associated with the address (URI). Figure 2 shows another window to set up the SAP transport credentials.

Figure 1 Static one-way send port

Figure 2 Setting a physical send port in BizTalk Explorer for the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite

The send port created previously can then be used to access the SAP system remotely in the Add Adapter Wizard. Figure 3 shows the Add Adapter Wizard used in the process of generating schemas using the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite.

Figure 3 Add Adapter Wizard in BizTalk Server 2004

Figure 4 is where we search the IDocs, BAPIs, or RFCs in the SAP system using a configured port. Here, we search the ORDERS05 IDoc and choose the ORDERS05 IDoc from the results list. Finishing the wizard generates an ORDERS05 schema and saves it under the BizTalk project.

Figure 4 Schema Generation Wizard for ORDERS05 IDoc

Key Capabilities of the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite

What is an IDoc? IDoc stands for Intermediate Document in SAP. IDocs are categorized according to their message types, and each message type contains the basic IDoc type. The IDoc we use in our scenario is ORDERS05, which is a basic IDoc type and is categorized under the ORDERS message type. Using the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite, we can generate the ORDERS05 schema as shown in the steps in the previous section.

Usually, the ORDERS05 schema is around 1,700 KB in size and complicated in structure. The first element of the schema is EDI_DC40, which contains the control record information representing the IDoc header message. Some of the important fields in this element are IDOCTYP, MESTYP, SNDPOR, SNDPRT, SNDPRN, RCVPOR, RCVPRT, and RCVPRN. It is important to have appropriate values in these fields for the SAP system to identify a valid inbound IDoc. IDOCTYP is the type of IDoc, MESTYP is a message type, SNDPOR is a send port, SNDPRT is a send port type, and SNDPRN is a send port number. Similarly, RCVPOR is a receive port, RCVPRT is a receive port type, and RCVPRN is a receive port number.

Another element in this schema is E1EDK14. This part is important because it defines the organizational data such as the Sales Organization, Distribution Channel, and Division in the SAP system for the IDoc. It has a qualifier to identify each type of E1EDK14 message. For example, the QUAL field in the schema (which represents the qualifier) is 008 for Sales Organization, 007 for Distribution Channel, and 006 for Division. Each qualifier has an Org Id to represent which type of Sales Organization it is, which type of Distribution Channel, and so on.

E1EDK03 is the next segment, which defines dates. It contains a qualifier (IDDAT) and a value (DATUM) to hold the date type and the date. Examples of a qualifier (IDDAT) are 012 for Document Date, 022 for Purchase Order Date, and 028 for Due Date.

E1EDKA1 is a segment in this message type where it defines the partner information. It contains the address of the business partner. The individual roles are defined in the PARVW field and the partner number is defined in the PARTN field. It has other fields such as NAME1, NAME2, STRAS, STRAS2, ORT01, REGIO, PSTLZ, TELF1, and TITLE. All of these fields define Firstname, Lastname, Street1, Street2, City, State, Zip, and so on. In this segment, PARVW identifies the business partner role type, such as AG to be sold-to-party, RE to be bill-to-party, LF to be vendor, and WE to be ship-to-party.

Figure 5 shows a sample ORDERS05 schema.

Figure 5 A sample of the ORDERS05 IDoc schema in the BizTalk Schema Editor

The E1EDP01 segment contains information about the line item. POSEX is the first field in this segment and signifies the line item number of a line item. The ACTION field defines which action to take before the dispatch, or which action to carry out by the receiver. MENGE and MENEE describe the quantity and unit of measure, while BMNG2 and PMENE describe the quantity in price unit and price unit of measure, respectively. The other two segments, E1EDP19 and E1EDP20, are subsegments of E1EDP01. E1EDP19 includes the material description. It has a qualifier (QUAL) to pass different types of material descriptions. For example, 001 is a material number used by a customer and 002 is a material number used by a vendor. E1EDP20 includes scheduled quantity and dates for an item. It has fields like WMENG, AMENG, EDATU, EZEIT, and ACTION. For example, WMENG is a scheduled quantity, EDATU is a scheduled date, and EZEIT is a scheduled time.

The RosettaNet Purchase Order Request document uses a 3A4 schema. The purchase order request schema is applied to issue a new purchase order request. Primarily, it enables a buyer to issue a purchase order and obtain a response from the provider to notify if a certain line item is accepted, rejected, or pending via the purchase order confirmation schema. This scenario does not cover the confirmation message back to the user.

The main elements of the Purchase Order Request schema are fromRole, PurchaseOrder, thisDocumentGenerationDateTime, thisDocumentIdentifier, and toRole. The fromRole segment contains information about the partner role description. It signifies the business description, contact information, and physical location of the role initiating the business document exchange.

The PurchaseOrder element is another part of this schema that contains the core information about the purchase order itself. It has elements to hold information like account description, document reference, shipping information, product line item, shipping destination, and total amount. The thisDocumentGenerationTime element identifies the date and timestamp of the current document, and the thisDocumentIdentifier element identifies a unique number of the current document.

Figure 6 shows a sample RosettaNet 3A4 Purchase Order Request schema.

Figure 6 A sample of the RosettaNet 3A4 schema in the BizTalk Schema Editor

The toRole segment represents the role that receives the document in the business document exchange and contains information similar to the fromRole segment.

Mapping a source schema to a destination schema is done in the BizTalk Mapper tool. In this example, the source schema is 3A4 Order Request and the destination schema is the ORDERS05 IDoc schema. Generally, we connect nodes from the source schema to the destination schema to link the values from the source node to the destination node for message transformations. However, in this sample, both the source and destination schemas are large and complicated. Due to its intricate structure and numerous nodes, the mapping is more complex than simply linking the source and destination nodes. In order to surmount the complicated logic between the source and destination nodes, BizTalk Server 2004 provides functoids.

The BizTalk Mapper tool provides built-in functoids such as a looping functoid, a logical existence functoid, a value mapping functoid, an isEqual functoid, an indexing functoid, and many more. On top of these built-in functoids, BizTalk Server 2004 provides the flexibility to add a customized functoid to meet a developer’s needs. Below we have several figures to define each group of functoids we use in order to enable a valid mapping between the source and destination schemas.

The E1EDK14 node in the destination message is looped with different values for the qualifiers (QUAL) and the corresponding ORGID coming from the source schema. In this case, we are using the logical existence functoid and the value mapping functoid along with the looping functoid. The logical existence functoid is used to check the existence of a value in the source node and the value mapping functoid is used to validate the logic of the input parameters. The latter functoid takes two parameters and compares the value to be true or false. If the logic is true, it passes the value to the destination node; otherwise, nothing happens.

Figure 7 shows the mapping of the source schema to the destination schema using a looping functoid, a logical existence functoid, and a value mapping functoid.

Figure 7 Mapping using looping, logical existence, and value mapping functoids

We use a looping functoid in cases where multiple nodes in the source schema are linked to a single node in the destination schema. The single destination node consumes different values from the multiple source nodes. For example, in our map, the GlobalBusinessIdentifier node under the billTo structure and the GlobalBusinessIdentifier node under the shipTo structure of the source 3A4 schema are linked to the PARTN node in the E1EDKA1 structure of the destination ORDERS05 schema. Hence, the looping functoid generates as many E1EDKA1 segments along with the PARTN elements as the number of nodes linked from the destination schema. Figure 8 shows the mapping of the source schema to the destination schema using another scenario of utilizing the looping functoid, the logical existence functoid, and the value mapping functoid.

Figure 8 Mapping using looping, logical existence, and value mapping functoids

The E1EDK03 node in the destination schema is looped with different values for the qualifier (QUAL) and different dates (DATUM) for each qualifier similar to how we did this in the E1EDK14 node. However, in Figure 9, we use the iteration functoid to separate the DocumentReference nodes one at a time and pass the datetime value to the DATUM node in the destination schema.

Figure 9 Mapping using iteration, equal, and value mapping functoids

In Figure 10, we use the string find and string extract functoids. The string find functoid returns a position in a string where a specified string begins. Accordingly, the string extract functoid extracts a string specified by the start and end positions of an input string. In our example below, these two functoids are used to extract the data from a timestamp value and are passed to the DATUM node in the destination schema.

Figure 10 Mapping using string find and string extract functoids

Microsoft BizTalk Accelerator for RosettaNet (BTARN) 3.0 builds on top of BizTalk Server to enable business communications among business partners. It provides support for the RosettaNet Implementation Framework (RNIF) and Partner Interface Processes (PIPs) to automate transactions. RNIF defines how systems transmit the RosettaNet messages. The RNIF standard helps in transferring, routing, packaging, and securing the messages traveling from one system to another. This standard also defines the message structures, acknowledgments, MIME encoding, and digital signatures based on HTTP, MIME, and XML technologies. The RosettaNet organization defines message exchanges using the RNIF specifications. RNIF provides a predefined flow to exchange messages among integrated systems.

Messages are sent from the initiator to the responder systems and passed through the BTARN 3.0 installed in both ends. The line-of-business application starts the flow of the message by sending it to the initiator system in its raw format. Then, the message transforms into the RNIF-compliant message and gets sent over the Internet to the responder computer. When the responder system receives a double-action message (a 3A4 message in our scenario), it converts the message from an RNIF-compliant message to the message in a proprietary format and sends an acknowledgment to the initiator as a response.

The BTARN Management Console configures processes, a home organization, partners, and agreements between the home and the partner organizations. In our case, the home organization is CONTOSO, the partner organization is FABRIKAM, the agreement is Contoso_To_Fabrikam _3A4, and the process configuration we use is STD_3A4_V02.02 (Request Purchase Order).

Since we do not use Secure Sockets Layer (SSL) server authentication and signing certificates in this sample, we must change the behavior of the document exchange between home and partner organizations by changing the parameters of the STD_3A4_V02.02 process configuration settings. To do so, we double-click the STD_3A4_V02.02 under Process Configuration Settings in the BTARN 3.0 Management Console or right-click the STD_3A4_V02.02 and click Properties on the context menu. The BTARN 3.0 Management Console is shown in Figure 11.

Figure 11 BTARN 3.0 Management Console showing STD_3A4_V02.02 process configuration settings

Once we have the properties window opened for STD_3A4_V02.02, we change the parameters to false as shown in Figure 12. This allows us to exchange documents without using the encryption and signing certificates.

Figure 12 STD_3A4_V02.02 process configuration activity settings

In order to create the home organization, we right-click the surface on the right side of the screen under Home organization in the BTARN 3.0 Management Console, point to New on the context menu and click Home Organization. A Home Organization property window pops up as shown in Figure 13. We then enter the Name and Global Business Identifier (GBI), also called DUNS number, to uniquely identify this organization. Finally, we enter the contact information on the Contact Properties tab and click OK. Similar steps are followed to create a new partner organization.

Figure 13 BTARN 3.0 Management Console's home organization properties

When we create an agreement between the home and partner organizations, we click on the right surface under Agreements and point to New to open the New Agreements Properties window as shown in Figure 14. Then we enter the name of the agreement, choose My Organization and Partner Organization, and click the Ports tab. On the Ports tab, we enter the Action URL, Signal URL, and Sync URL as "http://localhost/BTARNApp/RNIFReceive.aspx" for all and click OK to create this agreement.

Figure 14 New Agreement Properties window

Since this scenario involves only one computer to transmit the 3A4 request and receive a response message versus using two separate computers to process the flow, we use a loopback command to create an agreement between the CONTOSO and FABRIKAM organizations. The loopback command that comes with BTARN 3.0 is located in <drive>:\Program Files\Microsoft BizTalk Accelerator for RosettaNet 3.0\SDK. The two commands listed below generate a loopback agreement between a CONTOSO organization and a FABRIKAM organization:

> <Loopback /enable CONTOSO
> Loopback /mirror "Contoso_To_Fabrikam_3A4"

Figure 15 Microsoft BizTalk Accelerator for RosettaNet Management Console

Figure 15 shows the Microsoft BizTalk Accelerator for RosettaNet Management Console where we can view the process configuration settings, home organizations, partners, and agreements. To open this application, click Start, point to All Programs, point to Microsoft BizTalk Accelerator for RosettaNet 3.0, and then click BizTalk Accelerator for RosettaNet Management Console.

Our scenario starts off with the Web client application. The Web interface allows users to enter the home organization name, the partner organization name, the PIP instance ID, and the service content. The service content holds the 3A4 XML message. For more information on the Web interface, see "Web Client Interface" below.

As soon as the user submits the message from the Web interface, the initiator computer stores it in the SQL Server database. Then BTARN on the initiator computer sends the message from the SQL Server database to the SQL adapter. The SQL adapter forwards the message to the XML receive pipeline that does a simple XML validation of the message. BizTalk Server then routes this message to the MessageBox database. As soon as it reaches the MessageBox database, the private process processes the service content of the message, and the public process processes the RNIF headers of the message. Soon after that, BTARN routes the message back to the MessageBox database and the send pipeline performs assembly and signing/encryption/encoding of the message, ready to be routed to the HTTP adapter. Finally, BTARN routes the message to the RNIFSend.aspx page, which sends it over the Internet to its destination. Figure 16 shows the flow of the message starting from the line-of-business application to the point where the RNIFSend.aspx page sends it off to the responder system via the Internet.

Figure 16 Flow of an initiator message

The following components are involved in processing the message in the initiator system:

• SQL adapter
  
• XML receive pipeline
  
• Initiator private process
  
• Initiator public process
  
• XML send pipeline
  
• HTTP adapter
  
• RNIFSend.aspx page
  

On the other end, when the responder computer receives the message from the initiator system, BTARN submits the message to the HTTP adapter, which forwards it immediately to the receive pipeline. The receive pipeline decodes, disassembles, and performs party resolution, and then transforms the message to the proprietary format of the back-end line-of-business application. BTARN then routes the message to the MessageBox database. The public process processes the RNIF headers of the message and the private process processes the service content of the message. The private process also generates an acknowledgment for the public process, the MessageBox database, the send pipeline and the HTTP adapter for return over the Internet back to the initiator system. BTARN then reroutes the message to the MessageBox database. The send pipeline assembles and signs/encrypts/encodes the message. BTARN routes the message to the SQL adapter, which submits the message to the SQL Server. When the message gets stored in the SQL Server engine of the responder computer, the rprtRN3A4_ORDERS05 receive port pulls the message from the MessageToLOB table in the BTARNDATA database in the SQL Server engine using the SQL adapter located in the responder computer. The RN3A4_ORDERS05 orchestration extracts the service content and creates the 3A4 message. This message is transformed into the ORDERS04 IDoc message, and then it is sent to the designated SAP system using the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite. For more information on the responder RN3A4_ORDERS05 orchestration, see the "Overall Architecture" section.

Figure 17 Flow of a responder message

Figure 17 shows the flow of the responder message. The following components are involved in processing the message in the responder system:

• RNIFReceive.aspx page
  
• HTTP adapter
  
• Receive pipeline
  
• Responder public process
  
• Responder private process
  
• SQL adapter
  
• Send pipeline
  
• Microsoft BizTalk Adapter v2.0 for mySAP Business Suite
  

Orchestrations are created in BizTalk Server for business process flow. The orchestration, as shown in Figure 18, is implemented to pull a message from the BTARN database located in the responder computer and forward it to the designated SAP system. This orchestration starts when the responder system completes its process of storing the message in the BTARN database of the SQL Server engine. The SQL adapter in the responder system then extracts the message from the BTARN database using the receive port. This receive port passes the message to the receive pipeline, which stores it into the MessageBox database of Microsoft BizTalk Server 2004. Hence, the orchestration we implemented subscribes to the MessageBox database and extracts the service content message as a core 3A4 message instance using the MsgHeaderHelper solution. Before we run the RNPIP3A4_ORDERS04_BTS BizTalk solution, we must install the MsgHeaderHelper in the global assembly cache. Finally, the orchestration transforms the 3A4 message to an ORDERS05 IDoc message using the map defined in the BizTalk Mapper tool.

Figure 18 shows the top portion of the orchestration. This part of the orchestration is defined inside a long-running transaction scope and receives the message from a 3A4ReceivePort. After it receives the message, the ConstructServiceContentMsg extracts the service content message and assigns it to the SvcContent variable, using the MsgAssignment shape in the orchestration to construct the 3A4 message. At the same time, this orchestration also handles System.Exception should an error occur during the message flow.

Figure 18 BizTalk orchestration to receive a RosettaNet message and extract a service content 3A4 message – Part I

Figure 19 Send 3A4 message to the SAP system after transforming it to the ORDERS05 IDoc message

Figure 19 is the other half of the orchestration. It has a parallel action shape and distributes the action to acknowledge the receipt of the RosettaNet 3A4 message while sending the ORDERS05 IDoc message to the SAP system. The 3A4 message is transformed to the ORDERS05 IDoc message before it is sent out to the assigned SAP system.

A Web interface exposes the fields that are passed to BizTalk Accelerator for RosettaNet (BTARN) 3.0 for further processing. The primary fields are the Home Organization, the Partner Organization, the 3A4 Instance ID, and the Service Content message exposed on the Web interface. When the user clicks the submit button with information in the text fields, it passes the values to BTARN. Figure 20 shows the Web client interface.

Note
Disable the anonymous access to the Web folder in the IIS manager on the Directory Security tab of the Properties window.

Figure 20 Web interface to insert Home, Partner, 3A4 Instance ID, and the Service Content message

When the page above submits data, the browser redirects to the query data page and polls the MessageToLOB table to fetch the signal messages from the BTARN database located in the initiator system. Some of the signal messages defined in BTARN 3.0 are 10 as a request signal, 25 as a response signal, and 50 as a response signal with an acknowledgment.

In Figure 21, the Outgoing Message section shows information from the MessageFromLOB table in the BTARN database and the Incoming Message section shows information from the MessageToLOB table in the BTARN database of the initiator computer.

Figure 21 Web interface to check the status of the messages

When the designated SAP R/3 system receives the ORDERS05 IDoc, we can create a new purchase order, and change and display the document by using transactions such as VA01, VA02, or VA03. In Figure 22, we use transaction VA03 to display information to view a newly arrived purchase order number 9190 located in the SAP system.

Figure 22 Display purchase order using transaction VA03

Other useful transactions to check the receipt of ORDERS05 IDoc are WE19 and WE20. Transaction WE19 lets us view the IDoc in a structured format, and WE20 allows us to view the same IDoc in a segment-by-segment format. Figures 23 and 24 display the transactions WE19 and WE20 in the SAP system.

Figure 23 Use of transaction WE19 to view ORDERS05 IDoc

Figure 24 Use of transaction WE20 to view ORDERS05 IDoc

In this document, we explored an end-to-end flow of a purchase order generated from a Web interface to a designated SAP R/3 system using Microsoft BizTalk Accelerator for RosettaNet (BTARN) 3.0. The RosettaNet 3A4 schema, BTARN 3.0, the Microsoft BizTalk Adapter v2.0 for mySAP Business Suite, and Microsoft BizTalk Server 2004 are the main components used as a channel to enable the communication between the Web interface and the external SAP system.