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

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

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

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

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

SAP NetWeaver Process Integration 7.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.

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

SAP Partner Connectivity Kit Overview

Supports Smaller Companies / Subsidiaries to exchange XML documents with their business partners / 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. SAP PCK is the developing and testing platform for new modules and adapters.

SAP NetWeaver Process Integration 7.1

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

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

SAP PI Adapter Standard Modules

AS Java
Your JCA 1.0 Adapter JCA 1.0 SPIVerbind. JCA 1.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.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.jar etc.

ejb-Call

Session ejb Aufruf

Gener. AF Module ejb

Spezif. AF Module ejb

Aufruf

R>

AS Java System and Add-On Services

<R>

XIMessages

Messag. HTTP(S) Servlet JDBC/ Service (Web Cont.) Open SQL Database (SAP DB, etc.)

AF AF ... Config. Utilities Logtables

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 7.1

10

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.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. 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 EJBs

SAP NetWeaver Process Integration 7.1

11

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 7.1

12

Adapter Module (UML Diagram)

Method called by ModuleProcessor

Access to message Content

Access to adapter configuration

SAP NetWeaver Process Integration 7.1

13

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 7.1

14

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

15

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 7.1

16

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 7.1

17

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 7.1

18

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 7.1

19

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 7.1

20

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 7.1

21

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

22

Agenda

1. 2. 3.

Adapter Framework Overview Module Development Overview Logging in the Adapter Modules
1. 2. 3.

Introduction Create Adapter Module As an EJB 2.1 Deploy the Adapter Module on the Java EE Server

4.

Developing Adapter Modules

SAP NetWeaver Process Integration 7.1

23

Agenda

1. 2. 3.

Adapter Framework Overview Module Development Overview Logging in the Adapter Modules
1. 2. 3.

Introduction Create Adapter Module As an EJB 2.1 Deploy the Adapter Module on the Java EE Server

4.

Developing Adapter Modules

SAP NetWeaver Process Integration 7.1

24

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.1

25

Development Environment

Adapter development, deployment and testing is possible on a single machine, 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. For testing purposes integration scenarios can be configured in SAP PCK (e.g. loopback scenario).

SAP Partner Connectivity Kit

PCK Configuration and Monitoring

Adapter FW Messaging Queuing Security Handling

File/DB/JMS Marketplace 3rd Party Sys.

Resource Adapter

SAP NetWeaver Process Integration 7.1

26

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 7.1

27

Java Doc for Module Development

SAP NetWeaver Process Integration 7.1

28

Available Documentation

The Adapter Development documentation is available via http://help.sap.com

The documentation for SAP NetWeaver PI 7.1 will be available soon on SAP Help Portal.

SAP NetWeaver Process Integration 7.1

29

Agenda

1. 2. 3.

Adapter Framework Overview Module Development Overview Logging in the Adapter Modules
1. 2. 3.

Introduction Create Adapter Module As an EJB 2.1 Deploy the Adapter Module on the Java EE Server

4.

Developing Adapter Modules

SAP NetWeaver Process Integration 7.1

30

Create the Adapter Module EJB

Steps in the SAP NetWeaver Developer Studio

1. 2.

Create an EJB J2EE 1.4 Module Project (to create EJB 2.1) Apply the libraries (at least com.sap.aii.af.lib.mod.jar and com.sap.aii.af.ms.ifc_api.jar) Create a package (in folder ejbModule) Create a stateless session bean Write the code of the Java class Adjust the ejb-jar.xml Adjust the ejb-j2ee-engine.xml Build the EJB archive (JAR)

3. 4. 5. 6. 7. 8.

SAP NetWeaver Process Integration 7.1

31

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 7.1

32

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 7.1

33

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 7.1

34

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 7.1

35

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.org/2001/XMLSchema-instance" id="ejb-jar_ID" interface generated version="2.1" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"> names <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

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 7.1

36

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=http://www.w3.org/2001/XMLSchema-instance 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 7.1

37

Agenda

1. 2. 3.

Adapter Framework Overview Module Development Overview Logging in the Adapter Modules
1. 2. 3.

Introduction Create Adapter Module As an EJB 2.1 Deploy the Adapter Module on the Java EE Server

4.

Developing Adapter Modules

SAP NetWeaver Process Integration 7.1

38

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 7.1

39

Create the Enterprise Application Archive

Steps in the SAP NetWeaver Developer Studio

1. 2. 3. 4. 5.

Create an Enterprise Application Project. Add the EJB module. Adjust the application-j2ee-engine.xml like follows. Build the Application archive (EAR). Deploy the EAR file to the SAP PCK/AE.

SAP NetWeaver Process Integration 7.1

40

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

SAP NetWeaver Process Integration 7.1

41

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 7.1

42

Deploy the EAR File Using NW Developer Studio

Used mainly for testing purposes

SAP NetWeaver Process Integration 7.1

43

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 7.1

44

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 7.1

45