Webmethods Adapter

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 login 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. 2. 3. 4. 5. 6.

Use wm.art.admin.connection.listResources and specify the "JDBCAdapter" as adapterTypeName This will return all the JDBC adapters on the IS server Loop over the result set and branch on the /connDataNode/connectionAlias create a sequence with the adapter alias and have a branch on the /connDataNode/connectionState if enabled, run a query on the database - select sysdate from dual 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. 2. 3. 4. 5. 6. 7.

Download the ojdbc14 Oracle Driver 10g version from Oracle website. Shutdown IntegrationServer. Make backup on classes12.zip or classes12.jar. Remove the classes12.zip or classes12.jar from IntegrationServer/lib/jars directory. Copy the driver file into IntegrationServer/lib/jars directory. Restart IntegrationServer. After restart, make sure all Oracle connections are established.

Version Tested

1. 2. 3. 4. 5. 6. 7. 8.

webMethods Platform version 6.5 with following patches IS_6-5_SP1_Flow_Fix1 IS_6-5_SP1_WebSvcsXML_Fix1 IS_6-5_SP1_SrvPrtcl_Fix4 IS_6-5_SP1_Core_Fix3 IS_6-5_SP1 Oracle 9.2.0.5 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://:1521;SID=) 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 need to be configured using Admin console Its not like a JDBC Adapter

Everything can be configured via Developer 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: Folder Name: Connection Alias: User Name: Password: Client : Language: Application Server: System Number: Listener/ProgramID:

RFCConnections RFCConnections VEL_D7B D7B_OIS QAZQ12@# 300 EN SAPD7B.SAPNET.HP.COM 00 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://:/invoke/sap.monitor.rfcTrace/deleteAll?type=RFC To delete SAP Log Files... http://:/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: BC1 BC2 0A241C27363E4AE771390AA5 Here is a sample RFC response message: 0000000000021317

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.