Adapter Concept Guide

Topics:
1. JDBC Adapter
2. SAP Adapter
3. WmDB

1. JDBC Adapter

 JDBC Adapter provides a way to exchange data with relational databases through the use of a JDBC driver
and we perform this adapter task with the help of web Methods Integration Server.
 The adapter provides real-time communication with the database without changes to your existing application
infrastructure.
 Using JDBC Adapter client can perform database transaction like insert, update, delete etc.
 The JDBC Adapter supports the databases like Oracle, Sybase, Teradata and Microsoft SQL Server.
 JDBC Adapter provides a set of user interfaces, services, and templates that enable you to create integrations
with databases using a JDBC driver.

Adapter connections: It enables IS to connect to database systems at run time.

Adapter services: It enables IS to start and perform database operations on a database.
Adapter notifications: It notifies to IS when we perform some action on particular database table.
Adapter Connections: JDBC Adapter connects to a database through a JDBC driver at run time. JDBC Adapter
connections contain parameters that IS uses to manage Connections to the database so that they can be used by
JDBC Adapter to provide services. We can configure connections using IS Administrator. We must have IS
Administrator privileges to access JDBC Adapter's administrative screens.

JDBC Adapter connections support the following transaction types:

1. NO_TRANSACTION: No transaction control over the operations i.e. the connection automatically commits
(Auto Commit) all operations.
2. LOCAL_TRANSACTION: With this transaction type, all of the operations on the same connection in one
transaction boundary will be committed or rolled back together.
Note: Insert Notifications, Update Notifications, Delete Notifications, and Ordered Notifications support
LOCAL_TRANSACTION mode only.
3. XA_TRANSACTION: This transaction type allows the connection to support two-phase transactions executed
across multiple databases. In one transaction boundary, all of the operations on multiple connections will be
committed or rolled back together.
 In Explicit: A transaction starts when the pub.art.transaction:startTransaction service is executed. The
transaction is completed when either the pub.art.transaction:commitTransaction or
pub.art.transaction:rollbackTransaction service is executed.

The isolation level settings can be specified in the Other Properties field of the Connection Configuration screen.
Connection Pools: Connection pools improve performance by enabling adapter services to reuse open connections
instead of opening new connections.

Built-In Services for Connections

IS provides built-in services that enable you to programmatically control Connections at design time. 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.
There are two built-in services, setAdapterServiceNodeConnection and setPollingNotificationNodeConnection that
enable you to change the connection associated with an adapter service or notification respectively.

Steps Configuring JDBC Adapter:

A. Create package in WM developer with some name (like : AllAdapter)
B. Adapters -> JDBC Adapter -> Connections -> Configure New Connection -> JDBC Adapter Connection
- >provide all required information ->save connection ->Click No inside Enabled

Configure Connection Type -> JDBC Adapter

Package: AllAdapter
Folder Name: JDBCAdapter
Connection Name: JDBCAdapter

Connection Properties
Transaction Type: LOCAL_TRANSACTION or XA_TRANSACTION or NO_TRANSACTION
DataSource Class: oracle.jdbc.pool.OracleDataSource
serverName: localhost
user: adapter
password: adapter
 Retype password: adapter
databaseName: xe
portNumber: 1521
networkProtocol: tcp
Other Properties: driverType=thin

Connection Management Properties leave as it is.

Explanation of all parameter:

Package: The package in which we create the connection.
Folder Name: The Folder Name in which we create the connection.
Connection Name: The name you want to give to the connection and connection names cannot have spaces or
special characters reserved by the Integration Server or Developer.
NO_TRANSACTION: The connection automatically commits operations (Generally used).
LOCAL_TRANSACTION: The connection uses local transactions.
XA_TRANSACTION: The connection uses XA transactions.
DataSource Class Name: The name of the JDBC driver’s DataSource or XADataSource class for example:
oracle.jdbc.pool.OracleDataSource
Server Name: The name of the server that hosts the database.
User*: The user name that the connection will use to connect to the database.
Password*: The password for the database user name specified in user.
Retype password: Retype the password you just entered.
DatabaseName: The database to which the connection will connect.
Port Number: The port number that the connection will use to connect to the database.
Network Protocol: A standard JDBC Data Source property to indicate the name of the network protocol that the
connection will use when connecting to the database. Use this field only if you use an Oracle JDBC OCI driver.
Type tcp, which is the name of the network protocol.
Enable Connection Pooling: Enables the connection to use connection pooling.
Minimum Pool Size : If connection pooling is enabled means 'true', this field specifies the number of connections to
create when the connection is enabled. The adapter will keep open the number of connections you configure here
regardless of whether these connections become idle.
Maximum Pool Size : If connection pooling is enabled, this field specifies the maximum number of connections that
can exist at one time in the connection pool.
Pool Increment Size: If connection pooling is enabled, this field specifies the number of connections by which the
pool will be incremented if connections are needed, up to the maximum pool size.
Expire Timeout: If connection pooling is enabled, this field specifies the number of milliseconds that an inactive
connection can remain in the pool before it is closed and removed from the pool.
Startup Retry Count (For Integration Server 6.1 only): The number of times that the system should attempt to
initialize the connection pool at startup if the initial attempt fails. The default is 0.
Startup BackoffTimeout (For Integration Server 6.1 only): The number of seconds that the system should wait
between attempts to initialize the connection pool.

Creating adapter service:

An Adapter Service: An adapter service is a service that connects to an adapter’s resource and initiates an operation
on the resource. Adapter services are created using service templates included with the adapter.
 Create or locate folder where you want to create adapter service for example:JDBCAdapter
 Click on New -> click on Adapter Service -> click on Next -> click on JDBC Adapter -> click on Next button ->
Adapter Connection Name you should use -> click on Next -> Select any one of the following Statements
which u want to execute -> click on Next. -> Give the relative name of which u selected the Statement( for
example SelectEMP) -> click on Finish

Web Methods JDBC minimum pool size? (Only look this article)
Performance-wise a min connection > 0 will be "better" for the first set of transactions that is processed in IS using
those connections. That is because the connections to the DB will already be established--the time cost of connecting
and logging in was incurred during start-up rather than when a JDBC service was invoked.
With a min size of 0, the first JDBC service that is invoked will be delayed a bit while the connection is made and log-
in accomplished. After that, there is no overhead (for that connection--each connection up to max pool size will
connect and log-in when multiple connections are needed).

An idle pool will drop the connections back to 0 at some point, and then the next JDBC services will incur the
connect/log-in overhead again.

For busy pools, the actual connections will not go back to 0. They will be maintained and connection/log-in overhead
avoided.

The biggest problem with a min connection > 0 is the potential for stale sessions. This can cause a JDBC service
failure if a session is kept and is idle long enough for the DB to close the session or if the DB is restarted.

As usual, it is a trade-off. You want to strike a balance between keeping too many idle connections (wasteful and risks
stale connections) and establishing connections too often (time delay and impact on the DB server). It is likely rare
that a value other than 0 should/must be used.
The Integration Server requires access to the Java classes for each JDBC driver that it will use. Typically,
where must such Java classes be placed?
Ans: webMethods6\IntegrationServer\lib\jars
How do I sort using the JDBC select adapter service?
Ans: Although there is no tab to specify "order by" the same functionality is able to be specified in the "SELECT" tab.
One of the columns in the is labelled "Sort Order" which will allow you to specify the column(s) you wish to sort by. To
alter the order: simply alter the order of the columns selected
What is meant by "Block time out" and "Expire time out " in jdbc adapter configuration ?
Ans: Block timeout: refers to how much time the IS should wait to get connection from connection pool before
throwing exception. Expire Timeout:refers to how much time the free connection stay as it is before it expires.
What is the internal process for JDBC Adapter notification? what is the use of buffer table , sequence and
trigger objects for Adapter notification?
Ans: Insert and Update Adapter notifications use exactly once notification feature which ensures notification data will
not be duplicated even if a failure occurs during processing since it assigns Unique IDs for each pulishable document.
If there is a processing failure, the IS checks for duplicate records in storage and ignores any of the duplicate IDs
created during failure.
Stored procedure notification do not use publishable document unique IDs so they do not have support for exactly one
notification feature.
Insert, Update and Delete Notifications use a combination of triggers and buffer tables to capture the events happen
on specific tables in a dbase. While configuring the notification you configure the triggers and buffer tables. Adapter
creates trigger and buffer table only when you enable a notification. The trigger monitors the table and inserts the data
in buffer table and buffer tables holds the data. When you disable a notification adapter drops the trigger and
corresponding buffer table.
Notification publishes the publishable document which contains a single row from buffer tables and after publishing the
data/row is removed from buffer table.
How do I change JDBC connections between environments?
Ans: First solution is to use WmDeployer and to set it up to change the parameters of the JDBC connection as part of
the deployment map configuration.
Other solution is to have the JDBC connections in a separate package from the code and to only migrate it when a
connection is added/removed and to configure it for the particular environment. This allows you to migrate the other
packages and leave these other packages alone. The disadvantage is the manual reconfiguration required, but this
can be ok with the appropriate discipline.
How do I do a special join with JDBC Adapter Services?
Solution
As some special join syntax is still fairly database dependent (although there is now provision in the ISO/ANSI SQL
syntax), a custom SQL adapter service appears to be one possible solution to achieving it.
You replace any input variables with questions marks ("?") and then for each question mark you have to add an entry
to the Input JDBC list. These have to match the order and the type expected.
For any output column you need to add a corresponding entry in the output JDBC list. This will tell webMethods what it
should try to extract from your query.
Other Notes
For special joins:
Oracle has the (+) operator for outer joins (and also supports specification in the FROM )
Sybase has *= syntax
MySQL uses syntax in the from block
How do I know what datasource class to use in the connection screen?
Ans: Hit the help link while configuring the connection and you will find a list of the data source classes for different
types of database and different transaction model (e.g. XA vs LOCAL transactions).

How do I move an adapter connection in webMethods?

Ans: Using the web admin for the adapter (e.g. follow the link from the main admin screen for the WmJDBCAdapter)
you can copy an existing connection. Set the new package and folder path to the desired one.
Use Developer and find the old connection and do a "find dependents".
Then for each service call the WmART package service "pub.art.service:setAdapterServiceNodeConnection" passing
in the serviceName and the new connection alias.
If the connection was used for adapter notifications: for each notification call
pub.art.notification:setPollingNotificationNodeConnection.
Note: you should not be mixing adapter services and adapter polling Notifications on the one connection.
When there are no more dependents, delete the connection using the web admin for the adapter.
How do I reload the JDBC adapter once the database goes down?
Problem
The JDBC adapter doesn't refresh the connection to a database once the database has restarted
An example is as follows:
The adapter is connected to an Oracle DB. The database goes down for 1hour for backup purposes and then comes
back up. A transaction is sent to the database, but an error is thrown, saying something like "Unable to invoke
adapterServiceName"
Solution
Write a service that will reload the JDBC adapter after the database has come up:
1. Use wm.art.admin.connection.listResources and specify the "JDBCAdapter" as adapterTypeName
2. This will return all the JDBC adapters on the IS server
3. Loop over the result set and branch on the /connDataNode/connectionAlias
4. create a sequence with the adapter alias and have a branch on the /connDataNode/connectionState
5. if enabled, run a query on the database - select sysdate from dual
6. if successful, the adapter is working successfully otherwise, you'll need to reload the adapter using -
wm.art.admin.connection.setResourceState

How do I sort using the JDBC select adapter service?

Ans:Although there is no tab to specify "order by" the same functionality is able to be specified in the "SELECT" tab.
One of the columns in the is labelled "Sort Order" which will allow you to specify the column(s) you wish to sort by.
To alter the order: simply alter the order of the columns selected.
How do I use the dynamic SQL adapter service type of the JDBC ?
Ans:The dynamic SQL adapter is very similar to the custom SQL adapter service template except that it allows special
markup in the SQL which will result in a new input which will form part of the SQL statement itself. This is more
powerful than the custom SQL because the custom SQL has fixed SQL while allowing dynamic input and output.
Syntax for dynamic portions of the Query
The SQL syntax will be treated specially if you specify a dollar sign, open a curly brace, variable name then close curly
brace.
e.g.
${
variableNameHere
}
The substitution of these parts takes place before the question marks have their values filled. There is no problem with
passing in a statement with question mark placeholders.
Examples
The following will allow you to pass in the table name to return all the rows from. The table name would be passed in a
variable called "tableNameToSelect":
select * from ${tableNameToSelect}
The following will allow you to specify the entire query in an input variable called "theWholeSQLStatement":
${theWholeSQLStatement}
How should I organize my connection pools?
Ans:If you have adapter notifications and adapter services then you will need to have two separate connections.
Otherwise you may get strange errors about transactions and the like.
Avoid having connection pools shared across different functional areas, even if they are pointing to the same
database. Reasons for this are:
Tuning the size of the pool becomes quite difficult if you have multiple types of usage of a pool.
It is not possible to easily change the database settings for one without impacting on the other.
One approach is to have separate pools for each package (generally; not a hard rule though), since your packages
should generally be divided up according to functional area too.
A good strategy: create a different user for each functional area, even if you are going to use the same database. That
way it can be easier to detect performance problems.
How to do a clean oracle uninstallation?
Ans:By default, the software uninstallation provided by Oracle does not totally remove oracle related information. The
following describes on how to do a clean oracle uninstallation:
Do software uninstallation by clicking on the setup.exe used to install Oracle (i.e. there is a link to uninstall oracle)
Delete all oracle related folders from windows explorer
Go to the Windows registry and remove the following:
HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\OracleServiceORCL\
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\
Remove related windows service using the following command from a dos-prompt:
SC delete ServiceName
Restart computer
How to insert BLOB data more than 4KB using SQL query into Oracle ?
Problem
Failed to insert SQL query contained BLOB data larger than 4KB characters into Oracle database using
WmJDBCAdapter version 6.0.3 InsertSQL Adapter service thru classes12.zip.
Solution
1. Download the ojdbc14 Oracle Driver 10g version from Oracle website.
2. Shutdown IntegrationServer.
3. Make backup on classes12.zip or classes12.jar.
4. Remove the classes12.zip or classes12.jar from IntegrationServer/lib/jars directory.
5. Copy the driver file into IntegrationServer/lib/jars directory.
6. Restart IntegrationServer.
7. After restart, make sure all Oracle connections are established.
Version Tested
 1. webMethods Platform version 6.5 with following patches
2. IS_6-5_SP1_Flow_Fix1
3. IS_6-5_SP1_WebSvcsXML_Fix1
4. IS_6-5_SP1_SrvPrtcl_Fix4
5. IS_6-5_SP1_Core_Fix3
6. IS_6-5_SP1
7. Oracle 9.2.0.5
8. WmJDBCAdapter version 6.0.3
Caution
After replaced the classes12.zip or classes12.jar, it is best to perform all database connections and queries test on all
existing DB flow services in development, testing, pre-production environments before apply to production
environment.
Full regression test is best recommended.
This solution tested on "driverType=thin" and not "driverType=oci".
How to modify a JDBC adapter connection in adapter services?
Service
pub.art.service:setAdapterServiceNodeConnection
Input Parameters
serviceName: the fully qualified name of the adapter service we would like to change
connectionAlias: the fully qualified name of the new adapter connection to replace the existing one
An Example
Moving an adapter connection definition into another package
1. Create a new JDBC adapter connection (with the same parameters as the existing one but specify the new
package).
2. Execute the pub.art.service:setAdapterServiceNodeConnection service (on each adapter service) to update the
dependency of the adapter services to the connection.
3. Remove the old JDBC Adapter connection (from the JDBC admins page).
JDBC pool says no suitable driver found but the jdbc url is correct?
This message I've found appears a lot when you copy and paste the JDBC URLs from a web page and it inserts a
leading space.
Other causes are forgetting to put the "wm" part of the URL e.g. jdbc:oracle versus jdbc:wm:oracle
(jdbc:wm:oracle://<yourip>:1521;SID=<your>)
Leaking database connections in WmDB?
If you're using WmDB and having trouble with leaking connections check that you are not closing your sessions
correctly. This is extremely important inside of a transformer step as the pipleines are cleaned up, but
connections/sessions are left lying around and un-touchable by a clean up invocation to closeAll.
Notes on WmDB:
1) To turn pooling on you MUST set the following property:
watt.server.db.connectionCache=server
If you do not set this property you ARE NOT using a connection pool. By default this property IS NOT set. You can still
define a connection alias in the console but that's all you are doing - a pool will not be created and each time you call
a built in DB service you will CREATE a new connection. If you don't call pub.db.close on that connection, it will never
be freed.
2) if you are using pooling and you pass connection info (url, driver, user passwd) into the db services AS WELL as an
alias name you might actually make more connections than the max set in your pool. If, when you call the service, the
pool is already maxed and you have also passed in connection info it will make a NEW connection using that info.
3) There is a hidden property that you can set that will force the server to check each connection object in the pool
before it hands it out. If the connection is bad it will free it and create a new one. Whilst this may have a performance
hit, if you are having problems with dropped connections it is a good thing to do. The property is:
watt.server.db.testSQL=select 'x' from dual (or any SQL that will always return a record - quickly)
4) ALWAYS call pub.db.close or pub.db.closeAll after you have used a built in DB service. IF you don't, the connection
WILL NOT be returned to the pool. It will eventually time out and be destroyed, but never returned to the pool - NOT
GOOD!

What do I do if I get a "Adapter Runtime Error" when enabling a JDBC Adapter Connection?
Error Message
[ART.0114.1007E] Adapter Runtime: Error Logged. See Error log for details. Error: [ART.118.5042] Adapter Runtime
(Connection): Unable to enable connection resource folder:service.
[ART.118.5063] Adapter Runtime (Connection): Unable to start connection folder:service: after 1 attempt(s).
com/ddtek/jdbc/extensions/ExtEmbeddedConnection
"Error Connection
Solution
Ensure you have the sl53_cj33.jar file located in the IS/lib/jars/ directory. Ensure that the extension of the file is .jar
(not .zip).

2. SAP Adapter

Difference between SAP Adapter 4.6 and 6.5?

SAP Adapter 4.6 SAP Adapter 6.5

Uses WmPartners Package Uses WmSap package

Works based on Message Type Works based on IDoc Type

Has same log file for all the IDoc sent/received Have individual log file for each IDoc

Stores Idocwith the TID name Here TID is divided into 3 parts as like in SAPThe
folder structure will be WmSap-->1st part of TID--
>2nd part of TID --> 3rd part.xml(contains the
IDoc)3rd part.xtn(log file for the IDoc)

Listners, Listnernotification, routing notification all Everything can be configured via Developer
need to be configured using Admin console
Its not like a JDBC Adapter Almost similar to JDBC Adapter
How to Create a SAP Adapter connection:

Adapters (IS)->click SAP Adapter->configure new connection->fill the following info -> click on Save Connection.

Package: RFCConnections
Folder Name: RFCConnections
Connection Alias: VEL_D7B
User Name: D7B_OIS
Password: QAZQ12@#
Client : 300
Language: EN
Application Server: SAPD7B.SAPNET.HP.COM
System Number: 00
Listener/ProgramID: SAP-OMIH

On the connections screen, click “No” in the enabled column for the connection you want to enable.
How to Create a Listener:
Adapters (IS)->click SAP Adapter->Go to Listeners -> Configure new listener->Click on RFC listener->Fill in the below
form and click on Save Listener.
Package = RFCConnections
Folder Name = RFCConnections.Listeners.Velocity
Listener Name = SAP_OMIH
Retry Limit = 5
Retry Backoff Timeout = 10
Program ID = SAP-OMIH
Gateway Host = SAPD7C.SAPNET.HP.COM
Gateway Service = sapgw00
Number of Threads = 5
Repository Server = VEL_D7C
SNC Enabled = No
SNC Quality of Service = Use global build-in default settings
RFC Trace = Off
Log Transaction status = on
Store Message body = on
Make status column as “Enabled” for the newly created Listener as shown below.
Create a SAP Adapter (RFC to SAP Inbound): which is used to invoke the RFC function module in the SAP

 Create or locate folder where you want to create adapter service for example:SAPAdapter
 Click on New -> click on Adapter Service -> click on Next -> click on SAP Adapter -> select an Adapter
Connection Alias -> click on Next -> Select RFC Adapter Service -> click on Next ->Give the relative name of
which u want and locate in folder( for example SAPEMP) -> click on Finish
 Open created adapter and provide function pattern and group pattern. And click on save.

1. In the previous step, on the Function search tab, in the Function pattern field, type all or part of the name of
function module for which you want to create an adapter service.
2. Use pattern matching characters if you are unsure of the complete name and want SAP Adapter to search for
several RFCs with similar names.
3. Just enter the pattern and press enter.
4. Under function name, a list of RFCs that match your criteria you specified in previous step is displayed.

Steps to create a SAP Adapter Notification which listens for the SAP Call to webMethods (i.e. RFC to SAP
Outbound):
Go to RoutingNotifications package -> then go to RoutingNotifications folder then -> Create a folder structure
SAPD7C -> Right click on the SAPD7C, select New -> All Choices -> Adapter Notification(as shown below) and click
on Next -> Select SAP Adapter and click on Next ->RFC Listener Notification (Synchronous) and next->select the
adapter notification Listner and click next->provide same name and click on next-> click on next-> click on finish.
Open created adapter and provide function search info:
Function Pattern:RFC*
Group Pattern:*
Function name:RFCING
Function Description:
Group name:SYST
1. In the previous step, on the Function search tab, in the Function pattern field, type all or part of the name of
function module for which you want to create an adapter service.
2. Use pattern matching characters if you are unsure of the complete name and want SAP Adapter to search for
several RFCs with similar names.
3. Just enter the pattern and press enter.
4. Under function name, a list of RFCs that match your criteria you specified in previous step is displayed.
5. Once the Adapter notification is created, whenever the SAP function module (which you given in Function
search tab) issue a call, this Adapter notification will trigger the corresponding webMethods service and
respond back to SAP.

IDoc from webMethods to SAP System

SAP Inbound IDocs: To send a IDoc to SAP, just ensure that there is a connection exists between webMethods and
SAP. Then use the below three services.
1.pub.sap.idoc:documentToIDoc :
This service will convert the document into IDoc.
2.pub.sap.idoc:encodeSDATA:
Converts every SDATA field from a Document object to a String object.
•This service is usually called prior to sending an IDoc to SAP System.
•Note:There is a client service called pub.sap.client:sendIDoc that allows us to send iDocList directly.
3.pub.sap.transport.ALE:OutboundProcess
•This service actually sends the IDoc to SAP System.

IDoc from SAP System to webMethods

• Go to RoutingNotifications package -> then go to RoutingNotifications folder then -> Create a folder structure
SAPD7C -> Right click on the SAPD7C, select New -> All Choices -> Adapter Notification and click on Next -> Select
SAP Adapter and click on Next -> Select ALE Listner Notification (Synchronous) and click on Next -> Select the
Adapter Notification Listener and click on Next -> enter Name as “routingRule” and go to SAPD7C and click on Next -
> Select the Invoke Service and Click Next -> Click on finish.
Provide below information in IDOC settings:
Idoc Type:
Moniter IDOC:

Receiving IDoc Using Default Routing Rule

 The routing rule uses the default listener and triggers the webMethods service for further processing .
 The default routing rule will be the only solution for the below scenario as the SAP Adapter 6.5 makes uses of
IDoc Type rather than the Message Type.
 Suppose say, there are interfaces which has same IDoc type but different message type.
 At this time we can’t make use of ALE, we want to use the Default Routing Notification only.

 Go to RoutingNotifications package -> then go to RoutingNotifications folder then -> Create a folder structure
SAPD7C -> Right click on the SAPD7C, select New -> All Choices -> Adapter Notification(as shown below)
and click on Next -> Select SAP Adapter and click on Next -> Select Routing Notification (Synchronous)
and click on Next -> Select the routingListener and click on Next -> enter Name as “routingRule” and go to
SAPD7C and click on Next -> Select the Invoke Service and Click Next -> Click on finish.
 Need to provide below details under Transport Settings Tab as shown in below screen.
Sender: SAPD7C
Receiver: OMIH2
Message: ALEAUD
Transport: IS
 Go to Adapter Settings tab and click on browse button for Service Name
 Select the Service Invoke and click on OK as shown below. Then SAVE and exit.
 Go to WM Console -> Go to Adaptors -> SAP Adaptor -> Listener Notifications Link -> Filter for
“RoutingNotifications.SAPD7C.OMIH2.ALEAUD:routingRule”
 Make it Enable status to “Yes”
•Sender –An arbitrary string that indicates who sent the message. If the Sender column has character “*” it indicates
that any SAP system can send the data to that particular SAP Adapter.
•Receiver –An arbitrary string that indicates the message destination. If the Receiver column has character “*” it
indicates that it can receive IDoc from any SAP system.
•Message type –is the message type sent by SAP system.

Create SAP Instance in webMethods:

An SAP instance defines a group of resources such as memory, work processes and so on, usually in support of a
single application server or database server within a client/server environment. Application servers share the same
memory areas and are controlled by the same dispatcher process. The instance of the SAP system can be defined as
an administrative unit which consist of different components that makes up the SAP system. These include the
dispatcher, work processes, internet communication manager, assigned memory structures and the gateway.
Can you spell SAP, ERP, CRM, XML and EDI properly?
1. Systems appications & Products
2. Enterprise Resource Planning
3. Customer Relationship Management
4. Extended Markup language
5. Electronic Data Interchange

webMethods SAP Integration for ERP

1 Requirements
In future our Integration Platform(IP) will need to facilitate communication of legacy application with our ERP
environment. Communication with ERP is proposed to go through SAP Process Integration (PI). This
document details various options for this communication.
Do we need EntireX to talk to SAP PI?
What additional components do SAP need to install on their side of the fence?
Are there standard adapters we can use on the IP side of the fence?
Any other infrastructure tidbits we might need to know about in order to establish connectivity with SAP PI
How to ensure working with different SAP versions?

2 SAP PI Overview
SAP PI is SAP's EAI software. It provides adapters to communicate with external systems (e.g. Web service, JMS,
FTP, ...), can communicate with SAP ERP systems, and provides functionality to implement mapping logic. SAP PI
sits on top of SAP Web Application Server.
SAP PI consists of two components: the SAP PI Integration Server that interacts with the SAP Enterprise Core
Components and the SAP PI Adapter Engine that provides the ability to interact with other systems via adapters. SAP
PI includes a number of adapters to interact for example via HTTP, Web service, JMS, or FTP. Additional adapters
may be purchased from 3rd party vendors.

3 Connectivity Options
3.1 Direct Integration of ERP and IP (SAP <-> webMethods (SAP Adapter))
The webMethods SAP adapter is used together with a dedicated webMethods Integration Server instance to provide
integration between ERP and the IP. The dedicated webMethods Integration Server allows a decoupling between the
Integration Backbone and the SAP integration.
Benefits:
Fewer different components to manage
Proven approach used by numerous customers
DHL operations familiar with the management of webMethods IS
Promises best performance
Asynchronous & synchronous communication possible
Drawbacks:
Requires additional webMethods knowledge in ERP

3.2 Communication via PI using the XI adapter (SAP <-> SAP PI <-> webMethods (SAP PI Adapter))
webMethods provides an adapter to interact with SAP PI directly. This adapter exists since the XI days and remains
unchanged for interaction with SAP PI. A dedicated webMethods IS is only used for connectivity, all mapping &
transformation already done on the Integration Backbone.
Benefits:
Skips the external SAP PI Adapter Engine => better performance than JMS or Web services that used the Adapter
Engine
Asynchronous & synchronous communication possible
Drawbacks:
XI adapter is an older product that has seen limited usage (officially supported on webMethods 8.x)
Requires servers for PI and dedicated webMethods Integration Server => increased management efforts

3.3 Communication via PI using Web services (SAP <-> SAP PI <-> webMethods (webServices))
SAP PI provides a Web services adapter to call and offer Web services. This functionality can be used in conjunction
with the built-in Web service functionality of webMethods to integrate ERP and the IP.
Benefits:
Standards-based communication
Web services to be offered and called directly from the Integration Backbone integration layer
Drawbacks:
Most likely the slowest approach
Possibility of incompatibilities in the respective Web service stacks of SAP PI and webMethods
Asynchronous communication not intuitive

3.4 Communication via PI using JMS (SAP <-> SAP PI <-> webMethods (JMS))
SAP PI provides a JMS adapter to call and offer Web services. This functionality can be used in conjunction with the
built-in JMS functionality of webMethods to integrate ERP and the IP. SAP PI includes its own JMS provider but the
usage of webMethods Broker is recommended.
Benefits:
Standards-based communication
JMS is the standard communication in the Integration Backbone
Drawbacks:
Should be faster than Web services but slower than the other two options
JMS configuration on SAP PI Adapter Engine non-trivial (especially as features like authentication and encryption are
to be used)
Synchronous communication possible but not very intuitive
3.5 Ignored Options
The following options have been discounted and not researched in detail:
File, FTP via PI: not desired for new interfaces
HTTP: less strict than SOAP, might introduce manageability issues
RFC-based communication via PI: no benefits over RFC-based direct communication
XI-based communication with SAP EC component

Recommendation
A direct integration using the webMethods SAP adapter is the preferred approach. It simplifies the overall system
landscape as only one EAI platform is running and also ensures better performance as fewer components are
involved. The only downside is that it requires some webMethods knowledge on the ERP side to offer the necessary
functionality via SAP adapter and webMethods Integration Server.
If the use of SAP PI is mandated, the JMS based integration is the best choice.
Sending an IDOC from a SAP system.
When a IDOC is sent by an SAP system it is received by WM IS and some processing is done on the IDOC or stored
in a secondary storage device .
When a IDOC is received a flow service in IS has to be executed , we have to give the service name , folder name
and package name in the routing role(when a routing rule is defined).
Receive an IDOC service:
-> Sap.idoc.decodesdata (byte array to values object (with key & value)).
-> Sap . idoc . encode
Service out (XML Data -------------- IDOC data) (IDOC in values format to XML string)
-> Sample.IO.test.write to file
Filename : file path ........... XML
IDOC data ---------- file content
For test sending an IDOC to wM IS
1) Open web browser and paste the link
http://localhost:5555/SAP/submit-IDOCXML.html
2) Copy and paste the IDOC in text area (IDOC which is in XML format).
3) Modify the fields
< RCVPRN> Receiving logical system name given by SAP people(Found in routing rule)
sending logical system name given by SAP people (or found in Routing rule)
message type MATMOS(ORDERS) INVOICE/------------ Given by SAP
4) Click on the submit button to send the IDOC to an IS
Sending an IDOC (MATMAS) format to an SAP system and Data in the form of XML file.
Steps:
1) Get an sample MATMAS DOC in XML format.
2) Create a DTD from the MATMAS XML file . This is a document type in (MATMAS FORMAT)
3) Collect the mandatory fields for MATMAS and create a Document with the fields
(IDOC _ MAN).
4) Create a document type with the configurations for sending an IDOC
(IDOC--CONFIG)
DOCUMENT:
-> Table name -- EDI - DC40
-> Direct (2 for sending)
- > IDOC type (MATMAS 01/02/03)
-> Message type (MATMAS)
-> SNDPOR – MIR 57
-> SNDPRN -- MIR 57 LS (logical system name created in SAP server)
-> SNDPRT -- LS (Partner type)
-> RCVPOR -- SAP IDS
-> RCVPRN – IDS47800
-> Receiver port - LS
5) Create an XML Document from the XML file (Data in XML format) (IDOC __ XML)
6) Send IDOC service (For sending an IDOC)

-> get file inputs

File name : Path DTD ref of (IDOC -- CONFIG)
Load AS : bytes DTD ref of (IDOC --MAN)
-> String to document (SAP BC 4.7) XML String to XML node (WM 6.1)
Body
Bytes ---> file data
-> Document to record (SAP BC 4.7) XML node to document (WM 6.1)
Bound node -- (Ref DTD/ document of XML)
MATMAS 03.outbound : XML(XML)
-> MAP
IDOC configuration (all fields ->
IDOC – MAN (all fields -> (MATMAS - FORMAT)
XML (all fields -> (recognised fields)
-> Transform hierarchy to flat [pub.sap.idoc.transform hierarchy to flat]
(MATMAS - format) ------ bound node
[reformat IDOC fromhierrachia format to RFC format]
-> Outbond process [pub. Sap.transport.ALE.OUTBOUND Process]
Transport params -> server : SAP server name – WM SAP
 [To send an IDOC to SAP server ]
DEBMAS and ORDERS IDOCS sending Same as MATMAS but mandatory fields changes
-> In SAPBC developer 4.1 we can create an SAP IDOC (document type) by giving the parameters IDOC type :
ORDERS 02 / MATMAS 03/
-> In SAPBC 4.6 Document is called a RECORD.
1) SAPBC ------> SAP
-> We just have to give the package name and folder name while configuring SAP BC -> SAP map and a service
name is given.
-> After that by refreshing the developers page we can find that service in the path.
2) SAP -------> SAP BC
-> We have to give the package name and folder name while configuring. SAP
-> SAP BC map and a service which is already created in any folder (folder name) and service name has to be given
while configuring SAP -> SAP BC map.
-> Then when we refresh our developer browser a flow service is created in our developer in the same package in
which we had given ref of WM service.
-> The service name is same(SAP service) which is by default stored in path.
SAP -> INBOUND -> WMSAP -> BAPI-COMPANY CODE -> GETLIST
(SAP server name) (SAP service name)
Which invokes our add service.
-> Double click on BAPI – COMPANY CODE _ GETLIST and copy all the input and output fields and paste it in our
service (add ) map the require fields and save.
-> SAP system will call BAPI – COMPANY CODE –getlist which in turn calls our wM flow service add by the input
parameters provided by SAP system and output is generated by our service (add).which is then provided to BAPI –
COMPANY CODE –GETLIST flow service then to SAP system.

Q:How to convert an IDOC values xml to a Document Type?

Ans:Use sap.idoc:transformFlatToHierarchy
Q:The number and size of SAP trace files and logs can grow significantly depending on the number of
transactions/communications between the webMethods server and SAP. This can introduce problems with
maintenance, usually in the manner of either an increase in time, effort and/or cost to perform the
maintenance?
Ans:Removing the trace files and logs can be manually carried out in the SAP adapter console. To do this, simply go
to the Administration Console, click on the SAP link, navigate to the monitoring link and there will be options to remove
the trace files and logs. Another approach is to carry out this task in an automated fashion. This can be done by
scheduling the following http invocations:
To delete RFC Trace Files...
http://<ip>:<port>/invoke/sap.monitor.rfcTrace/deleteAll?type=RFC
To delete SAP Log Files...
http://<ip>:<port>/invoke/sap.monitor.rfcTrace/deleteAll?type=SAP
Q:How to get the IDoc document number created in SAP after successfully submitting an IDOC
asynchronously to SAP using pub.sap.client:sendIDoc?
Ans:SAP provides an RFC called INBOUND_IDOCS_FOR_TID. This RFC expects SAP transaction id (the same
transaction id used to invoke the sendIDoc service) as an input and returns a list of IDoc document numbers.
Here is a sample RFC request message:
<?xml version="1.0" encoding="iso-8859-1"?>
<sap:Envelope xmlns:sap="urn:sap-com:document:sap" version="1.0">
<sap:Header xmlns:rfcprop="urn:sap-com:document:sap:rfc:properties">
<saptr:From xmlns:saptr="urn:sap-com:document:sap:transport">BC1</saptr:From>
<saptr:To xmlns:saptr="urn:sap-com:document:sap:transport">BC2</saptr:To>
</sap:Header>
<sap:Body>
<rfc:INBOUND_IDOCS_FOR_TID xmlns:rfc="urn:sap-com:document:sap:rfc:functions">
<TID>0A241C27363E4AE771390AA5</TID>
</rfc:INBOUND_IDOCS_FOR_TID>
</sap:Body>
</sap:Envelope>
Here is a sample RFC response message:

<?xml version="1.0" encoding="iso-8859-1"?>

<sap:Envelope xmlns:sap="urn:sap-com:document:sap" version="1.0">
<sap:Body>
<rfc:INBOUND_IDOCS_FOR_TID.Response xmlns:rfc="urn:sap-com:document:sap:rfc:functions">
<I_DOCNUM>
<item>0000000000021317</item>
</I_DOCNUM>
</rfc:INBOUND_IDOCS_FOR_TID.Response>
 </sap:Body>
</sap:Envelope>
Q:The SAP Adaptor cannot be installed using the webMethods Installer.
I installed the SAP Adaptor but am getting these exceptions:
Cannot view the SAP console from IS web admin. SAP link not shown under Adapters.
java.lang.reflect.InvocationTargetException: com/wm/pkg/sap/Log
Can't find library sapjcorfc (sapjcorfc.dll) in java.library.path
Ans:
Follow these steps to install the SAP adaptor:

Go to Advantage and log in. You will need an account that has access to software downloads. Please refer to your
licensing agreements with webMethods.
Go to software download for webMethods and look for SAP adaptor 4.6
SAP adaptor 4.6 relies on WmPartner. Download and install this first. (To install view installation instructions)
Download SAP adaptor 4.6 package SAP.zip. Put this in the replication/inbound and install via web admin console.
Shutdown your server.
Copy LIBRFC32.dll and sapjcorfc.dll from packages\SAP\code\libs to your windows SYSTEM32 directory.
Restart windows.
Start up IS.
In the web console the SAP link should show under Adapters.
Realtime Scenerio:
Automated transactions involving publish/subscribe on the broker are failing while sending BAPI's to SAP
with the following error:

com.wm.pkg.sap.BCException: Null session ID, cannot lock session

at com.wm.pkg.sap.rfc.SessionManager.lockSession(Unknown Source)
at com.wm.pkg.sap.rfc.SessionManager.lockSession(Unknown Source)
at pub.sap.client.lockSession(Unknown Source)

This error does not occur when manually running the service that the trigger subscribing to the broker
document invokes.

The code snippet looks like this:

pub.sap.client:lockSession
(pub.sap.bapi:decode)
(pub.sap.client:createTID)
pub.sap.transport.BAPI:OutboundProcess
pub.sap.bapi:commit

Problem
When running IS as a Windows NT service, SAP trace files are not created in the directory defined by setting
the RFC_TRACE_DIR in server.bat as per described in the adapter's installation guide.

pub.sap.client:releaseSession
Solution:
a) webMethods patch fix
Go to Advantage and log in. You will need an account that has access to software downloads. Please refer to your
licensing agreements with webMethods.
Apply patch IS_6-1_SP2_PubSub_Fix3 as per this support article on advantage:
http://advantage.webmethods.com/article/?id=SR-1-88000881

b) Code change
If applying the above patch does not work, simply disable the following three steps from the code snippet:

pub.sap.client:lockSession
pub.sap.bapi:commit
pub.sap.client:releaseSession
This should allow transactions to be processed but is not recommended as a long term solution.

Problem
We've had several cases where you can create a SAP Alias in webMethods and connect ok, then create a
listener in webMethods and that reports that it can connect ok, but then go into SAP and run SM59 and it
cannot connect back to webMethods.

Solution
The solution was to delete the individual listeners inside the SAP alias and recreate them.

Q:How to send an IDoc flat file into SAP?

Ans:Here is a quick 2-step process to send an IDoc flat file into SAP via the ALE/IDoc interface. The RFC that is
actually invoked is called:

IDOC_INBOUND_ASYNCHRONOUS
Firstly, invoke the following service. This service converts an input string into the equivalent IDoc format that is
understood by the file port of the SAP system.

pub.sap.idoc:decodeString
Secondly, invoke the following service. This service routes the IDoc into the designated SAP system. You will need to
configure an SAP Server in the SAP Adapter before invoking this service.

pub.sap.transport.ALE:OutboundProcess

Problem
When running IS as a Windows NT service, SAP trace files are not created in the directory defined by setting the
RFC_TRACE_DIR in server.bat as per described in the adapter's installation guide.

SET RFC_TRACE_DIR=%IS_DIR%\packages\WmSAP\logs
Solution
Define the RFC_TRACE_DIR as a system variable in Windows. Follow these steps:

Right click on My Computer.

Click on Properties. This will open the System Properties window.
Click on Advanced tab.
Click on Environment Variables button. This will open the Environment Variables window.
Under the System variables section, click on the New button.
Define the variable RFC_TRACE_DIR and provide the value as the target directory.
Click Ok button until all windows are closed.
Restart your IS service and SAP trace files should be created in your target directory.

Problem
The user that posted this document (SAPUser) could not be associated with a partner to check their identity.

Solution
You need to determine the appropriate group. For example assigning SAPUser to the TNAdministrators group will
resolve the problem. But, do you really want to do this?

Problem
Testing an RFC using Adapters > SAP Adapter > Lookup > RFC-XML Template returns the correct response.
But a different response is returned when running a service that invokes the RFC using
pub.sap.transport.RFC:OutboundProcess.

Solution
Ensure that you drop $tid from the pipeline before invoking pub.sap.transport.RFC:OutboundProcess in order to get
the correct response. Dropping this variable makes synchronous RFC call to SAP.

Alternatively you can also use pub.sap.client:invoke to make a synchronous call to RFC.