SAP Suite Adapter

How the SAP Suite Adapter Works

Communicating and Processing IDocs

After installing SAP JCo and the SAP Suite adapter, you configure the adapter and use it in business processes. To communicate with SAP R/3 and your trading partners, and to process IDocs, Sterling B2B Integrator provides several business processes that work together. These business processes use BPML activities, services, and adapters to retrieve documents, perform EDI and IDoc translation, and send documents. These business processes must be used together. To implement the business processes, you must perform minimal configuration.

There are two types of IDoc processing: file-based and ALE-based.

SAP Inbound IDoc (SAPInboundIDoc.bp)

SAPInboundIDoc runs after the translation of inbound EDI data to IDoc. Sterling B2B Integrator envelope definitions are associated with SAP routes using the SAP cross-reference configuration. SAP Inbound IDoc inserts the proper routing information into the IDoc control record and transfers the completed IDoc to SAP using the SAP Inbound Delivery business process.

SAP Outbound IDoc (SAPOutboundIDoc.bp)

The SAP Suite adapter retrieves IDocs from SAP R/3. After retrieving IDocs, the SAP Outbound IDoc business process provides end-to-end processing of IDocs. The SAP Outbound IDoc business process enables IDocs to be grouped based on the user-provided EDI envelope definitions. While processing IDocs and preparing them for translation, the SAP Outbound IDoc business process generates status messages that describe processing results. After translation, the SAP Outbound IDocs business process calls the SAP Inbound Delivery business process, which uses FTP to send the status messages back to SAP R/3.

SAP Inbound Delivery (SAPinbDelivery.bp)

SAP Outbound ALE (SAPOutboundALE.bp)

The SAP Suite adapter receives IDocs from SAP R/3 using ALE technology. After receiving IDocs, the SAP Outbound ALE business process provides end-to-end processing of IDocs. The SAP Outbound ALE business process enables IDocs to be grouped based on the user-provided EDI envelope definitions. While processing IDocs and preparing them for translation, the SAP Outbound ALE business process generates status messages that describe processing results. After translation, the SAP Outbound ALE business process calls the SAP Delivery ALE business process to send the status messages back to SAP R/3.

SAP Delivery ALE (SAPALEDelivery.bp)

The SAP Outbound ALE business process uses the SAP Delivery ALE business process to send status messages back to SAP R/3 after IDoc to EDI translation is complete.

For more information, see Implementing the SAP R/3 Business Processes.

Business Scenario

Your company receives a purchase order from a trading partner in EDI format. You need to translate the EDI file to IDoc format and send it using file-based RFC to your back-end SAP system for further processing.

Business Solution Example

This business solution example focuses only on the SAP Suite adapter configuration and the SAP Inbound IDoc business process.

Example SAP Suite Adapter Configuration

A sample configuration might look like the following:

(Screen 1 of 2)

(Screen 2 of 2)

Business Solution Example Business Processes

The following example shows the predefined SAPInboundIDoc business process in the GPM. This business process is specified on the EDI inbound envelope and runs after EDI Deenveloping and after the EDI to IDoc translation is complete. The translated IDoc is input to the business process and becomes the primary document.

The following example shows the corresponding business process solution using BPML.

The following example shows the predefined SAPinbDelivery business process used to send the IDoc to the SAP system.

The following example shows sample output returned to the business process when the IDoc has been successfully received by the SAP system.

<EDI_DATA_INCOMING>
<PATHNAME>/sapmnt/I02/directory/orders.dat</PATHNAME>
<PORT>EDIPORT</PORT>
</EDI_DATA_INCOMING>

The EDI_DATA_INCOMING element represents the SAP Remote Function Call (RFC) that started. The PATHNAME and PORT elements are the input parameters that were passed into the SAP RFC.

A Basic Status of “Success” and Advanced Status of “None” in the Business Process Modeler indicate that the SAP Suite adapter successfully executed the RFC and that the SAP system has verified the EDI_DC header segment of the IDoc.

Running the Business Solution Example

See Usage Examples for additional examples of using the SAP Suite adapter.

Implementing the SAP Suite Adapter

Installing the SAP Java Connector

You must download and install the most recent version within 2.1.x of the SAP Java Connector (SAP JCo) before installing the SAP Suite adapter. The SAP JCo contains libraries and packages that support various platforms and enable the SAP Suite adapter to communicate with an SAP system and with Sterling B2B Integrator. After obtaining the SAP JCo, you must make the files available to the host system where Sterling B2B Integrator is installed.

Downloading the SAP Java Connector

Installing on UNIX

Installing on Windows

Installing on iSeries

Creating an SAP Suite Adapter Configuration

Before You Begin

See Configuring the SAP Suite Adapter for a description of the parameters used to define this information.

Configuring the SAP Suite Adapter

Whether you plan to create a business process that includes the SAP Suite adapter or use the predefined business processes, you must create a service configuration of the SAP Suite adapter. For more information, see Managing Services and Adapters.

To create and enable a configuration of the SAP Suite adapter, use the following table to configure the parameters:

Synchronous BAPI

The following table describes the fields to configure for synchronous BAPI:

Synchronous RFC

The following table describes the fields to configure for synchronous RFC:

File-based IDoc RFC

The following table describes the fields to configure for file-based IDoc RFC:

ALE-based IDoc RFC

The following table describes the fields to configure for ALE-based IDoc RFC:

User Properties

The following table describes the fields to configure user properties:

RFC Server Configuration (Outbound)

The following table describes the fields to configure RFC properties:

Connection Pool Settings

The following table contains the settings used to configure a connection pool:

Application User Settings

The following table contains the user setting for the service configuration:

Editing the SAP Suite Adapter Configuration Parameters

Upon installation, the connection pool, RFC server, and trace parameters that enable connection to an SAP system are preconfigured.

Implementing the SAP R/3 Business Processes

To implement the business processes for SAP R/3, you need to perform the minimal configurations for the SAP Outbound IDoc, SAP Inbound Delivery, and SAP Delivery ALE business processes. The SAP Inbound IDoc and SAP Outbound ALE business processes require no additional setup.

Refer to the following sections to determine the information that you must provide to implement the business processes.

SAP Outbound IDoc (SAPOutboundIDoc.bp)

The following table provides the parameters to define for the preconfigured services, as appropriate:

SAP Inbound Delivery (SAPinbDelivery.bp)

The following table provides the parameters to define for the preconfigured services, as appropriate:

SAP Delivery ALE (SAPALEDelivery.bp)

The following table provides the parameters to define for the preconfigured services, as appropriate:

You are now ready to check in the business processes to Sterling B2B Integrator.

Configuring an SAP R/3 Route

Sterling B2B Integrator uses SAP routes to determine how to route IDocs to and from external trading partners. When creating the inbound routes, indicate which key fields in the IDoc EDI_DC control record are used to identify the IDoc.

Configuring an Inbound Route

Configuring an Outbound Route

Configuring an SAP R/3 Cross-Reference

To enable Sterling B2B Integrator to process inbound and outbound IDocs and translate them to and from EDI, you must specify SAP cross-references to look up the EDI envelope associated with the SAP route defined for the IDoc.

Configuring an Inbound Cross-Reference

Configuring an Outbound Cross-reference

Configuring for Load Balancing

If the SAP system is load-balanced (“SAP system is loadbalanced” = Yes in the SAP Suite adapter configuration), you must configure the /etc/services file as shown in the following table. The /etc/services file is used to map port numbers to service names.

For the sapmsXXX service type, XXX is the SAP System ID. For example, if the SAP System ID is E01, the entry should read as follows:

sapmsE01 35YY/tcp #SAP System Message Port

YY is the SAP System Number.

Retrieving IDoc and Schema Format Descriptions

IDoc and schema format descriptions can be obtained either by using the new SapSuiteBuilder interface or with the command line-based tool, CmdlineSAPSuiteBuilder.

Retrieving Descriptions Using the SAP Suite Builder Interface

Retrieving Descriptions Using the SAP Command Line Interface

This section contains information about retrieving IDoc and schema format descriptions using the SAP Command Line interface. The CmdlineSAPSuiteBuilder is a command line-based tool that is installed when the SAP Suite adapter is installed. The CmdlineSAPSuiteBuilder enables a connection to an SAP R/3 system and delivers a particular IDoctype or schema (or its extension) in the form of a data definition format (.ddf) or schema (.xsd) file (see DDF in create mode or XSD in create mode). In List mode, the CMDLineSAPSuiteBuilder delivers a list of either IDocs or schemas from the SAP R/3 system to which it is connected. You can then use the .ddf and the .xsd in the Sterling B2B Integrator Map Editor to define your mapping requirements.

Requirements

Based on SAP R/3 requirements for retrieving IDocs, the CMDlineSAPSuiteBuilder utility needs particular RFC function calls, including IDOCTYPE_READ_COMPLETE and IDOC_RECORD_READ. Before running the utility, confirm that the necessary RFC function calls are available.

Running the CmdlineSAPSuiteBuilder Utility

There is always a create mode or a list mode for DDF and for XSD. The following examples illustrate how to use the different modes of the CmdlineSAPSuiteBuilder utility:

DDF in create mode

<arguments> =

DDF -c -i ORDERS01 -s 45A -v 3 -p SAPreadIdoc.properties -o orders01.ddf

Create the ddf file orders01.ddf that contains the IDoc structure of the IDOCtype ORDERS01 of segment release 45A and record type version 3. The corresponding SAP-related host and user information are read from the file SAPreadIdoc.properties.

The CmdlineSAPSuiteBuilder utility requests the password for the SAP username (field User) as configured in the property file (this is the case in every mode).

In addition, the CmdlineSAPSuiteBuilder program writes to a log file whose name is specified with the token saplogger.logfilename in the property file log.properties. Its amount of output ranges from only fatal messages to all messages (NONE, FATAL, ERROR, WARN, TIMING, INFO, DEBUG, ALL). Its value depends on the token saplogger.loglevel in the same property file log.properties that is common to the SAP Suite adapter package. This logging mechanism is in every mode.

DDF in list mode

<arguments> =

DDF -l -f ORDERS -s 45A -p SAPreadIdoc.properties

Deliver to stdout a list of all IDoctypes (and/or extensions) beginning with the string ORDERS.

XSD in create mode

<arguments> =

XSD -c -r BAPI_MATERIAL_AVAILABILITY-p SAPreadIdoc.properties -o BAPI_Material_Availibility.xsd

Create an XML schema from the RFC BAPI_MATERIAL_AVAILABILITY that, in this case, stands for a particular BAPI of the BusinessObject MATERIAL in the file BAPI_Material_Availibility.xsd. SAP-related properties are read from the file SAPreadIdoc.properties.

XSD in list mode

Property File Used by CmdlineSAPSuiteBuilder

The property file must be customized before using the utility. Each line in this file should have the following format:

<fieldname> = <value>

The following table describes the possible field names and their default values in the property file:

Error Messages

When the CmdlineSAPSuiteBuilder utility detects errors, the utility writes the errors to either stdout or to the logfile associated with saplogger.logfilename. Typically, errors are written to stdout only if during command-line parsing something was wrong. At this stage, the name of the logfile is still not known.

Business Process Definition Parameters – Transactions

The following table describes the business process parameters for transactions:

Business Process Definition Parameters

The following tables describe the usage options of the business process parameters (IP = Instance Parameter, WP = Workflow Parameter):

Export Parameters

The following table describes the business process parameters when exporting parameters:

TID Management for SAP Outbound

The SAP Suite adapter manages transactional integrity for SAP outbound to confirm that an IDoc packet has been successfully processed once. The SAP R/3 system assigns a transaction ID (TID) for every IDoc packet. The SAP Suite adapter stores the TID in the Sterling B2B Integrator database in the SAP_TID table. Each row in the following table represents a separate IDoc packet and contains the following rows:

The Outbound Flow Process

Advanced Status Returned by the SAP Suite Adapter

The following table includes the advanced status that may be returned by the SAP Suite adapter:

Running SAP Suite Adapter in an External JVM

The SAP Suite Adapter allows you to decide for each instance whether it should run within the Sterling B2B Integrator JVM (standard behavior for all adapters) or in an external Java Virtual Machine (JVM) managed by an SAP Controller Server.

When you run SAP Suite Adapter instances external to Sterling B2B Integrator, it provides stability to instance server and increases the critical IDoc size limit. For example, it does not affect the stability of Sterling B2B Integrator, when large IDoc files are received. We recommend you to configure SAP Suite Adapter instances to run in an external JVM if you receive IDocs more than 2 MB (or 4000 IDoc segments) frequently in Sterling B2B Integrator.

Configuring an SAP Suite Adapter in an External JVM

Adding SAP Controller Property

Installing SAP Controller Windows Service (Windows only)

You have to install SAP Controller once as a Windows service if you want to run SAP Suite Adapter instances in an external JVM. The SAP Controller is not installed automatically with installWindowsService.cmd, as it is an optional service.

Starting the SAP Controller Server

The SAP Controller server should be started and registered to the Sterling B2B Integrator JNDI context to start external SAP Suite instances in an external JVM.

If you have configured SAP Suite instances as external in sap.properties property file and required for Windows only, the SAP Controller Windows service is installed and then the server starts automatically by the standard Sterling B2B Integrator scripts run.sh (UNIX) or startWindowsService.cmd (Windows). However, if you remove the external properties from sap.properties file and uninstall the SAP Controller Windows service on Windows, the SAP Controller will no longer start automatically with the Sterling B2B Integrator scripts run.sh (UNIX) and startWindowsService.cmd (Windows).

When the SAP Controller is starting, it automatically starts all external SAP Suite instances configured as external with status as active. After the SAP Controller is started, the external SAP Suite instances are ready for inbound and outbound communication.

A file sapcontroller.pid is created in <siroot> directory indicating that SAP Controller is running. This file contains the process ID of the SAP Controller.

When the Sterling B2B Integrator is started and SAP Suite instances are enabled, you can see the registered SAP Controller and one or more external SAP Suite instances with JNDI name suffix SapSuite_<node>.ext in the Sterling B2B Integrator JNDI tree.

Starting the SAP Controller Server Manually

You can view the SAP Controller Service in the Windows Services dialog with the status Started as shown in the following figure. The port number may be different on your system.

Stopping the SAP Controller Server

Enabling, Disabling, or Reconfiguring External SAP Suite Adapter Instances

The SAP Suite adapter instances running externally on an SAP Controller Server can be created, enabled, disabled, or reconfigured in the Sterling B2B Integrator administration interface similar to the instances that run internally.

Enabling or disabling External SAP Suite Adapter Instances

The System Troubleshooting > Adapters screen displays both internal and external SAP Suite Adapter instances. If you disable an external SAP Suite adapter instance, the SAP Controller shuts down the instance and you will not be able to send or receive transmissions from the connected SAP system.

However, if you enable a previously disabled external SAP Suite adapter instance, the SAP Controller starts the instance again and reestablishes the connection to the SAP system.

Reconfiguring External SAP Suite Adapter Instances

If you change one or more global or instance properties of an external SAP Suite Adapter instance in the SAP Suite Adapter configuration menu and save the changes, the external adapter instance restarts with the new configuration properties automatically.

SAP Controller Logs

The SAP Controller creates a log file sapcontroller.log in the startup phase under <siroot>/logs directory. After you register the SAP Controller in Sterling B2B Integrator, it uses the standard SAP Suite log file sap.log. The SAP Controller log level is similar to the log level configured for SAP Suite Adapter.

Uninstalling the SAP Controller Windows Service (Windows only)

The SAP Controller is not uninstalled automatically with uninstallWindowsService.cmd as it an optional service.

Restarting SAP Controller Service

You can restart the SAP Controller Service by following the stop script steps as mentioned in Stopping the SAP Controller Server and start as mentioned in Starting the SAP Controller Server section.

When the SAP Controller is starting, it automatically starts all external SAP Suite instances configured as external with status as active. After the SAP Controller is started, the external SAP Suite instances are ready for inbound and outbound communication.

Checking SAP Controller Service Failover

The script startSAPIsAliveChecker[.cmd|.sh] is a diagnosis tool to check for the SAP Controller Server state and the SAP Suite instances running in the controller.

<siroot>/bin/startSAPIsAliveChecker.sh [-l [<count>]] 
         [-w <loop_wait_period>] 
         startSAPIsAliveChecker.sh -s  

Windows:

siroot>\bin\startSAPIsAliveChecker.cmd [-l [<count>]] 
[-w <loop_wait_period>] 
startSAPIsAliveChecker.sh –s

Restarting SAP Controller Server Example

The following scripts check the status of the SAP Controller and restart it if it is not active.

UNIX Example

The following script starts the SAP Controller server automatically if it is not active. It executes periodically by the standard UNIX scheduling mechanism crontab. The following crontab file checks the SAP Controller in an interval of 15 minutes each:

(15 * * * * <si_root>/install/bin/checkSAPController.sh)
#!/bin/sh 
# Restart SAP Controller Service if it is not active
cd <si_root>/install/bin 
startSAPIsAliveChecker.sh 
rc=$? 
if [ $rc -ne 0 ]; then
  echo "The SAP Controller Server needs to be restarted [rc=$rc]"
  stopSAPController.sh
 startSAPController.sh
  exit 1 
fi

Windows Example

The following script starts the SAP Controller server automatically if it is not active:

Windows, CheckSAPController.cmd 
@echo off  
setlocal 
cd <si_root>\install\bin
call startSAPIsAliveChecker.cmd 
set rc=%errorlevel% 
if %rc% NEQ 0 (
  echo The SAP Controller Server needs to be restarted (rc=%rc%)"
  stopSAPControllerWindowsService.cmd
 startSAPControllerWindowsService.cmd
  exit /B %rc% 
)	

Modifying SAP Controller JVM Settings

You should never change the SAP Controller parameter default values unless you experience unusual situations like out-of-memory exceptions during operation. You can change values if you are asked to by IBM® support.

Modifying SAP Controller JVM Settings for 32-Bit Platforms

To change the JVM heap memory settings:

Modifying SAP Controller JVM Settings for 64-Bit Platforms

To change the JVM heap memory settings:

Heap Memory Consumption Example

The RFC call parameters are transferred over the network and collected in the RFC server component of the SAP Suite Adapter in heap memory. The RFC server component is part of the SAP JCo libraries, which consist of a Java layer and an underlying native code layer. The RFC Server allocates Heap Memory to store the actual RFC parameters transferred in the RFC call. This data size may be considerably higher than the sum of the used data in all RFC parameters (“raw” data size). The SAP Suite adapter always transfers the complete data structure with fixed maximum length records including the unused fields independent of whether the parameter is filled with data or not.

The following section analyses an example with an IDoc of 20 MB “raw” data size:

A MATMAS IDoc with 71300 lines (100 IDocs with 713 lines per Idoc) is transferred with the standard SAP outbound RFC call. Each line represents one IDOC_DATA_REC40 structure in SAP, which is 1063 bytes. You can compute the IDoc size in Java heap memory as follows:

71,300 lines x 1,063 byte/line x 2 bytes/char = 151,583,800 bytes

In the RFC native layer, 75,791,900 bytes will be temporary allocated by “libRFC“ outside of the Java heap additionally. Therefore, a total of 227,375,700 bytes are allocated by the SAP JCo libraries. Additionally, the heap space allocated by the SAP Suite Adapter has to be added: The SAP JCo libraries pass the IDoc data to the SAP Suite Adapter in a data structure that does not contain unused data any more. While processing the IDoc data, the SAP Suite Adapter allocates about 3x raw data size heap memory, which is 3 x 20MB = 60MB. In the example a total of 227 MB + 60 MB = 287 MB is allocated on the heap for a “raw” 20 MB IDoc.

The following general formula computes the allocated heap space in bytes for an IDoc with “#idoc_lines” and a raw data size of “idoc_raw_size” bytes:

Modifying Security Properties

You can modify the security.properties file to make sure that Sterling B2B Integrator pass phrase is recognized when the SAP Controller starts.

Usage Examples

The following sections contain examples using the SAP Suite adapter for inbound and outbound processing.

Inbound and Outbound IDoc Processing Preconditions

The inbound and outbound IDoc examples in the following sections focus only on the SAP Suite adapter configuration and the SAP inbound and outbound business processes for sending and receiving IDocs.

Inbound Processing Examples

Sending an IDoc Using ALE

The following example illustrates an SAP Suite adapter configuration used for sending an IDoc document using ALE technology:

(Screen 1 of 2)

(Screen 2 of 2)

The following example using the GPM illustrates a business process that uses the SAP Suite adapter to send an IDoc using ALE technology to an SAP system. The dimmed values were specified on the SAP Suite adapter configuration instance.

(Screen 1 of 4)

(Screen 2 of 4)

(Screen 3 of 4)

(Screen 4 of 4)

The following example illustrates the same business process using BPML. The IDoc file orders.dat is the input passed to the business process and becomes the primary document. The primary document is input to the SAP Suite adapter.

The following example illustrates information returned from SAP to the business process, indicating that the SAP system transaction manager allowed Sterling B2B Integrator to open a transaction:

Starting an SAP BAPI Module

The following example illustrates an SAP Suite adapter configuration used for starting a BAPI in an SAP system to retrieve company information.

(Screen 1 of 2)

(Screen 2 of 2)

The following example illustrates the input passed to the business process.

The following example using the GPM illustrates a business process that uses the SAP Suite adapter to start the BAPI_COMPANY_GETDETAIL BAPI. The dimmed values were specified in the SAP Suite adapter configuration instance.

(Screen 1 of 5)

(Screen 2 of 5)

(Screen 3 of 5)

(Screen 4 of 5)

(Screen 5 of 5)

The following example illustrates the same business process using BPML.

The following example illustrates the company information returned from SAP to the business process as a primary document. The information is returned in XML format.

 <BAPI_COMPANY_GETDETAIL> 
	<COMPANYID>999999</COMPANYID> 
	<COMPANY_DETAIL> 
 	<COMPANY>999999</COMPANY> 
 	<NAME1>HANDSOME, INC</NAME1> 
 	<NAME2/> 
 	<COUNTRY>USA</COUNTRY> 
 	<LANGU>E</LANGU> 
 	<STREET>5555 EAST MARTIN AVE</STREET> 
 	<PO_BOX/> 
 	<POSTL_COD1>80220</POSTL_COD1> 
 	<CITY>DENVER</CITY> 
 	<CURRENCY>DOLLAR</CURRENCY> 
 	<COUNTRY_ISO>USA</COUNTRY_ISO> 
 	<CURRENCY_ISO>DOLLAR</CURRENCY_ISO> 
 	<LANGU_ISO>USA</LANGU_ISO> 
	</COMPANY_DETAIL> 
	<RETURN> 
 	<TYPE/> 
 	<CODE/> 
 	<MESSAGE/> 
 	<LOG_NO/> 
 	<LOG_MSG_NO>000000</LOG_MSG_NO> 
 	<MESSAGE_V1/> 
 	<MESSAGE_V2/> 
 	<MESSAGE_V3/> 
 	<MESSAGE_V4/> 
	</RETURN> 
</BAPI_COMPANY_GETDETAIL> 

In addition, the SAP Suite returns session information from the SAP system and puts it in the process data of the initiating business process. For example:

 <?xml version="1.0" encoding="UTF-8"?> 
<ProcessData> 
 <PrimaryDocument SCIObjectID="server1:252e596c:fb4e22589c:-76b0"/> 
 <BapiCallReturnStructure> 
    <RETURN> 
     <TYPE/> 
      <CODE/> 
     <MESSAGE/> 
      <LOG_NO/> 
     <LOG_MSG_NO>000000</LOG_MSG_NO> 
     <MESSAGE_V1/> 
      <MESSAGE_V2/> 
     <MESSAGE_V3/> 
      <MESSAGE_V4/> 
   </RETURN> 
  </BapiCallReturnStructure> 
</ProcessData> 

Outbound Processing Examples

Receiving a File-based IDoc from SAP Using RFC

This section includes an example SAP Suite adapter configuration and the predefined SAPOutboundIDoc business process that runs when a file-based IDoc is received from an SAP system.

The following example illustrates an SAP Suite adapter configuration used for receiving a file-based IDoc from an SAP system.

The following example using the GPM illustrates the SAPOutboundIDoc business process that runs by the SAP Suite adapter for an outbound file-based IDoc. This business process retrieves the filed-based IDoc from a directory on the SAP system and processes the file (translates the IDoc to EDI format and sends it to a trading partner). In addition, the business process starts a subprocess that uses an instance of the SAP Suite adapter to send a status message back to the SAP system.

(Screen 1 of 2)

(Screen 2 of 2)

The following example illustrates the same business process using BPML.

The following example illustrates the status message sent to the SAP system upon successful completion of the outbound business process that ran.

An SAP administrator can then view the status messages in the SAP system.

Receiving an ALE IDoc from SAP Using RFC

This section includes an example SAP Suite adapter configuration and the predefined SAPOutboundALE business process that runs when an IDoc is received from an SAP system using ALE technology.

The following example illustrates an SAP Suite adapter configuration used for receiving an IDoc from an SAP system using ALE Technology.

The following example using the GPM illustrates the SAPOutboundALE business process that runs by the SAP Suite adapter for an outbound ALE IDoc. With ALE technology, the IDoc is included in the outbound request and becomes the primary document for the outbound business process that ran. The business process processes the IDoc (translates the IDoc to EDI format and sends it to a trading partner). In addition, the business process starts a subprocess that uses an instance of the SAP Suite adapter to send a status message back to the SAP system.

(Screen 1 of 2)

(Screen 2 of 2)

The following example illustrates the same business process using BPML.

The following example illustrates the status message sent to the SAP system upon successful completion of the outbound business process that ran.

EDI_DC40 900    46C   2   SYSTAT01
    STATUS      ALETSTPORTLI  0000001111                       
                                                               
   SAPI02    LS  SITEST        20040408041857                  
                                                               
                                                 
E2STATS001
     900       000001000000  EDI_DS40  90000000000006922012004040804185724
           Sterling SAPSuite         Control information of EDI
subsystem OK                                                   
                                                               
                                                               
                                                               
                                                               
                                        S 
E2STATS001
     900       000002000000  EDI_DS40  90000000000006922012004040804185706
           Sterling SAPSuite           Translation OK          
                                                               
                                                               
                                                               
                                                               
                                                               
                                                               
         S 
E2STATS001     
900       000003000000  EDI_DS40  90000000000006922012004040804185708
           Sterling SAPSuite          Syntax check OK          
                                                               
                                                               
                                                               
                                                               
                                                               
                                                               
        S 
E2STATS001      900
      000004000000  EDI_DS40  90000000000006922012004040804185710
           Sterling SAPSuite          Interchange handling OK  
                                                      
                                                               
                                                               
                                                               
                                                               
                                                               
   S 

An SAP administrator can then view the status messages in the SAP system.

Receiving a Request from SAP and Returning a Synchronous Response Using RFC

This section includes an example SAP Suite adapter configuration and an example business process that runs when a request is received from an SAP system that requires a synchronous response. For example, a trading partner might need a price list for a particular order item before fulfilling the order.

You register an RFC in the SAP Suite adapter configuration instance that receives outbound RFC requests.

Examples:

The following example illustrates a simple custom RFC module Z_TRIGGERSI that starts by the SAP system. This RFC module has two import parameters – PARAM and VALUE – and one export parameter – RES.

FUNCTION Z_TRIGGERSI. 
*"---------------------------------------------------------------------- 
*"*"Locale Interface: 
*"  IMPORTING 
*"  VALUE(PARAM) TYPE  STRING OPTIONAL 
*"  VALUE(VALUE) TYPE  STRING OPTIONAL 
*"  EXPORTING 
*"  VALUE(RES) TYPE  STRING 
*"---------------------------------------------------------------------- 
write 'test'. 
 
ENDFUNCTION. 

The following example illustrates an SAP Suite adapter configuration used for receiving the RFC request.

(Screen 1 of 2)

(Screen 2 of 2)

When an outbound RFC is detected by the SAP Suite adapter, the RFC server runs the business process specified on the SAP Suite adapter configuration. The RFC parameters are input to the business process and become the primary document. For example:

<?xml version="1.0" encoding="UTF-8"?> 
<Z_TRIGGERSI> 
<PARAM>AAA</PARAM> 
<VALUE>BBB</VALUE> 
<RES></RES> 
</Z_TRIGGERSI>

The following example using the GPM illustrates an example business process that starts by the SAP Suite adapter for an outbound RFC request. This business process creates and returns a response to the RFC back to SAP.

The following example illustrates the same business process using BPML.

The following example illustrates the response sent back to the SAP system:

<Z_TRIGGERSI>
<RES>My Response</RES> 
</Z_TRIGGERSI> 

Connection Retry

When the SAP Suite adapter is started during the application startup, the RFC Server tries to establish a connection to the SAP System configured in the adapter instance. The default behavior of the RFC Server component is to keep trying to establish a connection until it successfully opens a connection.

However, for some permanent login error types, no retry is performed. For example, if the configuration has a wrong SAP user password, then no retry is performed because the error has to be resolved manually (by entering the correct password). Also, no retry is performed if a login fails because of a locked SAP user, which requires the SAP Administrator to manually unlock the user.

Sometimes, the SAP user that is used to login by the SAP Suite adapter is locked during SAP maintenance, and then unlocked after the maintenance. In this case, the User locked error must be treated as a temporary error condition and a connection retry is required so that the RFC Server can reconnect automatically after the SAP user is unlocked.

Troubleshooting Tips

This section contains troubleshooting tips for using the SAP Suite adapter.

Java Error in the SAP Outbound Business Process

For the SAPOutboundIDoc.bp, if the FS_WriteEDI service (which is a instance of the File System adapter) is not configured properly to extract data, the Advanced Status column in the Business Process Monitor page displays the following Java error message:

java.io.FileNotFoundException

In addition, the Status Report column does not provide a report. In this circumstance, the FS_WriteEDI service is working as designed. However, the Advance Status Details will show that a file was not found occurs if the FS_WriteEDI service is not configured correctly.