developing user enhancement modules in the adapter engine · (java se) partner connectivity...

SAP NetWeaver Process Integration 7.1 1

SAP NetWeaver Regional Implementation GroupSAP NetWeaver Product ManagementDecember 2007

SAP NetWeaver Process Integration 7.1Developing User Enhancement Modulesin the Adapter Engine


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


1. Adapter Framework Overview2. Module Development Overview3. Logging in the Adapter Modules4. Developing Adapter Modules

Agenda



Agenda


The SAP PI Adapter Framework

Based on SAP NW Application Server JavaUniform Handling of Deployment,Configuration, Administration, Monitoring andSecurityTechnical Basis for Adapter Engine and SAPPartner Connectivity KitAdapters run as services within the SAP NWApplication Server Java and use the services ofthe Adapter Framework (for example Queuingand Logging)Usage of open standards: SOAP, JMS,JDBC…..


Integration Server

AdapterEngine

(Java SE)

Partner ConnectivityKitOptional non-central

Adapter EngineCentralAdapter Engine

SAP NetWeaver Process Integration 7.1Architecture

ES Repository / Integration Directory / System Landscape Directory

Business Process Engine

Integration Engine

Adapter FrameworkMessagingQueuing

Security HandlingR

esourceAdapter

Resource

Adapter

Resource

Adapter

Adapter FWMessagingQueuing

Security Handling


Security Handling

PCK Configurationand Monitoring

HTTP

/IDoc

Adapter

Adapter

File/DB/JMSMarketplace

3rd Party Sys.

FileDB

JMSSOAP

SAP &Non-SAPSystem


3rd Party Sys.


3rd Party Sys.

Adapter FrameworkMessagingQueuing

Security Handling


Security Handling


Security Handling

Applications based on SAP Web Application Server version 6.20 or higher can communicate withthe 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 theSAP NetWeaver PI via adapters. SAP provides an Adapter Framework and an Adapter Engine forthis communication.

SAP NW PI 7.1 introduces a new, Java EE based adapter architecture. The adapter engine isinstalled centrally on the Integration Server; it can also be installed locally (close to the Businesssystem), but still be configured, managed, and monitored centrally.

Additionally, the SAP Partner Connectivity Kit, the toolset for enabling small partners orsubsidiaries with no native XML messaging capabilities to communicate with SAP NetWeaver PI, isbased on the Adapter Engine.


SAP Partner Connectivity Kit – Overview

Supports Smaller Companies / Subsidiaries to exchange XML documents with theirbusiness partner’s / headquarters' SAP PI

SAP / 3rdParty Appl.

SAP NWPI

Smaller Company / Subsidiary

SAPPCK

SAPApplication

3rd PartyApplication

Large Business Partner /Headquarters

Internet

SAPPCK

Provides a Platform for Development of own JCA Resource Adapters andAdapter Modules

SAP Partner Connectivity Kit can connect smaller companies or subsidiaries to Process Integrationfor message exchange.

SAP PCK is the developing and testing platform for new modules and adapters.


Use Cases for Adapter Module Development

Converting the payload (not covered with standards)Changing the encoding (escaping, de-escaping)Encryption and decryptionCreating and merging of additional attachments



Agenda


SAP PI Adapter Standard Modules

Channeltemplates define amodule chain tobe processed bythe SAP PI AFModule Processor

The default chaincan be modifiedby customers

Standard modulescan be re-used toaccess JCAadapters and SAPPI MessagingSystem

AS Java

Database (SAP DB, etc.)

Messag.Service

HTTP(S) Servlet(Web Cont.)

JDBC/Open SQL

Log-tables

AFConfig.

AFUtilities

AS Java System and Add-On Services

AFEntry ejb

AF ModuleProzessor

AF Modul-Exit ejb

ejb 2.0 Container

Gener. AFModule ejb

Spezif.AF Module ejb

Your JCA 1.0Adapter

JCA 1.0 CCIConnections

JCA 1.0Framework

DeployedJava and

PI-system-libraries:

aii_af_service_util.jar

etc.

...

R >Java-Classes

Java-Classes

Rv

R >

Rv

Rv

Rv

R >R >

Rv

Session ejbAufruf

Session ejbCall

ejb-Call Service-Aufruf

ejb-Call

^Rv

JCA 1.0 SPI-Verbind.

Your Protocol<R>

<R>

XI-Messages

^Rv

The figure shows the modules that are involved in the message exchange. It also shows technicaltracing and logging mechanisms.

The blocks shown in gray are parts of the Adapter Framework. The white blocks are part of ASJava. You must make the orange blocks available in adapter development.

The Adapter Framework mainly consists of Enterprise JavaBeans. As a rule, these are statelesssession beans. They communicate with the adapters using the Enterprise JavaBeans containerand the JCA framework.


MessagingSystem

Adapter Module Processor

AdapterModule

Module2

Module1

Module1

Module2

AdapterModule

JCA 1.0Adapter

Receiver DirectionAsynchronousCommunication

Sender DirectionAsynchronousCommunication

Standard AdapterModule

Customer-SpecificAdapter Modules

For each adapter it is possible to define generic modules in the module processor: You have thepossibility to extend the functionality of a specific adapter.

The default module configuration for a certain adapter is displayed in the communication channelconfiguration.

Module configuration is defined as message-protocol and adapter type specific.

Stateless

Sequence matters!

Modules are EJB‘s


Adapter Module Chain

Custom modulescan be added todefault modulechains

Additionalconfigurationparameters canbe specified eachmodule

You have the option of specifying generic modules for adapters that are configured in thecommunication channel. These modules equip the adapters with additional functions. If it is notpossible 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 arelocated in the module processor and are displayed in the module processor once a communicationchannel has been created.


Adapter Module (UML Diagram)

Access toadapter configuration

Access tomessage Content

Method called byModuleProcessor


Adapter Module (Code Fragment)

public class CreateAttachmentimplements 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");

}

}



Agenda


Logging

Developers and systems management experts might have differentrequirements on logging mechanisms.The PI Adapter Framework Logging API supports methods for displaying

processing output in the SAP PI Message Display Tooltrace output in the SAP NetWeaver Application Server Java

The trace output can be maintained by default in the XML configuration filelog-configuration.xml or at runtime in the Log Configuration of the SAPNetWeaver Administrator.


Logging: Service Trace

SAP NetWeaverAdministrator providesa Log Viewer.

Trace output isconfigured in theLog Configurator.

Each log destination canbe separately displayedand filtered according touser-specific needs.

The Log Viewer can be accessed in the SAP NetWeaver Administrator:

Select Availability and Performance Management -> Log Viewer


Logging: Service Trace (Code Fragment)

public class CreateAttachment implements SessionBean,Module {

private Location loc = null;


try{

String SIGNATURE = "YourSignature";loc =

Location.getLocation(CreateAttachment.class.getName();loc.entering(SIGNATURE,new Object[] { moduleContext, inputModuleData });


} catch (Exception e) {loc.catching(SIGNATURE, e);loc.errorT(SIGNATURE, "Error occurred");

}

}


Logging: Audit Log

The SAP PI Message DisplayTool provides comprehensivefilter mechanisms to find therelevant messages.

For each message contentand audit log can bemonitored.


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.


Logging: Audit Log (Code Fragment)

public class CreateAttachmentimplements SessionBean, Module {



MessageKey key =new MessageKey(msg.getMessageId(),

MessageDirection.OUTBOUND);

PublicAPIAccess pa =PublicAPIAccessFactory.getPublicAPIAccess();

AuditAccess audit = pa.getAuditAccess();audit.addAuditLogEntry(key,

AuditLogStatus.SUCCESS,"CreateAttachment: Module called");

}

}



Agenda


1. Adapter Framework Overview2. Module Development Overview3. Logging in the Adapter Modules

1. Introduction2. Create Adapter Module As an EJB 2.13. Deploy the Adapter Module on the Java EE Server

4. Developing Adapter Modules

Agenda





Agenda


Development Kit and Module Processor

Development Kit for development of additional adapters (partner and customersolutions)

Based on SAP NetWeaver Application Server Java and JCA (Java EE ConnectorArchitecture)

SAP NetWeaver Certification of Third-Party Adapters

Module processor as extension concept

Default-Modules per Adapter


Development Environment

Adapter development, deploymentand testing is possible on a singlemachine, no full-blown SAPNetWeaver PI is required.

Installation of SAP PCK alreadycontains a sample adapter (includingadapter metadata) and a samplemodule that should serve as astarting point.

For testing purposes integrationscenarios can be configured inSAP PCK (e.g. loopback scenario).

SAP Partner ConnectivityKit


Security Handling

Resource

Adapter

PCK Configurationand Monitoring


3rd Party Sys.


Java Doc And Code Samples For ModuleDevelopment

The Java Doc is contained in the sample adapter JAR file included with theSAP 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\connectors\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


Java Doc for Module Development


Available Documentation

The AdapterDevelopmentdocumentation isavailable viahttp://help.sap.com

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

http://help.sap.com/





Agenda


Create the Adapter Module EJB

Steps in the SAP NetWeaver Developer Studio1. 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 andcom.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)


Overview of Usable Libraries

For the module development you have to extract following librariesfrom 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


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() {

}


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.


Code Sample: Adding an AdditionalAttachment

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;

}


The ejb-jar.xml

<?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"version="2.1" xsi:schemaLocation="http://java.sun.com/xml/ns/j2eehttp://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">

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

The ejb-jar.xml file can be generated with the NW Developer Studio.

Replace thegenerated 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 theAdapter Module Development Kit. You find them in the library com.sap.aii.af.lib.mod.jar

http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd%22


The ejb-j2ee-engine.xml

<?xml version="1.0" encoding="UTF-8"?><ejb-j2ee-engine

xmlns:xsi=http://www.w3.org/2001/XMLSchema-instancexsi: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>

Configuration tool in the NW Developer Studio can be used to generatethis file.

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

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.





Agenda


Files in the SDA/EAR

Besides the JAR file with the Adapter Module classes and the ebjdescriptors, there are following files with path META-INF

MANIFEST.MFContains the version numbers and the provider names.

SAP_MANIFEST.MFContains version numbers, content, and component names,similar to a catalog. The SDM uses this information to managethe deployment information in its database.

application.xmlContains display names and references to icons if the adapteris displayed with SAP J2EE tools.

application-j2ee-engine.xmlContains 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 adaptermodule.


Create the Enterprise Application Archive

Steps in the SAP NetWeaver Developer Studio1. 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.


The application-j2ee-engine.xml

sap.comlibraryhardcom.sap.base.technology.facade

sap.comlibraryhardcom.sap.aii.af.lib.facade

Providername

Referencetarget-type

Referencetype

Reference target

sap.cominterfacehardcom.sap.aii.af.ifc.facade

sap.comservicehardcom.sap.aii.af.svc.facade

sap.comlibraryhardengine.j2ee14.facade

sap.comservicehardengine.security.facade

In this file you have to create following references


Deploying SAP PI Adapter Components

SAP recommends to useSAP Java Support PackageManager (JSPM) fordeployment.Software Delivery Archives(SDA) can contain softwarecomponents of differenttypes (e.g. applications,libraries).Detailed version informationand dependencies to othercomponents simplifyprogram management.You can create SDA fileswith the CompositionEnvironment CommandLine Tool (CECLT), whichis part of the SAP NWDeveloper Studioinstallation.


Deploy the EAR File Using NW DeveloperStudioUsed mainly for testing purposes


Check Deployment Using SAP NetWeaverAdministrator

Check, if the EJB isdeployed and active

Open the SAP NetWeaver Administrator.

Select Configuration Management -> Infrastructure -> Application Modules

Search your module by name.


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 changedwithout 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 orregistered 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 registeredtrademarks 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. Datacontained 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 writtenpermission 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, andfunctionalities 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 issubject 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 containedwithin 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 aparticular 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 limitationshall 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 thesematerials and does not endorse your use of third-party Web pages nor provide any warranty whatsoever relating to third-party Web pages.

developing user enhancement modules in the adapter engine · (java se) partner connectivity...

Documents