SAP NetWeaver Process Integration 7.1 Developing User Enhancement Modules in the Adapter Engine SAP NetWeaver Regional Implementation Group SAP NetWeaver Product Management December 2007 SAP NetWeaver Process Integration 7.1 1 Benefits This presenations helps you to: Understand the architecture of SAP PI Adapter Framework Use the SAP NetWeaver Developer Studio to develop and deploy the adapter module Use SAP Partner Connectivity Kit (PCK) to test the adapter module Understand the requirement and steps during the development process Configure the adapter module in the communication channel Monitor the adapter module processing in the Runtime Workbench SAP NetWeaver Process Integration 7.1 2 Agenda 1. 2. 3. 4. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules Developing Adapter Modules SAP NetWeaver Process Integration 7.1 3 Agenda 1. 2. 3. 4. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules Developing Adapter Modules SAP NetWeaver Process Integration 7.1 4 Administration.The SAP PI Adapter Framework Based on SAP NW Application Server Java Uniform Handling of Deployment. Monitoring and Security Technical Basis for Adapter Engine and SAP Partner Connectivity Kit Adapters run as services within the SAP NW Application Server Java and use the services of the Adapter Framework (for example Queuing and Logging) Usage of open standards: SOAP. SAP NetWeaver Process Integration 7.. JMS. JDBC…. Configuration.1 5 . SAP NW PI 7. including “legacy” SAP systems (those on Basis releases lower than Version 6. File/DB/JMS Marketplace 3rd Party Sys. is based on the Adapter Engine.1 Architecture ES Repository / Integration Directory / System Landscape Directory Integration Server Business Process Engine Integration Engine Optional non-central Adapter Engine Resource Adapter Resource Adapter Adapter FW Messaging Queuing Security Handling Adapter Engine (Java SE) Central Adapter Engine HTTP/IDoc Adapter Adapter Framework Messaging Queuing Security Handling Partner Connectivity Kit PCK Configuration and Monitoring Adapter FW Messaging Queuing Security Handling Resource Adapter Adapter File DB JMS SOAP SAP & Non-SAP System File/DB/JMS Marketplace 3rd Party Sys. the toolset for enabling small partners or subsidiaries with no native XML messaging capabilities to communicate with SAP NetWeaver PI. SAP provides an Adapter Framework and an Adapter Engine for this communication.20).20 or higher can communicate with the SAP NetWeaver PI in the native XI-SOAP format via proxies. Java EE based adapter architecture. Additionally. communicate with the SAP NetWeaver PI via adapters. SAP NetWeaver Process Integration 7. File/DB/JMS Marketplace 3rd Party Sys. managed. and monitored centrally. Applications based on SAP Web Application Server version 6. it can also be installed locally (close to the Business system). The adapter engine is installed centrally on the Integration Server.SAP NetWeaver Process Integration 7.1 6 .1 introduces a new. but still be configured. All other applications. the SAP Partner Connectivity Kit. SAP NetWeaver Process Integration 7. SAP PCK is the developing and testing platform for new modules and adapters.SAP Partner Connectivity Kit – Overview Supports Smaller Companies / Subsidiaries to exchange XML documents with their business partner’s / headquarters' SAP PI Large Business Partner / Smaller Company / Subsidiary Headquarters SAP Application SAP / 3rd Party Appl. SAP PCK Internet SAP NW PI 3rd Party Application Provides a Platform for Development of own JCA Resource Adapters and Adapter Modules SAP PCK SAP Partner Connectivity Kit can connect smaller companies or subsidiaries to Process Integration for message exchange.1 7 . de-escaping) Encryption and decryption Creating and merging of additional attachments SAP NetWeaver Process Integration 7.Use Cases for Adapter Module Development Converting the payload (not covered with standards) Changing the encoding (escaping.1 8 . 4. 3. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules Developing Adapter Modules SAP NetWeaver Process Integration 7.1 9 .Agenda 1. 2. 1 10 .. JCA 1. As a rule.) AF AF . It also shows technical tracing and logging mechanisms. They communicate with the adapters using the Enterprise JavaBeans container and the JCA framework.0 Container AF Module Prozessor R v R v R > AF Modul- AF Entry ejb Exit ejb ejb-Call RServicev JavaClasses aii_af_ service_ util. You must make the orange blocks available in adapter development. ejb-Call Session ejb Aufruf Gener. AF Module ejb Aufruf R> AS Java System and Add-On Services <R> XIMessages Messag. etc.0 SPIVerbind. HTTP(S) Servlet JDBC/ Service (Web Cont.jar etc. SAP NetWeaver Process Integration 7. these are stateless session beans. Config. Utilities Logtables The figure shows the modules that are involved in the message exchange. The blocks shown in gray are parts of the Adapter Framework. The Adapter Framework mainly consists of Enterprise JavaBeans. The white blocks are part of AS Java..0 Adapter JCA 1. AF Module ejb Spezif.SAP PI Adapter Standard Modules AS Java Your JCA 1.) Open SQL Database (SAP DB.0 Framework Session ejb Call R v R> ^ R v ^ R v Your Protocol <R> R> Java-Classes Deployed Java and PIsystemlibraries: R v JCA 1.0 CCI Connections Channel templates define a module chain to be processed by the SAP PI AF Module Processor The default chain can be modified by customers Standard modules can be re-used to access JCA adapters and SAP PI Messaging System ejb 2. Stateless Sequence matters! Modules are EJB‘s SAP NetWeaver Process Integration 7.Adapter Module Processor Receiver Direction Asynchronous Communication Customer-Specific Adapter Modules Standard Adapter Module Module 1 Messaging System Adapter Module Module 2 Module 2 Adapter Module JCA 1.1 11 . The default module configuration for a certain adapter is displayed in the communication channel configuration.0 Adapter Module 1 Sender Direction Asynchronous Communication For each adapter it is possible to define generic modules in the module processor: You have the possibility to extend the functionality of a specific adapter. Module configuration is defined as message-protocol and adapter type specific. 1 12 . If it is not possible to add modules to an adapter.Adapter Module Chain Custom modules can be added to default module chains Additional configuration parameters can be specified each module You have the option of specifying generic modules for adapters that are configured in the communication channel. you will not be able to select the Module tab page. The modules that are the basis of the adapter configuration on the Parameters tab page are located in the module processor and are displayed in the module processor once a communication channel has been created. These modules equip the adapters with additional functions. SAP NetWeaver Process Integration 7. Adapter Module (UML Diagram) Method called by ModuleProcessor Access to message Content Access to adapter configuration SAP NetWeaver Process Integration 7.1 13 . ModuleData inputModuleData) throws ModuleException { Message messageIN = (Message) inputModuleData.1 14 .getPrincipalData(). XMLPayload xmlPayloadIN = messageIN. String parameter = moduleContext. Module { public ModuleData process( ModuleContext moduleContext.Adapter Module (Code Fragment) public class CreateAttachment implements SessionBean.getContextData("parameter"). } } SAP NetWeaver Process Integration 7.getDocument(). 2.Agenda 1.1 15 . 3. 4. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules Developing Adapter Modules SAP NetWeaver Process Integration 7. SAP NetWeaver Process Integration 7. The PI Adapter Framework Logging API supports methods for displaying processing output in the SAP PI Message Display Tool trace output in the SAP NetWeaver Application Server Java The trace output can be maintained by default in the XML configuration file log-configuration.Logging Developers and systems management experts might have different requirements on logging mechanisms.xml or at runtime in the Log Configuration of the SAP NetWeaver Administrator.1 16 . Trace output is configured in the Log Configurator.1 17 . The Log Viewer can be accessed in the SAP NetWeaver Administrator: Select Availability and Performance Management -> Log Viewer SAP NetWeaver Process Integration 7. Each log destination can be separately displayed and filtered according to user-specific needs.Logging: Service Trace SAP NetWeaver Administrator provides a Log Viewer. loc.getName().1 18 .getPrincipalData(). ModuleData inputModuleData) throws ModuleException { try{ String SIGNATURE = "YourSignature". new Object[] { moduleContext. } catch (Exception e) { loc.catching(SIGNATURE. public ModuleData process(ModuleContext moduleContext. "Error occurred").Logging: Service Trace (Code Fragment) public class CreateAttachment implements SessionBean. Module { private Location loc = null.getLocation(CreateAttachment. } } SAP NetWeaver Process Integration 7.errorT(SIGNATURE.class. e). inputModuleData }). loc = Location. loc.entering(SIGNATURE. Message messageIN = (Message) inputModuleData. Logging: Audit Log The SAP PI Message Display Tool provides comprehensive filter mechanisms to find the relevant messages. SAP NetWeaver Process Integration 7.1 19 . For each message content and audit log can be monitored. 1 20 . SAP PI AF provides standard methods within its logging framework.Logging: Audit Log For each message an audit log is written that shows processing details (e. the executed module chain). SAP NetWeaver Process Integration 7.g. PublicAPIAccess pa = PublicAPIAccessFactory. audit.Logging: Audit Log (Code Fragment) public class CreateAttachment implements SessionBean. AuditAccess audit = pa.OUTBOUND).getMessageId().addAuditLogEntry(key.SUCCESS.getPrincipalData().getPublicAPIAccess(). "CreateAttachment: Module called"). MessageKey key = new MessageKey(msg. ModuleData inputModuleData) throws ModuleException { Message messageIN = (Message) inputModuleData. } } SAP NetWeaver Process Integration 7.1 21 . MessageDirection.getAuditAccess(). Module { public ModuleData process( ModuleContext moduleContext. AuditLogStatus. Agenda 1.1 22 . Adapter Framework Overview Module Development Overview Logging in the Adapter Modules Developing Adapter Modules SAP NetWeaver Process Integration 7. 2. 4. 3. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules 1. Introduction Create Adapter Module As an EJB 2. 3.Agenda 1. 2.1 23 . 3. Developing Adapter Modules SAP NetWeaver Process Integration 7. 2.1 Deploy the Adapter Module on the Java EE Server 4. 3. 2.1 24 . 2. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules 1. Introduction Create Adapter Module As an EJB 2. Developing Adapter Modules SAP NetWeaver Process Integration 7.1 Deploy the Adapter Module on the Java EE Server 4.Agenda 1. 3. 1 25 .Development Kit and Module Processor Development Kit for development of additional adapters (partner and customer solutions) Based on SAP NetWeaver Application Server Java and JCA (Java EE Connector Architecture) SAP NetWeaver Certification of Third-Party Adapters Module processor as extension concept Default-Modules per Adapter SAP NetWeaver Process Integration 7. no full-blown SAP NetWeaver PI is required. Installation of SAP PCK already contains a sample adapter (including adapter metadata) and a sample module that should serve as a starting point.1 26 . deployment and testing is possible on a single machine.Development Environment Adapter development.g. SAP Partner Connectivity Kit PCK Configuration and Monitoring Adapter FW Messaging Queuing Security Handling File/DB/JMS Marketplace 3rd Party Sys. loopback scenario). Resource Adapter SAP NetWeaver Process Integration 7. For testing purposes integration scenarios can be configured in SAP PCK (e. <serverDir> is C:\usr\sap\J2E\J01\j2ee\cluster.Java Doc And Code Samples For Module Development The Java Doc is contained in the sample adapter JAR file included with the SAP NetWeaver PI/PCK system. The source code for the example adapter module is located in the file.html to display the Java Doc. under the subdirectory: <serverDir>\apps\sap. for example. Open index.af.sample.module. Copy the file aii_adapter_sample_ra. sample_module.app\EJBContainer\ applicationjars SAP NetWeaver Process Integration 7.af.com\com.1 27 .aii.jar.sample.com\com.rar to a separate directory on your computer.aii. Extract the JAR file to the same directory.ra\connector\bin\connecto rs\aii_adapter_sample_ra.jar from <serverDir>\apps\sap.sap.sap. 1 28 .Java Doc for Module Development SAP NetWeaver Process Integration 7. SAP NetWeaver Process Integration 7.Available Documentation The Adapter Development documentation is available via http://help.1 will be available soon on SAP Help Portal.1 29 .sap.com The documentation for SAP NetWeaver PI 7. 1 Deploy the Adapter Module on the Java EE Server 4.1 30 . 3. 3. Introduction Create Adapter Module As an EJB 2. 2. Developing Adapter Modules SAP NetWeaver Process Integration 7.Agenda 1. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules 1. 2. lib. 5. 6. 2.sap.Create the Adapter Module EJB Steps in the SAP NetWeaver Developer Studio 1.xml Build the EJB archive (JAR) 3.af.xml Adjust the ejb-j2ee-engine.af.4 Module Project (to create EJB 2.ms. 4. 7.1) Apply the libraries (at least com.ifc_api.1 31 .mod.sap.aii.jar) Create a package (in folder ejbModule) Create a stateless session bean Write the code of the Java class Adjust the ejb-jar.aii. 8.jar and com. Create an EJB J2EE 1. SAP NetWeaver Process Integration 7. jar: <bin>/system – com.aii.ifc/lib – <bin> = /usr/sap/<SID>/J01/j2ee/cluster/bin SAP NetWeaver Process Integration 7.jar: <bin>/services/com.cpa.ms.sap.jar You find the libraries here: – com.af.aii.lib.ms.svc_api.jar – adapter services com.svc_api.svc_api.aii.aii.jar – dealing with payload and attachments sap.ms.aii.sap.ifc_api.sap.af.ms.af.com~tc~logging~java~impl.sap.af.cpa.sap.aii.jar – the interface Module com.ms.ifc_api.af.af.af.com~tc~logging~java~impl.sap.lib.af.sap.jar: <bin>/ext/com.af.af.cpa.ifc_api.sap.aii.aii.sap.jar – reading channel entries com.sap.ifc/lib – sap.svc_api.svc/lib – com.1 32 .aii.af.sap.jar: <bin>/ext/bin/interfaces/com.aii.af.aii.sap.aii.jar: <bin>/interfaces/com.ifc_api.af.jar: <bin>/services/com.aii.ms.lib/lib – com.mod.svc/lib – com.aii.sap.af.sap.sap.jar – writing trace com.af.aii.Overview of Usable Libraries For the module development you have to extract following libraries from your PCK/AF installation com.mod. public void ejbRemove() { } public void ejbActivate() { } SAP NetWeaver Process Integration 7. import javax.ejb.*.CreateException. public class YourClass implements SessionBean.ejb.mp.af. import javax.interfaces.*.sap.Adapter Module EJB Template (1) package yourPackage.api.aii.module.sap. import com.1 33 .ejb. import javax. import com.SessionBean.engine.messaging. Module{ private SessionContext myContext.SessionContext.lib. Adapter Module EJB Template (2) public void ejbPassivate() { } public void setSessionContext(SessionContext context) { myContext = context.1 34 . } public void ejbCreate() throws CreateException { } public ModuleData process(ModuleContext moduleContext. } } You only need to apply code to the method process. SAP NetWeaver Process Integration 7. ModuleData inputModuleData) throws ModuleException { // put your code here return inputModuleData. } return inputModuleData.1 35 .createTextPayload(). } catch (Exception e) { ModuleException me = new ModuleException(e).setContentType("text/plain"). attachment. inputModuleData. attachment. } SAP NetWeaver Process Integration 7.getPrincipalData(). throw me. TextPayload attachment = msg.Code Sample: Adding an Additional Attachment public ModuleData process(ModuleContext moduleContext.addAttachment(attachment). ModuleData inputModuleData) throws ModuleException { try { Message msg = (Message) inputModuleData.setName("Attachment"). attachment.setText("Hello World"). msg.setPrincipalData(msg). af.module.lib.af.sap.aii.lib.module.sun.af.aii. You find them in the library com.0" encoding="UTF-8"?> <ejb-jar xmlns="http://java. The interface names of the Adapter Module classes are always the standard interfaces of the Adapter Module Development Kit.mp.The ejb-jar.com/xml/ns/j2ee http://java.ModuleHome</home> <remote>com.w3.ModuleRemote </remote> <local-home> com.sap.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.jar SAP NetWeaver Process Integration 7.ModuleLocal</local> <ejb-class>yourPackage.xml defines the package and class names corresponding to an ejb name.aii.xsd"> names <description>EJB JAR description</description> <display-name>EJB JAR</display-name> <enterprise-beans> <session> <ejb-name>YourEJBName</ejb-name> <home>com.lib.xml file can be generated with the NW Developer Studio.xml The ejb-jar.ModuleLocalHome </local-home> <local>com.lib.sun.mod.1 36 .YourClass</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> </ejb-jar> Replace the The ejb-jar.aii.aii.1" xsi:schemaLocation="http://java.mp.mp.af. <?xml version="1.sap.module.module.mp.org/2001/XMLSchema-instance" id="ejb-jar_ID" interface generated version="2.sap.lib.sap.com/xml/ns/j2ee/ejb-jar_2_1.af. w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="ejb-j2ee-engine.1 37 .com/<application-name>/<ejb-name> where the application name is set in the application. If you do not define a JNDI name here.xml Configuration tool in the NW Developer Studio can be used to generate this file.xml in the EAR.xsd"> <enterprise-beans> <enterprise-bean> <ejb-name>YourEJBName</ejb-name> <jndi-name>YourJNDIName</jndi-name> <session-props/> </enterprise-bean> </enterprise-beans> </ejb-j2ee-engine> The ejb-j2ee-engine. The adapter module is called by this JNDI name. <?xml version="1. Therefore this name has to be set to the module configuration.The ejb-j2ee-engine.0" encoding="UTF-8"?> <ejb-j2ee-engine xmlns:xsi=http://www. the JNDI name is sap.xml defines the JNDI name corresponding to an ejb name. SAP NetWeaver Process Integration 7. 3. 2. Developing Adapter Modules SAP NetWeaver Process Integration 7.1 38 .Agenda 1.1 Deploy the Adapter Module on the Java EE Server 4. 2. Introduction Create Adapter Module As an EJB 2. Adapter Framework Overview Module Development Overview Logging in the Adapter Modules 1. 3. there are following files with path META-INF MANIFEST.xml Contains display names and references to icons if the adapter is displayed with SAP J2EE tools. application.sda) as a template for the settings of your adapter module. application-j2ee-engine. SAP_MANIFEST. SAP NetWeaver Process Integration 7. similar to a catalog.MF Contains the version numbers and the provider names.1 39 . and component names. content.xml Contains references required during SDM deployment.xml Use the sample module (sample_module.Files in the SDA/EAR Besides the JAR file with the Adapter Module classes and the ebj descriptors. you have to add the file log-configuration. The SDM uses this information to manage the deployment information in its database. If you want to use the trace of the AS Java engine.MF Contains version numbers. 1 40 . Deploy the EAR file to the SAP PCK/AE. Build the Application archive (EAR). Adjust the application-j2ee-engine. 3. Add the EJB module.Create the Enterprise Application Archive Steps in the SAP NetWeaver Developer Studio 1. Create an Enterprise Application Project. SAP NetWeaver Process Integration 7. 5.xml like follows. 2. 4. lib.com sap.af.facade com.security.com sap.com SAP NetWeaver Process Integration 7.facade com.facade Reference type hard hard hard hard hard hard Reference target-type service library service interface library library Provider name sap.sap.sap.sap.com sap.The application-j2ee-engine.ifc.com sap.aii.svc.af.technology.base.af.sap.1 41 .xml In this file you have to create following references Reference target engine.aii.facade com.com sap.facade com.aii.facade engine.j2ee14. 1 42 .g.Deploying SAP PI Adapter Components SAP recommends to use SAP Java Support Package Manager (JSPM) for deployment. You can create SDA files with the Composition Environment Command Line Tool (CECLT). SAP NetWeaver Process Integration 7. libraries). Software Delivery Archives (SDA) can contain software components of different types (e. applications. Detailed version information and dependencies to other components simplify program management. which is part of the SAP NW Developer Studio installation. 1 43 .Deploy the EAR File Using NW Developer Studio Used mainly for testing purposes SAP NetWeaver Process Integration 7. 1 44 .Check Deployment Using SAP NetWeaver Administrator Check. SAP NetWeaver Process Integration 7. if the EJB is deployed and active Open the SAP NetWeaver Administrator. Select Configuration Management -> Infrastructure -> Application Modules Search your module by name. . OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. ICA. All Rights Reserved No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. XHTML and W3C are trademarks or registered trademarks of W3C®. This document contains only intended strategies. Java is a registered trademark of Sun Microsystems. used under license for technology invented and implemented by Netscape. The information in this document is proprietary to SAP. copied. This document is provided without a warranty of any kind. Parallel Sysplex. Outlook. System p5. indirect. and/or development. OS/2. Inc. product strategy. mySAP. and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Tivoli. SAP assumes no responsibility for errors or omissions in this document. xSeries. OSF/1. Data contained in this document serves informational purposes only. SAP. Sweden. text. fitness for a particular purpose. SAP NetWeaver Process Integration 7. zSeries. VideoFrame. or consequential damages that may result from the use of these materials. WebSphere. Windows. This document is a preliminary version and not subject to your license agreement or any other agreement with SAP. The information contained herein may be changed without prior notice. MVS/ESA. S/390. and PowerPoint are registered trademarks of Microsoft Corporation. mySAP. special. IBM. The statutory liability for personal injury and defective products is not affected. xApp. System z. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third-party Web pages nor provide any warranty whatsoever relating to third-party Web pages. OS/390. z/OS. and functionalities of the SAP® product and is not intended to be binding upon SAP to any particular course of business.com. Adobe. graphics. System z9. Netfinity. Inc. or transmitted in any form or for any purpose without the express prior written permission of SAP AG. R/3. Microsoft. Citrix.1 45 . SAP shall have no liability for damages of any kind including without limitation direct. OS/400. pSeries. links. and Motif are registered trademarks of the Open Group. Acrobat. xApps. WinFrame. X/Open. and MultiWin are trademarks or registered trademarks of Citrix Systems. i5/OS. POWER. and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. the Adobe logo. Excel. AFP. Program Neighborhood. National product specifications may vary. POWER5+. including but not limited to the implied warranties of merchantability. This limitation shall not apply in cases of intent or gross negligence. Inc. SAP NetWeaver. or other items contained within this material. Please note that this document is subject to change and may be changed by SAP at any time without notice. Oracle is a registered trademark of Oracle Corporation. Informix. World Wide Web Consortium. XML. System i5. DB2. No part of this document may be reproduced. developments. UNIX. Intelligent Miner. System x. iSeries. JavaScript is a registered trademark of Sun Microsystems. System i. AIX. Massachusetts Institute of Technology. either express or implied. AS/400. MaxDB is a trademark of MySQL AB. MetaFrame. HTML. All other product and service names mentioned are the trademarks of their respective companies. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.Copyright 2007 SAP AG. PostScript. DB2 Universal Database. or non-infringement. System p. SAP does not warrant the accuracy or completeness of the information. POWER5.