Overview of webMethods Adapter for SAP
What Is IBM webMethods Adapter for SAP?
IBM webMethods Adapter for SAP allows you to extend your SAP business processes and integrate non-SAP products using open and non-proprietary technology. Adapter for SAP allows for both asynchronous and bi-directional, real-time communication to and from the SAP system. You can:
-
Execute SAP's implementation-independent Business
Application Programming Interface (BAPI) methods, as they are described in the Business Object
Repository (BOR). BAPIs are stable, precisely-defined, and well-documented interfaces to SAP
solutions, providing standardized access to SAP solutions on a semantic level. You can quickly and
easily create XML-based services that execute a BAPI. Applications within your organization can then
invoke the services to execute a BAPI on the SAP system. Similarly, your business partners can make
requests over the Internet to invoke a service that executes a BAPI. The BAPI-interfaces provide a
unified access to the application-level functionality, independent of the type of call: Both
synchronous and asynchronous processing can be triggered by using these interfaces.
Asynchronous processing transparently uses the Application Link Enabling (ALE) services inside the SAP system for the client to integrate the business processes.
- Execute SAP Remote Function Calls (RFCs) from Adapter for SAP. You can access all SAP functionality that is available via RFC from Adapter for SAP. External applications do not need to understand SAP datatypes, ABAP structures, or the RFC protocol to communicate with an SAP system.
- Send IDocs to the Adapter for SAP. You can send Intermediate Documents to Adapter for SAP for further synchronous processing or let them be published to subscribers asynchronously.
- Call services from SAP systems. You can invoke services from an SAP system. This allows the SAP users to access information that is available via Adapter for SAP. Adapter for SAP enables integration between trading partners, thereby extending the reach of your SAP infrastructure to customers, partners, and suppliers.
- Route SAP business documents based on criteria you specify. Adapter for SAP provides rich routing capabilities for BAPIs, RFCs, and IDocs. Different transport types are available out-of-the-box. These include the routing of a business document to another SAP system or simply to a remote URL in an XML format.
Adapter for SAP allows you to increase customer loyalty and efficiency across the supply chain by tightly integrating your business infrastructure with that of any partner. Typical deployment scenarios for Adapter for SAP are:
- Real-time integration between supplier inventories and your SAP system
- Real-time integration between product, price, and availability information from any number of suppliers and your purchasing application
- Real-time integration between fulfillment and order tracking applications and your shippers' internal systems
Functional Highlights
- Synchronous and asynchronous communication with SAP systems through RFC, tRFC, qRFC, and bgRFC
- Bi-directional and multithreaded communication to and from SAP systems
- Load balancing of incoming SAP documents.
- Support of publishing to the local IBM webMethods Integration Server, to the Broker, or to JMS for asynchronous adapter notifications
- Support of "publish and wait" and "direct service invocation" execution modes for synchronous adapter notifications
- Higher level services to process SAP IDocs and BAPIs
- Easy XML and Internet enabling of existing SAP releases
- Support of BizTalk XML envelopes for BAPI and RFC calls
- Support of unified error handling of BAPIs and RFCs on XML level
Complete SAP System Integration
Adapter for SAP incorporates a full-fledged RFC Client and Server. These provide real-time bi-directional (outbound and inbound) communication to and from the SAP system. From an SAP application point of view, calling Adapter for SAP is no different from calling any other RFC server. The SAP proprietary RFC format is converted to XML so that no SAP software is needed on the other end of the communication line.
Adapter for SAP transparently supports both synchronous (RFC) and asynchronous (tRFC) calls from SAP systems. Thus, BAPIs and ALE scenarios are supported. Adapter for SAP also supports qRFC for IDoc processing and inbound bgRFC calls from SAP.
As a special service, SAP IDocs can be converted to a structured object with direct access to each single field. This allows you to modify an IDoc's contents on the fly. For example, if you want to customize incoming IDocs based on local data format, you can do so. You can also access existing BAPIs in SAP systems from a browser or client application, or you can send XML documents to the SAP system. Developing applications with Adapter for SAP requires no knowledge of SAP data structures, significantly reducing deployment time and cost.
Integrating SAP Systems Over the Internet
Most integration scenarios describe two systems communicating with each other securely over the Internet, despite existing firewall restrictions. Adapter for SAP leverages HTTP to seamlessly exchange data between two or more SAP systems across the Internet, without requiring changes to the existing security infrastructure.
In addition, Adapter for SAP transparently manages communication between different SAP system versions.
Routing IDocs, RFCs, and BAPIs
Adapter for SAP provides rich routing capabilities for synchronous RFCs, asynchronous IDocs, and BAPIs, giving you better control of your trading relationships. Within minutes, you can configure Adapter for SAP to send an IDoc to another SAP system or to a remote URL in an XML format.
BAPIs provide a simple way to access SAP solutions. They can handle both synchronous and asynchronous calls to an SAP system using the same XML message format. Asynchronous BAPI calls are provided by using the ALE services inside the SAP system; you can leverage ALE mechanisms without having to deal with the sometimes complex IDoc format. This works for all IDocs that are generated from BAPIs.
Inside the SAP system, administrators can use the full bandwidth of services provided by ALE, including:
- Performance benefits through asynchronous processing
- Monitoring services
- Distribution services
BAPI interfaces are developed according to strict development guidelines, so they are well-defined, stable, implementation-independent, and well-documented.
The SAP Interface Repository provides public web-based access to the collection of BAPI interfaces provided by SAP and to the corresponding documentation.
In short, the use of BAPIs leads to the following advantages:
- SAP solutions are accessed on a standardized, implementation-independent level. Implementation on the SAP system can therefore be exchanged without invalidating the (BAPI) interface used by clients.
- A business management function which is implemented as a BAPI can be called both synchronously and asynchronously by using the same XML message.
Support for IDoc- and RFC-XML
Adapter for SAP is the de-facto XML interface to existing SAP systems releases. It supports all versions of IDoc- and RFC-XML (XRFC), as specified by the SAP-XML Specification. With Adapter for SAP SAP-XML interface, you can invoke RFCs via XML and convert IDocs to the SAP-XML format.
Support of BizTalk XML Envelopes for BAPI and RFC Calls
By default, Adapter for SAP will use the standardized BizTalk XML envelope format for these XML messages. This simplifies data exchange with other Web messaging systems. The BizTalk XML envelope differentiates between an application-specific XML body and an XML header, which is used to exchange transport-specific information, for example for routing purposes. The BizTalk XML envelope can be used with both BAPI and RFC XML calls and also for both synchronous and asynchronous processing. See Using BizTalk Envelopes with Adapter for SAP for more information.
Support of Unified Error Handling of BAPIs and RFCs on the XML Level
To allow generic error evaluations on the client, regardless of the interface type (BAPI, RFC) used, the bXML format unifies the error handling of BAPIs and RFCs. In this way, interface type-specific error handling concepts (BAPI return parameter and function module exceptions) are converted on an XML level into a standardized type of error representation.
Built-in BAPI Tools
A set of tools to simplify the handling of BAPI calls has been integrated into Adapter for SAP.
For easy identification of the relevant application interfaces, Adapter for SAP includes a built-in BAPI Browser. This browser provides access to the interface data for each business object and its BAPIs and also serves as a search tool to the SAP interface world. With the built-in BAPI browser, you can quickly identify the necessary information to set up a routing notification for BAPIs.
Services to simplify the handling of BAPI transaction control have also been added to Adapter for SAP.
Maintaining Transaction Status Information
Transaction status information can be stored in MySQL database or in a file in Integration Server locally or in a centralized repository. Locally stored transaction status information will be accessed only by Adapter for SAP on which the transaction is executed. The transaction status information stored in a central repository will be accessed by multiple instances of Adapter for SAP that are grouped. The available types of storing the transaction status information are:
- Shared Transaction Store in MySQL
- Local Transaction Store in a File System
- Centralized Transaction Store
- Shared Transaction Store
Shared Transaction Store in MySQL
The Transaction Store is used to store the transaction status information in a MySQL database. For more information about configuring Adapter for SAP to use MySQL database to store transactions, see Installing Adapter for SAP, Post-Installation Steps to Configure Adapter for SAP to Use MySQL for Transaction Store, and Upgrade Adapter for SAP 10.1 to use MySQL for Transaction Store. Adapter for SAP provides a persistent transaction store that the transaction manager uses to track all IDocs and all tRFC calls routed to and from SAP systems via IBM webMethods Integration Server. The transaction store in MySQL can be shared by multiple Adapter for SAP instances. For more information, see Managing Transactions and the Transaction Store.
Local Transaction Store in a File System
The Transaction Store is used to store the transaction status information locally in a file by default. Adapter for SAP provides a persistent transaction store that the transaction manager uses to track all IDocs and all tRFC calls routed to and from SAP systems via IBM webMethods Integration Server. For more information, see Managing Transactions and the Transaction Store.
Centralized Transaction Store
The Centralized Transaction Store (CTS) is a group of adapters for SAP that belong logically together, that share a single Centralized Transaction Store. The CTS is used to store all the processed transactions in a central repository in a file, so that the transaction status information will always be synchronized and valid. The CTS allows reliable tRFC/IDoc load balancing. There can always be just one CTS per adapter group, not two or more. All adapters of SAP that are configured to share a specific CTS are considered to be in the same group. You must configure the Remote Server with alias "SAPGroupStore" for each Adapter for SAP of your adapter group (and in exactly the same way). For more information, see Considerations about Adapter for SAP Centralized Transaction Store or Shared Transaction Store and Centralized Transaction Store.
Shared Transaction Store
The Shared Transaction Store (STS) is a common transaction repository shared by several adapters for SAP that belong logically together. Similar to CTS, the STS is used to store all the processed transactions in a central repository in a file, so that the transaction status information will always be synchronized and valid. It is a more robust configuration without central server so there is no single point of failure. All adapters for SAP that are configured to share a specific STS are considered to be in the same group. You must configure the location of the STS repository with the configuration switch watt.sap.xtn.cts.txstore for each Adapter for SAP of your adapter group (and in exactly the same way). For more information, see Considerations about Adapter for SAP Centralized Transaction Store or Shared Transaction Store and Shared Transaction Store.
Architecture and Components
Basic Concepts
To use Adapter for SAP successfully, you should understand the following terms and concepts:
| Term | Description |
|---|---|
| BAPI | Business functions in an SAP system that are written in the programming language ABAP. BAPIs are formalized RFCs. Systems remote from the SAP system commonly use BAPIs to have the SAP system perform an action. |
| RFC Server (Listener) | SAP terminology for a process that can accept Remote Function Calls (RFCs)
from SAP systems. This allows SAP systems to access functions on external systems. In Adapter for SAP terminology,
this is a listener. Listeners are one or more threads on Adapter for SAP that wait for incoming requests from SAP systems. Listeners are named and registered with an SAP gateway to indicate that they are ready to accept requests. Listeners can accept RFC or tRFC requests. |
| RFC Client | SAP terminology for a process that sends RFCs to an SAP system to invoke functions. |
| tRFC (Transactional RFC) | Protocol for ensuring that an RFC is successfully executed and executed exactly once on the target system. Adapter for SAP can handle both inbound and outbound tRFCs. |
| bgRFC (Background RFC) | Protocol for background and queued transactional processing. Adapter for SAP handles inbound
bgRFC calls from SAP. Note: To use the support of bgRFC, install IBM webMethods Adapter for SAP
Fix 1 and later.
|
| tRFC protocol | Communications method that:
The transactional RFC (tRFC) protocol ensures that an RFC is successfully executed and that it is executed exactly once. |
| TID | Transaction ID. A globally unique identifier used by tRFC to ensure exactly one execution. Can be up to 24 alphanumeric characters in length. |
| RFC | Requests that the SAP system initiates to have functions performed on remote systems, or calls remote systems initiate to have the SAP system perform a function. |
| RFC protocol | Communications method that the SAP system uses to synchronously and asynchronously invoke a function on a remote system, and a remote system uses to synchronously and asynchronously invoke a function on the SAP system. |
| Service | Integration Server functions that are named with a hierarchical folder/service syntax. Services can be flow, Java, or C/C++ developed by you, third-party vendors, or provided with webMethods components. |
| JCo 3 Library | Code library provided by SAP allowing third parties to integrate the RFC protocol into applications. This is how Adapter for SAP communicates with the SAP system. |
| IDoc (Intermediate Document) | EDI-like SAP business document. |
| Routing Listener | A process that accepts messages and routes them to a configured location, for
example, messages can be routed to an SAP system, another Integration Server, or a remote URL
in an XML format. Note: If you need to use a routing listener, you do not need
to create one. Adapter for SAP includes a pre-configured routing listener called wm.sap.internal.ls:routingListener. For more
information about the routing listener, see Overview.
|
| Shared Transaction Store in MySQL | A MySQL database repository that Adapter for SAP uses to track all transactions that pass through Adapter for SAP. The database can be shared by multiple Adapter for SAP instances. |
| Local Transaction Store in a File System | A file-based repository that Adapter for SAP uses to track all transactions that pass through Adapter for SAP. |
| Centralized Transaction Store | A file-based centralized repository maintained by the CTS server that Adapter for SAP uses to track all transactions that pass through all the adapters of Adapter for SAP group. |
| Shared Transaction Store | A file-based common shared repository that Adapter for SAP uses to track all transactions that pass through all the adapters of Adapter for SAP group. |
The following illustrates the components in a system that uses Adapter for SAP to communicate between an SAP System and a local Integration Server.
The following illustrates the components in a system that uses Adapter for SAP to communicate between an SAP System and a remote Integration Server connected to the local Integration Server by way of either a Broker or a JMS provider:
Invoking Business Logic
Adapter for SAP incorporates an RFC Server and RFC Client to provide real-time inbound and outbound communication to and from the SAP system.
Adapter for SAP uses the RFC Client to send requests to execute RFCs on the SAP system.
Adapter for SAP uses the RFC Server (Listener) to listen for incoming requests to do one of the following:
- Execute services on Integration Server. Adapter for SAP performs this action for synchronous adapter notifications configured with an execution mode of "service invoke." For more information about execution modes, see Service Execution Modes.
- Publish the request to the local Integration Server (or to a remote Integration Server connected to the host Integration Server by way of a Broker or a JMS provider) and optionally wait for a reply document. Adapter for SAP performs this action for asynchronous adapter notifications and for synchronous adapter notifications configured with an execution mode of "publish and wait." For more information about execution modes, see Service Execution Modes.
From an SAP system point of view, calling Adapter for SAP is no different from calling any other RFC server.
The following diagram illustrates this process when Adapter for SAP is communicating with the host Integration Server. Adapter for SAP can also communicate with a remote Integration Server that is connected to the host Integration Server by way of a Broker or a JMS provider.
Sending Messages Through the Routing Listener
When Adapter for SAP receives a request on the RFC Server (Listener) that is not associated with a specific adapter notification, Adapter for SAP sends the request to the routing listener. The routing listener can receive:
- IDoc calls from an SAP system or IDoc-XML messages from any web client
- RFCs from an SAP system or RFC-XML and bXML messages from any web client
It then uses routing notifications to determine where to route the messages. The routing notification indicates where to route the message based on who the message is from (sender), who is to receive the message (receiver), and the message type.
A message can be:
- Routed to an SAP system (IDocs, RFCs, and BAPIs)
- Routed to a service on the local machine or a remote machine
- HTTP posted to an URL
Adapter Package Management
Adapter for SAP is provided as a package called WmSAP that you manage like any package on the Integration Server.
Several considerations exist regarding how you set up and effectively manage your packages on the Integration Server, such as the following:
- Configure user-defined packages for your adapter connections and adapter services. See Managing the Adapter Package for details.
- Understand how package dependencies work so you make the best decisions regarding how you manage your adapter services. See Package Dependency Requirements and Guidelines for details.
- Control which development groups have access to which adapter services. See Controlling Group Access for details.
- Understand how clustering, an advanced feature of IBM webMethods Integration Server, works to effectively manage your adapter services. See Using the Adapter in a Clustered Environment for details.
- Enable and disable packages. See Enabling Packages for details.
- Load, reload, and unload packages. See Loading, Reloading, and Unloading Packages.
Adapter Connections
An adapter connection enables Adapter for SAP service to connect to an SAP system.
The adapter supports an RFC type of adapter connection. For instructions for configuring, viewing, editing, enabling, and disabling Adapter for SAP connections, see Adapter Connections. For information about setting user privileges, see IBM webMethods Integration Server Administrator’s Guide for your release.
For a list of tasks that you must do before you can create your connections, see Before Configuring or Managing Adapter Connections.
Connection Pools
Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. By default, connection pooling is enabled for all adapter connections.
A connection pool is a collection of connections with the same set of attributes. Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections instead of opening new connections.
Run-Time Behavior of Connection Pools
When you enable a connection, the Integration Server initializes the connection pool, creating the number of connection instances you specified in the connection's Minimum Pool Size parameter. Whenever an adapter service needs a connection, Integration Server provides a connection from the pool. If no connections are available in the pool, and the maximum pool size has not been reached, the server creates one or more new connections (according to the number specified in Pool Increment Size) and adds them to the connection pool. If the pool is full (as specified in Maximum Pool Size), the requesting service will wait for Integration Server to obtain a connection, up to the length of time specified in the Block Timeout parameter, until a connection becomes available. Periodically, the Integration Server inspects the pool and removes inactive connections that have exceeded the expiration period that you specified in Expire Timeout.
If the connection pool initialization fails because of a network connection failure or some other type of exception, you can enable the system to retry the initialization any number of times, at specified intervals.
For information about configuring connections, see Adapter Connections on Adapter Connections.
Built-In Services for Connections
Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.
The built-in service pub.art.services:setAdapterServiceNodeConnection enables you to change the connection associated with an adapter service. See Changing the Connection Associated with an Adapter Service at Design Time.
Changing the Connection Associated with an Adapter Service at Design Time
Integration Server provides a built-in service that you can use at design time to change the connection associated with an adapter service. This built-in service is namedpub.art.service:setAdapterServiceNodeConnection. Using this service, you can change the specific connection associated with an adapter service at design time so that you do not need to recreate adapter services.
Other built-in services enable you to control connections; for more information, see Built-In Services for Connections.
Changing the Connection Associated with an Adapter Service at Run Time
Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar backend resources.
For example, you can configure an adapter service to use a default connection that interacts with your company's production application server. However, at runtime you can override the default connection and instead use another connection to interact with the company's test application server.
For more information about overriding a service's default connection at runtime, see Dynamically Changing a Service's Connection at Run Time.
Adapter Services
Adapter services allow you to connect to the adapter's resource (that is, an SAP system) and initiate an operation on the resource from Integration Server. You call adapter services from a flow or Java service to interact with function modules on an SAP system.
At design time, the adapter obtains information about the SAP document on the SAP system. You configure adapter services using the templates provided with Adapter for SAP. Each template represents a specific technique for doing work on a resource, such as invoking a function module on an SAP system. An adapter service template contains all the code necessary for interacting with the resource but without the data specifications. You provide these specifications when you configure a new adapter service.
You use Designer to configure the adapter service. Some familiarity with using these tools is required. For more information, see IBM webMethods Service Development Help for your release.
Adapter for SAP provides the following adapter service template:
| Adapter Service Template | Description |
|---|---|
| RFC Adapter Service (synchronous) | Invokes an RFC on the SAP system, executes a tRFC, or confirms a transaction. |
Adapter Listeners and Listener Notifications
The adapter uses an RFC listener to enable the SAP system to make Remote Function Calls to Integration Server. It uses the following types of notifications to handle the RFCs passed through the RFC listener.
Listeners
A listener continually monitors an SAP system for RFC requests to send to Integration Server. When a call is made from the SAP system, the listener passes the message to a listener notification.
A listener is a real-time process that you configure, enable, and disable using Integration Server Administrator. For detailed instructions on how to configure listeners, see Listeners.
Listener Notifications
A listener notification works in conjunction with a listener to filter and process the RFC requests in Adapter for SAP. Adapter for SAP uses the following listener notifications to process requests:
| Listener Notification | Description |
|---|---|
| ALE Listener Notification (synchronous) | Handles incoming IDocs synchronously. |
| ALE Listener Notification (asynchronous) | Handles incoming IDocs asynchronously. |
| RFC Listener Notification (synchronous) | Handles incoming RFCs and tRFCs synchronously. |
| RFC Listener Notification (asynchronous) | Handles incoming RFCs, tRFCs, and bgRFCs asynchronously. |
| Routing Notification (synchronous) | Is used by the adapter to route all incoming requests that are not mapped to a service. The routing notification is a special case listener notification. See Routing Messages Through Adapter for SAP for more information about routing notifications. |
Choice of Publish Destinations
You can choose the destination to which asynchronous notifications should publish messages. Specifically, you can choose whether the asynchronous notification templates use JMS APIs to publish messages to Integration Server or IBM webMethods Broker APIs to publish notification messages to IBM webMethods Broker.
This feature allows you to add asynchronous adapter notification receive steps to a business process model using the same protocol used in existing receive steps in the model.
For steps for selecting a publish destination for asynchronous notification messages, see Listener Notifications.
Service Execution Modes
Synchronous adapter notifications execute flow services and return values from those services. Integration Server supports the following two execution modes to determine how the notification executes a flow service and returns output:
- Service Invoke mode: When this mode is selected, the adapter notification invokes a flow service directly and returns values as output from that service.
- Publish and Wait mode: When this mode is selected, the adapter notification publishes the received data either to the local Integration Server or to IBM webMethods Broker connected to that Integration Server by converting request documents into publishable documents, and then waits for a reply. This mode is needed when a synchronous adapter notification is represented as a receive step in a process model.
For steps for specifying execution modes for synchronous adapter notifications, see Listener Notifications.
Viewing the Adapter's Update Level
About this task
You can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the adapter's About page in Integration Server Administrator.
Controlling Pagination
About this task
You can control the number of items that are displayed on the adapter Connections screen, Listeners screen, and Listener Notifications screen. By default, 10 items are displayed per page. Click Next and Previous to move through the pages, or click a page number to go directly to a page.
To change the number of items displayed per page, set the watt.art.page.size property and specify a different number of items.
To set the number of items per page