SAP NetWeaver Process Integration 7.1 Developing User Enhancement Modules in the Adapter Engine

Size: px

Start display at page:

Download "SAP NetWeaver Process Integration 7.1 Developing User Enhancement Modules in the Adapter Engine"

Mervyn Randall
5 years ago
Views:

1 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

2 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

3 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 4. Developing Adapter Modules SAP NetWeaver Process Integration 7.1 3

4 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 4. Developing Adapter Modules SAP NetWeaver Process Integration 7.1 4

The SAP PI Adapter Framework Based on SAP NW Application Server Java Uniform Handling of Deployment, Configuration, Administration, Monitoring and Security Technical Basis for Adapter Engine and SAP

5 The SAP PI Adapter Framework Based on SAP NW Application Server Java Uniform Handling of Deployment, Configuration, Administration, 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, JMS, JDBC.. SAP NetWeaver Process Integration 7.1 5

6 SAP NetWeaver Process Integration 7.1 Architecture ES Repository / Integration Directory / System Landscape Directory Integration Server Business Process Engine Adapter Engine (Java SE) Adapter HTTP/IDoc Adapter Integration Engine Central Adapter Engine Adapter Framework Messaging Queuing Security Handling Resource Adapter Optional non-central Adapter Engine Adapter FW Messaging Queuing Security Handling Resource Adapter Partner Connectivity Kit PCK Configuration and Monitoring Adapter FW Messaging Queuing Security Handling Resource Adapter File DB JMS SOAP SAP & Non-SAP System File/DB/JMS Marketplace 3rd Party Sys. File/DB/JMS Marketplace 3rd Party Sys. File/DB/JMS Marketplace 3rd Party Sys. Applications based on SAP Web Application Server version 6.20 or higher can communicate with the SAP NetWeaver PI in the native XI-SOAP format via proxies. All other applications, including legacy SAP systems (those on Basis releases lower than Version 6.20), communicate with the SAP NetWeaver PI via adapters. SAP provides an Adapter Framework and an Adapter Engine for this communication. SAP NW PI 7.1 introduces a new, Java EE based adapter architecture. The adapter engine is installed centrally on the Integration Server; it can also be installed locally (close to the Business system), but still be configured, managed, and monitored centrally. Additionally, the SAP Partner Connectivity Kit, the toolset for enabling small partners or subsidiaries with no native XML messaging capabilities to communicate with SAP NetWeaver PI, is based on the Adapter Engine. SAP NetWeaver Process Integration 7.1 6

7 SAP Partner Connectivity Kit Overview Supports Smaller Companies / Subsidiaries to exchange XML documents with their business partner s / headquarters' SAP PI Large Business Partner / Headquarters Smaller Company / Subsidiary 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. SAP PCK is the developing and testing platform for new modules and adapters. SAP NetWeaver Process Integration 7.1 7

8 Use Cases for Adapter Module Development Converting the payload (not covered with standards) Changing the encoding (escaping, de-escaping) Encryption and decryption Creating and merging of additional attachments SAP NetWeaver Process Integration 7.1 8

9 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 4. Developing Adapter Modules SAP NetWeaver Process Integration 7.1 9

10 SAP PI Adapter Standard Modules AS Java Session ejb Call <R> Session ejb Aufruf XI- Messages R v AF Entry ejb Messag. Service R > ejb-call AS Java System and Add-On Services HTTP(S) ejb 2.0 Container Gener. AF Module ejb JCA 1.0 Framework AF Module Prozessor R v JCA 1.0 SPI- Verbind. R v Servlet (Web Cont.) Your JCA 1.0 Adapter Spezif. AF Module ejb Database (SAP DB, etc.) ^ R v R > ejb-call ^ R v JDBC/ Open SQL JCA 1.0 CCI Connections AF Modul- Exit ejb AF Config. R v RService- v Aufruf R > AF Utilities R > Java-Classes Deployed Java and PIsystemlibraries: Java- Classes... Your Protocol<R> aii_af_ service_ util.jar etc. Logtables 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 The figure shows the modules that are involved in the message exchange. It also shows technical tracing and logging mechanisms. The blocks shown in gray are parts of the Adapter Framework. The white blocks are part of AS Java. You must make the orange blocks available in adapter development. The Adapter Framework mainly consists of Enterprise JavaBeans. As a rule, these are stateless session beans. They communicate with the adapters using the Enterprise JavaBeans container and the JCA framework. SAP NetWeaver Process Integration

11 Adapter Module Processor Receiver Direction Asynchronous Communication Customer-Specific Adapter Modules Standard Adapter Module Messaging System Module 1 Adapter Module Module 2 Module 2 Adapter Module Module 1 JCA 1.0 Adapter 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. The default module configuration for a certain adapter is displayed in the communication channel configuration. Module configuration is defined as message-protocol and adapter type specific. Stateless Sequence matters! Modules are EJB s SAP NetWeaver Process Integration

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

12 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. These modules equip the adapters with additional functions. If it is not possible to add modules to an adapter, 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. SAP NetWeaver Process Integration

13 Adapter Module (UML Diagram) Method called by ModuleProcessor Access to message Content Access to adapter configuration SAP NetWeaver Process Integration

14 Adapter Module (Code Fragment) public class CreateAttachment implements SessionBean, Module { } public ModuleData process( ModuleContext modulecontext, ModuleData inputmoduledata) throws ModuleException { } Message messagein = (Message) inputmoduledata.getprincipaldata(); XMLPayload xmlpayloadin = messagein.getdocument(); String parameter = modulecontext.getcontextdata("parameter"); SAP NetWeaver Process Integration

15 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 4. Developing Adapter Modules SAP NetWeaver Process Integration

16 Logging Developers and systems management experts might have different requirements on logging mechanisms. 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.xml or at runtime in the Log Configuration of the SAP NetWeaver Administrator. SAP NetWeaver Process Integration

17 Logging: Service Trace SAP NetWeaver Administrator provides a Log Viewer. Trace output is configured in the Log Configurator. Each log destination can be separately displayed and filtered according to user-specific needs. The Log Viewer can be accessed in the SAP NetWeaver Administrator: Select Availability and Performance Management -> Log Viewer SAP NetWeaver Process Integration

18 Logging: Service Trace (Code Fragment) public class CreateAttachment implements SessionBean, Module { private Location loc = null; public ModuleData process(modulecontext modulecontext, ModuleData inputmoduledata) throws ModuleException { try{ String SIGNATURE = "YourSignature"; loc = Location.getLocation(CreateAttachment.class.getName(); loc.entering(signature, new Object[] { modulecontext, inputmoduledata }); } Message messagein = (Message) inputmoduledata.getprincipaldata(); } catch (Exception e) { loc.catching(signature, e); loc.errort(signature, "Error occurred"); } SAP NetWeaver Process Integration

19 Logging: Audit Log The SAP PI Message Display Tool provides comprehensive filter mechanisms to find the relevant messages. For each message content and audit log can be monitored. SAP NetWeaver Process Integration

20 Logging: Audit Log For each message an audit log is written that shows processing details (e.g. the executed module chain). SAP PI AF provides standard methods within its logging framework. SAP NetWeaver Process Integration

21 Logging: Audit Log (Code Fragment) public class CreateAttachment implements SessionBean, Module { } public ModuleData process( ModuleContext modulecontext, ModuleData inputmoduledata) throws ModuleException { Message messagein = (Message) inputmoduledata.getprincipaldata(); MessageKey key = new MessageKey(msg.getMessageId(), MessageDirection.OUTBOUND); PublicAPIAccess pa = PublicAPIAccessFactory.getPublicAPIAccess(); AuditAccess audit = pa.getauditaccess(); audit.addauditlogentry(key, AuditLogStatus.SUCCESS, "CreateAttachment: Module called"); } SAP NetWeaver Process Integration

22 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 4. Developing Adapter Modules SAP NetWeaver Process Integration

23 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 1. Introduction 2. Create Adapter Module As an EJB Deploy the Adapter Module on the Java EE Server 4. Developing Adapter Modules SAP NetWeaver Process Integration

24 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 1. Introduction 2. Create Adapter Module As an EJB Deploy the Adapter Module on the Java EE Server 4. Developing Adapter Modules SAP NetWeaver Process Integration

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

26 Development Environment Adapter development, deployment and testing is possible on a single machine, no full-blown SAP NetWeaver PI is required. SAP Partner Connectivity Kit PCK Configuration and Monitoring Installation of SAP PCK already contains a sample adapter (including adapter metadata) and a sample module that should serve as a starting point. Adapter FW Messaging Queuing Security Handling Resource Adapter For testing purposes integration scenarios can be configured in SAP PCK (e.g. loopback scenario). File/DB/JMS Marketplace 3rd Party Sys. SAP NetWeaver Process Integration

27 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. Copy the file aii_adapter_sample_ra.jar from <serverdir>\apps\sap.com\com.sap.aii.af.sample.ra\connector\bin\connecto rs\aii_adapter_sample_ra.rar to a separate directory on your computer. <serverdir> is C:\usr\sap\J2E\J01\j2ee\cluster, for example. Extract the JAR file to the same directory. Open index.html to display the Java Doc. The source code for the example adapter module is located in the file, sample_module.jar, under the subdirectory: <serverdir>\apps\sap.com\com.sap.aii.af.sample.module.app\ejbcontainer\ applicationjars SAP NetWeaver Process Integration

28 Java Doc for Module Development SAP NetWeaver Process Integration

29 Available Documentation The Adapter Development documentation is available via The documentation for SAP NetWeaver PI 7.1 will be available soon on SAP Help Portal. SAP NetWeaver Process Integration

30 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 1. Introduction 2. Create Adapter Module As an EJB Deploy the Adapter Module on the Java EE Server 4. Developing Adapter Modules SAP NetWeaver Process Integration

31 Create the Adapter Module EJB Steps in the SAP NetWeaver Developer Studio 1. Create an EJB J2EE 1.4 Module Project (to create EJB 2.1) 2. Apply the libraries (at least com.sap.aii.af.lib.mod.jar and com.sap.aii.af.ms.ifc_api.jar) 3. Create a package (in folder ejbmodule) 4. Create a stateless session bean 5. Write the code of the Java class 6. Adjust the ejb-jar.xml 7. Adjust the ejb-j2ee-engine.xml 8. Build the EJB archive (JAR) SAP NetWeaver Process Integration

32 Overview of Usable Libraries For the module development you have to extract following libraries from your PCK/AF installation com.sap.aii.af.lib.mod.jar the interface Module com.sap.aii.af.ms.ifc_api.jar dealing with payload and attachments sap.com~tc~logging~java~impl.jar writing trace com.sap.aii.af.svc_api.jar adapter services com.sap.aii.af.cpa.svc_api.jar reading channel entries com.sap.aii.af.ms.ifc_api.jar You find the libraries here: com.sap.aii.af.lib.mod.jar: <bin>/ext/com.sap.aii.af.lib/lib com.sap.aii.af.ms.ifc_api.jar: <bin>/ext/bin/interfaces/com.sap.aii.af.ms.ifc/lib sap.com~tc~logging~java~impl.jar: <bin>/system com.sap.aii.af.svc_api.jar: <bin>/services/com.sap.aii.af.svc/lib com.sap.aii.af.cpa.svc_api.jar: <bin>/services/com.sap.aii.af.cpa.svc/lib com.sap.aii.af.ms.ifc_api.jar: <bin>/interfaces/com.sap.aii.af.ms.ifc/lib <bin> = /usr/sap/<sid>/j01/j2ee/cluster/bin SAP NetWeaver Process Integration

33 Adapter Module EJB Template (1) package yourpackage; import javax.ejb.createexception; import javax.ejb.sessionbean; import javax.ejb.sessioncontext; import com.sap.aii.af.lib.mp.module.*; import com.sap.engine.interfaces.messaging.api.*; public class YourClass implements SessionBean, Module{ private SessionContext mycontext; public void ejbremove() { } public void ejbactivate() { } SAP NetWeaver Process Integration

34 Adapter Module EJB Template (2) public void ejbpassivate() { } public void setsessioncontext(sessioncontext context) { mycontext = context; } public void ejbcreate() throws CreateException { } public ModuleData process(modulecontext modulecontext, ModuleData inputmoduledata) throws ModuleException { // put your code here return inputmoduledata; } } You only need to apply code to the method process. SAP NetWeaver Process Integration

35 Code Sample: Adding an Additional Attachment public ModuleData process(modulecontext modulecontext, ModuleData inputmoduledata) throws ModuleException { try { Message msg = (Message) inputmoduledata.getprincipaldata(); TextPayload attachment = msg.createtextpayload(); attachment.setname("attachment"); attachment.setcontenttype("text/plain"); attachment.settext("hello World"); msg.addattachment(attachment); inputmoduledata.setprincipaldata(msg); } catch (Exception e) { ModuleException me = new ModuleException(e); throw me; } return inputmoduledata; } SAP NetWeaver Process Integration

The ejb-jar.xml The ejb-jar.xml file can be generated with the NW Developer Studio. <?xml version="1.0" encoding="utf-8"?> <ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.

36 The ejb-jar.xml The ejb-jar.xml file can be generated with the NW Developer Studio. <?xml version="1.0" encoding="utf-8"?> <ejb-jar xmlns=" xmlns:xsi=" id="ejb-jar_id" version="2.1" xsi:schemalocation=" <description>ejb JAR description</description> <display-name>ejb JAR</display-name> <enterprise-beans> <session> <ejb-name>yourejbname</ejb-name> <home>com.sap.aii.af.lib.mp.module.modulehome</home> <remote>com.sap.aii.af.lib.mp.module.moduleremote </remote> <local-home> com.sap.aii.af.lib.mp.module.modulelocalhome </local-home> <local>com.sap.aii.af.lib.mp.module.modulelocal</local> <ejb-class>yourpackage.yourclass</ejb-class> <session-type>stateless</session-type> <transaction-type>container</transaction-type> </session> </enterprise-beans> </ejb-jar> Replace the generated interface names The ejb-jar.xml defines the package and class names corresponding to an ejb name. The interface names of the Adapter Module classes are always the standard interfaces of the Adapter Module Development Kit. You find them in the library com.sap.aii.af.lib.mod.jar SAP NetWeaver Process Integration

37 The ejb-j2ee-engine.xml Configuration tool in the NW Developer Studio can be used to generate this file. <?xml version="1.0" encoding="utf-8"?> <ejb-j2ee-engine xmlns:xsi= xsi:nonamespaceschemalocation="ejb-j2ee-engine.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.xml defines the JNDI name corresponding to an ejb name. The adapter module is called by this JNDI name. Therefore this name has to be set to the module configuration. If you do not define a JNDI name here, the JNDI name is sap.com/<application-name>/<ejb-name> where the application name is set in the application.xml in the EAR. SAP NetWeaver Process Integration

38 Agenda 1. Adapter Framework Overview 2. Module Development Overview 3. Logging in the Adapter Modules 1. Introduction 2. Create Adapter Module As an EJB Deploy the Adapter Module on the Java EE Server 4. Developing Adapter Modules SAP NetWeaver Process Integration

39 Files in the SDA/EAR Besides the JAR file with the Adapter Module classes and the ebj descriptors, there are following files with path META-INF MANIFEST.MF Contains the version numbers and the provider names. SAP_MANIFEST.MF Contains version numbers, content, and component names, similar to a catalog. The SDM uses this information to manage the deployment information in its database. application.xml Contains display names and references to icons if the adapter is displayed with SAP J2EE tools. application-j2ee-engine.xml Contains references required during SDM deployment. If you want to use the trace of the AS Java engine, you have to add the file log-configuration.xml Use the sample module (sample_module.sda) as a template for the settings of your adapter module. SAP NetWeaver Process Integration

40 Create the Enterprise Application Archive Steps in the SAP NetWeaver Developer Studio 1. Create an Enterprise Application Project. 2. Add the EJB module. 3. Adjust the application-j2ee-engine.xml like follows. 4. Build the Application archive (EAR). 5. Deploy the EAR file to the SAP PCK/AE. SAP NetWeaver Process Integration

41 The application-j2ee-engine.xml In this file you have to create following references Reference target Reference type Reference target-type Provider name engine.security.facade hard service sap.com engine.j2ee14.facade hard library sap.com com.sap.aii.af.svc.facade hard service sap.com com.sap.aii.af.ifc.facade hard interface sap.com com.sap.aii.af.lib.facade hard library sap.com com.sap.base.technology.facade hard library sap.com SAP NetWeaver Process Integration

42 Deploying SAP PI Adapter Components SAP recommends to use SAP Java Support Package Manager (JSPM) for deployment. Software Delivery Archives (SDA) can contain software components of different types (e.g. applications, libraries). Detailed version information and dependencies to other components simplify program management. You can create SDA files with the Composition Environment Command Line Tool (CECLT), which is part of the SAP NW Developer Studio installation. SAP NetWeaver Process Integration

43 Deploy the EAR File Using NW Developer Studio Used mainly for testing purposes SAP NetWeaver Process Integration

Select Configuration Management -> Infrastructure -> Application

44 Check Deployment Using SAP NetWeaver Administrator Check, if the EJB is deployed and active Open the SAP NetWeaver Administrator. Select Configuration Management -> Infrastructure -> Application Modules Search your module by name. SAP NetWeaver Process Integration

45 Copyright 2007 SAP AG. 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. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iseries, pseries, xseries, zseries, System i, System i5, System p, System p5, System x, System z, System z9, z/os, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/os, POWER, POWER5, POWER5+, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mysap, mysap.com, xapps, xapp, SAP NetWeaver, 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. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. The information in this document is proprietary to SAP. No part of this document may be reproduced, copied, or transmitted in any form or for any purpose without the express prior written permission of SAP AG. This document is a preliminary version and not subject to your license agreement or any other agreement with SAP. This document contains only intended strategies, developments, and functionalities of the SAP product and is not intended to be binding upon SAP to any particular course of business, product strategy, and/or development. Please note that this document is subject to change and may be changed by SAP at any time without notice. SAP assumes no responsibility for errors or omissions in this document. SAP does not warrant the accuracy or completeness of the information, text, graphics, links, or other items contained within this material. This document is provided without a warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall have no liability for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. This limitation shall not apply in cases of intent or gross negligence. The statutory liability for personal injury and defective products is not affected. 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. SAP NetWeaver Process Integration