Introduction

With the addition of new adapter support in IBM® WebSphere® Message Broker V6.1 (hereafter called Message Broker), you can communicate a with a SAP system using the embedded WebSphere Adapter for SAP. This new function offers a number of advantages, including ease of operation and improved performance, and is now the the recommended solution over MQSeries Link for R3. Along with these benefits, there are some migration issues that require attention when moving from an architecture that uses the R3Link to a one that uses the WebSphere Message Broker Adapter Nodes. These issues are covered in this article. As part of the migration, you will need to create new artifacts to use in Message Broker. Doing this is not difficult and this article shows you how.

The R3Link was used in a number of different ways. Migration for the most common usage scenarios is covered in this article and the cases are listed here and shown in Figure 1 below:

1. Sending IDocs from SAP via the R3Link to a Message Broker message flow
2. Sending IDocs from SAP via the R3Link to an application
3. Sending IDocs from a Message Broker flow via the R3Link to SAP
4. Sending IDocs from an application via the R3Link to SAP

The R3Link can be used to send and receive IDocs between SAP and an application. In this migration case, the target application will produce and consume messages in the format of the R3Link. If this application is to continue to send and receive messages as formatted by the R3Link, an intermediary is needed to convert messages in both directions. Message Broker can fulfill that role, as explained later in the article. This migration assumes:

• You have a working R3Link installation (including SAP).
• You have access to the R3Link configuration files.
• You have some knowledge of the R3Link.
• You have some knowledge of SAP.
• You have a SAP logon.
• You have a working Message Broker installation.
• You have some knowledge of developing Message Broker message flows.

This article shows you how to migrate off the R3Link, which is replaced with a message flow with a SAP adapter node. In Migration Scenarios #1 (SAP to Message Broker) and #3 (Message Broker to SAP), there is an existing message flow. In these cases, the message flow has to be migrated and then altered to use the new adaptor nodes for SAP. In Migration Scenarios #2 (SAP to an application) and #4 (application to SAP), there is no existing message flow, so it is more accurate to say that you are building a new message flow to replace the functionality of the R3Link. This article has five parts:

• Configuring the adaptor connection
• Creating a new message flow
• Migrating an existing message flow
• Changing SAP settings
• Deploying the flow

The sections "Configuring the adapter," "Changing SAP settings," and "Deploying the flow" are common and must be completed for all migration cases. The section "Creating a new message flow" is applicable to Migration Scenarios #2 and # 4. The section "Migrating an existing message flow" relates to Migration Scenarios #1 and #3.

Configuring the adaptor connection

In all migration cases, the first step is to configure the adapter connection, because in all cases you need communication with SAP. Use the Adapter Connect wizard in the Message Broker toolkit, as described below:

When you first open the Message Broker toolkit, you are asked to select a workspace:

This screen is where you save your projects. To accept the default location, click OK. If this is the first time you have used this workspace, you will see the welcome screen. To close it, click Go to the Message Broker Toolkit:

To return to the Welcome screen, click Help => Welcome. If you have not used the Message Broker toolkit before, it is worth exploring the links off this screen at some point.

You can now start configuring the adapter. To create and configure the adapter node, start the Adapter Connection wizard: click Start from adapter connection in the broker development view of the Broker Application Development perspective, as shown in Figure 4 below. If Start from adapter connection is not visible, click the button next to Active Working Set. You can also start the wizard by clicking File => New => Adapter Connection.

You will see the Adapter Connection Wizard window. Select IBM WebSphere Adapter for SAP Software transaction support (IBM: 6.1) and click Next:

The next screen is the Connector Import, where you set the connector project name. Change it to a meaningful name, such as one including the name of your SAP system, and click Next. Fill in information about the JAR and library files. For more information, see Adding external software dependencies for SAP in the Information centre.

The steps you have taken to this point only need to be completed once to set up the connect project. The following steps must be completed for each new SAP adapter you create. You will need one adapter for each instance of the R3Link. You should now see the Adaptor Style window. In this case we are migrating a flow that processes information that originated from SAP, which is called an inbound flow. Click Next.

If you are migrating an R3Link that sends IDocs to SAP, then select Outbound. Follow the remaining steps. Any deviation for the outbound IDoc process will be highlighted.

In the R3Link world, the direction was relative to SAP, so data that was sent from SAP was called outbound. With the WebSphere Message Broker V6.1 Adapter for SAP (hereafter called the Message Broker Adapter for SAP), the direction is relative to the broker, so in this case it is called inbound. You can find the values for the Configure Setting for Discovery Agent in the R3Link smqDestConf file. Here is an example of a smqDestConf file:

receivingdestination
receivingpartner=ORDERS0
edi_mestype=MATMAS
outboundqueuemanager=V61QM
outboundqueue=R3LINK_O
calluserexit=no
exitname=
exitbuffer=
client=001
language=E 
hostname=1.1.1.1 
systemnumber=00 
userid=anID 
password=aPassword 
default=yes

The required values are in bold. The outboundqueue name will be needed when the flow is developed. Change SAP interface name to ALE pass-through IDoc. Your screen should look like this:

The next screen is the IDoc Discovery window . To set a filter, click the Filter button (make sure you have first clicked Discover IDoc From System):

In this case you are looking for a MATMAS05 IDoc, so you set the filter:

Once it is discovered, select it. Click Add selected objects to be imported to move the IDoc into the Object to be Imported" window, and then click Next:

At the Configure Objects screen, click Next. If you are configuring an outbound adapter, a window will pop up before moving to the next screen. Click OK. The next screen will show the business object namespace. Copy the namespace, because you will need it when you write the message flow. Click OK.

In the Publishing Object Configuration Properties screen, you must enter the RFC program ID and password. The RFC program ID is in the R3Link out.ini file, and is called programid. To set the password, click Advanced, which will display additional properties. Scroll down until you find the password property and set it to the required password:

At the next screen, change the name of the message flow project, message set project, and message set. Enter a name for the Adapter component. The name will appear in the adapter properties. Pick a name that differentiates this adapter from all others. For example, you could use a standard like <SAP transaction>_<direction (o or i)>. This example uses MATMAS05_i_R3Link_migration. R3Link_migration is added to the name to make the function of the adapter clear:

You can now click Finish on the Adapter Connection Wizard. When you see a Tip window, click OK. This completes the adapter configuration. The next step is message flow development.

Creating a new message flow

In the case where you sent IDocs from SAP to an application over the R3Link or received them into SAP from an application over the R3Link, a message flow must be built to facilitate this communication, as the R3Link will not longer be able to do this. The R3Link produces messages with the structure shown in Figure 12:

This section assumes that the target application sends and receives the messages, in the above structure. In this migration case, you must ensure that the message flow produces or receives messages with the same structure. Depending on the direction of the communication, one or both different message flow types will be needed. If you already have a message flow that processes R3link messages, you should see the next section "Migrating an existing message flow."

Creating a new inbound message flow

An inbound message flow will be needed when receiving IDocs from SAP and forwarding them to an application that expects to receive data in R3Link format.

The first step is to open the message flow. If you have followed the steps earlier, you will have a message flow and message set project. Open the message flow by expanding the plus sign next to the message set. In the example it is MATMAS05_i_R3Link_migration => Flow => default broker schema. Double-click on the flow name -- for example, MATMAS05_i_R3Link_migrationFlow.msgflow:

The message flow canvas will be displayed. Drag the adapter to the canvas. To find the adapter, expanding MATMAS05_i_R3Link_migrationMessageSet => Adapters => Inbound => SAP, as shown in Figure 13. You will see two nodes: the node on the left is the adapter and the node to the right is a subflow, which should be deleted, as it does not provide the functionality you need. Add a subflow called Add_SAP_Header to the canvas (to find out how to import the subflow, see Appendix B: Importing Add_SAP_Header_Project_Interchange_file.zip). This subflow takes the message from the adapter and transforms it to the same structure as the R3Link message. You also need to add an MQOutput node, which can be found on the palette next to the canvas:

Connect the output terminal from the adapter to the input terminal of the subflow Add_SAP_Header and the output terminal from Add_SAP_Header to the input terminal of the MQInput node. The flow should look like this:

Click on the node Add_SAP_Header and select Properties. Below the canvas, you will see the properties of this node:

You can fill in the values according to the smqDestConf file. Right-click on MQOutput node and select Properties. Under Properties tab => Basic, enter the output queue and, if needed, a queue manager. Take the values for the queue and queue manager names from the smqDestConf file. (These properties are optional.)

In the smqDestConf file, the outboundqueue name is R3LINK_O. However, in the flow, the name has been changed to R3LINK_I in order done to make the naming standard consistent, as shown in Figure 17 below, O means outbound, receiving from SAP, and I means inbound, sending to SAP. This means that the target application must be changed to process the messages off the queue named R3LINK_I instead of R3LINK_O. This change reduces confusion when troubleshooting problems.

You can now save the flow. It is ready to be deployed, but before you do so, go to the section Changing SAP setting.

Creating a new outbound message flow

An outbound message flow is needed when forwarding IDocs to SAP for an application that expects data in R3Link format. The first step is to open the message flow. If you followed the steps earlier, you will have a message flow and message set project. Open the message flow by expanding the plus sign next to the message set. In this case that is MATMAS05_o_R3Link_migration => Flow => default broker schema. Double-click on the flow name (for example, MATMAS05_o_R3Link_migrationFlow.msgflow):

The message flow canvas will be displayed.

You need to add an MQInput node to your flow. It an be found on the palette in the WebSphere MQ section (next to the canvas), as shown in Figure 19 below. Drag the MQInput node onto the canvas of your flow. The message needs to be transformed from the R3Link structure to the Message Broker Adapter for SAP adapter structure, which you do with a Compute node, found on the palette in the Transformation section.

Drag the outbound adapter to the canvas. To find the adapter, expand MATMAS05_o_R3Link_migrationMessageSet => Adapters => Inbound => SAP, as shown in Figure 18 above.

Now you can wire up the nodes. The output terminal of the MQInput node must be connected to the input terminal of the Compute node, and the output terminal of the Compute node must be connected to the input Terminate of the adapter node. The flow should look like this:

Right-click on the MQInput node and select Properties. Under the Properties tab => Basic, enter the input queue, as shown in Figure 21 below. Take the value for the queue from the in.ini file. The name of the property in this file that contains the queue name is inboundqueue.

The domain property must also be set on the MQInput node. Click Input Message Parsing and select BLOB : For messages with an unspecified format from the domain dropdown.

In the in.ini file, the name of the queue is R3LINK_I. However in the flow, the name has been changed to R3LINK_O in order to make the naming consistent (O means outbound, sending from the broker to SAP, and I means inbound, sending from SAP to the broker). Therefore you must change the source application to send the messages to the queue named R3LINK_O instead of to R3LINK_I. Making this change reduces confusion when troubleshooting.

The message that is read off the queue R3LINK_I conforms to the structure of an R3Link message, shown in Figure 12 above. The message set that represents this message is not compatible with the WebSphere Message Broker Adapter for SAP. You must add a small amount of code to the Compute node to transform the message. Double-click on the Compute node to open up the ESQL editor, which will contain some lines of ESQL in it. In this example replace the lines:

	-- CALL CopyMessageHeaders();
	-- CALL CopyEntireMessage();

with:

	-- CALL CopyMessageHeaders();
	-- CALL CopyEntireMessage();
	

The best way to enter the code is to use code completion:

1. Delete the lines to be replaced.
2. Type "SET OutputRoot".
3. Type Ctrl-Space. A window will open.
4. Select DataObject.
5. Click .
6. Type Ctrl-Space.
7. Select the SAP transaction you want (it will end in the transaction name).
8. Type Ctrl-Space.
9. Click .
10. Select IdocStreamData (you could have typed the ESQL without code completion, but using code completion reduces the chance of making typos).
11. To finish the line, type "= InputRoot.BLOB.BLOB".

The code should look like this:

   DECLARE ns NAMESPACE 'http://www.ibm.com/xmlns/prod/websphere/j2ca/sap/sapmatmas05';

   CREATE COMPUTE MODULE MATMAS05_o_R3LINKFlow_Compute
      CREATE FUNCTION Main() RETURNS BOOLEAN
      BEGIN

         SET OutputRoot.DataObject.ns:SapMatmas05.IDocStreamData = InputRoot.BLOB.BLOB;
		
         RETURN TRUE;
   END;

   CREATE PROCEDURE CopyMessageHeaders() BEGIN
      DECLARE I INTEGER 1;
      DECLARE J INTEGER;
      SET J = CARDINALITY(InputRoot.*[]);
      WHILE I < J DO
         SET OutputRoot.*[I] = InputRoot.*[I];
         SET I = I + 1;
      END WHILE;
   END;

   CREATE PROCEDURE CopyEntireMessage() BEGIN
      SET OutputRoot = InputRoot;
   END;
END MODULE;

The ESQL code could have been written without using code completion. but using it reduces the chance typos. You do not need the two procedures but it does no harm to leave them.

You can now save the flow. The flow is now ready to be deployed, but before you do so, go to the section Changing SAP setting.

Migrating an existing message flow

In the case where a message flow was already sending or receiving R3Link format messages directly from the R3Link, there will be an existing message flow that must be migrated. This section shows you how to migrate your existing message flow to use the Message Broker Adapter for SAP. It is assumed that you have:

• Configured the Adapter
• Imported the existing message flow and any dependent message sets into the Message Broker workspace. (This task is not covered in this article.)

The Message Broker Adapter for SAP could deliver IDocs in unparsed form or in a parsed XML form. The unparsed form is compatible with the R3Link. However, if the message flow uses the IDoc parser, then consider rewriting the message flow to use the parsed XML form of the IDoc, because the IDoc parser is deprecated.

Migrating an existing inbound message flow

An inbound message flow is a flow that receives IDocs from SAP. Here are the steps needed to migrate an existing inbound message flow. Import the message flow to be migrated into your workspace. Replace the MQInput node with the adapter, the subflow Add_SAP_Header, and a Reset Content Descriptor. See Appendix B to find out how to import Add_SAP_Header project. Figure 22 shows an example of the flow before and after migration:

The subflow Add_SAP_Header adds an MQ SAP header to the IDoc. If required, you can populate the fields client, language, host name, user id, password, and system number in the MQ SAP header by setting the user-defined properties of the subflow. For an example, see Figure 16 above. Set the user-defined values according to the smqDestConf file. The properties of the Reset Content Descriptor must be identical to the MQInput node.

The flow is now ready to be deployed, but before you do so, go to the section Changing SAP setting.

Migrating an existing outbound message flow

An outbound message flow is a flow that sends IDocs to SAP. Here are the steps needed to migrate an existing outbound message flow. Open the message flow you imported into your Message Broker workspace. Replace the MQOutput node with a Reset Content Descriptor, followed by a Compute node, followed by the outbound adapter Request node. Figure 23 below shows a message flow that has been migrated. Whilst your message flow may not look exactly like those shown, the principle of migration is the same and similar changes need to be made.

In most cases, the MQInput node will have the message domain set to IDOC. The Message Broker node for SAP needs the IDoc to be in the BLOB domain, so set the message domain of the Reset Content Descriptor to BLOB.

In the Compute node, you must type the ESQL (using code completion). Here is an example of the ESQL code:

DECLARE ns NAMESPACE 'http://www.ibm.com/xmlns/prod/websphere/j2ca/sap/sapmatmas05';

CREATE COMPUTE MODULE MATMAS05_o_unparsedFlow_Compute
   CREATE FUNCTION Main() RETURNS BOOLEAN
   BEGIN

      SET OutputRoot.DataObject.ns:SapMatmas05.IDocStreamData = InputRoot.BLOB.BLOB;

      RETURN TRUE;
   END;

END MODULE;

This code is for a SAP MATMAS05 transaction. If you are not using this transaction, code completion will help you to get the correct syntax. The first line is a declaration. If you use code completion, the Message Broker toolkit will generate this line for you. This line can be ignored -- in fact the only line that you need to type is the one that starts with SET, which you must type between BEGIN and RETURN TRUE in your function. This line takes the IDoc and places it in the correct part of the tree. Using code completion will help eliminate typos. After typing "DataObject" type Ctrl-Space to invoke code completion, as shown in Figure 24 below. The correct element is usually at the bottom of the code completion list -- it is the line with the SAP transaction at the end. When you find the correct entry, hit enter. The line will be added to the ESQL statement and declare the correct namespace at the top of the code.

Changing SAP setting

The R3Link requires a Non-Unicode setting to communicate with SAP. The Message Broker Adapter node requires a Unicode setting to communicate with SAP, so this setting must be altered. To do so, log on to SAP and run transaction SM59. Locate the RFC connection that corresponds with the programid in the out.ini file in the TCP/IP connections folder. In the MDMP & Unicode tab, select the Unicode button:

Make sure your backout procedure documents the need to change the setting back to Non-Unicode.

Deploying the flow

To deploy your message flow, follow the steps in the Message Broker Toolkit help: Click Help => Search, then type "Deploying a message flow application" in the Search expression box. Under local help, click the help topic Deploying a message flow application and follow the instructions.

Conclusion

There are issues you need to consider when moving from an architecture that uses the R3Link to one that uses Message Broker:

• Deciding the migration strategy
• Developing a backout plan
• Changing existing message flows
• Creating new artifacts to use in Message Broker
• Changing the SAP setting

These steps are not difficult, and with some planning you can have a smooth migration. This article has shown you how to migrate a single flow, and can be part of a migration strategy that will enable a smooth transition between the two architectures.

Appendix A. Troubleshooting

The flow does not deploy

First, check the event log: Double-click on the Event Log in the Domain view:

The Event log has a historical view of messages relating to interaction between the configuration manger and the broker, which should help you troubleshoot the problem. The most recent message is at the top:

In the case above, the error message BIP3450E was received, and the detailed message says "incomplete logon data." This error was caused by failure to set the password, and you can resolve it by setting the password in the adapter, which is the node that was dragged on to the message flow earlier. To set the password, select Show Advanced => Advanced connection configuration.

The flow does not work

If you have successfully deployed your flow, the first thing to check is whether the broker is communicating with the SAP system. Use the SAP transaction SMGW. If the message flow has been deployed you should see:

• Under Local LU name: your hostname
• Under Local TP name: DataFlow
• Under Users: your ID

In the example in Figure 28 below you can see the hostname CPS, which is the name of the system on which the broker is running. User name is stewart and TP name is DataFlow, which identifies the Message Broker execution group. This information confirms that the adapter node is trying to communicate with SAP.

If the adapter is not connected, check the adapter’s connection details and also the SAP Unicode setting (see the section Changing SAP setting). You may find some helpful information in the user trace log.

If the SAP transaction SMGW is as expected, use SAP transaction SM59. Locate your RFC connection and double-click it. Click Connection Test to make sure the adapter is connected to SAP. Here is the result of a successful connection test:

If you have deployed your flow and are connected, but you get unexpected results, you can debug your message flow with the Debugger provided with the Message Broker Toolkit. To find out more about the Debugger, enter "Testing and debugging message flow applications" in the Search help bar of the Message Broker Toolkit.

Appendix B. Importing Add_SAP_Header project

The project Add_SAP_Header is provided in the file Add_SAP_Header.zip. This project adds the SAP header to the start of the message. To import this project:

1. From your workspace, click File => Import.
2. In the Import Select wizard, expand Other.
3. Select Project Interchange and click Next.
4. Browse to Add_SAP_Header_Project_Interchange_file.zip, then click on the project and click Finish.

You will now see the project in your workspace. Add the subflow to your project: expand Add_SAP_Header => Flows => (default broker schema) and drag Add_SAP_Header.msgflow to the flow canvas, as shown below:

The section Migrating an existing inbound message flow above explains how to use this subflow.

Back to top

Download

Information about download methods

Resources

• WebSphere Message Broker developer resources page
  Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
  
  
• WebSphere Message Broker product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere Message Broker information center
  A single Eclipse-based Web portal to all WebSphere Message Broker V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
  
  
• WebSphere Message Broker documentation library
  WebSphere Message Broker specifications and manuals.
  
  
• WebSphere Message Broker forum
  Get answers to your technical questions and share your expertise with other WebSphere Message Broker users.
  
  
• WebSphere Message Broker support page
  A searchable database of support problems and their solutions, plus downloads, fixes, problem tracking, and more.
  
  
• WebSphere MQ developer resources page
  Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  
  
• WebSphere MQ product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere MQ V6 information center
  A single Eclipse-based Web portal to all WebSphere MQ V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere MQ environment.
  
  
• WebSphere MQ documentation library
  WebSphere MQ product manuals.
  
  
• WebSphere MQ public newsgroup
  A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users.
  
  
• WebSphere SOA solutions developer resources page
  Get technical resources for WebSphere SOA solutions.
  
  
• developerWorks WebSphere Business Integration zone
  For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
  
  
• WebSphere Business Integration products page
  For both business and technical users, a handy overview of all WebSphere Business Integration products
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Technical books from IBM Click
  Convenient online ordering through Barnes & Noble.
  
  
• developerWorks technical events and Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Configuring the adaptor connection
• Creating a new message flow
• Migrating an existing message flow
• Changing SAP setting
• Deploying the flow
• Conclusion
• Appendix A. Troubleshooting
• Appendix B. Importing Add_SAP_Header project
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Message Broker
• Webcast: WebSphere Message Broker: Converting Maps to ESQL using Support Pac IA9Y
• Briefing: WebSphere flexible business processes for a smarter planet
• Buy: WebSphere Message Broker

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers