6-5-SP1 SAP Adapter Users Guide

webMethods SAP Adapter
Users Guide
VERSION 6.5 SERVICE PACK 1
webMethods, Inc. South Tower 3877 Fairfax Ridge Road Fairfax, VA 22030 USA 703.460.2500 http://www.webmethods.com
webMethodsAccess,webMethodsAdministrator,webMethodsBroker,webMethodsDashboard,webMethodsDeveloper,webMethodsFabric,webMethods Glue,webMethodsInstaller,webMethodsIntegrationServer,webMethodsMainframe,webMethodsManager,webMethodsModeler,webMethodsMonitor, webMethodsOptimize,webMethodsPortal,webMethodsServicenet,webMethodsTradingNetworks,andwebMethodsWorkflowaretrademarksof webMethods,Inc.webMethodsandthewebMethodslogoareregisteredtrademarksofwebMethods,Inc. AcrobatandAdobeareregisteredtrademarks,andReaderisatrademarkofAdobeSystemsIncorporated.Amdocsisaregisteredtrademark,andClarifyCRM isatrademarkofAmdocs.AribaisaregisteredtrademarkofAriba,Inc.BEA,BEAWebLogicServer,Jolt,andTuxedoareregisteredtrademarks,andBEA WebLogicPlatformisatrademarkofBEASystems,Inc.ActionRequestSystem,BMCSoftware,PATROL,andRemedyareregisteredtrademarksofBMC Software,Inc.BroadVisionisaregisteredtrademarkofBroadVision,Inc.ChemeStandardsandCIDXaretrademarksofChemicalIndustryDataExchange. UnicenterisaregisteredtrademarkofComputerAssociatesInternational,Inc.PopChartisaregisteredtrademarkofCORDATechnologies,Inc.Kenanand ArborareregisteredtrademarksofCSGSystems,Inc.DataConnectionandSNAPIXareregisteredtrademarksofDataConnectionCorporation.DataDirect, DataDirectConnect,andSequeLinkareregisteredtrademarksofDataDirectTechnologies.D&BandDUNSareregisteredtrademarksofDun&Bradstreet Corporation.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregisteredtrademarkoftheEuropeanUnionandtheUnitedStates.Financial InformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCand TransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PARISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isa registeredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,DB2,Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,OS/400, RACF,RS/6000,SQL/400,S/390,System/390,VTAM,z/OS,andWebSphereareregisteredtrademarks;andCommunicationsSystemforWindowsNT,DB2 UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBMCorporation.InnoDBisatrademarkofInnobaseOy.Itaniumisaregisteredtrademarkof IntelCorporation.JBossisaregisteredtrademark,andJBossGroupisatrademarkofJboss,Inc.LinuxisaregisteredtrademarkofLinusTorvalds.W3Cisa registeredtrademark,andXWindowSystemisatrademarkoftheMassachusettsInstituteofTechnology.MetaSolvisaregisteredtrademarkofMetasolv Software,Inc.ActiveX,Microsoft,Outlook,VisualBasic,Windows,andWindowsNTareregisteredtrademarks;andWindowsServerisatrademarkof MicrosoftCorporation.SixSigmaisaregisteredtrademarkofMotorola,Inc.Firefoxisaregisteredtrademark,andMozillaisatrademarkoftheMozilla Foundation.MySQLisaregisteredtrademarkofMySQLAB.nCipherisatrademarkofnCipherCorporationLtd.TeradataisaregisteredtrademarkofNCR International,Inc.NetscapeisaregisteredtrademarkofNetscapeCommunicationsCorporation.ServletExecisaregisteredtrademark,andNewAtlantaisa trademarkofNewAtlantaCommunications,LLC.SUSEisaregisteredtrademarkofNovell,Inc.AppiaisaregisteredtrademarkandJavelinTechnologiesis atrademarkofNYFIX,Inc.CORBAisaregisteredtrademarkofObjectManagementGroup,Inc.JDEdwards,OneWorld,Oracle,PeopleSoft,Siebel,and Vantiveareregisteredtrademarks,andPeopleSoftPureInternetArchitectureandWorldSoftwarearetrademarksofOracleCorporation.InfranetandPortal aretrademarksofPortalSoftware,Inc.RedHatisaregisteredtrademarkofRedHat,Inc.PIPandRosettaNetaretrademarksofRosettaNet,anonprofit organization.SAPandR/3areregisteredtrademarksofSAPAG.SWIFTandSWIFTNetareregisteredtrademarksofSocietyforWorldwideInterbank FinancialTelecommunicationSCRL.SPARCandSPARCStationareregisteredtrademarksofSPARCInternational,Inc.SSAisaregisteredtrademark,and BaanandSSAGlobalaretrademarksofSSAGlobalTechnologies,Inc.EJB,EnterpriseJavaBeans,Java,JavaServer,JDBC,JSP,J2EE,Solaris,Sun,andSun Microsystemsareregisteredtrademarks;andJavaNamingandDirectoryInterface,SOAPwithAttachmentsAPIforJava,JavaServerPages,andSunSoftare trademarksofSunMicrosystems,Inc.SybaseisaregisteredtrademarkofSybase,Inc.VERITASisaregisteredtrademark,andVERITASClusterServerisa trademarkofSymantecCorporation.UNIXisaregisteredtrademarkofTheOpenGroup.UnicodeisatrademarkofUnicode,Inc.VeriSignisaregistered trademarkofVerisign,Inc. Allothermarksarethepropertyoftheirrespectiveowners. Copyright2006bywebMethods,Inc.Allrightsreserved,includingtherightofreproductioninwholeorinpartinanyform. Document ID: ADAPTER-SAP-UG-65SP1-20061006
Contents
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAP System Screens and Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
13 14 15 15
Chapter 1. About the webMethods SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What Is the webMethods SAP Adapter? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functional Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Complete SAP System Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integrating SAP Systems Over the Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing IDocs, RFCs and BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for IDoc- and RFC-XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support of BizTalk XML Envelopes for BAPI and RFC Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . Support of Unified Error Handling of BAPIs and RFCs on the XML Level . . . . . . . . . . . . . . . . . Built-in BAPI Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Maintaining Transaction Status Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Centralized Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking Business Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending Messages Through the Routing Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run-Time Behavior of Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-In Services For Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Connection Associated with an Adapter Service at Design Time . . . . . . . . . . . . . Changing the Connection Associated with an Adapter Service at Run Time . . . . . . . . . . . . . . . Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter Listeners and Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods Manager Support for the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Adapters Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
18 19 19 20 20 21 21 21 22 22 22 22 23 23 25 26 28 28 29 29 29 30 30 30 31 31 31 32 32
webMethods SAP Adapter Users Guide Version 6.5 SP1
Contents
Chapter 2. System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Questions on Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Minimum Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Questions on Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initial Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Consumption Per Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Consumption for RFC Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDoc Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 34 34 34 35 35 36 37 37 37 37 38 38 39 40 40 40 40
Chapter 3. Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing the Adapter Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Package Dependency Requirements and Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading, Reloading, and Unloading Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reloading Packages Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unloading Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing and Exporting Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is webMethods Integration Server Clustering? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Clustering for the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Outbound RFCs Are Balanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Inbound RFCs Are Balanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Replicating Packages to webMethods Integration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling the Redirection of Administrative Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clustering Considerations and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Each Integration Server in a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 42 43 44 45 45 45 45 46 46 47 47 47 48 49 49 49 50 51 51
Considerations When Installing SAP Adapter Packages . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Considerations When Configuring Connections with Connection Pooling Enabled . . . . . . 53 Considerations about SAP Adapter Centralized Transaction Store . . . . . . . . . . . . . . . . . . 53
Chapter 4. Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up the SAP System for SNC Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamically Changing a Services Connection at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Execution of an RFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Execution of an RFC-XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Execution of a BAPI Via XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting to Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a List of Business Objects in the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a Business Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a BAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a BAPI Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a Key Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating XML Calls for a BAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting a BAPI from an HTTP client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
55
56 56 56 62 62 63 64 64 65 66 66 67 67 68 68 68 69 69 70 71 71 72
Chapter 5. Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Adapter Service that Executes an RFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an RFC Adapter Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the RFC Adapter Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting an RFC-XML Document from an HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
74 74 75 75 76 77
Chapter 6. Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of a Listener Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitor IDocs Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forward Confirm Event Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
79
80 80 81 81
Contents
Action Equals 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action Equals 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an RFC Destination on an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before you Configure New Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring an RFC Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the RFC Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Listener Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before You Configure Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependencies for Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RFC Listener Notification (Synchronous) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALE Listener Notification (Synchronous) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Synchronous Listener Notification Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RFC Listener Notification (Asynchronous) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALE Listener Notification (Asynchronous) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Synchronous RFC Adapter Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Function Module in an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an RFC Adapter Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Product Retrieval Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Synchronous ALE Listener Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create an Empty Flow Service Called mapOrders02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create an Asynchronous ALE Listener Notification for IDoc Type Orders02 . . . . . . . . . . . Define the Input and Output Signatures for the mapOrders02 Service . . . . . . . . . . . . . . . . Map Fields from Orders02RequestDocument to PurchaseOrder Document . . . . . . . . . . .
82 83 84 87 87 87 91 92 93 94 95 96 96 97 97 97 98 99 99 101 103 103 105 106 106 107 107 108 109 109 110 110 110 111 113 114 115 115 116 116
Testing the Listener Notification from the SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Setting Up the SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Chapter 7. Generating Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Generating Document Types for RFC Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Document Types for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create an IDoc Document Type Using the DDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating an IDoc Document Type from a DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Document Type from a Sample IDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 122 122 123 124
Chapter 8. Routing Messages Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . 127

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Components of a Routing Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sender, Receiver, and Message Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forward Confirm Event Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing Notification Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Routing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Wildcards as Routing Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing the Message (Transport) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring a Routing Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALE Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RFC Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAPI Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Routing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Routing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a Routing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending an RFC from an SAP System to the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The SBCHEADER Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Using an SBCHEADER Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a BAPI from an SAP System to the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up a Routing Notification for the XML Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Routing Using the XML Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending IDocs with ALE from an SAP System to an SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing RFCs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting RFC Based IFR-compatible XML Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 129 130 130 131 132 132 132 132 134 134 134 135 136 136 137 138 139 139 140 140 140 143 146 146 146 147 149 149 149
Contents
RFC Based XML Messages Using IFR Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting RFCs via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting RFCs in an E-mail Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing BAPIs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up a Routing Notification and the BAPI Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting BAPI-based XML IFR-Compatible XML Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAPI XML Transaction Commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronous Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Asynchronous Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing IDocs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting an IDoc-XML Document from an HTTP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting an IDoc via FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting an IDoc in an E-mail Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Posting an IDoc from a Web Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transmitting IDocs between Two Integration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping IDocs to Other Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Empty Flow Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Routing Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Document Type for Your IDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transforming the IDoc to a Hierarchical Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping IDoc Information to Pipeline Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Mapping Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content-Based Routing and Mapping for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Routing Arbitrary XML Documents Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
150 150 150 150 150 151 152 152 153 153 154 155 157 157 158 158 158 159 159 160 160 160 161 161 163 164 166
Chapter 9. Transaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Managing Transactions and the Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automatic Cleanup of the Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuration Parameters for the Transaction Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the ALE Monitoring Features Via the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDoc Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prepare the SAP Adapter for IDoc Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Update Via ALEAUD IDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 170 172 173 174 174 175 176 176 176 177 177
Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Further Setup in the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Update Via SYSTAT IDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setup the participating SAP Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prepare the Integration Server for Automatic SYSTAT IDoc . . . . . . . . . . . . . . . . . . . . . . . . Centralized Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring a Centralized Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Centralized Store Configuration and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing the Configuration of a Centralized Transaction Store . . . . . . . . . . . . . . . . . . . . . . . .
177 178 179 179 179 180 181 182 185 186
Chapter 10. Logging and Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing and Deleting RFC Trace Files and SAP Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring SAP Adapter Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Output Information in the SAP Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Response Time Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 188 189 189 189
Chapter 11. Coding Client Applications and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking RFCs from the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling Public SAP Adapter Services from Java Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving IDocs from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing and Modifying Fields in IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting an IDoc to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructing an IDoc with the SAP Java IDoc Class Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending IDocs to an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Features for HTTP and SAP-XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: HTTP POST of an IDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling a BAPI Synchronously from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling a BAPI Asynchronously from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 192 192 193 193 194 194 196 196 197 197 201
Chapter 12. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

SAP Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Authentication Between the SAP Adapter and an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . Authentication Through User Name and Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication Through X.509 Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication When the SAP Adapter Acts As an RFC-Server . . . . . . . . . . . . . . . . . . . . . . . . . Using the SAP Adapter with the SAP Cryptographic Library for SNC . . . . . . . . . . . . . . . . . . . . . Installing the SAP Adapter According to Your Security Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 208 208 208 210 211 213
Contents
Chapter 13. Managing the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Data DICtionary Cache (DDIC Cache) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Information in the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Information from the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing the DDIC Cache for an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing Elements from the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 217 218 218 219
Appendix A. Package Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Package Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Appendix B. Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

General SAP Adapter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 server.cnf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Appendix C. ABAP Types in the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

ABAP Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Appendix D. Built-in Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

SAP Client Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XRFC Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDoc Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IDoc-XML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bXML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAPI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Administration Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transport Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAP Listener Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . webMethods SAP Adapter IDoc Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 245 248 254 256 257 259 261 266 276 280 283 284
Appendix E. Deprecated Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

List of Deprecated Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Appendix F. Working with Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Using Different Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . To Receive Data from HTTP, FTP, E-mail or File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . To Send Data Via HTTP, FTP, E-mail or Save It to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . To Encode Data from SAP Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 288 288 288
10
Appendix G. Using BizTalk Envelopes with the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . 291

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of the BizTalk Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction to Standard BizTalk Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Representation of Routing and Address Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Representation of SAP Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Further BizTalk Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Representation of Communication and Processing Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Representation of Application Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 292 292 294 295 296 296 297 298
Appendix H. Using IFR-XML Format with the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . 299

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of XML Envelopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Structure of Request and Response Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Way of Representing Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Error Handling Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Format for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Request Business Documents for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Response Business Documents for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Exception Business Documents for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exception Document for Return Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exception Document for Return Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Format for RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Request Business Documents for RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Response Business Documents for RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of Exception Business Documents for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Format for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Format for Manually Defined IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 300 301 302 302 303 304 304 305 306 307 309 309 310 311 312 312
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
11
Contents
12
About This Guide
About This Guide

ThisguidedescribeshowtoconfigureanddevelopapplicationsforthewebMethodsSAP Adapter.Itcontainsinformationforadministratorswhomanagethesystem,andfor applicationdeveloperswhocreateapplicationsthatusethesystem. Tousethisguideeffectively,youshould: UnderstandthebasicconceptsoftheSAPAdapterandXML. HaveageneralideaabouthowtoperformbasictaskswiththeDeveloper. Knowhowtocreateflowservicesand/orJavaservices. BefamiliarwiththesetupandoperationofthewebMethodsIntegrationServer.
Related Documentation
Thefollowingdocumentsarecompanionstothisguide.SomedocumentsareinPDF formatandothersareinHTML. Refer to this book... webMethods IntegrationServer AdministratorsGuide For... InformationaboutusingtheServerAdministratorto configure,monitor,andcontrolthewebMethodsIntegration Server.Thisbookisforserveradministrators. Youwillfindthisbookat: webMethods_directory\IntegrationServer\doc\Integration ServerAdminGuide.pdf webMethodsDeveloper UsersGuide Informationaboutcreatingandtestingservicesandclient applications.Thisbookisforapplicationdevelopers. Youwillfindthisbookat: webMethods_directory\Developer\doc\DeveloperUsers Guide.pdf webMethodsDeveloper OnlineReference InformationaboutthecontrolsintheDeveloperapplication windowsandstepbystepproceduresdescribinghowto performtaskswiththeDeveloper. YoucanaccesstheonlinereferencebyclickingHelpinan applicationwindowordialogbox.
13
Refer to this book... webMethodsBuiltIn ServicesReference Guide
For... Thisguidedescribesthebuiltinservicesprovidedwitha standardinstallationofIntegrationServerandlocatedinthe WmPublicpackage. Youwillfindthisdocumentat: webMethods_directory\Developer\doc\IntegrationServerBISRe ference.pdf
SerializationofABAP datainXML
IndepthinformationabouthowABAPdataisserializedin XMLmessages.ThisserializationisusedforRFCandBAPI parameters. Youwillfindthisinformationat: http://ifr.sap.com/home/Documents/ABAP_Serialization.htm
XMLFormat Specifications
IndepthinformationabouthowRFCs,BAPIsandIDocsare formattedinXML. Youwillfindthisguideat: http://ifr.sap.com/home/Documents/XML_index_E.htm
webMethodsSAP AdapterIDocJavaAPI Documentation
IndepthinformationaboutthewebMethodsSAPAdapter implementationoftheSAPJavaIDocClassLibrary. Youwillfindthisguideat: webMethods_directory\Integration Server\packages\WmSAP\pub\doc\api\index.html
Document Conventions
Convention Bold Italic Description Identifieselementsonascreen. Identifiesvariableinformationthatyoumustsupplyorchangebased onyourspecificsituationorenvironment.Identifiestermsthefirst timetheyaredefinedintext.Alsoidentifiesserviceinputandoutput variables. IdentifiesstoragelocationsforservicesonthewebMethodsIntegration Serverusingtheconventionfolder.subfolder:service. Identifiescharactersandvaluesthatyoumusttypeexactlyor messagesthatthesystemdisplaysontheconsole.
Narrow font
Typewriter font
14
SAP System Screens and Procedures
Convention UPPERCASE \ []
Description Identifieskeyboardkeys.Keysthatyoumustpresssimultaneouslyare joinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.
SAP System Screens and Procedures

ThisguidecontainssomeSAPGuiimagesandprocedures.Dependingontheversionof yourSAPsystemandtheplatformonwhichitisrun,youractualscreenscanappear slightlydifferentlythantheonesdescribedinthisguide.Asaresult,someSAPsystem procedurescanalsodifferfromwhatisdescribedinthisguide.
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyou withimportantsourcesofinformationaboutthewebMethodsIntegrationPlatform: Troubleshooting Information.webMethodsprovidestroubleshootinginformationfor manywebMethodscomponentsinthewebMethodsKnowledgeBase. Documentation Feedback.ToprovidedocumentationfeedbacktowebMethods,gotothe DocumentationFeedbackFormonthewebMethodsBookshelf. Additional Documentation.AllwebMethodsdocumentationisavailableonthe webMethodsBookshelf.
15
16
CHAPTER
About the webMethods SAP Adapter

What Is the webMethods SAP Adapter? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Functional Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Architecture and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Adapter Listeners and Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 webMethods Manager Support for the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Viewing the Adapters Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
17
CHAPTER 1 About the webMethods SAP Adapter
What Is the webMethods SAP Adapter?

ThewebMethodsSAPAdapterallowsyoutoextendyourSAPbusinessprocessesand integratenonSAPproductsusingopenandnonproprietarytechnology.TheSAP Adapterallowsforbothasynchronousandbidirectional,realtimecommunicationto andfromtheSAPsystem.Youcan: Execute SAPs implementation-independent Business Application Programming Interface (BAPI) methods,astheyaredescribedintheBusinessObjectRepository(BOR).BAPIsare stable,preciselydefined,andwelldocumentedinterfacestoSAPsolutions,providing standardizedaccesstoSAPsolutionsonasemanticlevel.Youcanquicklyandeasily createXMLbasedservicesthatexecuteaBAPI.Applicationswithinyour organizationcantheninvoketheservicestoexecuteaBAPIontheSAPsystem. Similarly,yourbusinesspartnerscanmakerequestsovertheInternettoinvokea servicethatexecutesaBAPI.TheBAPIinterfacesprovideaunifiedaccesstothe applicationlevelfunctionality,independentofthetypeofcall:Bothsynchronousand asynchronousprocessingcanbetriggeredbyusingtheseinterfaces. AsynchronousprocessingtransparentlyusestheApplicationLinkEnabling(ALE) servicesinsidetheSAPsystemfortheclienttointegratethebusinessprocesses. Execute SAP Remote Function Calls (RFCs) from the SAP Adapter.YoucanaccessallSAP functionalitythatisavailableviaRFCfromtheSAPAdapter.Externalapplicationsdo notneedtounderstandSAPdatatypes,ABAPstructuresortheRFCprotocolto communicatewithanSAPsystem. Send IDocs to the SAP Adapter.YoucansendIntermediateDocumentstotheSAP Adapterforfurthersynchronousprocessingorletthembepublishedtosubscribers asynchronously. Call services from SAP systems. YoucaninvokeservicesfromanSAPsystem.This allowstheSAPuserstoaccessinformationthatisavailableviatheSAPAdapter.The SAPAdapterenablesintegrationbetweentradingpartners,therebyextendingthe reachofyourSAPinfrastructuretocustomers,partners,andsuppliers. Route SAP business documents based on criteria you specify.TheSAPAdapterprovides richroutingcapabilitiesforBAPIs,RFCs,andIDocs.Therearedifferenttransport typesavailableoutofthebox.Theseincludetheroutingofabusinessdocumentto anotherSAPsystemorsimplytoaremoteURLinanXMLformat.
18
Functional Highlights
TheSAPAdapterallowsyoutoincreasecustomerloyaltyandefficiencyacrossthesupply chainbytightlyintegratingyourbusinessinfrastructurewiththatofanypartner.Typical deploymentscenariosfortheSAPAdapterare: RealtimeintegrationbetweensupplierinventoriesandyourSAPsystem Realtimeintegrationbetweenproduct,price,andavailabilityinformationfromany numberofsuppliersandyourpurchasingapplication Realtimeintegrationbetweenfulfillmentandordertrackingapplicationsandyour shippersinternalsystems
SynchronousandAsynchronousCommunicationwithSAPsystemsviaRFCand tRFC BidirectionalcommunicationtoandfromSAPsystems HigherlevelservicestoprocessSAPIDocsandBAPIs EasyXMLandInternetenablingofexistingSAPreleases SupportofBizTalkXMLenvelopesforBAPIandRFCcalls SupportofunifiederrorhandlingofBAPIsandRFCsonXMLlevel
Complete SAP System Integration

TheSAPAdapterincorporatesafullfledgedRFCClientandServer.Theseprovidereal timebidirectional(outboundandinbound)communicationtoandfromtheSAPsystem. FromanSAPapplicationpointofview,callingtheSAPAdapterisnodifferentfrom callinganyotherRFCserver.TheSAPproprietaryRFCformatisconvertedtoXMLso thatnoSAPsoftwareisneededontheotherendofthecommunicationline. TheSAPAdaptertransparentlysupportsbothsynchronous(RFC)andasynchronous (tRFC)callsfromSAPsystems.Thus,BAPIsandALEscenariosaresupported. Asaspecialservice,SAPIDocscanbeconvertedtoastructuredobjectwithdirectaccess toeachsinglefield.ThisallowsyoutomodifyanIDocscontentsonthefly.Forexample,if youwanttocustomizeincomingIDocsbasedonlocaldataformat,youcandoso.Youcan alsoaccessexistingBAPIsinSAPsystemsfromabrowserorclientapplication,oryoucan sendXMLdocumentstotheSAPsystem.DevelopingapplicationswiththeSAPAdapter requiresnoknowledgeofSAPdatastructures,significantlyreducingdeploymenttime andcost.
19
Integrating SAP Systems Over the Internet

Mostintegrationscenariosdescribetwosystemscommunicatingwitheachothersecurely overtheInternet,despiteexistingfirewallrestrictions.TheSAPAdapterleveragesHTTP toseamlesslyexchangedatabetweentwoormoreSAPsystemsacrosstheInternet, withoutrequiringchangestotheexistingsecurityinfrastructure. Inaddition,theSAPAdaptertransparentlymanagescommunicationbetweendifferent SAPsystemversions.
Routing IDocs, RFCs and BAPIs

TheSAPAdapterprovidesrichroutingcapabilitiesforsynchronousRFCs,asynchronous IDocs,andBAPIs,givingyoubettercontrolofyourtradingrelationships.Withinminutes, youcanconfiguretheSAPAdaptertosendanIDoctoanotherSAPsystemortoaremote URLinanXMLformat. BAPIsprovideasimplewaytoaccessSAPsolutions.Theycanhandlebothsynchronous andasynchronouscallstoanSAPsystemusingthesameXMLmessageformat. AsynchronousBAPIcallsareprovidedbyusingtheALEservicesinsidetheSAPsystem; youcanleverageALEmechanismswithouthavingtodealwiththesometimescomplex IDocformat.ThisworksforallIDocsthataregeneratedfromBAPIs. InsidetheSAPsystem,administratorscanusethefullbandwidthofservicesprovidedby ALE,including: Performancebenefitsthroughasynchronousprocessing Monitoringservices Distributionservices BAPIinterfacesaredevelopedaccordingtostrictdevelopmentguidelines,sotheyare: welldefined stable implementationindependent welldocumented
20
TheSAPInterfaceRepositoryprovidespublicwebbasedaccesstothecollectionofBAPI interfacesprovidedbySAPandtothecorrespondingdocumentation. Inshort,theuseofBAPIsleadstothefollowingadvantages: SAPsolutionsareaccessedonastandardized,implementationindependentlevel. ImplementationontheSAPsystemcanthereforebeexchangedwithoutinvalidating the(BAPI)interfaceusedbyclients. AbusinessmanagementfunctionwhichisimplementedasaBAPIcanbecalledboth synchronouslyandasynchronouslybyusingthesameXMLmessage.
Support for IDoc- and RFC-XML

TheSAPAdapteristhedefactoXMLinterfacetoexistingSAPsystemsreleases.It supportsallversionsofIDocandRFCXML(XRFC),asspecifiedbytheSAPXML Specification.WiththeSAPAdapterSAPXMLinterface,youcaninvokeRFCsviaXML andconvertIDocstotheSAPXMLformat. Note: ThecurrentversionofRFCXMLiscalledXRFC.
Support of BizTalk XML Envelopes for BAPI and RFC Calls

Bydefault,theSAPAdapterwillusethestandardizedBizTalkXMLenvelopeformatfor theseXMLmessages.ThissimplifiesdataexchangewithotherWebmessagingsystems. TheBizTalkXMLenvelopedifferentiatesbetweenanapplicationspecificXMLbodyand anXMLheader,whichisusedtoexchangetransportspecificinformation,forexamplefor routingpurposes.TheBizTalkXMLenvelopecanbeusedwithbothBAPIandRFCXML callsandalsoforbothsynchronousandasynchronousprocessing.SeeAppendix G, UsingBizTalkEnvelopeswiththeSAPAdapterformoreinformation.
Support of Unified Error Handling of BAPIs and RFCs on the XML Level
Toallowgenericerrorevaluationsontheclient,regardlessoftheinterfacetype(BAPI, RFC)used,thebXMLformatunifiestheerrorhandlingofBAPIsandRFCs.Inthisway, interfacetypespecificerrorhandlingconcepts(BAPIreturnparameterandfunction moduleexceptions)areconvertedonanXMLlevelintoastandardizedtypeoferror representation.
21
Built-in BAPI Tools

AsetoftoolstosimplifythehandlingofBAPIcallshasbeenintegratedintotheSAP Adapter. Foreasyidentificationoftherelevantapplicationinterfaces,theSAPAdapterincludesa builtinBAPIBrowser.Thisbrowserprovidesaccesstotheinterfacedataforeach businessobjectanditsBAPIsandalsoservesasasearchtooltotheSAPinterfaceworld. WiththebuiltinBAPIbrowser,youcanquicklyidentifythenecessaryinformationtoset uparoutingnotificationforBAPIs. ServicestosimplifythehandlingofBAPItransactioncontrolhavealsobeenaddedtothe SAPAdapter.
Maintaining Transaction Status Information

Thetransactionsstatusinformationcanbestoredlocallyorinacentralizedrepository. ThetransactionstatusinformationstoredlocallywillbeaccessedonlybythatSAP Adapteronwhichthetransactionisexecuted.Thetransactionstatusinformationstoredin acentralrepositorywillbeaccessedbyalltheSAPAdaptersthataregrouped.Thetwo typesofstoringthetransactionstatusinformationare: TransactionStore CentralizedTransactionStore
Transaction Store
TheTransactionStoreisusedtostorethetransactionstatusinformationlocally.TheSAP Adapterprovidesapersistenttransactionstorethatthetransactionmanagerusestotrack allIDocsandalltRFCcallsroutedtoandfromSAPsystemsviathewebMethods IntegrationServer.Formoreinformation,seeManagingTransactionsandthe TransactionStoreonpage 170.
Centralized Transaction Store

TheCentralizedTransactionStore(CTS)isagroupofSAPAdaptersthatbelonglogically together,thatshareasingleCentralizedTransactionStore.TheCTSisusedtostoreallthe processedtransactionsinacentralrepository,sothatthetransactionstatusinformation willalwaysbesynchronizedandvalid.TheCTSallowsreliabletRFC/IDocloadbalancing. TherecanalwaysbejustoneCTSperadaptergroup,nottwoormore.AllSAPAdapters thatareconfiguredtoshareaspecificCTSareconsideredtobeinthesamegroup.You havetoconfiguretheRemoteServerwithaliasSAPGroupStoreforeachSAPAdapterof youradaptergroup(andinexactlythesameway).Formoreinformation,see ConsiderationsaboutSAPAdapterCentralizedTransactionStoreonpage 53and CentralizedTransactionStoreonpage 181.
22
Architecture and Components

Basic Concepts
TousetheSAPAdaptersuccessfully,youshouldunderstandthefollowingtermsand concepts: Term BAPI Description BusinessfunctionsinanSAPsystemthatarewritteninthe programminglanguageABAP.BAPIsareformalizedRFCs. SystemsremotefromtheSAPsystemcommonlyuseBAPIs tohavetheSAPsystemperformanaction. SAPterminologyforaprocessthatcanacceptRemote FunctionCalls(RFCs)fromSAPsystems.ThisallowsSAP systemstoaccessfunctionsonexternalsystems.InSAP Adapterterminology,thisisalistener. ListenersareoneormorethreadsontheSAPAdapterthat waitforincomingrequestsfromSAPsystems.Listenersare namedandregisteredwithanSAPgatewaytoindicatethat theyarereadytoacceptrequests.ListenerscanacceptRFC ortRFCrequests. RFC Client tRFC (Transactional RFC) SAPterminologyforaprocessthatsendsRFCstoanSAP systemtoinvokefunctions. ProtocolforensuringthatanRFCissuccessfullyexecuted andexecutedexactlyonceonthetargetsystem.TheSAP AdaptercanhandlebothinboundandoutboundtRFCs. Communicationsmethodthat: AnSAPsystemusestoasynchronouslyinvokea functiononaremotesystem. Aremotesystemusestoasynchronouslyinvokea functionontheSAPsystem. ThetransactionalRFC(tRFC)protocolensuresthatanRFC issuccessfullyexecutedandthatitisexecutedexactlyonce. TID TransactionID.AgloballyuniqueidentifierusedbytRFC toensureexactlyoneexecution.Canbeupto24 alphanumericcharactersinlength. RequeststhattheSAPsysteminitiatestohavefunctions performedonremotesystems,orcallsremotesystems initiatetohavetheSAPsystemperformafunction.
RFC Server (Listener)
tRFC protocol
RFC
23
Term RFC protocol
Description CommunicationsmethodthattheSAPsystemusesto synchronouslyandasynchronouslyinvokeafunctionona remotesystem,andaremotesystemusestosynchronously andasynchronouslyinvokeafunctionontheSAPsystem. IntegrationServerfunctionsthatarenamedwitha hierarchicalfolder/servicesyntax.Servicescanbeflow, Java,orC/C++developedbyyou,thirdpartyvendors,or webMethods. CodelibraryprovidedbySAPallowingthirdpartiesto integratetheRFCprotocolintoapplications.Thisishow theSAPAdaptercommunicateswiththeSAPsystem. EDIlikeSAPbusinessdocument. Aprocessthatacceptsmessagesandroutesthemtoa configuredlocation,forexample,messagescanberouted toanSAPsystem,anotherIntegrationServer,oraremote URLinanXMLformat. Note: Ifyouneedtousearoutinglistener,youdonotneed tocreateone.TheSAPAdapterincludesapreconfigured routinglistenercalledwm.sap.internal.ls:routingListener. Formoreinformationabouttheroutinglistener,see Overviewonpage 129.
Service
LIBRFC
IDoc (Intermediate Document) Routing Listener
Transaction Store Centralized Transaction Store
ArepositorythattheSAPAdapterusestotrackall transactionsthatpassthroughtheSAPAdapter. AcentralizedrepositorythattheSAPAdapterusestotrack alltransactionsthatpassthroughalltheadaptersofaSAP Adaptergroup.
24
ThefollowingillustratesthecomponentsinasystemthatusestheSAPAdapter:
Invoking Business Logic

TheSAPAdapterincorporatesanRFCServerandRFCClienttoproviderealtime inboundandoutboundcommunicationtoandfromtheSAPsystem. TheSAPAdapterusestheRFCClienttosendrequeststoexecuteRFCsontheSAP system.
25
Outbound Requests mapped to an Adapter Service
TheSAPAdapterusestheRFCServer(Listener)tolistenforincomingrequeststoexecute servicesontheIntegrationServer.FromanSAPsystempointofview,callingtheSAP AdapterisnodifferentfromcallinganyotherRFCserver.

Inbound Requests mapped to an Adapter Notification
Sending Messages Through the Routing Listener

WhentheSAPAdapterreceivesarequestontheRFCServer(Listener)thatisnot associatedwithaspecificadapternotification,theSAPAdaptersendstherequesttothe routinglistener.Theroutinglistenercanreceive: IDoccallsfromanSAPsystemorIDocXMLmessagesfromanywebclient RFCsfromanSAPsystemorRFCXMLandbXMLmessagesfromanywebclient
26
Inbound Requests into the Routing Listener
Itthenusesroutingnotificationstodeterminewheretoroutethemessages.Therouting notificationindicateswheretoroutethemessagebasedonwhothemessageisfrom (sender),whoistoreceivethemessage(receiver),andthemessagetype. Amessagecanbe: RoutedtoanSAPsystem(IDocs,RFCsandBAPIs) Routedtoaserviceonthelocalmachineoraremotemachine HTTPpostedtoanURL

Outbound Transports Called from a Routing Notification
27
Note: AnSAPAdapterinboundcallisanoutboundcallfromtheSAPsystemspointof view.
Adapter Package Management

TheSAPAdapterisprovidedasapackagecalledWmSAPthatyoumanagelikeany packageontheIntegrationServer. Thereareseveralconsiderationsregardinghowyousetupandeffectivelymanageyour packagesontheIntegrationServer,suchasthosedescribedinthefollowinglist. Configureuserdefinedpackagesforyouradapterconnectionsandadapterservices. SeeManagingtheAdapterPackageonpage 42fordetails. Understandhowpackagedependenciesworksoyoumakethebestdecisions regardinghowyoumanageyouradapterservices.SeePackageDependency RequirementsandGuidelinesonpage 43fordetails. Controlwhichdevelopmentgroupshaveaccesstowhichadapterservices.See ControllingGroupAccessonpage 46fordetails. Understandhowclustering,anadvancedfeatureofthewebMethodsIntegration Server,workstoeffectivelymanageyouradapterservices.SeeUsingtheAdapterin aClusteredEnvironmentonpage 47fordetails. Enableanddisablepackages.SeeEnablingandDisablingPackagesonpage 44for details. Load,reload,andunloadpackages.SeeLoading,Reloading,andUnloading Packagesonpage 45.
Adapter Connections
AnadapterconnectionenablesanSAPAdapterservicetoconnecttoanSAPsystem. TheadaptersupportsanRFCtypeofadapterconnection.Forinstructionsforconfiguring, viewing,editing,enabling,anddisablingSAPAdapterconnections,seeChapter 4, AdapterConnections.Forinformationaboutsettinguserprivileges,seethewebMethods IntegrationServerAdministratorsGuide. Foralistoftasksthatyoumustdobeforeyoucancreateyourconnections,seeBefore ConfiguringorManagingAdapterConnectionsonpage 56.
28
Adapter Connections
Connection Pools
TheIntegrationServerincludesaconnectionmanagementservicethatdynamically managesconnectionsandconnectionpoolsbasedonconfigurationsettingsthatyou specifyfortheconnection.Bydefault,connectionpoolingisenabledforalladapter connections. Aconnectionpoolisacollectionofconnectionswiththesamesetofattributes.The IntegrationServermaintainsconnectionpoolsinmemory.Connectionpoolsimprove performancebyenablingadapterservicestoreuseopenconnectionsinsteadofopening newconnections.
Run-Time Behavior of Connection Pools

Whenyouenableaconnection,theIntegrationServerinitializestheconnectionpool, creatingthenumberofconnectioninstancesyouspecifiedintheconnectionsMinimum Pool Sizeparameter.Wheneveranadapterserviceneedsaconnection,theIntegrationServer providesaconnectionfromthepool.Ifnoconnectionsareavailableinthepool,andthe maximumpoolsizehasnotbeenreached,theservercreatesoneormorenewconnections (accordingtothenumberspecifiedinPool Increment Size)andaddsthemtotheconnection pool.Ifthepoolisfull(asspecifiedinMaximum Pool Size),therequestingservicewillwait fortheIntegrationServertoobtainaconnection,uptothelengthoftimespecifiedinthe Block Timeoutparameter,untilaconnectionbecomesavailable.Periodically,theIntegration Serverinspectsthepoolandremovesinactiveconnectionsthathaveexceededthe expirationperiodthatyouspecifiedinExpire Timeout. Iftheconnectionpoolinitializationfailsbecauseofanetworkconnectionfailureorsome othertypeofexception,youcanenablethesystemtoretrytheinitializationanynumber oftimes,atspecifiedintervals. Forinformationaboutconfiguringconnections,seeChapter 4,AdapterConnectionson page 55.
Built-In Services For Connections

IntegrationServer6.5providesbuiltinservicesthatenableyoutoprogrammatically controlconnections.Youcanusethemtoenableanddisableaconnection,andtoreturn usagestatisticsandthecurrentstate(EnabledorDisabled)anderrorstatusfora connection.TheseservicesarelocatedintheWmARTpackage,inthepub.art.connection folder. Thebuiltinservicepub.art.services:setAdapterServiceNodeConnectionenablesyoutochangethe connectionassociatedwithanadapterservice.SeeChangingtheConnectionAssociated withanAdapterServiceatDesignTimeonpage 30. Fordetails,seethewebMethodsIntegrationServerBuiltInServicesReference,whichis availablefromtheHelpmenuofthewebMethodsDeveloper.
29
Changing the Connection Associated with an Adapter Service at Design Time

TheIntegrationServerprovidesabuiltinservicethatyoucanuseatdesigntimeto changetheconnectionassociatedwithanadapterservice.Thisbuiltinserviceisnamed pub.art.service:setAdapterServiceNodeConnection.Usingthisservice,youcanchangethespecific connectionassociatedwithanadapterserviceatdesigntimesothatyoudonotneedto recreateadapterservices. Note: Thisbuiltinservicecanberunatdesigntimeonly;donotuseitwithinan IntegrationServerfloworJavaservice.Youmustrunthisservicedirectlyfromthe DeveloperbyselectingtheserviceintheDeveloperandrunningit. Fordetails,seethewebMethodsIntegrationServerBuiltInServicesReference,whichis availablefromtheHelpmenuofthewebMethodsDeveloper. Otherbuiltinservicesenableyoutocontrolconnections;formoreinformation,seeBuilt InServicesForConnectionsonpage 29.
Changing the Connection Associated with an Adapter Service at Run Time

Beginningwithversion6.5,theIntegrationServerenablesyoutodynamicallyselectthe connectionaserviceusestointeractwiththeadaptersresource.Thisfeatureenablesone servicetointeractwithmultiple,similarbackendresources. Forexample,youcanconfigureanadapterservicetouseadefaultconnectionthat interactswithyourcompanysproductionapplicationserver.However,atruntimeyou canoverridethedefaultconnectionandinsteaduseanotherconnectiontointeractwith thecompanystestapplicationserver. Formoreinformationaboutoverridingaservicesdefaultconnectionatruntime,see DynamicallyChangingaServicesConnectionatRunTimeonpage 62.
Adapter Services
Adapterservicesallowyoutoconnecttotheadaptersresource(thatis,anSAPsystem) andinitiateanoperationontheresourcefromtheIntegrationServer.Youcalladapter servicesfromafloworJavaservicetointeractwithfunctionmodulesonanSAPsystem. Atdesigntime,theadapterobtainsinformationabouttheSAPdocumentontheSAP system.YouconfigureadapterservicesusingthetemplatesprovidedwiththeSAP Adapter.Eachtemplaterepresentsaspecifictechniquefordoingworkonaresource,such asinvokingafunctionmoduleonanSAPsystem.Anadapterservicetemplatecontainsall thecodenecessaryforinteractingwiththeresourcebutwithoutthedataspecifications. Youprovidethesespecificationswhenyouconfigureanewadapterservice.
30
Adapter Listeners and Listener Notifications
YouusethewebMethodsDevelopertoconfiguretheadapterservice.Somefamiliarity withusingthewebMethodsDeveloperisrequired.SeethewebMethodsDeveloperUsers Guideformoreinformation. TheSAPAdapterprovidesthefollowingadapterservicetemplate: Adapter Service Template RFC Adapter Service (synchronous) Description InvokesanRFContheSAPsystem, executesatRFC,orconfirmsatransaction.
Adapter Listeners and Listener Notifications

TheadapterusesanRFClistenertoenabletheSAPsystemtomakeRemoteFunction CallstotheIntegrationServer.Itusesfourdifferenttypesofnotificationstohandlethe RFCspassedthroughtheRFClistener.
Listeners
AlistenercontinuallymonitorsanSAPsystemforRFCrequeststosendtotheIntegration Server.WhenacallismadefromtheSAPsystem,thelistenerpassesthemessagetoa listenernotification. Alistenerisarealtimeprocessthatyouconfigure,enable,anddisableusingthe Administrator.Fordetailedinstructionsonhowtoconfigurelisteners,seeListenerson page 87.
Listener Notifications
AlistenernotificationworksinconjunctionwithalistenertofilterandprocesstheRFC requestsintheSAPAdapter.TheSAPAdapterusesfivedifferentlistenernotificationsto processrequests: Listener Notification ALE Listener Notification (synchronous) ALE Listener Notification (asynchronous) RFC Listener Notification (synchronous) Description HandlesincomingIDocssynchronously. HandlesincomingIDocsasynchronously. HandlesincomingRFCsandtRFCssynchronously.
31
Listener Notification RFC Listener Notification (asynchronous) Routing Notification (synchronous)
Description HandlesincomingRFCsandtRFCsasynchronously. Isusedbytheadaptertorouteallincomingrequests thatarenotmappedtoaservice.Therouting notificationisaspecialcaselistenernotification.See Chapter 8,RoutingMessagesThroughtheSAP Adapterformoreinformationaboutrouting notifications.
webMethods Manager Support for the Adapter

ThewebMethodsManagerServerisasystemsmanagementfacilitybasedontheOpen ManagementInterface(OMI).ItautomaticallymanagestheSAPAdaptercomponentsif theManagerServermanagestheIntegrationServeronwhichtheSAPAdapteris installed.ThemanagedSAPAdaptercomponentsare: Adapterconnections Adapterservices Listeners Listenernotifications SeethewebMethodsManagerServerProgrammersGuideforinformationabouttheobject interfacesavailabletotheSAPAdapter.Theseobjectinterfacesarethespecificattributes andoperationsthatyoucanperformtomanagetheSAPAdaptercomponents.
Viewing the Adapter s Update Level

WhenusingtheSAPAdapterwithIntegrationServer6.5,youcanviewthelistofupdates thathavebeenappliedtotheadapter.ThelistofupdatesappearsintheUpdatesfieldon theadaptersAboutpageintheIntegrationServerAdministrator.
32
CHAPTER
System Requirements
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
33
CHAPTER 2 System Requirements
Overview
Fordetailedinformationonsystemrequirements,seethewebMethodsSAPAdapter InstallationGuide. ThewebMethodsSAPAdapterversion6.5issupportedonallplatformswhereboththe webMethodsIntegrationServerversion6.5andSAPJavaConnectoraresupported.For informationonsupportedplatformsforSAPJavaConnector,seeOSSnote0000549268.
CPU
ForjustInternetenablinganSAPsystem,anaveragePCwillbesufficient.Forheavy loadscenarios,youshouldadjustyourhardwareaccordingly.
Disk Space
Questions on Sizing
AppropriatesizingfortheSAPAdapterinstallationstronglydependsonthebusiness scenarioyouwanttoestablish.Forspecifyingyourindividualrequirements,youshould answerthefollowingquestionsfirst: 1 2 Isthereaneedforyourowndevelopment,andifso,howbigdoyouexpectyour scenariotobe?SmallPackage:<1MB,averagePackage:<5MB,bigPackage:10MB Whatkindofdataflowdoyouexpect?Thatis,whatkindoftransactionalmessages andtheirsize,howmanyperday,forhowlongdoyouwanttokeepthemintheSAP Adaptertransactionstoreaftertheyarecompleted(Confirmed) Doyouneedtokeepstatisticalinformationofthekindwrittentoaudit.logand session.log?(SeethewebMethodsIntegrationServerAdministratorsGuideforan explanationofthesetwologfiles.)
34
Disk Space
Transaction Store
Youmustdeterminethestoragespaceforthetemporarilystoredtransactions.Usethe followingformula: (Averagesizeofatransactionalmessage)x(Numberoftransactionsperday)x (NumberofdaysyouwanttomaintainConfirmedtransactionsforreference).
To determine the average size of one transactional message 1 Determinethecurrentsizeofthe webMethods_directory/IntegrationServer/packages/WmSAP/txStore/directory, includingitssubdirectories. Send100typicaltransactionalmessages(transactionsyouwilluseinproduction) throughtheSAPAdapter. Checkthesizeofdirectoryagain. Dividethedifferenceby100todeterminetheaveragesizeofyourtransactional message.Forexample,atypicalORDERSIDocisbetween13kBand35kB.
2 3 4
Note: Youmightwanttoschedulethepub.sap.transaction:sweepservicetoadministerthe growthofthetransactionstore.Formoreinformationabouttheservice,see pub.sap.transaction:sweeponpage 265.
Log Files
Thelogfilesneedadditionaldiskspace.IftheSAPAdapterrunsonahighdebuglevel duringtheimplementationandtestphase,itcanwrite1GBperday.Typicaldatavolumes withastandarddebuglevel(4orlower)maygeneratebetween10kBand40MBperday (dependingontraffic).Thebiggestpartsareconsumedbyauditlogandsessionlog, whichareusedforstatisticalevaluations.Youcanturnofftheselogstosavediskspace. ThentheSAPAdapterneedsonlyafewkBeachdayfortheerrorlogandserverlog. However,itisnotrecommendedthatyouturnofftheselogs.ThiswillonlysaveafewkB andeliminatesallpossibilitiesfordeterminingthecauseoferrors.
To turn off the logs Audit Log:UsetheEdit Extended SettingsfeatureoftheIntegrationServerAdministrator toviewthewatt.server.auditLogkeyandeditthekeyasfollows: watt.server.auditLog=off.
35
Tip! YoucanalsoadjustthisparameterbyshuttingdowntheIntegrationServerand addingtheparametertooreditingitinthe webMethods_directory/IntegrationServer/config/server.cnffile. Session Log:UsetheEventManagertoolintheDevelopertosetthefollowingevents totheEnabledstatusfalse: Session End Event Session Expire Event Session Start Event Stats Log: UsetheEventManagertosetStat EventeventtotheEnabledfalse.
Example of Minimum Disk Space

ThefollowingisanexampleoftheminimumdiskspaceforanaverageSAPAdapter: Component Required disk space (MB) 80 ~5 280 280 645
Component BasicInstallation CustomerPackages(each) TransactionStore(1000ORDERSperday,keptfortwoweeks) Logfiles(keptfortwoweeks) Total
36
Memory
Memory
Questions on Sizing
1 HowmanytaskswilltheIntegrationServerhavetohandlesimultaneously?For example,howmanyRFCs,httprequests,ftpconnections,startedlistenersandRFC listenerswilltheIntegrationServerhavetohandlesimultaneouslyatthepeaktimeof theday?Thisdeterminesthenumberofsessionsn.Formoreinformation,see ConsumptionPerSessiononpage 37. ForhowmanySAPsystemswilltheSAPAdapterregisteranRFClistener?How manythreadsdotheselistenershave? Howmanymessages(XMLdocuments,IDocs,RFCcalls)gothroughtheIntegration Serversimultaneouslyatthepeaktimeoftheday?Isthereanyexpensivemappingto bedone?
2 3
Initial Consumption
TheIntegrationServerneedsapproximately80MBRAMtostartupandjustrunwithout anyheavyloadonit.DependingontheloadandexpectedtrafficontheIntegration Server,youneedtoaddthefollowing:
Consumption Per Session

EachtasktheIntegrationServerwillhandle(incominghttprequest,incoming/outgoing RFCcall)requiresonesessionontheIntegrationServer.Ifnisthenumberofsessions(see question1),addthefollowingamountofRAM:
n MB
Ifnprovestobemuchlargerthan75,usetheEdit Extended Settingsfeatureofthe IntegrationServerAdministratortoviewthewatt.server.threadPoolkeyandeditthe keytoenabletheIntegrationServertohandlemorethan75tasksinparallel.The IntegrationServerthenprovidesapoolofunusedsessions,andthenextrequestcanbe processedimmediatelywithoutwaitingforanewsessiontobecreated. Note: IfthesizeofyourhardwaredoesnotsupportthislevelofRAMusage,donotchange watt.server.threadPool. Youcanalsoincreasethevalueofthewatt.server.threadPoolMin=10parameterto enhanceperformance.
37
Tip! YoucanalsoadjusttheseparametersbyshuttingdowntheIntegrationServerand addingtheparameterstooreditingtheminthe webMethods_directory/IntegrationServer/config/server.cnffile Formoreinformationabouttheseparameters,seethewebMethodsIntegrationServer AdministratorsGuide. Note: Thisprocedureshouldbeusedwithcaretoavoidunnecessarymemoryoverload. Forexample,ifyoukeepapoolof1000sessionsandtheIntegrationServerrarelyneeds morethan100,youwillwastealotofmemoryandresources.
Consumption for RFC Listeners

Inthenextstep,youwillneedextramemoryforeveryRFClistenerthread(seequestion 2).Foreachlistenerthread,add10MB.Asthisconsumesalotofmemory,thenumberof threadsforalistenermustbechosenwithcare. Note: Ifthenumberofthreadsistoosmall,theSAPsystemcannotsendRFCsinparallel. TheRFCsmustbequeueduntilanIntegrationServerthreadisfreetoprocessthem.The SAPsystemsworkprocesses,tryingtosendRFCs,arethenblockedandtheSAPsystems performanceslowsdownconsiderably.Ontheotherhand,ifthenumberofthreadsistoo high,theIntegrationServerconsumesalotofmemory.ThismayslowdownIntegration Serverperformance.Tooptimizethenumberofthreads,determinetheaveragenumberof workprocessestheSAPsystemwilluseforsendingRFCs.
Payload
Youwillhavetocalculatetheamountofmemoryrequiredtoprocessdocuments simultaneously(seequestion3).Usethefollowingequationtocalculateyourneeds: Payloadconsumption=(documentsizexmemFactor+RFCSize)xnumberofparallel documents,where: memFactor=3+thenumberofINVOKEstatementsintheadapterornotification service(iftherearemappingsbetweendocumentformatsanddifferentXML dialects)+theSSLvalue.TheSSLvalue=0or1,accordingtowhetherdocuments areencryptedwithSSLornot. RFCSize=0,ifnoRFCisinvolvedintransportingthedocument. RFCSize=(1063bytesxnumberofsegments+524bytes)xnumberofIDocsin package,iftheIDocsareeithersentorreceivedviaRFC.
38
Memory
Ifyouareindoubtaboutyourassumptionsforthesevalues,youshouldrunafewtests andwatchbyhowmuchthememoryactuallyincreasesduringprocessingofone document. Important! Bydefault,theIntegrationServerstartswith128MBRAM.Afteryouhave calculatedthememorythatyourSAPAdaptershoulduse,youhavetomodifythesetting: setJAVA_MAX_MEM=128M inwebMethods_directory/IntegrationServer/bin/server.bat(orserver.shonUNIX)before startingtheIntegrationServer.
Example of Memory Usage

Thefollowingisanexampleofaserverhandling1000ORDERSperday: TheIntegrationServerhasonestandardRFClistenerwith3threads. Youexpectapeakloadofthreedocumentsinparallel,resultinginthreeparallel sessions.AllowanothersessionforanAdministratororDevelopertologon occasionally.TogetherwiththesessioncreatedbytheRFClisteners,thisprovidesa totalofeightparallelsessionsand4MB. TheIntegrationServerwillhandleapeakofthreedocumentsinparallel,andtheXML PackagedoessomemappingwhenconvertingtheIDoctoXML.Forarelativelysmall documentof20kBina50segmentIDoc,thisresultsinamemoryconsumptionof (20kBx6+52.4kB)x3=517.2kB(thatcanberoundedupto1MB.) Task Required IntegrationServercorefunctionality Sessions RFCListeners Documentprocessing Total RAM (MB) 80 4 30 1 115
Inthisexample,youshouldbefinewithapproximately128MBofmemoryforthe IntegrationServeralone.Afteraddingmemoryfortheoperatingsystemandothertasks,a 256MBmachinewillbemorethansufficient.
39
Miscellaneous
Encryption
WhenusingSSLtoencryptXMLdocuments,thetimeneededtoprocessadocumentwill increasebyafactorof3.Inthiscase,youthereforeneedtotakeaCPUfromthenext higherclass. YoualsohavetochangetheformulaforcalculatingtheRAMneededforprocessing documents:increasememFactorbyone.
IDoc Packets
TheperformancecanbevastlyimprovedbyusingIDocPacketsofawellchosensize.If thepacketsizeistosmall,youwillnottakefulladvantageoftheperformance improvement.Ifitistobig,theIntegrationServermayrunoutofmemoryorstart swapping.Youshoulddosometestingtofindtheoptimumsize;itdependsontheIDoc typeaswellasonthesizeofyourmachine.
Logging
Iftheproductionscenarioinvolvesinvokingthousandsofservicesinashortperiodof time,youcanachieveahugeperformanceimprovementbyturningoffAuditLogging. Forinformationaboutturningofflogging,seeLogFilesonpage 35.
40
CHAPTER
Package Management
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Managing the Adapter Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Controlling Group Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Using the Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
41
CHAPTER 3 Package Management
Overview
ThefollowingsectionsdescribehowtosetupandmanageyourSAPAdapterpackages, setupAccessControlLists(ACL),andusetheadapterinaclusteredenvironment.
Managing the Adapter Package

TheSAPAdapterisprovidedasapackagecalledWmSAP.YoumanagetheWmSAP packageasyouwouldmanageanypackageontheIntegrationServer. Whenyoucreateconnections,adapterservices,andadapternotifications,definethemin userdefinedpackagesratherthanintheWmSAPpackage.Doingsowillallowyouto managethepackagemoreeasily. Asyoucreateuserdefinedpackagesinwhichtostoreconnections,adapterservices,and adapternotifications,usethepackagemanagementfunctionalityprovidedinthe DeveloperandsettheuserdefinedpackagestohaveadependencyontheWmSAP package.Thatway,whentheWmSAPpackageloadsorreloads,theuserdefined packagesloadautomatically.Seethefollowingdiagram:
SAP Connections Package (user-defined) WmART WmSAP SAP Adapter Services Package (user-defined) SAP Notifications Package (user-defined) Adapter n Connections Package (user-defined)
Adapter n
KEY: A sets a dependency on B: A B
Adapter n Services Packages (user-defined) Adapter n Notifications Packages (user-defined)
42
Packagemanagementtasksinclude: Settingpackagedependencies(seePackageDependencyRequirementsand Guidelinesonpage 43). EnablingandDisablingPackagesonpage 44. ImportingandExportingPackagesonpage 45. ControllingGroupAccessonpage 46.
Package Dependency Requirements and Guidelines

Thissectioncontainsalistofdependencyrequirementsandguidelinesforuserdefined packages.Forinstructionsforsettingpackagedependencies,seethewebMethodsDeveloper UsersGuide. Auserdefinedpackagemusthaveadependencyonitsassociatedadapterpackage, WmSAP.(TheWmSAPpackagehasadependencyontheWmARTpackage.) PackagedependenciesensurethatatstartuptheIntegrationServerautomatically loadsorreloadsallpackagesintheproperorder:theWmARTpackagefirst,the adapterpackagenext,andtheuserdefinedpackage(s)last.TheWmARTpackageis automaticallyinstalledwhenyouinstalltheIntegrationServer.Youshouldnotneed tomanuallyreloadtheWmARTpackage. Iftheconnectionsandadapterservicesofanadapteraredefinedindifferent packages,then: Apackagethatcontainstheconnection(s)musthaveadependencyonthe adapterpackage. Packagesthatcontainadapterservicesmusthaveadependencyontheir associatedconnectionpackage. Keepconnectionsfordifferentadaptersinseparatepackagessothatyoudonotcreate interdependenciesbetweenadapters.Ifapackagecontainsconnectionsfortwo differentadapters,andyoureloadoneoftheadapterpackages,theconnectionsfor bothadapterswillreloadautomatically. TheIntegrationServerwillnotallowyoutoenableapackageifithasadependency onanotherpackagethatisdisabled.Thatis,beforeyoucanenableyourpackage,you mustenableallpackagesonwhichyourpackagedepends.Forinformationabout enablingpackages,seeEnablingandDisablingPackagesonpage 44.
43
TheIntegrationServerwillallowyoutodisableapackageevenifanotherpackage thatisenabledhasadependencyonit.Therefore,youmustmanuallydisableany userdefinedpackagesthathaveadependencyontheadapterpackagebeforeyou disabletheadapterpackage.Forinformationaboutdisablingpackages,seeEnabling andDisablingPackagesonpage 44. Youcannameadapterservicesandnotificationsthesamenameprovidedthatthey areindifferentfolders.
Enabling and Disabling Packages

Allpackagesareautomaticallyenabledbydefault.Whenyouwanttotemporarily prohibitaccesstotheelementsinapackage,disablethepackage.Whenyoudisablea package,theserverunloadsallofitselementsfrommemory.Disablingapackage preventstheIntegrationServerfromloadingthatpackageatstartup. To enable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofthenavigationarea,clickManagement. ClickNointheEnabledcolumn.Theserverdisplaysa column. andYesintheEnabled
Note: Enablinganadapterpackagewillnotcauseitsassociateduserdefinedpackage(s)to bereloaded.Forinformationaboutreloadingpackages,seeLoading,Reloading,and UnloadingPackagesonpage 45. Important! Beforeyoumanuallyenableauserdefinedpackage,youmustfirstenableits associatedadapterpackage(WmSAP).Similarly,ifyouradapterhasmultipleuser definedpackages,andyouwanttodisablesomeofthem,disabletheadapterpackage first.Otherwise,errorswillbeissuedwhenyoutrytoaccesstheremainingenableduser definedpackages.
To disable a package 1 2 3 OpentheIntegrationServerAdministratorifitisnotalreadyopen. InthePackagesmenuofthenavigationarea,clickManagement. ClickYesintheEnabledcolumnforthepackagethatyouwanttodisable.Theserver issuesaprompttoverifythatyouwanttodisablethepackage.ClickOKtoenablethe package.Whenthepackageisdisabled,theserverdisplaysNointheEnabledcolumn.
44
Adisabledadapterwill: RemaindisableduntilyouexplicitlyenableitusingtheAdministrator. NotbelistedinthewebMethodsDeveloper.
Loading, Reloading, and Unloading Packages

Ifuserdefinedpackagesareproperlyconfiguredwithadependencyontheadapter package(asdescribedinPackageDependencyRequirementsandGuidelineson page 43),atstartuptheIntegrationServerautomaticallyloadsorreloadsallpackagesin theproperorder:theWmARTpackagefirst,theadapterpackagenext,andthenode package(s)last.YoushouldnotneedtomanuallyreloadtheWmARTpackage.
Reloading Packages Manually

Reloadingauserdefinedpackagewillnotcauseitsassociatedadapterpackagetobe reloaded.Youcanreloadadapterpackagesanduserdefinedpackagesfromeitherthe IntegrationServerAdministrator(byclickingtheReloadiconontheManagement window)orfromthewebMethodsDeveloper(byrightclickingthepackageandselecting theReload Packageoptionfromthemenu).
Unloading Packages
Atshutdown,theIntegrationServerunloadspackagesinthereverseorderinwhichit loadedthem:itunloadsthenodepackage(s)first,theadapterpackagenext,andthe WmARTpackagelast(assumingthedependenciesarecorrect).
Importing and Exporting Packages

YouimportandexportpackagesusingtheDeveloper.Exportingallowsyoutoexportthe packagetoa.zipfileandsaveittoyourharddrive.The.zipfilecanthenbeimportedfor usebyanotherpackage. Important! Donotrenamepackagesyouexport;therenamefunctioniscomparableto movingapackage,andwhenyouimporttherenamedpackage,youloseanytriggers, connections,andnotificationsassociatedwiththispackage Fordetailsaboutimportingandexportingpackages,seethewebMethodsDeveloperUsers Guide.
45
Setting Package Dependencies

Yousetpackagedependenciesifagivenpackageneedsservicesinanotherpackageto loadbeforeitcanload.Forexample,anypackagesyoucreateforSAPAdapterservices shouldidentifythewebMethodsSAPAdapterpackage(WmSAP)asapackage dependencybecausetheyrequireservicesinWmSAPtoloadfirst.Usethefollowing guidelines: Setpackagedependenciesfromtheadapterservicepackagetothepackagecontaining theconnectionifyouconfigureaconnectioninonepackageandtheadapterservices inanotherpackage.Thatis,thepackagethatcontainstheconnectionshouldload beforetheadapterservicepackage. Whenyousetthispackagedependency,itensuresthatifsomeonedisablesthe connectionpackageandthenreenablesit,theadapterserviceswillreloadcorrectly. Ifboththeconnectionandadapterservicesareinthesamepackage,thenno dependenciesneedtobeset. Ingeneral,packagescontainingconnectionsshouldhaveadependencysettothe adapterpackageitself.Thatis,theadapterservicepackageshoulddependonthe adapterconnectionpackage,whichshoulddependontheadapterpackage.Similarly, iftheadapterservicesareinthesamepackageastheconnections,theonly dependencythatyouneedtosetisbetweentheadapterconnectionpackageandthe adapterpackage. Formoreinformationaboutsettingpackagedependencies,seethewebMethodsDeveloper UsersGuide.
Controlling Group Access

Tocontrolwhichgroupshaveaccesstowhichadapterservices,useaccesscontrollists (ACLs).Forexample,youcanuseACLstopreventonedevelopmentgroupfrom inadvertentlyupdatingtheworkofanothergroup,ortoallowordenyaccesstoservices thatarerestrictedtoonegroupbutnottoothers. ForinformationaboutassigningandmanagingACLs,seethewebMethodsDeveloperUsers Guide.
46
Using the Adapter in a Clustered Environment

What Is webMethods Integration Server Clustering?
ClusteringisanadvancedfeatureofthewebMethodsplatformthatsubstantiallyextends thereliability,availability,andscalabilityofthewebMethodsIntegrationServer. TheclusteringfeatureusesasharedclusterstoretoholdwebMethodsIntegrationServer stateinformationandutilizationmetricsforuseinloadbalancingandautomaticfailover support.Becausethisactivityistransparenttotheclient,clusteringmakesmultiple serverslookandbehaveasone. Clusteringingeneralprovidesthefollowingbenefits: Load balancing. Thisfeature,providedautomaticallywhenyousetupaclustered environment,allowsyoutospreadtheworkloadoverseveralservers,thusimproving performanceandscalability. Failover support. Clusteringenablesyoutoavoidasinglepointoffailure.Ifaserver cannothandlearequest,orbecomesunavailable,therequestisautomatically redirectedtoanotherserverinthecluster. Note: webMethodsIntegrationServerclusteringredirectsHTTPandHTTPSrequests, butdoesnotredirectFTPorSMTPrequests. Scalability.Youcanincreaseyourcapacityevenfurtherbyaddingnewmachinesand webMethodsIntegrationServertothecluster. FordetailsonwebMethodsIntegrationServerclustering,seethewebMethodsIntegration ServerClusteringGuide. Important! IfyouuseclusteringwiththeSAPAdapter,SAPtransactions,liketransactional tRFCcallsandIDocs,willnotbesupported.YoucanonlyusenontransactionalRFCsand BAPIsinaclusteredenvironment.
About Clustering for the SAP Adapter

TheevaluationofclusteringhasshownthatitsadvantagesinthespecificSAP environmentarerestricted.Asaresult,webMethodsgenerallyrecommendsthatyou insteadinstallseveralindependentIntegrationServersfrontedbyanexternalload balancer.Thereasonsforthisrecommendationaredescribedinthefollowingsections. Reviewtheadvantagesanddisadvantagesofclusteringinyourspecificenvironment carefullybeforedecidingontheimplementation.
47
Inthelightoftheserestrictions,clusteringoffersthefollowingadvantageand disadvantages. Advantage: Noadditionalloadbalancingcomponentisneeded. Disadvantages: LoadbalancingforvariouskindsofHTTPclientsiseasiertoachievewithanexternal loadbalancerandseveralinstancesofindependentIntegrationServers. Scalabilitythroughloadbalancingisnotreached.IndependentIntegrationServers frontedbyanexternalloadbalancerofferabettersystemperformance. Failovermechanismsonlymakessenseformultisteptransactions.WithanSAP backendsystem,thesetransactionsareboundtoasingleIntegrationServer,sothe checkpointsupportoftheclusterdoesnotapply.
How Outbound RFCs Are Balanced

WithregardtoSAPlogicalunitofwork(LUW)management,notethefollowing additionalrestrictions. WheneveritisnecessarytomaintaintheusercontextintheSAPsystem,subsequentcalls mustbeissuedfromthesameIntegrationServeroverthesameRFCconnection.This limitstheuseofclusteringbecauseanRFCconnectioncannotbeputintotherepository server.ItisboundtoasingleIntegrationServer. ThemethodtobindanIntegrationServersessiontoanRFCconnectionistoembed subsequentrequestsofaSAPLUW(forexample,achangeBAPIanda BAPI_TRANSACTION_COMMIT)inabind/releaseblock.Theresultingservicecanthen beclustered. However,ifyouwanttoexecuteanSAPLUWthathasseveraldependentrequestsina rowthatcannotbeembeddedintooneservice,youmustensurethatthesameuser contextisalwaysused.Youmustalsoensurethatloadbalancingispreventedforeach dependentcall.Youpreventloadbalancing(theredirectionofyoursubsequentrequests) byaddingtherequeststotheIntegrationServer_Directory\config\redir.cnffilewiththe valuefalse.Forexample:
<value name=pub.sap.client:lockSession>false</value>
48
Youcanstartandfinishyourdependentrequestsequencebybindingandreleasingyour sessiontoyourRFCconnectionusingspecialservices. 1 TobindyourIntegrationServersessiontoanRFCconnection,callthe pub.sap.client:lockSessionservicebeforeanyseriesofrequeststhatmusthavethesame usercontextassignedattheSAPsystemhost.Forformoreinformationaboutthis service,seepub.sap.client:lockSessiononpage 233. ToreleaseyourIntegrationServersession,makesurethattheLUWiscomplete(all serviceshavebeencalled).Thencallthepub.sap.client:releaseSessionservice.Formore informationaboutthisservice,seepub.sap.client:releaseSessiononpage 234.
How Inbound RFCs Are Balanced

SAPlistenersintheSAPAdapterimplementselfregisteringRFCservers.Becausetheyall havethesameprogramID,theSAPsystemgatewayserviceautomaticallyusesload balancingforanyRFCcallstothisprogramID.Onlyonedestinationreceivesanysingle request;thegatewayserviceensuresthataslongasoneofthelistenerthreadsisidle,then norequestsfromtheSAPsystemwillbeblocked.
Configuring the Adapter in a Clustered Environment

WhenyouconfiguretheSAPAdaptertocreateadapterservices,youmust: EnsurethateachIntegrationServerintheclustercontainsanidenticalsetofpackages (seeReplicatingPackagestowebMethodsIntegrationServersonpage 49). Disabletheredirectioncapabilityforcertainpredefinedadministrativeservices(see DisablingtheRedirectionofAdministrativeServicesonpage 50).
Replicating Packages to webMethods Integration Servers

EverywebMethodsIntegrationServerintheclustershouldcontainanidenticalsetof packagesthatyoudefineusingtheSAPAdapter;thatis,youshouldreplicatetheSAP Adapterservicesandtheconnections,listeners,andlistenernotificationstheyuse. Toensureconsistency,createallpackagesononeserver,andreplicatethemtotheother servers.Ifyouallowdifferentserverstocontaindifferentservices,youmightnotderive thefullbenefitsofclustering.Forexample,ifaclientrequestsaservicethatresidesinonly oneserver,andthatserverisunavailable,therequestcannotbesuccessfullyredirectedto anotherserver. Forinformationaboutreplicatingpackages,seethechapteronmanagingpackagesinthe webMethodsIntegrationServerAdministratorsGuide.
49
Disabling the Redirection of Administrative Services

AsmentionedinWhatIswebMethodsIntegrationServerClustering?onpage 47,a serverthatcannothandleaclientsservicerequestcanautomaticallyredirecttherequest toanotherserverinthecluster.However,theSAPAdapterusescertainpredefined administrativeservicesthatyoushouldnotallowtoberedirected.Theseservicesareused internallywhenyouconfiguretheadapter.Ifyouallowtheseservicestoberedirected, yourconfigurationspecificationsmightbesavedonmultipleservers,whichisan undesirableresult.Forexample,ifyoucreatetwoSAPAdapterservices,onemightbe storedononeserver,whiletheotheronemightbestoredonanotherserver.Remember thatalladapterservicesmustresideonallwebMethodsIntegrationServersinthecluster. To disable the redirection of administrative services 1 2 ShutdowntheAdministrator.SeethewebMethodsIntegrationServerAdministrators Guidefortheproceduretodothis. Editthefollowingfile: IntegrationServer_Directory\config\redir.cnf 3 Addthefollowinglinestothefile:
<value name="wm.art">false</value> <value name="wm.sap">false</value>
SavethefileandrestartthewebMethodsIntegrationServer.
50
Clustering Considerations and Requirements

Note: ThefollowingsectionsassumethatyouhavealreadyconfiguredthewebMethods IntegrationServercluster.FordetailsaboutwebMethodsclustering,seethewebMethods IntegrationServerClusteringGuide. ThefollowingconsiderationsandrequirementsapplytotheSAPAdapterinaclustered environment.
Requirements for Each Integration Server in a Cluster

ThefollowingtabledescribestherequirementsofeachIntegrationServerinagiven cluster: All Integration Servers in a given cluster must have identical... IntegrationServer versions
For Example... OneIntegrationServerintheclustercannotbeversion6.5 andanotherIntegrationServerintheclusterbeversion 6.0.3allserversmustbeversion6.5,withthesameservice packsandfixes(updates)applied. AlladapterpackagesononeIntegrationServershouldbe replicatedtoallotherIntegrationServersinthecluster. Inthecluster,allSAPAdaptersmustbethesameversion, withthesamefixes(updates)andthesameSAPlibraries (versions)applied.
Adapterpackages Adapterversions
51
All Integration Servers in a given cluster must have identical... Userdefinedadapter packages
For Example... Eachpackagethatyouhaveconfiguredcontainingadapter connections,adapterservices,flowservices,listeners, triggers,andnotificationsfortheSAPAdapter,mustexist onalloftheIntegrationServersinthecluster,sothatall IntegrationServersintheclustercanhandleanygiven request. TheconfigurationandsettingsofallSAPAdapter connections,adapterservices,listeners,triggersand notificationsmustbeidenticalthroughoutthecluster. Toensureconsistency,createallpackagesononeserver,and replicatethemtotheotherservers.Ifyouallowdifferent serverstocontaindifferentservices,youmightnotderive thefullbenefitsofclustering.Forexample,ifaclient requestsaservicethatresidesinonlyoneserver,andthat serverisunavailable,therequestcannotbesuccessfully redirectedtoanotherserver.Forinformationabout replicatingpackages,seethechapteronmanagingpackages inthewebMethodsAdministratorsGuide. Note: Ifyouplantouseconnectionpoolsinaclustered environment,seeConsiderationsWhenConfiguring ConnectionswithConnectionPoolingEnabledonpage 53.
Adapterconnections
Ifyouconfigureaconnectiontotheapplicationserver,this connectionmustappearonallserversintheclustersothat anyIntegrationServerintheclustercanhandleagiven requestidentically. Ifyouplantouseconnectionpoolsinaclustered environment,seeConsiderationsWhenConfiguring ConnectionswithConnectionPoolingEnabledonpage 53.
Adapterservices
Ifyouconfigureaspecificadapterservice,thissameadapter servicemustappearonallserversintheclustersothatany IntegrationServerintheclustercanhandletherequest identically. IfyouallowdifferentIntegrationServerstocontaindifferent services,youmightnotderivethefullbenefitsofclustering. Forexample,ifaclientrequestsaservicethatresideson onlyoneserver,andthatserverisunavailable,therequest cannotbesuccessfullyredirectedtoanotherserver.
52
SeeReplicatingPackagestowebMethodsIntegrationServersonpage 49for informationaboutreplicatingadapterpackages,connections,andadapterservicesacross multipleIntegrationServersinacluster.
Considerations When Installing SAP Adapter Packages

ForeachIntegrationServerinthecluster,usethestandardSAPAdapterinstallation proceduresforeachmachine,asdescribedinthewebMethodsSAPAdapterInstallation Guide.
Considerations When Configuring Connections with Connection Pooling Enabled

Whenyouconfigureanadapterconnectionthatusesconnectionpoolsinaclustered environment,besurethatyoudonotexceedthetotalnumberofconnectionsthatcanbe openedsimultaneouslyforthatSAPsystem. Forexample,ifyouhaveaclusteroftwoIntegrationServerswithaconnectionconfigured toanSAPsystemthatsupportsamaximumof100connectionsopenedsimultaneously, thetotalnumberofconnectionspossibleatonetimemustnotexceed100.Thismeansthat youcannotconfigureaconnectionwithaninitialpoolsizeof100andreplicatethe connectiontobothservers,becausetherecouldbepossiblyatotalof200connections openedsimultaneouslytothisSAPsystem. Inanotherexample,consideraconnectionconfiguredwithaninitialpoolsizeof10anda maximumpoolsizeof100.Ifyoureplicatethisconnectionacrossaclusterwithtwo IntegrationServers,itispossiblefortheconnectionpoolsizeonbothserverstoexceedthe maximumnumberofconnectionsthatcanbeopenatonetime. ForinformationaboutconfiguringconnectionsfortheSAPAdapter,seeConfiguring AdapterConnectionsonpage 56. Formoregeneralinformationaboutconnectionpools,seethewebMethodsIntegration ServerAdministratorsGuide.
Considerations about SAP Adapter Centralized Transaction Store

WhenusingmultipleSAPAdaptersforinboundRFCloadbalancing,youconfigureRFC listenerswiththesameProgramIDoneachSAPAdaptersothattheSAPGatewaycan performloadbalancingandroutetRFCdocumentstodifferentSAPAdapters.TheSAP GatewayalsosendsouttRFCtransactionstatusinformationupdatestotheSAPAdapter listeners.Bydefault,thistransactionstatusinformationispersistedlocallyintheadapters transactionstore. However,communicationfailures,forexamplewhenanetworkconnectionfailsoran IntegrationServerbecomesunavailable,canleadtosituationswheretheSAPGatewayis sendingthetRFCtransactionstatusinformationnottothesingleSAPAdapterthathas processedthetRFC,butalsotoother,differentSAPAdaptersinthegroup.Inthiscase, thetransactionstatusinformationpersistedinthelocaltransactionstoresofthevarious adapterscanendupinaninconsistentandinvalidstate.
53
TopreventthesesynchronizationissueswithtRFCtransactioninformationupdates,you canconfigureyourgroupofSAPAdapterstouseasingleCentralizedTransactionStore (CTS)thathostsalltransactionstateinformationforallSAPAdaptersinthegroup. TheCentralizedTransactionStoreimplementsaclient/serversolution,whereoneSAP Adapterhoststhecentralizedstore(theCTSServer)andallotherSAPAdaptersaccess thisstoreasclients(CTSClients).Sincealltransactionstatusinformationupdatesarenow routedtoasingletransactionstore,nomoreduplicate,incomplete,orinconsistent transactionstateinformationwillbepersistedinlocaltransactionstores. NotethatitisnotrequiredthatyousetuptheCTSasanIntegrationServercluster.Instead youcanusetheCTSeitherwithanIntegrationServerclusterorwithagroupofSAP AdaptersonindependentIntegrationServers. ACTSisneededwhenyouwanttoimplementrobustinboundoroutboundload balancingusingtRFCsandIDocs.IfyoujustrunasingleSAPAdapter,thenaCTSwill notmakeanysense(anditwouldbeinternallytreatedlikealocalTransactionStorebythe adapter).IfyourunagroupofcompletelyindependentSAPAdaptersanddonotintend touseloadbalancingortRFCsorIDocswiththeseadapters,thenconfiguringaCTSwill notbeuseful. SAPAdaptersconfiguredasCTSClientswillpersistandlookupalltransaction informationintheCTS,thereforetheavailabilityandperformanceoftheCTSServerisof importance.EnsurethattheSAPAdapterthathoststheCTS(theCTSServer)isalways startedbeforeallotherSAPAdapters(Clients),andalsoensurethattheCTSserverisnot shutdownordisabledwhileotherCTSClientsarestillrunningandprocessing transactions. FormoreinformationaboutconfiguringtheCentralizedTransactionStore,see CentralizedTransactionStoreonpage 181.
54
CHAPTER
Adapter Connections
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Configuring Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Setting Up the SAP System for SNC Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Dynamically Changing a Services Connection at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . 62 Enabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Viewing Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Editing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Copying Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Deleting Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Disabling Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Testing the Execution of an RFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Testing the Execution of a BAPI Via XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
55
CHAPTER 4 Adapter Connections
Overview
ThischapterdescribeshowtoconfigureandmanageSAPAdapterconnections.Formore informationabouthowadapterconnectionswork,seeAdapterConnectionsonpage 28.
Before Configuring or Managing Adapter Connections

To prepare to configure or manage adapter connections 1 2 InstallthewebMethodsIntegrationServerandtheSAPAdapteronthesame machine.SeethewebMethodsSAPAdapterInstallationGuidefordetails. MakesureyouhavewebMethodsadministratorprivilegessothatyoucanaccessthe SAPAdaptersadministrativescreens.SeethewebMethodsIntegrationServer AdministratorsGuideforinformationaboutsettinguserprivileges. StartyourIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning. UsingtheAdministrator,makesuretheWmSAPpackageisenabled.SeeEnabling andDisablingPackagesonpage 44forinstructions. UsingtheDeveloper,createauserdefinedpackagetocontaintheconnection,ifyou havenotalreadydoneso.Formoreinformationaboutmanagingpackagesforthe adapter,seeManagingtheAdapterPackageonpage 42.
3 4 5
Configuring Adapter Connections

UsethefollowingproceduretodefinetheparametersthattheSAPAdapterwilluseto establishaconnectiontoanSAPsystem.TheSAPAdapterrequiresaconnectiontothe SAPsystemwheneverfunctionalityfromtheSAPsystemistobeinvoked;thatis whenevertheSAPAdapteractsasaclientforanSAPsystem.ButalsowhentheSAP AdapterreceivesacallfromanSAPsystem,itneedstomakeacallbacktothecalling systemtolookupthefunctioninterfaceorIDocdefinitionfromtheSAPDataDictionary (DDIC). To configure an adapter connection 1 2 3 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. OntheConnectionsscreen,clickConfigure New Connection. OntheConnectionTypescreen,clickRFC Connectionastheconnectiontype.
56
Forabasicconnection,completethefollowingfieldsintheSAP Adaptersection: Field Package Description/Action Thepackageinwhichtocreatetheconnection.Youmust createthepackageusingtheDeveloperbeforeyoucanspecify itusingthisparameter.Forgeneralinformationaboutcreating packages,seethewebMethodsDeveloperUsersGuide. Note: Configuretheconnectioninauserdefinedpackage ratherthanintheadapterspackage.SeeChapter 3,Package Managementforotherimportantconsiderationswhen creatingpackagesfortheSAPAdapter. Folder Name Thefolderinwhichtocreatetheconnection.
IntheConnection Propertiessection,completethefollowingfieldsusingthevalues fromyourconfiguredSAPsystem: Field Connection Alias Description/Action TheRFCconnectionname.ThisisthenamebywhichtheSAP systemwillbeknowntoSAPAdapterdevelopers,clients,and partners. TheSAPusername. TheSAPpassword. ThethreedigitSAPclientnumber. TheSAPlanguagecode.Ifconnectingtoaversion3SAP system,thisisonecharacter.Foraversion4orlaterSAP system,itistwocharacters.
User Name Password Client Language
Toconfigurelogonproperties,completeoneofthefollowingsteps: Toenableloadbalancing,configurethefollowingfields: Field Load Balancing Description/Action IfyouselectOn,thegrouploginconceptisactive. Completetheremainingfieldsinthisstep. IfyouselectOff,youwillconnecttoonededicated applicationserver.SkiptoCompletethefollowingfields tosetupthesingleserverlogon:onpage 58. Logon Group Thenameofthegroupyouwanttologin.
57
Field Message Server System ID
Description/Action ThehostnameorIPaddressofthemessageserver. The3digitIDoftheSAPsystem.
Completethefollowingfieldstosetupthesingleserverlogon: Field Application Server System Number Description/Action TheIPaddressorhostnameoftheSAPsystem. TheSAPsystemnumber(0099).
CompletethefollowingfieldsifyouareusinganexternalRFCServer: Important! ThesettingsshouldpointeithertotheGatewayatwhichthisRFC serverisregisteredortotheRepository Serverselectedbelow.Theloadbalancing andsingleserverlogonsettingswillbeignoredifyouconfigureanRFCserver. Field External RFC Server Description/Action IfyouselectYes,anexternalRFCserverwillbeused. Completetherestofthefieldsinthissection. IfyouselectNo,youdonotneedtocompletetherestofthe fieldsinthissection. Program ID Gateway Host TheProgramIDoftheexternalRFCServer GatewayHostforaccessingyourRFCServer.Mustbethe IPorDNaddressoftheGatewaytheRFCServeris registeredon. ThiscorrespondstothesystemnumberofyourRFC Server. Syntax:TheGatewayServicemustintheformofsapgwXX, whereXXisavaluefrom00to99. Example:sapgw07 Repository Server ThisserveristakenfromtheexistingSAPsystemlist.All repositorylookupssuchasmetadatalookupsfor structuresandfunctioninterfacesaredonethere.This helpsusingthirdpartyRFCServersfromtheSAP Adapterasclient.Theycanprovidetheirfunctionality withoutbeingextendedbyaspecificinterface,for example:RFC_GET_FUNCTION_INTERFACE
Gateway Service
58
Note: AnyserverprogramthatisenabledforRFCcommunicationcanbean externalRFCServer.InordertouseanexternalRFCServerwiththeSAP Adapter,theRFCServermustimplementatleastthefollowingfunctionmodules: RFC_FUNCTION_SEARCH RFC_GET_FUNCTION_INTERFACE RFC_GET_STRUCTURE_DEFINITION(iftheserverisrunningwitha3.xLib) DDIF_FIELDINFO_GET(iftheserverisrunningwitha4.xLib) ThelastthreefunctionmodulesarerequiredonlyiftheRFCServeristobeits ownRepository Server. 7 Optionally,completethefollowingfieldstoenablesecurity: Field SNC Enabled SNC Quality of Service Description/Action DetermineswhetherthisservershoulduseSecureNetwork Communications(SNC).Default:No. SNCQualityofservice,possiblevalues: Useglobalbuiltindefaultsettings Plaintext,butauthorization Eachdatapacketwillbeintegrityprotected Eachdatapacketwillbeprivacyprotected Usemaximumavailablesecurity SNC Name YourownSNCnameifyoudonotwanttousethedefault SNCname.Thisisthenameyouchosewhengeneratinga PersonalSecurityEnvironment(PSE). SNCnameoftheSNCpartner(RFCserver)orSNCnameof themessageserver(LoadBalancing).
SNC Partnername
59
Optionally,settheSAPRouterString: Field SAP Router String Description/Action TheSAProuterstring.Arouterstringcontainsasubstringfor eachSAPRoutertosetupaconnectionintheroute:thehost name,theportname,andthepassword,ifonewasgiven. Example: /H/127.0.0.1/H/ Syntax: /H/indicatesthehostname. TheSAProuterstringisonlyneededifthereexistsafirewall betweentheSAPsystemandIntegrationServer.Formore informationonconfiguringtheSAProuter,seetheSAPHelp PortalontheSAPServiceMarketplace.
Optionally,completetheadvancedsettingsfortheconnection: Field Use SAPGui Description/Action Runwithout/with/invisibleSAPGUIbetweentwoRFC functions. Values:Off/On/Hidden Default:Off RFC Trace Disables/enablesthecreationofRFCtraceinformationforthis clientconnection. Values:Off/On Default:Off FordetailedinformationonusingtheRFCtrace,see Chapter 10,LoggingandMonitoring. ABAP Debug Runwithout/withtheABAPdebugger Values:Off/On Default:Off
60
Field Log transaction status
Description/Action ThisswitchcanbesettoOnorOff. IfsettoOff,thentheprocessinglogswillnotbesaved, althoughatransactionwillbecreated(ormaintained),andthe transactioncanbemonitoredlateroninthetransactionlist. Tip! Activatingthisswitchreducestheamountofdiskspace neededandthetimeittakestologthetransactionstatus.Itstill allowsyoutocheckthecurrenttransactionstatusontheSAP Adapter.
Store message body
ThisswitchcanbesettoOnorOff. IfsettoOff,thenthemessagebodyoftheincomingdocument willnotbestoredtodisk,althoughatransactionwillbe created(ormaintained),andthetransactioncanbemonitored lateroninthetransactionlist. Tip! Activatingthisswitchreducestheamountofdiskspace neededandthetimeittakestopersistthemessagebody.Itstill allowsyoutotrackthemessagestatusontheSAPAdapter.
10 Click Save Connection tocommitthesechanges.
61
Setting Up the SAP System for SNC Connections

IfyouwanttouseSNCconnectionsforthecommunication,therearesomemoregeneral anduserspecificsettingsrequiredontheSAPsystem.Thesesettingsarelistedbelow: SAP system settings for SNC General SAP system settings for SNC: Certificate log in: General Settings:
Table/Parameter TableSNCSYSACL (SM30, view VSNCSYSACL, TYP=E) SNC nameentryoftheSAPAdapter. ProfileParameter: SNC/libsapsecu=./libsecude.sl (forHPUX) SNC/extid_login_diag=1 SNC/extid_login_rfc=1 TableSNCSYSACL(SM30, view VSNCSYSACL, TYP=E), activate: Certificate log in Diag RFC
Certificate log in: User specific settings:
TableUSREXTID (view VUSREXTID), Category DN EntrywithDN(DistinguishedName)fromusercertificate TheSeq.No.000isthedefaultentry. Setentryactive.
FordetailedinformationontheSAPapplicationserversettingsforSNC,seeyourSAP documentation.
Dynamically Changing a Services Connection at Run Time

FortheSAPAdapter,youcanchangetheservicesconnectioninoneoftwoways. TheadapterservicethatshipswiththeSAPAdapterintheWmSAPpackageinthepub.sap namespaceincludesafieldcalledserverName.Viathisfield,youcanspecifyatruntime theSAPsystemtobeupdated. Additionally,IntegrationServer6.5enablesyoutooverridethedefaultconnection associatedwiththeserviceatdesigntime.Tooverridethedefault,youmustcodeyour flowtopassavaluethroughthepipelineintoaservices$connectionNamefield.
62
Enabling Adapter Connections
Forexample,youhaveaflowwhoseprimarypurposeistocreateanentryonthe productionSAPsystem.However,youwanttheflowtohavethecapabilitytocreatethe entryonthetestserver,withthedecisionofwhichSAPsystemtoupdatetobemade programmaticallyatruntime.Theoutputsignatureoftheflowsfirstservicecontainsa fieldcalledTarget.TheflowcouldbranchbasedonthevalueinTarget. IfTargetcontainsthevalueproduction,thesecondserviceintheflowwouldignore $connectionNamethususingitsdefaultconnectiontoconnectto(andthenupdate) theproductionSAPsystem. However,ifTargetcontainsthevaluetest,thesecondserviceintheflowwoulduse thevalueinthe$connectionNamefromthepipelineandconnectto(andthenupdate) thetestSAPsystem. KeepinmindthatbothconnectionsthedefaultandoverridemusthavethesameSAP classesandmethods. Formoreinformation,seeChangingtheConnectionAssociatedwithanAdapterService atRunTimeonpage 30.
Enabling Adapter Connections

Aconnectionmustbeenabledbeforeyoucanconfigureanyadapterserviceusingthe connection,orbeforeanadapterservicecanusetheconnectionatruntime.Youenable adapterconnectionsusingtheAdministrator. Note: Whenyoureloadapackagethatcontainsenabledconnections,theconnectionswill automaticallybeenabledwhenthepackagereloads.Ifthepackagecontainsconnections thataredisabled,theywillremaindisabledwhenthepackagereloads.
To enable a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. OntheConnectionsscreen,clickNointheEnabledcolumnfortheconnectionyouwant toenable. TheIntegrationServerAdministratorenablestheadapterconnectionanddisplays a andYesintheEnabledcolumn. Ifyoureceiveanerrormessage,clicktheEditbuttontoviewtheconfiguration. Verifythatyourconfigurationinformationiscorrect.SeeEditingAdapter Connectionsonpage 64. IncaseofanRFCerrormessage,anRFCtracefilenameddev_rfc.trcwillbe writtentothewebMethods_directory\IntegrationServerdirectory.Thisfilecontains amoredetaileddescriptionoftheerrorcause.
63
Viewing Adapter Connection Parameters

YoucanviewaconnectionsparametersfromtheAdministratororfromtheDeveloper. To view the parameters for a connection using the Administrator 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. OntheConnectionsscreen,clicktheViewicon fortheconnectionyouwanttosee.
TheViewConnectionscreendisplaystheparametersfortheconnection.For descriptionsoftheconnectionparameters,seeConfiguringAdapterConnections onpage 56. 3 ClickReturn to SAP Adapter Connections toreturntothemainconnectionsscreen.
To view the parameters for a connection using the Developer 1 2 3 StarttheDeveloperifitisnotalreadyrunning. FromtheDevelopersnavigationarea,openthepackageandfolderinwhichthe connectionislocated. Clicktheconnectionyouwanttoview. TheparametersfortheconnectionappearontheConnection Informationtab.For descriptionsoftheconnectionparameters,seeConfiguringAdapterConnections onpage 56.
Editing Adapter Connections

Ifaconnectionparameterchanges,orifyouwanttoredefineparametersthataconnection useswhenconnectingtoanSAPsystem,youcanupdateaconnectionsparametersusing theAdministrator. Afteryoueditaconnection,youmustreloadtheWmSAPpackageforthechangetotake effect. To edit a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. Makesurethattheconnectionisdisabledbeforeeditingit.SeeDisablingAdapter Connectionsonpage 66forinstructions.
64
Copying Adapter Connections
OntheConnectionsscreen,clicktheEditicon
fortheconnectionyouwanttoedit.
TheEditConnectionscreendisplaysthecurrentparametersfortheconnection. Updatetheconnectionsparametersbytypingorselectingthevaluesyouwantto specify. Fordescriptionsoftheconnectionparameters,seeConfiguringAdapter Connectionsonpage 56. 4 ClickSave Changes tosavetheconnectionandreturntotheConnectionsscreen.
Copying Adapter Connections

YoucancopyanexistingSAPAdapterconnectiontoconfigureanewconnectionwiththe sameorsimilarconnectionpropertieswithouthavingtoretypeallofthepropertiesfor theconnection.YoucopyadapterconnectionsusingtheAdministrator. To copy a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. OntheConnectionsscreen,clicktheCopyicon copy. fortheconnectionyouwantto
TheCopyConnectionscreendisplaysthecurrentparametersfortheconnectionyou wanttocopy.Namethenewconnection,specifyapackagenameandfoldername, andeditanyconnectionparametersasneededbytypingorselectingthevaluesyou wanttospecify. Note: Whenyoucopyaconnection,thenewconnectiondoesnotsavethepasswordof theoriginalconnection.Youmustenterandthenretypethepasswordbeforeyoucan savethenewconnection. Fordescriptionsoftheconnectionparameters,seeConfiguringAdapter Connectionsonpage 56. 3 ClickSave Connection tosavetheconnectionandreturntotheConnectionsscreen.
65
Deleting Adapter Connections

IfyounolongerwanttouseaparticularSAPAdapterconnection,youcandeleteitby followingtheinstructionsinthissection.Youdeleteadapterconnectionsusingthe Administrator. Ifyoudeleteaconnection,theadapterservicesornotificationsthataredefinedtousethe connectionwillnolongerwork.However,youcanchangewhichconnectionanadapter serviceuses.Therefore,ifyoudeleteaconnection,youcanassignadifferentconnectionto anadapterserviceandreusetheservice.Todothis,youusethebuiltinwebMethods functionsetAdapterServiceNodeConnection.Formoreinformation,seeChangingthe ConnectionAssociatedwithanAdapterServiceatDesignTimeonpage 30. To delete a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. Makesurethattheconnectionisdisabledbeforedeleting.Todisabletheconnection, clickYesintheEnabledcolumnandclickOKtoconfirm.TheEnabledcolumnnow showsNo(disabled)fortheconnection. OntheConnectionsscreen,click fortheconnectionyouwanttodelete.
TheIntegrationServerdeletestheadapterconnection.
Disabling Adapter Connections

SAPAdapterconnectionsmustbedisabledbeforeyoucaneditordeletethem.You disableadapterconnectionsusingtheAdministrator. To disable a connection 1 2 IntheAdaptersmenuintheAdministratorsnavigationarea,clickSAP Adapter. OntheConnectionsscreen,clickYesintheEnabledcolumnfortheconnectionyou wanttodisable. TheadapterconnectionbecomesdisabledandyouseeaNointheEnabledcolumn.
66
Testing the Execution of an RFC
Testing the Execution of an RFC

AfteryouhaveverifiedthatyoucanconnecttoanSAPsystem,youcanusethefollowing proceduretoverifythattheSAPsystemacceptsandprocessesanRFCrequestfromthe SAPAdapter. To test an RFC from the SAP Adapter 1 2 3 4 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickLookup. FromthedropdownlistintheSystem IDfield,selectthesystemIDoftheSAPsystem thathoststhefunctionmoduleyouwanttotest. IntheFunction NamefieldoftheFunction Searchgroup,enterthenameofthefunction moduleyouwanttotest.Forexample,enterRFC_FUNCTION_*.ClickSearch.TheSAP AdaptersearchesforallRFCsthatbeginwithRFC_FUNCTION_. InthelistofmatchingRFCsthatisreturned,followthelinkoftheRFCyouwantto test.Forthisexample,selectRFC_FUNCTION_SEARCH.TheSAPAdapterdisplaysthe functionsignaturefortheselectedfunctionmodule.Itliststheimports,exports,and tablescomprisingthisfunctionmodule. SelectTest FunctiontoinvokethefunctionmoduleontheSAPsystemyouselectedin step 3. EnterRFC_*inthefieldFUNCNAMEandclickTest Function againtoproceed.Afterafew moments,ascreendisplaysthenumberoffunctionsfound. Followtheentrieslinkbesidethisrowcounttoviewthefunctionsfound.
6 7 8
Testing the Execution of an RFC-XML

YoucaninvokeafunctionmodulewithRFCXMLfromtheSAPAdapteruserinterface viatheLookupscreen.ThisscreencontainsanRFCXMLtemplateyoucanusetoinvoke functionmodules.PerformthefollowingproceduretoaccesstheLookupscreenand invokeafunctionmoduleviaRFCXML. To invoke a function module via XML from the SAP Adapter 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickLookup.
67
3 4
EnterthefunctionmoduleyouwouldliketoinvokeviaXMLintheFunction Name fieldoftheFunction By Namesection. SelectRFC-XML. ThisgeneratesaformcontainingtheXMLtemplatenecessarytoinvokethefunction module.FillintheappropriateinputsandselectInvoke on System ID.Youwillseethe XMLresponseinthebrowser(youmayhavetoselectView Sourcetoseetheactual XMLsourceinyourbrowser).
Testing the Execution of a BAPI Via XML

ThelookuptoolcomeswithabuiltinBAPIBrowser.Youcanusethistoolforanoverview oftheBAPIinterfacesinsideyourSAPsystem,andalsotodirectlycallaBAPIviaXML.
Starting to Browse
YoucanstartbrowsingyourBAPIsusingtheLookuptab.Hereyoucanenterthenameof abusinessobjectandaBAPI.ThisselectionalwaysappliestotheSAPsystemselectedin thefieldSystem ID. Thereareseveralwaysyoucanfillouttheform: InthegroupBAPI By NameenterthefullnameofthebusinessobjectandBAPI.Youcan eitherviewthedetailsoftheBAPIbyselectingLookupordirectlyinvoketheBAPIvia XMLbyclickingbXML. InthegroupBAPI By Nameenteronlythenameofthebusinessobject.SelectLookupto viewdetailsofthebusinessobjectandselectoneBAPIfromthelistofavailableBAPIs forthebusinessobject. InthegroupBAPI By Nameenter* inthebusinessobjectfieldtoviewalistofall businessobjectsavailableintheselectedsystem. Note: BusinessobjectnamesandBAPInamesarecasesensitive.
Displaying a List of Business Objects in the System

Byentering *inthebusinessobjectfieldontheLookupmainpage,youcanviewalistof allbusinessobjectsavailableontheselectedsystem. Eachlinkinthislistrepresentsabusinessobject.Ifyoufollowthelink,youwillgeta detailedviewofthisbusinessobject.Thislistcanalsocontainbusinessobjectsthatdonot containBAPImethods.
68
Displaying a Business Object

ByenteringacorrectnameofabusinessobjectinthecorrespondingfieldontheLookup mainpage,youcanviewdetailedinformationforthisbusinessobject.Thedetailed informationconsistsofalistofallthekeyfieldsofabusinessobjectandalistofallits BAPImethods.Forbusinessobjects,whichonlyprovideinstanceindependentmethods (staticmethodsinprogramminglanguageslikeCorJAVA),theKey fieldslistisempty. ForbusinessobjectsthatdonotprovideBAPIs,thelistofBAPIswillbeempty. Justfollowthelinkstothecorrespondingtablefieldstodisplaymoreinformationona specifickeyfieldorBAPI.
Displaying a BAPI
ByenteringthefullnameofthebusinessobjectandBAPIinthecorrespondingfieldon theLookupmainpage,youcandisplaydetailedinformationoftheBAPI.Youcanalso displaythisinformationbyfollowingthecorrespondinglinkonthedisplaypagefora businessobject. Field Static method Description TheStatic method flagistrueiftheBAPIisaninstanceindependent method.Inpractice,thatmeansthatyoudonothavetospecifythe businessobjectskeyfieldswhencallingthismethod. TheDialog methodflagistrueifthemethodisadialogmethod.Ifthe methodisnotusingadialog,theflagisfalse.DialogBAPIsrequire aSAPGui. TheFactory method flagistrueiftheBAPIisusedtocreateanobject instanceinsidetheSAPsystem.Factorymethodsreturnthekey fieldsofthebusinessobject. TheImplementing RFCisthemessagetypethathastobeusedtoset uproutingforsynchronouscallscomingfromanSAPsystem.This istechnicallyrealizedviaRFC,soherethenameofthe correspondingRFCfunctionmoduleinsidetheSAPsystemis provided.Althoughitispossibleatthemoment,itisnot recommendedtocallBAPIsdirectlyviaRFCXML,asthiswould onlybeanimplementationdependentviewoftheBAPI.
Dialog method
Factory method
Implementing RFC
69
Field ALE message type
Description TheALE message typeisthemessagetypethathastobeusedtoset uproutingforasynchronouscallscomingfromanSAPsystem. ThisistechnicallyimplementedviaIDoctransfers,butwhenusing theBAPIstyledXMLcalls,theALEmessagetypeisonlyneeded tosetuprouting. The ParametersfieldcontainsalistofallparametersintheBAPI interface.Byselectingthislink,youcandisplaymoreinformation oneachparameter.Pleasenotethatthekeyfieldsofabusiness objectarenotdisplayedinthisparameterareabutintheKey fields areaonthebusinessobjectdetailpage.
Parameters
ByclickingtheCreate XML templatebutton,youcangeneratetheXMLmessagethathasto beusedtoinvokethisBAPIviaXML.Afterithasbeengenerated,youcanimmediately sendtheXMLtotheSAPsystemfortestingpurposes(seebelow).
Displaying a BAPI Parameter

ByselectingaspecificparameterfromthelistofparametersprovidedontheBAPIdetail page,youcandisplayadditionalinformationforthisparameter. Field Internal Name Direction Description ParameternameoftheunderlyingRFC. Theusedirectionoftheparameterisdisplayed.BAPIsuse importing,exportingandchanging(=importingandexporting) parameters. IftheflagOptionalissettotrue,youcanomitthisparameterinan XMLmessage.Usually,theimplementationinsidetheSAPsystem usesspecificdefaultvaluesforoptionalparametersthatwere omitted. IftheflagTableissettotrue,thisparametermayconsistofseveral lines.EachlinehasthedatatypespecifiedintheABAP Dictionary Typefield. TheABAP Dictionary Typeisalinktothedatatypedescriptionused forthisparameter.Thismaybeawholestructureorjustafieldofa structure.Byfollowingthehyperlink,youwillalwaysseethe wholestructure.
Optional
Table
ABAP Dictionary Type
70
Displaying a Key Field

Byselectingaspecifickeyfieldfromthelistofkeyfieldsprovidedonthebusinessobject detailpage,youcandisplayadditionalinformationforthiskeyfield. Field Internal Name ABAP Dictionary Type Description ParameternameoftheunderlyingRFC. TheABAP Dictionary Typeisalinktothedatatypedescriptionused forthisparameter.Thisisusuallyafieldofastructureinsidethe SAPDataDictionary.Byfollowingthehyperlink,youwillseethe wholestructure. Note: Keyfieldsareusedwithinstancedependent(nonstatic) methodsandwithfactorymethods. Incallstothesemethods,thekeyfieldsofthecorresponding businessobjecthavetobespecifiedasattributesofthebusiness documentrootelement. Forexample,usingthekeyfieldCompanyCodeIdinacalltothe CompanyCode.GetDetail:
<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> .. </header> <body> <doc:CompanyCode.GetDetail CompanyCodeId="0001" xmlns:doc="urn:sap-com:document:sap:business" xmlns="" > </doc:CompanyCode.GetDetail> </body> </biztalk_1>
Generating XML Calls for a BAPI

ByenteringthefullnameofthebusinessobjectandBAPIinthecorrespondingfieldon theLookupmainpageandthenchoosingCreate XML Template,youcangenerateanXML messagerepresentingthecalltothisBAPI.Youcanalsogeneratethismessageby followingthecorrespondinglinkonthedisplaypageforaBAPI. ThepagedisplaystheXMLmessageneededtocalltheBAPIwhichiswrappedinthe BizTalkXMLenvelope.YoucanedittheXMLandenteryourspecificdataintothepre generatedXMLelementsforparametersandkeyfields.
71
YoucanalsoadjustthepregeneratedinformationintheBizTalkXMLheaderfieldsthat arefilledwithdefaultdata. TherearethreewaysofcallingtheBAPI,whichcanbeselectedthroughthelist: SynchronouslycallingtheBAPIinanSAPsystem. AsynchronouslycallingtheBAPIinanSAPsystem.ThisonlyworksforBAPIsthat aremappedtoanALEinterface.ToseewhethertheBAPIismappedtoanALE interface,checktheBAPIdetailpage.IfanALEmessagetypeisspecified,theBAPI canbecalledasynchronously. Applyingroutingnotification:ThecallwillbesenttotheBAPIinboundprocessofthe routinglistenerthatwillcheckifaroutingnotificationforthisBAPIcallexistsand willforwardthecalltothespecifiedservice.Thiswillonlyworkifacorrectrouting notificationhasbeensetup,otherwiseyouwillreceiveanXMLerrormessage. AfterclickingInvoke,theresultofyourXMLcallisdisplayed.Inthecaseofsynchronous processing,thiswillbeaBizTalkmessagewitheithertheexportingparametersofthe BAPIorwithanerrormessage. Forasynchronouscalls,thiswillbeaBizTalkmessagewithanemptybodyinthecaseof successorwithanerrormessage,ifthemessagecouldnotbedeliveredtoanSAPsystem. Applicationspecificerrorsarenotreturnedinthecaseofasynchronouscalls,butyoucan usetheALEmonitoringtoolsinthetargetSAPsystemtochecktheseerrors.
Posting a BAPI from an HTTP client

ForinformationaboutcallingaBAPIfromanexternalclientusinganXMLdocument,see Chapter 10,RoutingBAPIsthroughtheSAPAdapter.
72
CHAPTER
Adapter Services
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Creating an Adapter Service that Executes an RFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
73
CHAPTER 5 Adapter Services
Overview
AdapterservicesfortheSAPAdapterworkbyexecutingafunctionmoduleresidingon anSAPsystem.AfunctionmoduleperformsfunctionsagainstdataintheSAPsystem. Youcancreateaserviceforanyfunctionmodulethatisdesignatedforexternaluse(for example:remoteenabled).ThisincludesallBAPIs,whichareformalizedfunction modules. Beforeyoucancreateanadapterservice,youmustconfigureanRFCclientconnectionto theSAPsystemyouwanttoaccess.Youidentifyaconnectionaliasandspecify informationthatisrequiredtoconnecttotheSAPsystem.Tocreateanadapterservice, youselecttheSAPsystemandtheRFCthatyouwanttheservicetoexecute.Aftercreating theadapterservice,youcancreateaclientthatinvokestheservice. Thischapterdescribeshowtocreateanadapterserviceforaspecificfunctionmoduleon onespecificSAPsystemandhowtotesttheadapterservice. Note: YoumusthaveadministratorprivilegesontheIntegrationServertocreateanew RFCconnectiontoanSAPsystem.Ifyoudonothavesuchprivileges,haveyour IntegrationServeradministratorcreatethenewRFCconnectionforyou.
Creating an Adapter Service that Executes an RFC

TocreateanadapterservicethatexecutesanRFC,selecttheRFC Adapter Servicetemplate. Thisfeatureallowsthefunctionmoduletobeexposedasastandardservice.Afteryou createtheadapterservice,businesspartnersinterestedincallingthisservicecan incorporateitintotheirclientcode. Note: CallingaBAPIaccordingtoitsdefinitionintheBORiscurrentlynotpossibleasan adapterservice.Inthiscase,usetheBAPItransport. Note: AnSAPAdapteroutboundcallisaninboundcallfromtheSAPsystemspointof view.
74
Terminology
TousetheSAPAdaptersuccessfully,youshouldunderstandthefollowingtermsand concepts: Term Export Function Signature Import RFC Adapter Service Structure Table Description Outputparametersofafunctionmodule.Outputparametersare simplevaluesorstructures. Specificationsoftheimport,export,andtableparametersofan functionmodule.Alsoknownasafunctioninterface. InputparametertoanRFC.Inputparametersaresimplevalues (suchasstringornumber)orstructures. SAPAdapterterminologyforanassociationbetweenafunction moduleonanSAPsystemandanadapterservicebasedonthe RFCAdapterServicetemplateontheSAPAdapter. SAPdatastructurecontainingoneormorefields.Thiscanbe thoughtofasasinglerowofatable. SAPdatastructurethatisbothanimportandexporttoafunction. TablescanbecreatedandpassedtoanRFC.Thefunctionmodule canmodifythesetablesandreturnthem.Thetablesthemselvesare nodifferentfromrelationaldatabasetables;theyconsistofaseries offieldsandrowsofdataforthesefields.
Creating an RFC Adapter Service

UsethefollowingproceduretocreateanRFCadapterservicethatmakesaremote functioncalltoafunctionmoduleontheSAPsystem.Thisexampleshowshowtocreate anRFCadapterserviceforRFC_FUNCTION_SEARCH. Note: AnSAPAdapteroutboundcallisaninboundcallfromtheSAPsystemspointof view.
To create an adapter service for an RFC 1 2 3 4 OpentheDeveloper. SelectNew Adapter Service.ClickNext.
SelectSAP Adapterfromthelistofavailableadaptertypes.ClickNext. SelectapreviouslycreatedRFCconnectionthatpointstotheSAPsystemthathosts thefunctionmoduleforwhichyouwanttocreatetheadapterservice.ClickNext.
75
5 6 7
Fromthelistofavailabletemplates,selectRFC Adapter Service (synchronous).ClickNext. EnteranameandselectafolderwheretheRFCadapterserviceshouldbestored. ClickFinish. OntheFunction Searchtab,intheFunction Patternfield,typeallorpartofthenameof thefunctionmoduleforwhichyouwanttocreateanadapterservice.Usepattern matchingcharactersifyouareunsureofthecompletenameandwanttheSAP AdaptertosearchforseveralRFCswithsimilarnames.Forthisexample,enter RFC_FUNCTION_* intheFunction Patternfield. UnderFunction Name,alistofRFCsthatmatchthecriteriayouspecifiedinthe previousstepisdisplayed. SelectthenameoftheRFCforwhichyouwanttocreateanadapterservice.Forthis example,RFC_FUNCTION_SEARCH.Leaveallotherfieldsattheirdefaultvalues.
ClickSaveontheDevelopertosaveyourRFCadapterservice.
Testing the RFC Adapter Service

UsethefollowingproceduretotesttheRFCadapterserviceyoujustcreated. To test an RFC adapter service for a function module 1 IntheDeveloper,opentheRFCadapterserviceyoupreviouslycreated. OntheFunction Searchtab,youwillseevalueRFC_FUNCTION_SEARCHintheFunction Namefield. 2 3 Onthetoolbar,clickRun. EnterRFC_* intofieldFUNCNAMEtospecifyinput.ClickOK. TheresultsofRFC_FUNCTION_SEARCHwillbedisplayedintheFUNCTIONStable ontheResultspageoftheDeveloper. AfteryoucreateanRFCadapterservicethatexecutesafunctionmodule,youcancreate otherservicesandclientsthatinvoketheservice. Note: IfanoptionaltableisnotpassedtoanRFCadapterservice,novalueswillbe returnedforthattable. ToensurethattheoptionaltablegetsreturnedfromtheSAPsystem,inyourcalling serviceyouneedtoensurethatavalueissetattheinputsignatureoftheRFCadapter serviceyouwanttocall.InDeveloper,clickSet Valuetoassignan(empty)valuetothe optionalinputfieldoftheRFCadapterservice.
76
Forexample,youcallanadapterservicenamedTCC_MSS_GET_ERRORLOGfromawrapper flowservice.ThisadapterservicecontainsanoptionaltablecalledLOGLIST.Topassthis table,clickSet Valueforthisparameter. Iftheemptytableshouldonlybethedefaultvalue,deselectOverwrite Pipeline Value.With thesesetting,theoptionaltableisalwaysreturned.
Posting an RFC-XML Document from an HTTP Client

ThereareseveralpossiblewaystoinvoketheRFCadapterservicewhichwillcalla functionmodule.Itisimportantthatyouunderstandthenamespaceconventionfor services(seethewebMethodsIntegrationServerAdministratorsGuide). YoucaninvoketheserviceillustratedpreviouslybycallingthefollowingURL:
http://<Integration Server>:<port>/invoke/<folder1>.<folder2>/<service>
To invoke the service 1 Inaninteractivescenario,youcansimplycallitfromabrowserthesamewayyoucall anyotherserviceonIntegrationServer.TheinputparametersmustthenbeURL encoded,forexample:

http://localhost:5555/invoke/app/rfcGetStructureDefinition?TABNAME=USE R01
TheresponsecanthenberenderedviaanHTMLtemplate. 2 Inafullyautomatedscenarioyourapplicationwould,however,sendtherequest XMLdocumenttothisservice.Atemplateforavalidrequestdocumentforeach functionmodulecanbegeneratedfromtheLookupmenubyclickingtheRFC-XML button.ToinvoketheRFCadapterservice,youmustpostitintheHTTPbodyof requesttotheURL(asabove).YourapplicationmustalsosetsomekeysintheHTTP Header:

POST /invoke/<your complete service name> HTTP/1.1 --> the service name to be called Host: <xyz> --> host of http client Content-type: application/x-sap.rfc --> you have to set the content type. When sending an RFC-XML document, the content type should be application/x-sap.rfc Cookie: ssnid=<4711> --> This is optional. On the first connect Integration Server will generate a session cookie. When you use this for the following communication you will be assigned to the same Integration Server session. If you do not use the session cookie a new Integration Server session will be created with every HTTP request. Content-Length: <the length of the HTTP Body>
77
TheHTTPBodymustconsistoftheXMLdocument,encodedinRFCXML.Dependingon whetherthecallwasprocessedsuccessfully,youwillgetaresponseoranexceptionXML document.YoucanalsoforcetheSAPAdaptertoinvokethefunctionmodulewithtRFC bysettingatransactionIDintheEnvelopeoftheXMLdocument.However,youshould bearinmindthatonlyfunctionmoduleswithoutreturnparameterscanbecalledwith tRFC. Tip:Tosimulatearawpost,youcanusetheservicepub.client:http.
To use the pub.client.http service 1 2 3 4 5 6 UsingDeveloper,navigatetothepub.client:httpservice. SelectTest4Run. SpecifytheURLoftheRFCXMLhandlerservice.Forexample,

http://localhost:5555/invoke/app/rfcGetStructureDefinition
SpecifyPostasthemethod. PastethedocumentintotheStringfieldoftheDatasection. Addoneentryinthefieldheaders: Name:Contenttype Value:application/xsap.rfc
Formoreinformationaboutthepub.client:httpservice,seethewebMethodsBuiltInServices ReferenceGuide.
78
CHAPTER
Adapter Notifications
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Creating an RFC Destination on an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
79
CHAPTER 6 Adapter Notifications
Overview
YoucancreateRFCsontheSAPsystemthatinvokeservicesontheIntegrationServer. ThisallowsSAPuserstoaccesstheinformationthatisavailableviatheSAPAdapter. BeforeyoucancreateanRFCthatinvokesaservice,orsendanIDoctotheSAPAdapter, youmustconfiguretheSAPsystemtohaveanRFCdestinationforanRFClistener runningattheSAPAdapter.ThisenablestheSAPsystemtosendRFCstotheSAP Adapter.YoumustalsoconfiguretheSAPAdaptertohaveanRFClistenerthatlistensfor RFCsfromtheSAPsystem. AfteryouhavetheSAPsystemandtheSAPAdapterconfigured,youcancreatea functionmoduleontheSAPsystemthatrequeststheexecutionofaservice synchronouslyoryoucansendanIDoctotheSAPAdapterforfurthersynchronousor asynchronousprocessing.Todosoyoualsoneedtocreatealistenernotificationonthe SAPAdapter.ThelistenernotificationindicateseitherwhatservicetheSAPAdapteristo executewhenitreceivesamessagefromtheSAPsystemorhowtopublisha correspondingdocument. TheSAPAdaptersupportsthreetypesofnotificationsthatcanbeassignedtoanRFC listener. RFClistenernotification(synchronous) ALElistenernotification(synchronous) ALElistenernotification(asynchronous) IfthereisnolistenernotificationassignedtotheRFClistener,thereceivedmessagewillbe forwardedtotheroutinglistener.Formoreinformation,seeChapter 8,Routing MessagesThroughtheSAPAdapter. Note: Inthiscontext,synchronousorasynchronousreferstotheprocessingonthe IntegrationServer.ItdoesnotindicatehowthemessagewasprocessedontheSAP system.However,inthecaseofanALElistenernotification,thereisalwaysaTID assignedtothemessage.InthecaseofanRFClistenernotification,aTIDwillbepresent inthepipelineonlyfortransactionalRFCcallsfromtheSAPsystem.
Components of a Listener Notification

Inadditiontotherequest(andreply)fieldselection,alistenernotificationcontainsthe followingfields: AflagthatindicatesifincomingIDocsshouldbetrackedtolaterALEmonitoring fromthecallingsystem. AflagthatindicateswhethertheConfirmeventshouldbeforwardedtothereceiver.
80
Overview
Monitor IDocs Flag

AllALElistenernotificationsandroutingnotificationsthathaveanALEmessagetype assignedsupporttheMonitorIDocsfeature.Formoreinformation,seeUsingtheALE MonitoringFeaturesViatheSAPAdapteronpage 175.
Forward Confirm Event Flag

Allsynchronousadapternotifications(theRFClistenernotification,ALElistener notification,andtheroutingnotification)supporttheforwardConfirmeventfeature.This isausefulfeatureinscenarioswhereatransactionalrequestisreceivedbytheSAP AdapterandthenforwardedtoanSAPsystemviatRFC,andwheretheclientwantsto achievetransactionalbehaviorfromendtoend. Note: Thisfeatureisnotsupportedforanasynchronousadapternotification.For asynchronousadapternotifications,theBrokerapplicationthatreceivesthepublishable documentfromtheSAPAdaptershoulddeterminehowtoproceedaftersuccessfully executingandcommittingthetransactionalrequest. IftheForward Confirm eventflagisactivated,theSAPAdaptertriestoforwardthe ConfirmTIDevent,whichistriggeredbythetRFCprotocol,tothesamedestination wherethedocumentwent.Whathappensthendependsonthetransportused. TransportsthathaveanSAPsystemorotherIntegrationServerasthedestinationconfirm theTIDonthedestinationsystem.Thismaybecomeimportantinthosecaseswherethe finalreceiverofthemessageisanotherSAPsystem.ForeachtRFCitreceives,anSAP systemkeepsanentryinachecktable(ARFCRSTATE)toprotectagainstduplicate processingofthesamedocument.OnlyafterthesenderhasindicatedviaConfirmTID thatthisdocumentwillneveragainbeposted,thereceivingsystemcansafelyremovethis entryfromitschecktable. Uptoversion4.6,theSAPAdapterwouldnotforwardthisConfirmTIDevent,sothe checktableinthereceivingSAPsystemwouldkeepgrowing.Thisfeatureenablesaclean upthischecktableinscenarioslike: SAPsystemA>SAPAdapterA>Internet>SAPAdapterB>SAPsystemBor externalclient>SAPAdapter>SAPsystem iftheexternalclientusestheservicepub.sap.client:confirmTID.
81
ThefollowingtwosimplifieddynamicmodeldiagramsshowhowtheSAPAdapter handlesrequestsdifferentlydependingonthesettingofthe$actionparameter.Theyshow acombinedviewofthreepossiblescenarios: AlistenernotificationisdirectlyassignedtotheRFClistener. NolistenernotificationisassignedtotheRFClistener,andthemessageisforwarded totheroutinglistener. Themessageissentdirectlytotheroutinglistenerbycallingoneofthe pub.sap.transport.*:InboundProcessservices.
Action Equals 1
Inthescenariowherethevalueof$actionequals1(Execute),thecallingservicename,or incaseofaninboundtransport,thematchingconfirmservice,willbestoredinthe transactionstore(setServiceName()call).
$action=1
82
Overview
Action Equals 4
Inthescenariowherethevalueof$actionequals4(Confirm),thestoredservicenamewill beretrievedandtheservicewillbecalleddirectly,bypassingthenotification (getServiceName()call).
$action=4
Important! Ifyouexecutearoutingnotificationthathasatransportotherthanthe IntegrationServerassignedtransport,thecorrectconfirmservicewillbechosenand calledwithoutanyadditionalcodingneeded.Forallotherscenarios,theassignedservice willbecalledtwice.Youneedtocheckthevalueofthe$actionfieldtocorrectlyprocessthe request.
83
Creating an RFC Destination on an SAP System

ToenableyourSAPsystemtoissueremotefunctioncalls(RFCs)forservicesonan IntegrationServer,youmustdefineanRFCdestinationontheSAPsystem.EachSAP systemhasasingleRFCdestinationforanRFClistenerdefinedattheSAPAdapterthat identifieswheretheSAPsystemsendsallRFCsthatinvokeservicesontheIntegration Server. UsethefollowingproceduretoconfiguretheSAPAdapterlistenerasaregisteredRFC destinationontheSAPsystem. Note: YoumusthavetheproperauthorizationsonyourSAPsystemtoaddanRFC Destination.Ifyoudonothavethisauthorization,haveyourSAPadministratorperform thefollowingsteps.
To register SAP Adapter listener as an RFC destination 1 2 3 UsetheSAPGuitologintotheSAPsystem. SelectAdministration (SM59). System Administration Administration Network RFC Destinations
SelectTCP/IPconnections.
84
Creating an RFC Destination on an SAP System
4 5
SelectCreate. IntheRFC Destinationfield,typeanamethatwillmeaningfullyidentifyboththeSAP AdapterandtheSAPsystemitself.Forexample,iftheSAPsystemisnamedCERand theIntegrationServerisnamedIS,nameyourRFCdestinationISCER.Youwillneed toreenterthisnameseveraltimesduringthecourseofthissection,sokeepitsimple andmemorable. Important! Thisfieldiscasesensitive.Itisrecommendthatyoupickanamethatisall UPPERCASEcharacters.
6 7 8 9
Enter TintheConnection typefield(destinationtypeTCP/IP). EnteradescriptionintheDescriptionfieldthatdifferentiatesthisSAPAdapterfrom anyother. SelectSavefromthetoolbarorselectSavefromtheDestinationmenu. SelectRegistrationastheActivation Type.
10 InfieldProgram IDtypethenameofyourRFCdestinationfromstep 5.Enteritexactly asyoudidinstep 5.Thisisalsoacasesensitivefield. 11 SelectSavefromthetoolbarorselectSavefromtheConnectionmenu. 12 SelectGatewayOptionsfromtheDestinationsmenu. 13 EnterSAP system application serverintheGateway hostfield. 14 Entersapgwnn (wherennistheSAPsystemnumber) intheGateway servicefield. Note: ThisguaranteesthatyoucanaccesstheRFCServerfromallSAPapplication servers. 15 SelectOK. 16 SelectSave.
85
RemainonthecurrentscreenwhileyoucompletethestepsforcreatinganSAPAdapter listener.
86
Listeners
Listeners
Thissectiondescribeshowtocreate,modify,anddeletelisteners.
Before you Configure New Listeners

To prepare to configure a new listener 1 MakesurethatyouhavewebMethodsadministratorprivilegessothatyoucanaccess theSAPAdaptersadministrativescreens.Forinformationaboutsettinguser privileges,seethewebMethodsIntegrationServerAdministratorsGuide. StarttheIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning. UsingtheAdministrator,makesurethattheWmSAPpackageisenabled.Toverify thestatusoftheWmSAPpackage,seeEnablingandDisablingPackagesonpage 44. UsingtheDeveloper,createauserdefinedpackagetocontainthelistener,ifyouhave notalreadydoneso.Formoreinformationaboutmanagingpackages,seePackage Managementonpage 41fordetails.
2 3 4
Configuring an RFC Listener

TheSAPAdapterrequiresanRFClistenertolistenforinboundRFCrequestsfroman SAPsystem.UsethefollowingproceduretocreatealistenerontheSAPAdapterto respondtoRFCsissuedbytheSAPsystem. To create an RFC listener on the SAP Adapter 1 2 3 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickListeners. SelectConfigure new listenerandthenselectRFC listenerfromthelistofavailablelistener types.
87
CompletethefollowingfieldsontheConfigureListenerTypescreen(leaveallother fieldsattheirdefaultvalues): Field Package Description/Action Thepackageinwhichtocreatethelistener.Youmustcreate thepackageusingtheDeveloperbeforeyoucanspecifyit usingthisparameter.Forgeneralinformationaboutcreating packages,seethewebMethodsDeveloperUsersGuide. Note: Configurethelistenerinauserdefinedpackagerather thanintheadapterspackage.SeeChapter 3,Package Managementforotherimportantconsiderationswhen creatingpackagesfortheSAPAdapter. Folder Name Listener Name Program ID Thefolderinwhichtocreatethelistener. Thenameofthenewlistener. TheProgramIDthatyouspecifiedwhencreatingthe correspondingRFCdestinationontheSAPsystem.Thisfield iscasesensitive. GatewayHostforaccessingyourSAPsystem.Thismustbe exactlythesameparameterasyouchoseforthecorresponding RFCdestinationintheSAPsystem. TheGatewayService.ThiscorrespondstoyourSAPsystem number.IfyourSAPsystemnumberis01thenyour gatewayserviceissapgw01. Again,thismustbeexactlythesameparameterasyouchose forthecorrespondingRFCdestinationintheSAPsystem. Number of Threads ThenumberofsimultaneousincomingRFCsthatthislistener canhandle.
Gateway Host
Gateway Service
88
Listeners
Field Repository Server
Description/Action Theoutboundconnectionaliasisusedasarepositoryfor functioninterfacesandstructuredefinitionsofinboundcalls. ThiswayitispossibletouseRFCseveniftheyarenotdefined inthecallingsystem. Inthedropdownlistbox,youwillfind,selectingwhich, usesastaticlocalRFCmetadatarepositorywhichisrequired forthelisteneroftheWmSAPOptimizepackage.Thestatic localRFCmetadatarepositorywillthenappearintheDDIC cachepage. Important! DonotselectfromthedropdownListboxwhen creatingormodifyingalistener. Note: ThestaticlocalRFCmetadatarepositoryisonlyusedby theBAMforSAPprototype,andcannotbedirectlyutilizedby theSAPAdapteruser.
SNC Enabled SNC Quality of Service
DetermineswhetherthisservershoulduseSNC.Default:No. SNCQualityofservice,possiblevalues: Useglobalbuildindefaultsettings Plaintext,butauthorization Eachdatapacketwillbeintegrityprotected Eachdatapacketwillbeprivacyprotected Usemaximumavailablesecurity
SNC Name Authorization Service
YourownSNCnameifyoudonotwanttousethedefault SNCname.ThisisthenameyouchosewhengeneratingaPSE. CalledbytheRFClistenertocheckforauthorization.To provideapplicationspecificauthorizationhandlingtheuser mightprovideaserviceherethatimplementsspecification pub.sap.listener:listenerAuthorizationCheck.Thisservicehas toreturnGrantedinfieldaccessiftherequestshouldbe accepted.Ifnoserviceisspecifiedaccesswillbegranted.Ifan exceptionhappensduringexecutionofthisserviceora differentstringthanGrantedwillbereturnedtheaccesswill bedenied. Seepub.sap.listener:listenerAuthorizationCheck.on page 276forinformationabouttheservicespecification.
89
Field Unicode Listener RFC Trace
Description/Action EnablesordisablesthelistenertolistentoaUnicodesystem. ClickYes,ifyourSAPsystemisaUnicodesystem. WhetheryouwantRFCtracingenabledordisabled.Fora productionsystem,selectOff.WhenyouselectOn,SAP Adaptercollectstracinginrfc*.trcfilesindirectory webMethods_directory\IntegrationServer\. Fordetailedinformationaboutlogging,seeChapter 10, LoggingandMonitoring.Forinformationaboutchanging thedirectoryforthetracefiles,seeAppendix B,Server Configuration.
Log transaction status
ThisswitchcanbesettoOnorOff. IfsettoOff,thentheprocessinglogswillnotbesaved, althoughatransactionwillbecreated(ormaintained),andthe transactioncanbemonitoredlateroninthetransactionlist. Tip! SettingthisswitchtoOffreducestheamountofdiskspace neededandthetimeittakestologthetransactionstatus.Itstill allowsyoutocheckthecurrenttransactionstatusontheSAP Adapter.
Store message body
ThisswitchcanbesettoOnorOff. IfsettoOff,thenthemessagebodyoftheincomingdocument willnotbestoredtodisk,althoughatransactionwillbe created(ormaintained),andthetransactioncanbemonitored lateroninthetransactionlist. Tip! SettingthisswitchtoOffreducestheamountofdiskspace neededandofcoursethetimeittakestopersistthemessage body.ItstillallowsyoutotrackthemessagestatusontheSAP Adapter.
Important! AnRFClistenermustbeabletologintotheSAPsystemautomaticallywhen itstartsup.Additionally,iftherearenometadatayetforcalledfunctionmodulesin thecache,theremustbealoginoptiontotheRepositorySystemaswell.Otherwise,it willfailtostartuporreturnerrorswhenreceivingincomingRFCs. 5 SelectSave Listenertocommitthesesettings.
90
Listeners
Enabling Listeners
Afteryouhaveconfigurednotifications,youmustenablethelistenersothatthe associatednotificationswillcommunicateappropriatelywiththelisteneratruntime.You enablethelistenersusingtheAdministrator. TheStatuscolumnindicatesthereadinessofthelistener.IfthestatusisSucceeded,the listenerisreadytobeenabled.IfthestatusisFailed, anerroroccurredduringstartup.Ifan erroroccursduringstartup,thestatewillnotchangetoEnabledwhenrefreshingthe page.Errorsatthisstagetypicallyindicateaproblemwitheitherthelistener configurationorthenetwork.Reviewthelistenersettingsandcheckthenetwork. Formoreinformationonconfiguringlistenersandnotifications,seethesections ConfiguringanRFCListeneronpage 87andConfiguringListenerNotificationson page 99. Note: Whenyoureloadapackagethatcontainsenabledlisteners,thelistenerswillbe enabledautomaticallywhenthepackagereloads.Ifthepackagecontainsdisabled listeners,theywillremaindisabledwhenthepackagereloads.
To enable a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners.TheListenersscreenappears. SelectEnabledfromthelistintheStatefield.TheIntegrationServerAdministrator enablesthelistener. ThestatechangestoPendingenabled.AfterrefreshingtheListenerspage,you shouldseethestatechangedtoEnabled. Afteralistenerisenabled,aconnectionexistsbetweentheSAPAdapterandtheSAP system. Tip! TheEnable all suspendedlinkhelpsyouchangethestatequicklyformultiple listeners.
91
Testing the RFC Listener

UsethefollowingproceduretoverifythattheSAPsystemcansuccessfullyissuearemote functioncall(RFC)totheSAPAdapter. To test the RFC listener 1 TogglebacktoyourSAPGuisession.IfyourscreendoesnotcontainaTest Connection toolbarbutton,takethefollowingsteps. a b c 2 SelectAdministration Destinations(SM59). System Administration Administration Network RFC
OpentheTCP/IP connectionsfolder. SelecttheRFCdestinationyoupreviouslycreated.
SelecttheTest Connectiontoolbarbutton. IftheSAPsystemcansuccessfullyconnecttotheSAPAdapterRCFlistener,it willdisplayconnectioninformationasshownbelow. Ifyoureceiveanerrormessage,reviewthestepsforcreatinganRFCDestination andcreatinganRFClistenertoverifyyourconfigurationsettings.
92
Listeners
Viewing Listener Parameters

YoucanviewalistenersparametersfromtheAdministratororfromtheDeveloper.You alsocanviewthenotificationorderofalistener. To view a listeners parameters using the Administrator 1 2 3 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenerspage,clicktheViewicon forthelistenerthatyouwanttosee.
TheViewListenerscreendisplaystheparametersforthelistener.Fordescriptionsof thelistenerparameters,seeConfiguringanRFCListeneronpage 87. 4 ClickReturn toSAP Adapter Listeners toreturntothemainlistenersscreen.
To view a listeners parameters using the Developer 1 2 3 StarttheDeveloperifitisnotalreadyrunning. FromtheDevelopernavigationarea,openthepackageandfolderinwhichthe listenerislocated. Clickthelisteneryouwanttoview. TheparametersforthelistenerappearontheListener Information tab.Fordescriptions ofthelistenerproperties,seeConfiguringanRFCListeneronpage 87. To view the notification order of a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheadministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,clicktheViewicon forthelistenerthatyouwanttoview.
TheViewNotificationOrderscreendisplaystheorderofthenotificationsforthe listener.Tochangethenotificationorderforthelistener,refertotheprocedureTo editthenotificationorderofalisteneronpage 94fordetailedinstructions. 4 Click Return to SAP AdaptertoreturntotheEditListenerscreen.
93
Editing Listeners
YouusetheAdministratortoeditthelistenerinthefollowingsituations: Ifyouneedtoselectanewlyconfiguredconnection,orifyouneedtochangeany listenerpropertiesyoucanupdatethelistenerparameters. Ifyouneedtochangetheorderofthenotificationsthatareassociatedwiththe listener,seetheprocedureonhowToeditthenotificationorderofalisteneron page 94. To edit a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,makesurethatthelistenerisdisabledbeforeediting.To disablethelistener,seeDisablingListenersonpage 97. OntheListenersscreen,clicktheEditicon forthelistenerthatyouwanttoedit.
TheEditListenerscreendisplaysthecurrentparametersforthelistener.Updatethe listenersparametersbytypingorselectingthevaluesyouwanttospecify. Fordescriptionsofthelistenerparameters,seeConfiguringanRFCListeneron page 87. 5 Click Save ChangestosavethelistenerandreturntotheListenersscreen.
To edit the notification order of a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheadministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,makesurethatthelistenerisdisabledbeforeediting.To disablethelistener,seeDisablingListenersonpage 97fordetails. OntheListenersscreen,clicktheEditicon forthelistenerthatyouwanttoedit.
4 5
OntheEditListenerscreen,clickEdit Notification Order.
94
Listeners
OntheEditNotificationOrder screen,usetheUpandDown buttonstodeterminethe processingorderinwhichtheSAPAdapterinvokesthenotifications. Note: Forbetterprocessingresults,arrangeyournotificationsfromascendingto descendingorderstartingwiththemostdetailednotificationstotheleastdetailed notifications.Formoreinformationonnotificationsandtheirfiltercriteria,see DependenciesforListenerNotificationsonpage 98.
7 8
ClickSave Changestosavethenotificationorderofthelistener. Click Return to Edit ListenerstoreturntotheEditListenerscreen.
Copying Listeners
Youcancopyanexistinglistenertocreateanewlistenerwiththesameorsimilar propertieswithouthavingtotypeorspecifyallpropertiesforthelistener.Youcopy adapterlistenersusingtheAdministrator. To copy a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,clicktheCopyicon forthelistenerthatyouwanttocopy.
TheCopyListenerscreendisplaysthecurrentparametersforthelistenerthatyou wanttocopy.Namethenewlistenerandeditanylistenerparametersasneededby typingorselectingthevaluesyouwanttospecify. Fordescriptionsofthelistenerparameters,seeConfiguringanRFCListeneron page 87. 4 ClickSave Changes tosavethelistenerandreturntotheListenersscreen.
95
Deleting Listeners
Ifyounolongerwanttousealistener,usethefollowinginstructionstodeletethelistener. YouusetheAdministratortodeletelisteners. Important! IfyoudeleteanSAPAdapterlistener,anynotificationsthataredefinedtouse thelistenerwillnolongerwork.Youcannotchangewhichlisteneranotificationusesafter thenotificationisconfigured.However,youcanchangetheparametersforanexisting listener.Forinstructions,seeEditingListenersonpage 94.
To delete a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,makesurethatthelistenerisdisabledbeforedeletingit.To disablethelistener,seeDisablingListenersonpage 97fordetails. OntheListenersscreen,click forthelisteneryouwanttodelete.
TheIntegrationServerdeletesthelistener.
Suspending Listeners
Youcansuspendlistenersforanindefiniteperiodoftime.Suspendedlistenerscannotbe editedordeleted. Important! SuspendinglistenersfortheSAPAdapterhasthesameeffectasdisablingthem. Formoreinformationaboutdisablinglisteners,seeDisablingListenersonpage 97.
To suspend a listener 1 2 3 IntheAdapters menuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. OntheListenersscreen,selectSuspendedfromthelistintheStatefield.The IntegrationServerAdministratorsuspendsthelistener. TheSuspend all enabledlinkhelpsyouchangethestatequicklyformultiplelisteners. Whenyoususpendalistener,theactionmaynottakeeffectrightaway.Youmayhaveto waitaslongasthetimespecifiedintheTimeoutparameterforthelistener.Ifoneormore messagesappearonthequeuewithinthattimeinterval,theadaptermayreceiveand processthefirstmessage.
96
Disabling Listeners
Listenersmustbedisabledbeforeyoucaneditordeletethem.Youdisablelistenersusing theAdministrator. To disable a listener 1 2 IntheAdapters menuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. TheListenersscreenappears. 3 SelectDisabledfromthelistintheStatefield.TheIntegrationServerAdministrator disablesthelistener.
Whenyoudisablealistener,theactionmaynottakeeffectrightaway.Youmayhaveto waitaslongasthetimespecifiedintheTimeoutparameterforthelistener.Ifoneormore messagesappearonthequeuewithinthattimeinterval,theadaptermayreceiveand processthefirstmessage.
ThefollowingsectionsprovideinstructionsforconfiguringandmanagingSAPAdapter listenernotifications.TheSAPAdapterhasthreetypesoflistenernotificationsthatyou canconfigure: RFClistenernotifications(synchronous) ALElistenernotifications(synchronous) ALElistenernotifications(asynchronous) Formoreinformationonhowlistenernotificationswork,seeAdapterListenersand ListenerNotificationsonpage 31.
Before You Configure Listener Notifications

To prepare to configure a listener notification 1 2 InstallthewebMethodsIntegrationServerandtheSAPAdapteronthesame machine.Fordetails,seethewebMethodsSAPAdapterInstallationGuide. MakesurethatyouhavewebMethodsadministratorprivilegessothatyoucanaccess theSAPAdaptersadministrativescreens.SeethewebMethodsIntegrationServer AdministratorsGuideforinformationaboutsettinguserprivileges. StarttheIntegrationServerandtheAdministrator,iftheyarenotalreadyrunning.
97
4 5 6
UsingtheAdministrator,makesurethattheWmSAPpackageisenabled.Toverify thestatusoftheWmSAPpackage,seeEnablingandDisablingPackagesonpage 44. ConfigurealistenerusingtheAdministrator.Formoreinformationonhowto configureanewlistener,seeConfiguringanRFCListeneronpage 87. UsingtheDeveloper,createauserdefinedpackagetocontainthelistener,ifyouhave notalreadydoneso.Formoreinformationaboutmanagingpackages,seePackage Managementonpage 41.
Dependencies for Listener Notifications

Thefollowingtablelistsotherobjectsyoumustconfigureortasksyoumustcompleteto uselistenernotifications: Task 1 Configureanadapterconnection.Fordetails,see ConfiguringAdapterConnectionsonpage 56. ConfigureanRFCdestinationontheSAPsystem.For details,seeCreatinganRFCDestinationonanSAP Systemonpage 84. ConfigureanRFClistener.Fordetails,seeConfiguringan RFCListeneronpage 87. Selecttheappropriatenotificationtemplateandconfigure thenotification. Forinstructionstoconfigurenotifications,seeConfiguring ListenerNotificationsonpage 99. 5 ForasynchronousALEmessaging,youshouldcreatean IntegrationServertriggerthatsubscribestotheIntegration ServerdocumenttypethattheSAPAdaptercreatedwith theasynchronousnotification.RefertothewebMethods PublishSubscribeDevelopersGuideformoreinformation aboutusingtriggers. Enabletheadapternotifications.Forinstructionstoenable listenernotifications,seeEnablingListenerNotifications onpage 106. Developer Use this tool... Integration Server Administrator SAPsystem
Integration Server Administrator Developer
Integration Server Administrator
98
Configuring Listener Notifications

Thissectiondescribeshowtoconfigurethethreetypesoflistenernotifications. Note: RoutingnotificationsareusedwhennoRFClistenernotificationhasbeendefined. Formoreinformationaboutroutinglisteners,seeChapter 8,RoutingMessagesThrough theSAPAdapter.
RFC Listener Notification (Synchronous)

To configure an RFC listener notification 1 2 3 4 5 6 7 8 FromtheFilemenu,selectNew. SelectAdapter NotificationfromthelistofelementsandclickNext. SelectSAP AdapterastheadaptertypeandclickNext. SelectRFC Listener Notification (synchronous)fromthetemplateandclick Next. SelecttheappropriateNotification Listener Name andclickNext. Typeauniquenameforthesynchronouslistenernotificationandselectthe appropriatefolder.ClickNext. SelectaserviceandclickNext. ClickFinish. TheAdapterNotificationtemplatecreatesthefollowingitems: AnRFCsynchronouslistenernotification TwoSynchronousDocumentTypes: SynchronousReplyDocumentType SynchronousRequestDocumentType Note: YoucannoteditanyfieldsorpropertiesonthePublications Propertiestabfor theSynchronousRequestandReplyDocumentTypes.TheIntegrationServer doesnotpublishthesedocumenttypes.
99
Intheadapternotificationserviceeditor,youcanselecttheAdapter Settingstabatany timetoconfirmthefollowinglistenernotificationproperties: Adaptername Adapterlistenername Adapternotificationtemplate AdapternotificationserviceToeditthisservice,seeEditingSynchronous ListenerNotificationServicesonpage 103.
10 SelecttheFunction Searchtabtoverifyormodifythefollowing: Property Function Pattern Description AllorpartofthenameofthefunctionmoduleontheSAP system. Enterawildcardlikepatternforthefunctionmodulefor whichyouwantcreatethenotification.Youcanuseexact patterns,orpatternswithsingleormultiplewildcard characters. Group Pattern AllorpartofthenameoftheFunctionGroupontheSAP system. EnterawildcardlikepatternfortheFunctionGroupfor whichyouwantcreatethenotification.Youcanuseexact patterns,orpatternswithsingleormultiplewildcard characters. Function Name Function Description Group Name Theresultingfunctionmodulenamematchingtheprovided pattern. Thefunctionmoduledescription,ifitisavailableforthat functionmodule. Thegroupnamethefunctionmodulebelongsto.
11 Selectthe Request Field Selectiontabtospecifywhichfieldsshouldmatchthearriving messagetorunthenotification. SelectthefieldsbyselectingtheappropriateboxesintheUsecolumn.Youcanalso selectallfieldsbyusingtheCheck all rowsicon Uncheck all rowsicon . ordeselectallfieldsbyusingthe
100
12 Selectthe Reply Field Selectiontabtospecifywhichfieldsshouldmatchthereturning messagefromthenotification. SelectthefieldsbyselectingtheappropriateboxesintheUsecolumn.Youcanalso selectallfieldsbyusingtheCheck all rowsicon Uncheck all rowsicon . ordeselectallfieldsbyusingthe
13 SelecttheAdditional SettingstabtosettheForward confirm eventflag.Formore informationabouttheForwardConfirmEventFlag,seeForwardConfirmEvent Flagonpage 81. 14 SelectthePermissionstabtomanagetheaccesscontrollist(ACL)information.Usethe dropdownmenutoselecteachoftheACLtypes.Forgeneralinformationabout assigningandmanagingACLs,seethewebMethodsDeveloperUsersGuide. 15 FromtheFile menu,selectSave (orSave All).
ALE Listener Notification (Synchronous)

To configure an SAP synchronous listener notification 1 2 3 4 5 6 7 8 FromtheFilemenu,selectNew. SelectAdapter NotificationfromthelistofelementsandclickNext. SelectSAP AdapterastheadaptertypeandclickNext. SelectALE Listener Notification (synchronous)fromthetemplateandclick Next. SelecttheappropriateNotification Listener Name andclickNext. Typeauniquenameforthesynchronouslistenernotificationandselectthe appropriatefolder.ClickNext. SelectaserviceandclickNext. ClickFinish. TheAdapterNotificationtemplatecreatesthefollowingitems: AnALEsynchronouslistenernotification TwoSynchronousDocumentTypes: SynchronousReplyDocumentType SynchronousRequestDocumentType
101
Note: YoucannoteditanyfieldsorpropertiesonthePublications Propertiestabfor theSynchronousRequestandReplyDocumentTypes.TheIntegrationServer doesnotpublishthesedocumenttypes. 9 Intheadapternotificationserviceeditor,youcanselecttheAdapter Settingstabatany timetoconfirmthefollowinglistenernotificationproperties: Adaptername Adapterlistenername Adapternotificationtemplate AdapternotificationserviceToeditthisservice,seeEditingSynchronous ListenerNotificationServicesonpage 103. 10 SelecttheIDoctabtoverifyormodifythefollowing: Property IDoc type Cim type SAP system release Old IDoc type 2 Monitor IDocs Description IdentifiesthetypeofIDocexpectedbythelistener notification. TheIDoctypeextension(CIMtype/customerextension type). TheIDocrelease. TheIDocversion;uncheckedforanewversion3IDoc, checkedforoldversion2IDocs(likein3.1SAPsystems). SettoOntohavetheSAPAdapterlinktheIDocpackets TIDwiththeDOCNUMsoftheIDocsinthatpacketsothat laterALEIDocMonitoringwillbepossible.SettoOffto preventlinkingtheTIDwiththeDOCNUMS.
11 Selectthe Request Field Selectiontabtospecifywhichfieldsshouldmatchthearriving messagetorunthenotification. SelectthefieldsbyselectingtheappropriateboxesintheUsecolumn.Youcanalso selectallfieldsbyusingtheCheck all rowsicon Uncheck all rowsicon . ordeselectallfieldsbyusingthe
12 SelecttheAdditional SettingstabtosettheForward confirm eventflag.Formore informationabouttheForwardConfirmEventFlag,seeForwardConfirmEvent Flagonpage 81. 13 SelectthePermissionstabtomanagetheaccesscontrollist(ACL)information.Usethe dropdownmenutoselecteachoftheACLtypes.Forgeneralinformationabout assigningandmanagingACLs,seethewebMethodsDeveloperUsersGuide.
102
14 FromtheFile menu,selectSave (orSave All).
Editing Synchronous Listener Notification Services

Thelistenernotificationserviceisspecifiedduringtheinitialconfigurationofthe synchronouslistenernotification.Afterwardsyoumayneedtochangetheservicethatis invoked.Tochangethenotificationservice,completethefollowingsteps. Important! Beforeyouselectadifferentservice,makesurethatyouhavedisabledthe notification.Whenthenotificationisenabled,thenewserviceisutilized.Todisablethe notification,seeDisablingListenerNotificationsonpage 109.
To edit the notification service 1 2 3 4 5 FromDeveloper,intheadapternotificationserviceeditor,selecttheAdapter Settings tab. OpentheSelect Menuforthatservice. Selectanewservice. ClickOK. FromtheFile menu,selectSave (orSave All).
RFC Listener Notification (Asynchronous)

To configure an RFC listener notification 1 2 3 4 5 6 7 FromtheFilemenu,selectNew. SelectAdapter NotificationfromthelistofelementsandclickNext. SelectSAP AdapterastheadaptertypeandclickNext. SelectRFC Listener Notification (asynchronous)fromthetemplateandclickNext. SelecttheappropriateNotification Listener NameandclickNext. Typeauniquenamefortheasynchronouslistenernotificationandselectthe appropriatefolder.ClickNext. ClickFinish. TheAdapterNotificationtemplatecreatesthefollowingitems: AnRFCasynchronouslistenernotification APublishDocumentType
103
Intheadapternotificationserviceeditor,youcanselecttheAdapter Settingstabatany timetoconfirmthefollowinglistenernotificationproperties: Adaptername Adapterlistenername Adapternotificationtemplate 8 SelecttheFunction Searchtabtoverifyormodifythefollowing: Property Function Pattern Description AllorpartofthenameofthefunctionmoduleontheSAP system. Enterawildcardlikepatternforthefunctionmodulefor whichyouwantcreatethenotification.Youcanuseexact patterns,orpatternswithsingleormultiplewildcard characters. Group Pattern AllorpartofthenameoftheFunctionGroupontheSAP system. EnterawildcardlikepatternfortheFunctionGroupfor whichyouwantcreatethenotification.Youcanuseexact patterns,orpatternswithsingleormultiplewildcard characters. Function Name Function Description Group Name 9 Theresultingfunctionmodulenamematchingtheprovided pattern. Thefunctionmoduledescription,ifitisavailableforthat functionmodule. Thegroupnamethefunctionmodulebelongsto.
SelecttheRequest Field Selectiontabtospecifywhichfieldsshouldmatchthearriving messagetorunthenotification.
10 SelectthefieldsbyselectingtheappropriateboxesintheUsecolumn.Youcanalso selectallfieldsbyusingtheCheck all rowsicon Uncheck all rowsicon . ordeselectallfieldsbyusingthe
11 SelectthePermissionstabtomanagetheaccesscontrollist(ACL)information.Usethe dropdownmenutoselecteachoftheACLtypes.Forgeneralinformationabout assigningandmanagingACLs,seethewebMethodsDeveloperUsersGuide. 12 FromtheFilemenu,selectSave(orSave All).
104
ALE Listener Notification (Asynchronous)

To configure an asynchronous ALE listener notification 1 2 3 4 5 6 7 FromtheFilemenu,selectNew. SelectAdapter NotificationfromthelistofelementsandclickNext. SelectSAP AdapterastheadaptertypeandclickNext. SelectALE Listener Notification (asynchronous)fromthetemplateandclick Next. SelecttheappropriateNotification Listener Name andclickNext. TypeauniquenamefortheALEasynchronouslistenernotificationandselectthe appropriatefolder.Click Next. ClickFinish. TheAdapterNotificationtemplatecreatesthefollowingitems: AnALEasynchronouslistenernotification APublishDocumentType Intheadapternotificationserviceeditor,youcanselecttheAdapter Settingstabatany timetoconfirmthefollowinglistenernotificationproperties: Adaptername Adapterlistenername Adapternotificationtemplate 8 SelecttheIDoctabtoverifyormodifythefollowing: Property IDoc type Cim type SAP system release Old IDoc type 2 Monitor IDocs Description IdentifiesthetypeofIDocexpectedbythelistener notification. TheIDoctypeextension(CIMtype/customerextension type). TheIDocrelease. TheIDocversion;uncheckedforanewversion3IDoc, checkedforoldversion2IDocs(likein3.1SAPsystems). SettoOntohavetheSAPAdapterlinktheIDocpackets TIDwiththeDOCNUMsoftheIDocsinthatpacketsothat laterALEIDocMonitoringwillbepossible.SettoOffto preventlinkingtheTIDwiththeDOCNUMS.
105
Selectthe Request Field Selectiontabtospecifywhichfieldsshouldmatchthearriving messagetorunthenotification. SelectthefieldsbyselectingtheappropriateboxesintheUsecolumn.Youcanalso selectallfieldsbyusingtheCheck all rowsicon Uncheck all rowsicon . ordeselectallfieldsbyusingthe
10 SelectthePermissionstabtomanagetheaccesscontrollist(ACL)information.Usethe dropdownmenutoselecteachoftheACLtypes.Forgeneralinformationabout assigningandmanagingACLs,seethewebMethodsDeveloperUsersGuide. 11 FromtheFile menu,selectSave (orSave All).
Enabling Listener Notifications

Afteryouconfigurealistenernotification,youneedtoenableitusingtheAdministrator. To enable a listener notification 1 2 3 IntheAdaptersmenuintheAdministratornavigationarea,clickSAP Adapter. IntheSAP Adaptermenu,selectListener Notifications. OntheListenerNotificationsscreen,clickNointheEnabledcolumnforthelistener notificationyouwanttoenable. TheIntegrationServerAdministratorenablesthelistenernotificationanddisplaysa andYes inthe Enabledcolumn.
Testing Listener Notifications

Youcantestlistenernotificationstoensurethatyouhaveconfiguredthemcorrectly. To test listener notifications 1 2 3 ConfigurealistenerusingtheAdministrator.Forinstructionstoconfigurealistener, seeConfiguringanRFCListeneronpage 87. ConfigurealistenernotificationusingtheDeveloper.Forinstructionstoconfigurea notification,seeConfiguringListenerNotificationsonpage 99. EnablethelistenernotificationusingtheAdministrator.Forinstructionstoenablea listenernotification,seeEnablingListenerNotificationsonpage 106.
106
4 5
EnablethelistenerusingtheAdministrator.Forinstructionstoenablealistener,see EnablingListenersonpage 91. OnyourSAPsystem,invokearemotefunctioncallorsendanIDoctotheRFC destinationyourRFClistenerislisteningto.TheRFClistenerwillforwardthe receivedrequesttothematchingnotification.
Testing Publishable Document Types

Youcantestapublishabledocumenttypethatisassociatedwithanasynchronous notificationusingtherunicon intheDeveloper.Whenyoutestapublishable documenttype,youprovideinputvaluesthattheDeveloperusestocreateaninstanceof thepublishabledocumenttype.Youalsospecifyapublishingmethod(suchaspublish, publishandwait,deliver,ordeliverandwait).Developerthenpublishesadocumentand displaystheresultsofthepublishintheResultsdialogbox.Testingapublishable documenttypeprovidesawayforyoutopublishadocumentwithoutbuildingaservice thatdoestheactualpublishing.Ifyouselectapublicationactionwhereyouwaitfora replydocument,youcanverifywhetherreplydocumentsarereceived. Note: PriortorunningthePublishDocument,youneedtomakesurethatyouuncheckthe Field must exist at run-timefieldonthemsgBodyproperty.Toaccessthisfield,rightclick msgBody,selectProperties,andthenselecttheConstraintstab. Whenyoutestapublishabledocumenttype,theIntegrationServeractuallypublishesthe documentlocallyortotheBroker(whicheverisspecified). Forinstructionstotestapublishabledocumenttype,seethewebMethodsPublishSubscribe DevelopersGuide.Also,foracompletedescriptionoftheenvelopeparameterslocatedin theWmPublicfolder,seethewebMethodsBuiltInServicesReferenceGuide.Theenvelope parametersdefinethesendersaddress,thetimethedocumentwassent,passwordand certificateinformation,andotherusefulinformationforroutingandcontrol.
Viewing Listener Notifications

YouusetheDevelopertoviewlistenernotifications. To view a listener notification 1 2 IntheDeveloper,expandthepackageandfolderthatcontainthelistenernotification youwanttoview. Selectthelistenernotificationthatyouwanttoview. TheDeveloperdisplaystheconfiguredlistenernotificationintheadaptersAdapter NotificationEditor.
107
Editing Listener Notifications

YouusetheDevelopertoeditlistenernotifications,bothsynchronousandasynchronous. Wheneditingthelistenernotification,youcanalsoeditthepublishabledocumenttype associatedwiththeasynchronouslistenernotificationsortherequestandreplydocument typesthatareassociatedwithsynchronouslistenernotifications. To edit a listener notification 1 2 IntheDeveloper,expandthepackageandfolderthatcontainthelistenernotification youwanttoedit. Selectthelistenernotificationyouwanttoedit. TheDeveloperdisplaystheconfiguredlistenernotificationintheadaptersAdapter NotificationEditor. 3 Modifythevaluesforthelistenernotificationsparametersasneeded.Fordetailed descriptionsofthelistenernotificationsparameters,seeConfiguringListener Notificationsonpage 99forthespecifictypeoflistenernotificationthatyouwantto edit. Note: Becauselistenernotificationsinherentlydependonlisteners,youcannotchange alistenerforalistenernotificationafteryouconfigureit.
To edit the document types 1 2 3 IntheDeveloper,expandthepackageandfolderthatcontainthedocumenttypethat youwanttoedit. Openthelistenernotificationforthedocumentthatyouwanttoedit. SelecttheRequest Field SelectionorReply Field Selectiontabandmodifytheavailable valuesforthedocumenttypesparametersasneeded.Fordetaileddescriptionsofthe documenttypesparameters,seetheappropriateprocedureforthatlistener notificationtype.
108
Deleting Listener Notifications

IfyounolongerwanttouseaparticularSAPAdapterlistenernotification,youcandelete itbyfollowingtheinstructionsinthissection.Youdeletelistenernotifications,both synchronousandasynchronous,usingtheDeveloper. Important! Ifyoudeleteasynchronouslistenernotification,theassociatedrequestand replydocumenttypesaredeletedautomatically. Ifyoudeleteanasynchronouslistenernotification,theassociatedpublishabledocument typeisdeletedautomatically. Youcannotsolelydeletethedocumenttypesassociatedwiththesynchronousand asynchronouslistenernotifications.
To delete a listener notification 1 2 IntheDeveloper,expandthepackageandfolderthatcontainthelistenernotification youwanttodelete. RightclickthelistenernotificationandclickDelete.
Disabling Listener Notifications

YoudisablelistenernotificationsusingtheAdministrator. To disable a listener notification 1 2 3 IntheAdaptersmenuintheAdministratornavigationarea,clickSAP Adapter. IntheSAP Adaptermenu,selectListener Notifications. OntheListenerNotificationsscreen,clickYes intheEnabledcolumnforthelistener notificationyouwanttodisable.
ThelistenernotificationbecomesdisabledandNo displaysinthe Enabledcolumn.
109
Examples
Creating a Synchronous RFC Adapter Notification
ThefollowingtutorialexplainshowtoassigninboundRFCstoservicesontheIntegration Server.ItdescribesanapplicationinwhichtheSAPsystemrequestsaservicetoretrieve informationaboutaproduct. Note: AnSAPAdapterinboundcallisanoutboundcallfromtheSAPsystemspointof view.
Creating a Function Module in an SAP System

CallingaservicefromanSAPsystemrequires,ataminimum,aremotelycallablefunction modulewithadefinedsignature(imports,exports,andtables).NoABAPcoding,screen development,orotherworkisrequired. Note: ThefollowingstepsrequirethatyouhavedeveloperlevelaccessonyourSAP systemandsomebasicknowledgeoftheABAPWorkbenchandfunctionmodules.
To create a function module in an SAP system 1 2 3 4 5 UsingtheSAPGui,gototheABAP Function Library.SelectTools (SE37). ABAP Workbench
Createafunctiongroup,forexample:Z_FG01(MenuGoto/Functiongroups/Create group). EnterZ_IS_PRODUCTinfieldFunction module.ThisisthenameofyourSAPproduct retrievalfunction. SelectCreate. CompletethefollowingdialogsinaccordancewiththepoliciesgoverningyourSAP developmentenvironment.TheonlyaspectrelevanttotheSAPAdapteristhefield Processing type.SelectRemote-Enabled Moduletoallowthisfunctiontocallexternallyto theSAPAdapter. Definetheimport/exportparametersofyourfunction.Addanimportnamedsku. YoumustprovideanReference Typefield.Pickacharacterfieldwithalengthgreater than5.Forthisexample,useCHAR100. Addsixexports:name,product_type,product_length,product_width,price, availability.Again,youmustprovideReference Typefieldsforeachoftheexports. Forthistutorial,useCHAR100fortheseparameters.
110
Examples
8 9
MarkPass Valueforallparameters. Saveyourfunctionmoduleandactivateit.
Creating an RFC Adapter Notification

YouneedtoassociateaserviceontheIntegrationServerwiththeinboundRFC.The followingstepsassigntheapp:getProductDataservicetoinboundrequestsfor Z_IS_PRODUCT. To create an RFC adapter notification 1 2 3 4 OpentheDeveloperandselectNew > Adapter Notification.ClickNext. SelectSAP Adapterfromthelistofavailableadaptertypes.ClickNext. Fromthelistofavailabletemplates,selectRFC Listener Notification.ClickNext. SelectapreviouslycreatedRFClistener.ThelistenercorrespondstotheRFC destinationyouhavecreatedontheSAPsystemthathoststhefunctionmodulefor whichyouwanttocreatetheadapternotification.ClickNext. EnteranameandselectafolderwheretheRFCadapternotificationshouldbestored. ClickNext.
111
6 7
Selecttheservicethatshouldbeinvokedbythisadapternotification.(Inthiscase, app:getProductData.)ClickNextandthenFinish. OntheFunction Searchtab,intheFunction Patternfield,enterallorpartofthenameof thefunctionmoduleforwhichyouwanttocreateanRFCadapternotification.Use patternmatchingcharactersifyouareunsureofthecompletenameandwantthe SAPAdaptertosearchforseveralRFCswithsimilarnames. Forthisexample,enterZ_IS_*intheFunctionPatternfield. AlistofRFCnamesthatmatchthecriteriaisdisplayed.
SelectthenameoftheRFCforwhichyouwanttocreateanadapternotification.For thisexample,useZ_IS_PRODUCT. Note: IftheRFCyouexpecttoseeismissingfromthelist,youmightnothavedefined yourRFCConnectioncorrectly.ReviewthestepsinConfiguringAdapter Connectionsonpage 56.
ClickSaveontheDevelopertosaveyourRFCadapternotification. Leaveallotherfieldsattheirdefaultvalues.
112
Examples
Testing the Product Retrieval Function

UsethefollowingproceduretotesttheRFCyoujustcreated. To test an inbound RFC Usethefollowingproceduretotesttheproductretrievalfunction: 1 2 EnabletheRFCadapternotification. EnsurethatanRFCListenerisrunningbydoingthefollowing: a b c IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea, clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. VerifythattheRFClisteneryoucreatedfortheRFCdestinationontheSAP systemhostingZ_IS_PRODUCTshowsstatusEnabled,indicatingthatthe listenerisstartedandactive. IfthestatusisPendingenabled,refreshthelistenerscreenuntilthelistenerhas statusEnabled.Ifnolistenerappearsinthelist,refertoListenersonpage 87. 3 4 5 6 7 8 InanSAPGuisession,gototheABAP Workbench (SE37)totestyournewfunction module. EnterZ_IS_PRODUCTinfieldFunction moduleandselect Single test. IntheRFC target systemfield,typethenameofyourRFCDestination(inthisexample ISCER). Intheskufield,enteraSKU.Forthisexample,theSKUsthatareavailableareA, B,
C, D, or E.Caseisnotimportant.
Execute(F8)theRFCbyselectingtheappropriatetoolbarbuttonorselectingExecute fromtheFunction modulesmenu. Youwillreceivetheproductdatainyourexportslistsimilarasshowninthe followingfigure. Note: IfyoureceiveanerrorfromtheSAPAdapter,makesureyourRFCadapter notificationiscorrectandthatthe app:getProductData flowserviceisavailableand functional.
113
Creating a Synchronous ALE Listener Notification

IfyouneedtousetheinformationcontainedinanIDocindocumentsofanotherformat, youbuildaservicethatmapstheinformationfromfieldsintheIDoctothevariables usedbytheotherapplication.Forexample,totransferapurchaseorderfroman ORDERS02IDoctoanEDIsystem,youcreateaflowservicethatmapsinformationfrom theIDocfieldstofieldswithintheEDIsystemspurchaseorderdocument.Then,you definearoutingnotificationthattriggersthisflowservice. TocreateasamplesynchronousALElistenernotification,performthefollowing: 1 2 3 4 5 CreateanEmptyFlowServiceCalledmapOrders02 CreateanAsynchronousALEListenerNotificationforIDocTypeOrders02 DefinetheInputandOutputSignaturesforthemapOrders02Service MapFieldsfromOrders02RequestDocumenttoPurchaseOrderDocument TestingtheListenerNotificationfromtheSAPSystem
114
Examples
Create an Empty Flow Service Called mapOrders02

Usethefollowingproceduretocreateaflowservicenamedapp.idocs:mapOrders02with Developer(thisistheservicethatthesynchronousALEnotificationwillinvokebasedon theroutingrulecreatedinthenextstage). To create an empty flow service 1 2 3 IntheDeveloper,selecttheDefaultpackageandrightclicktoopentheshortcut menu.ClickNew,thenFolder,andnamethenewfolderapps. Selecttheappsfolderandcreateasubfoldercalledidocs. OntheFilemenu,clickNewandcreateanemptyflowservicecalledmapOrders02. Savetheserviceintheapps\idocsdirectory. Youwillselectthisservicewhencreatingalisteningnotification.
Create an Asynchronous ALE Listener Notification for IDoc Type Orders02

Thislistenernotificationinvokestheflowservicethatwillperformthemapping.When youcreatethelistenernotification,selecttheserviceyouhavepreviouslycreatedfor mappingtheIDoc. To create a synchronous ALE listener notification 1 2 3 4 5 6 7 8 FromtheFilemenu,selectNew>Adapter NotificationandthenclickNext. SelectSAP AdapterastheadaptertypeandclickNext. SelectALE Listener Notification (synchronous)fromthetemplateandclick Next. NamethelistenernotificationOrders02,andselecttheapp\idocsfolder. ClickNext. SelecttheserviceyoucreatedinCreateanEmptyFlowServiceCalledmapOrders02 onpage 115,clickNextandthenclickFinish. SelecttheIDoctabandchangetheIDoc typefieldtoORDERS02. Selectthe Request Field SelectiontabandclicktheCheck all rowsicon FromtheFile menu,selectSave (orSave All). .
115
Define the Input and Output Signatures for the mapOrders02 Service
ThisservicemapsanORDERS02IDoctoaspecificPurchaseOrderformat.Todothis,you needtodefinetheinputandoutputsignaturesfortheservice. To define the input and output signatures 1 2 3 OpenthemapOrders02serviceandselecttheInput/Outputtab. FortheInputfield,opentheSelectdialogandselectthe apps\idocs\Orders02RequestDocument. FortheOutputfield,opentheSelectdialogandselectthe WmSAP\sample\sap\records\PurchaseOrderdocument.
Map Fields from Orders02RequestDocument to PurchaseOrder Document

Afteryoudefinetheinputandoutputdocuments,youshouldmapfieldsfromtheinput totheoutput. To map fields from ORDERS02 to PO 1 2 Addamapstep. SelectthePipelinetabandselectoneormorefieldsfromORDERS02tomaptofields inPO.
Testing the Listener Notification from the SAP System

Beforeyoucantestthelistenernotification,youmustcompletetheproceduresinSetting UptheSAPSystemonpage 117. Totesttheflowserviceyoucreated,usetheSAPGuitosubmityoursampleIDoctothe SAPAdapter.ChecktheresultsoftheservicetoensurethattheIDocisbeingmapped correctly. IfyouwanttodebugyourserviceintheDeveloper,youcanusethesavePipelineToFileand restorePipelineFromFileservicestocaptureasubmittedIDoc To test the listener notification 1 UsetheSAPGuitosubmitanIDoctoyourflowservice.Whentheserviceexecutes, thesavePipelineToFileoperationwillmakeacopyofthepipeline(whichwillinclude yourIDoc)andsaveittoafile. DeletethesavePipelineToFileserviceandinserttherestorePipelineFromFileservice.
116
Examples
SelecttheTest Runcommandtoexecutetheflowservice.Whenitexecutes,the restorePipelineFromFileservicewillretrievethecopyofthepipelinecontainingyour IDoc,whichtheremainderoftheflowwilloperateon.
Whenyouarefinishedtesting,deletetherestorePipelineFromFileserviceandsavethe finishedflow.
Setting Up the SAP System

Note: YouperformthefollowingproceduresontheSAPsystem.Duetodifferencesamong SAPsystemsversionsandacrossplatforms,theseprocedurescandifferslightlyfrom whatyouneedtodo.Theyshouldbeusedasageneralguidetothestepsyouneedto take. TosetupanSAPsystemtosendIDocstotheSAPAdapter,usetheSAPGuitoperformthe followingsteps: 1 2 3 4 5 CreateanRFCDestination DefineaLogicalPort CreateaPartner CreateaPartnerProfile CreateaDistributionModelforthePartnerandMessageType
Create an RFC Destination YoumustcreateanRFCdestinationontheSAPsystem.Forinstructionsonhowtocreate anRFCDestination,refertoCreatinganRFCDestinationonanSAPSystemonpage 84. Define a Logical Port Thelowerlevelnetworkingrequiresthatasystemportnumberbeassociatedwiththe RFCdestination.Thelogicalportidentifiestheporttowhichmessagesaresent.The logicalportcanonlybeusedifanRFCDestinationwaspreviouslycreated. YoucandefineauniquelogicalportusingWE21(alternatively,usethefollowingmenu pathtodothis:Main screen Tools Business Communication IDoc-Basis IDoc Port Definition). 1 2 3 4 SelecttheTransactional RFC treeitemandclickCreate. Onthetoolbar,click New Entries. Eitherselectyourowndescriptiveportnameorletthesystemgenerateone. EntertheIDocversionyouwanttosendviathisport,theRFCdestinationyoujust created,andashortdescriptionofyourlogicalport,andthensavetheinformation.
117
Create a Partner AlogicalsubsystemmanagesoneormoreRFCDestinations.Youcancreateapartner (logicalsystem)usingSPRO_ADMIN(alternatively,usethefollowingmenupathtodothis: Main screen Tools AcceleratedSAP Customizing Project Management). 1 2 SelectSAP Reference IMG. Expandthefollowingnodes:Basis Components Application Link Enabling (ALE) Sending and Receiving Systems Logical Systems Define Logical System.(Youcan alsouseSALEandselectthepathdescribedabove,startingwithApplicationLink Enabling(ALE). SelectDefine Logical System. ClickNew Entries. Enteraninformativenameforyourpartnerandprovideashortdescription.After savingthepartnerinformation,assignittoaworkbenchrequest.
3 4 5
Create a Partner Profile UseWE20tocreateapartnerprofile(alternatively,usethefollowingsequencetodothis: Main screen Tools Business Communication IDoc-Basis IDoc Partner profile). 1 2 3 4 5 6 7 8 9 SelecttheLS (logical system) partnertypeinthetreeviewandclickCreate. EnterinthePartnerfieldthepartneryoucreatedinCreateaPartneronpage 118, andsavethepartnerprofile. Belowtheoutboundparametertablecontrol,clickInsert entry. EnterthemessagetypeoftheIDoc,(forexample:MATMAS). EnterthelogicalreceiverportyoucreatedbeforeandenterthebasictypeoftheIDoc, (forexample:MATMAS03). Savetheoutboundparameter. Belowtheinboundparametertablecontrol,clickInsert entry. EnterthemessagetypeoftheIDoc,(forexample:MATMAS)andtheprocesscode,(for example:MATM). Savetheinboundparameter.
118
Examples
Create a Distribution Model for the Partner and Message Type Afteryoudefineapartnerandpartnerprofile,youcancreateadistributionmodelthat triggersthecreationofacommunicationIDoc. IfyouareusingSAPsystem4.5orearlier,youcanuseBD64tocreatethedistribution model(alternatively,usethefollowingsequencetodothis:Main screen Tools Business Framework ALE Customizing). 1 2 3 4 OpentheCross-Application Componentsfolder,thentheDistribution (ALE) folder,thenthe Distribution Customer Model folderinthetreeview. SelectMaintain customer distribution model. CreateanewmodelusingModel Create.
Addamessagetypetoyourmodel,enterthesenderinthedialogbox(forexample:, CERCLNT800),enterthereceiver(yourlogicalsystem),andthemessagetype(MATMAS).
IfyouareusingSAPsystem4.6orlater,youcanuseBD64oralternatively,thefollowing procedure: 1 2 3 4 5 6 7 8 9 IntheMainscreen,selectTools SelectSAP Reference IMG. Expandthefollowingnodes:Basis Components Distribution (ALE) Modelling and Implementing Business Processes Maintain Customer Distribution Model. SelectMaintain Customer Distribution Model(BD64). Changeintotheeditmode. SelectCreate modelview. Enterashorttextstringandatechnicalnameforyournewmodelview. SelectyournewmodelviewinthetreeDistribution Model,andselectAdd message type. Inthedialogbox,enterthesender(forexample:CERCLNT800),thereceiver(your logicalsystem),andthemessagetype(MATMAS). AcceleratedSAP Customizing Project Management.
119
120
CHAPTER
Generating Document Types

Generating Document Types for RFC Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Generating Document Types for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
121
C H A P T E R 7 G e n e r a t i n g D o c u m e n t Ty p e s
Generating Document Types for RFC Structure

ThisfeatureallowsyoutogenerateanRFCdocumenttypeforanRFCstructuredefinedat anSAPsystem. Note: Todothis,youmusthavetheSAPAdapterplugininstalledonthemachinethat hoststheDeveloper.
To create a document type using the DDIC 1 2 3 4 5 6 7 OpentheDeveloper. OntheFilemenu,selectNew. OntheNewpanel,selectSAP Document TypeandthenclickNext. OntheNewSAPDocumentTypepanel,selectRFCandclickNext. SelecttheSystem IDandclickNext. SelecttheSAP Structure.Ifnostructureshavebeencached,youmusttypethestructure nameintothefield.ClickNext. Namethedocumenttypeandselectthefolderwhereitwillbeplaced.ClickFinish.
Generating Document Types for IDocs

Create an IDoc Document Type Using the DDIC
YoucancreateanIDocdocumenttypeusingthemetadatadescribingtheIDocstructure thatisavailableintheDDIC.ThisisthebestapproachforcreatinganIDocdocument type. Note: Todothis,youmusthavetheSAPAdapterplugininstalledonthemachinethat hoststheDeveloper.
To create a document type using the DDIC 1 2 3 4 OpentheDeveloper. OntheFilemenu,selectNew. OntheNewpanel,selectSAP Document TypeandthenclickNext. OntheNewSAPDocumentTypepanel,selectIDocandclickNext.
122
5 6 7
SelecttheSystem IDandclickNext. SelecttheIDoc type.IfnoIDocshavebeencached,youmusttypetheIDoctypeintothe field. Completetheremainingfieldsasfollows: Field Cimtype SAPsystemrelease OldIDoctype2 Description/Action TheIDoctypeextension(CIMtype/customerextension type). TheIDocrelease. TheIDocversion;uncheckedforanewversion3IDoc, checkedforoldversion2IDocs(likein3.1SAPsystems).
Oroptionally,leavethemblank.ClickNext. 8 Namethedocumenttypeandselectthefolderwhereitwillbeplaced.ClickFinish.
Generating an IDoc Document Type from a DTD

Note: IfyouareusingSAPsystemversion4.6Aorhigher,youcancreateaDTDforanIDoc fromtransactionWE60.(SeeyourSAPdocumentationforprocedures).Ifyouwantto generateadocumenttypefromaDTDthatyouhavecreated,youmustfirstcreatean XMLfilethatdefinesarootelementandpointstothisDTD.(UsetheXMLfilesthatSAP providesasguides.)UsethisXMLfiletobuildyourdocumenttype.
To create a document type from an IDoc DTD 1 2 3 4 OpentheDeveloper. OntheFilemenu,selectNew. OntheNewpanel,selectDocument TypeandthenclickNext. OntheNew Document Typepanel,dothefollowing: a b IntheFoldertree,selecttheFolderintowhichyouwanttosavethedocumenttype definition. IntheNamefield,typeanameforthedocumenttypeusinganycombinationof letters,numbers,and/ortheunderscorecharacter.(Youmightwanttoincludethe nameoftheIDocinthename.)
5 6
SelectNext OntheXML Format panel,selectLocal DTDorXML Document,andpressNext.
123
7 8 9
Fromhttp://ifr.sap.comyoucandownloadthecorrespondingXMLfileorDTDfile(or schema)toanydirectoryyourdeveloperhasaccessto. SelectFinish. IfyourIDocisearlierthanVersion3,editthedocumenttypetoremovethe40 designationfromthecontrolheaderelement.Forexample,changeEDI_DC40to EDI_DC.
10 ClicktheSavebutton.
Generating a Document Type from a Sample IDoc

IfyoudonothaveaccesstoanSAPsystemorifyoudonothave(orcannotcreate)aDTD foryourIDoc,youwillhavetogenerateyourdocumenttypefromasampledocument thatyousubmittotheDeveloperatdesigntime.Ifyouhavetousethisoption,youmust obtain(orcreate)acomprehensivesampledocumentbeforeyoubeginbuildingthe service.ThesampledocumentshouldcontainexamplesofallpossiblefieldsintheIDoc. (Fieldsthatarenotrepresentedinthesampledocument,willnotappearinthedocument type.) To save a pipeline image capturing the IDoc 1 2 3 4 OpentheDeveloper. OntheFilemenu,selectNew. OntheNewpanel,selectFlow ServiceandthenclickNext. OntheNew Flow Servicepanel,dothefollowing: a b IntheFoldertree,selecttheFolderintowhichyouwanttosavethedocument type. IntheNamefield,typeanameforthedocumenttypeusinganycombinationof letters,numbers,and/ortheunderscorecharacter.(Youmightwanttoincludethe nameoftheIDocinthename.)
5 6 7
PressFinish. NowswitchtotheemptyFlowServiceyoujustcreated. Click ontheFlow Panetoolbar,andselectthepub.flow:savePipeline service.(Ifthis servicedoesnotappearinthelist,selectBrowsetofindit.)Thisservicewillcopythe contentsofthepipelinesothatyoucanretrieveitinalaterstage.(Lateronthe savePipelinestepwillbedeletedfromyourflowagain.Itspurposeissimplytocapture acopyoftheIDocitisnotapermanentpartofyourflow.) SelectthePipelinetab.
124
Selectthe$namevariableunderService In,andclick
onthetoolbar.
10 TypeanameforthesavedpipelineandselectOK. 11 Click tosavetheflowservice.
12 SendyoursampleIDoctothisserviceasdescribedbelow: UsetheSAPGuiortheutilityat/WmSAP/submitIDocXML.htmltosubmityoursample IDocorsimplysendanIDocoverHTTPtotheroutinglistener.Specifysender,receiver, andmsgTypeasspecifiedfortheroutingnotificationthatshouldinvokethe app:mapOrders02service.Formoreinformationonhowtocreatearoutingnotificationsee ConfiguringaRoutingNotificationonpage 134. Makesurethatthedocumentyousubmitisacomprehensiveexamplethatcontainsall possiblefieldsforthatIDoc.Whentheroutinglistenerreceivesthisdocument,itinvokes theflowserviceyoucreatedabove,whichcapturestheIDocbymakingacopyofthe pipeline.Inthenextstep,youwillretrievethesavedimageofthepipeline. Note: ThepipelineimagecreatedbythesavePipelineoperationisstoredinmemoryandcan berecalledbyanysubsequentservice.However,theimageisnotstoredondisk.Ifthe serverisrestarted,itwillnolongerbeavailable.Youcancreateapermanentcopyby usingsavePipelineToFileinstead.
Use the following procedure to retrieve the pipeline image you created: 1 2 3 IntheDeveloper,createanewFlowthesameway,youcreatedapp.idocs:mapOrders02 SelecttheFlowtab. Select ontheFlow Panetoolbarandselectthepub.flow:restorePipelineservice.(If thisservicedoesnotappearinthelist,selectBrowsetolocateit.)Thisservicewill retrievethecontentsofthepipelineyousavedpreviously. Setinputfield$nameofthisservicetothenameofthesavedpipelineandselectOK. Asthenextstepofthisserviceinsertpub.xml:xmlNodeToDocument (tobefoundalsointhe WmPublicPackage),iftheIDocwassenttotheSAPAdapterviahttp,or pub.sap.idoc:iDocToDocument(tobefoundintheWmSAPPackage),iftheIDocwassentto theSAPAdapterfromanSAPsystemviatRFCorfromthesamplepage /WmSAP/submitIDocXML.html. Click tosavethisflowservice.
4 5
125
ExecutethisserviceandthenselecttheResultstabandlocatethedocument variable.It shouldcontainthedataofyourIDoc. NowcreateanemptyDocumentTypeandcopytheIDocstructurejustcaptured: a b c Selecttherootdocumentdefinedwithindocument.Inthisexample,theroot documentisORDERS02. Select Edit Copytomakeacopyoftherootdocument.
Nowswitchbacktotheemptydocumenttypeandmarktheemptypaneonthe righthandside.SelectEdit PastetopastethestructureofthecapturedIDocinto yourdocumenttype. Click tosavethisdocumenttype.
126
CHAPTER
Routing Messages Through the SAP Adapter

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Routing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Sending an RFC from an SAP System to the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . 140 Sending a BAPI from an SAP System to the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . 146 Sending IDocs with ALE from an SAP System to an SAP Adapter . . . . . . . . . . . . . . . . . . . 149 Routing RFCs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Routing BAPIs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Routing IDocs Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Mapping IDocs to Other Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Content-Based Routing and Mapping for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Routing Arbitrary XML Documents Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . 166
127
CHAPTER 8 Routing Messages Through the SAP Adapter
Introduction
ThischapterdescribeshowtoroutemessagesthroughtheSAPAdapter. WhentheSAPAdapterreceivestheIDocorRFC,itmatchesthesender,receiver,and messagetypeassociatedwiththeIDocorRFCtoitsroutingnotifications.Whenitlocates amatchingroutingnotification,thisisinvokedtoroutetheIDocorRFC.
Thischapterincludesinformationabouthowto: Createandmaintainroutingnotifications Updateservicesthatprocessroutingnotifications MapIDocstootherformats UsecontentbasedroutingforIDocsandarbitraryXMLdocumentsaswellas outboundmappingforIDocs Forspecificinformationabouthowto: Route... RFCs Through the SAP Adapter, see... SendinganRFCfromanSAPSystemtotheSAPAdapteron page 140andRoutingRFCsThroughtheSAPAdapteron page 149 SendingaBAPIfromanSAPSystemtotheSAPAdapteron page 146andRoutingBAPIsthroughtheSAPAdapteron page 103
BAPIs
128
Overview
Route... IDOCs
Through the SAP Adapter, see... SendingIDocswithALEfromanSAPSystemtoanSAP Adapteronpage 149andRoutingIDocsthroughtheSAP Adapteronpage 121 RoutingArbitraryXMLDocumentsThroughtheSAPAdapter onpage 166
XML
Overview
Normally,theRFCsandIDocssenttotheSAPAdapterfromanSAPsystemareassigned toaspecificservicebyanadapternotification.However,insomecases,youmightwantto routeanRFCorIDocthroughtheroutinglistener. TheSAPAdapterincludesadefaultroutinglistenerthatmanagestheroutingof messages.Itdetermineshowandwheretorouteamessagebasedonroutingnotifications thatyoudefine.Eachroutingnotificationisassociatedwithatransportthatwillbechosen andinvokedwhentheroutingnotificationiscalled. Whentheroutinglistenerreceivesamessage,itperformsaroutingnotificationlookup. Afterlocatingtheroutingnotificationfortheincomingmessage,thespecifiedoutbound transportgetsinvoked. Routingnotificationsindicatehowamessageistobeprocessed.Eachroutingnotification isuniquelyidentifiedbyitssender,receiver,andmessagetype.WhentheSAPAdapter receivesamessage,itperformsaroutingnotificationlookuptomatchthesender,receiver, andmessagetypeoftheincomingmessagewiththesender,receiver,andmessagetypeof theexistingroutingnotifications. Ifamatchingroutingnotificationisfound,theSAPAdapterprocessesthemessageasthe routingnotificationindicates.Ifaroutingnotificationisnotdefinedforthemessage, processingofthemessagewillbeabortedwithanexceptionthrown. Theroutingnotificationidentifiesatransport,whichindicateshowandwhereamessage istoberouted.Thetransportsyoucanspecifyallowyoutorouteamessagetoaservice, routeanIDoctoanSAPsystemviatRFC,routeanRFC/BAPItoanSAPsystemvia RFC/tRFC,orpostanIDocXML,RFCXML,orbXMLmessagetoaURL.
129
Components of a Routing Notification

Aroutingnotificationcontains:
1 2 3
Sender,receiver,andmessagetype. AflagthatindicateswhethertheConfirmeventshouldbeforwardedtothe receiver. AflagthatindicatesifincomingIDocsshouldbetrackedtolaterALE monitoringfromthecallingsystem(Takeseffectonlyiftherequestwas receivedviaaRFClistener). Howtoroutethemessage;thatis,thetransport. AdditionalParametersbasedontheselectedtransport.
4 5
Sender, Receiver, and Message Type

Thisinformationuniquelyidentifiesaroutingnotification.Theroutinglistenermatches incomingmessagestothesefieldstolocatetheroutingnotificationtoprocessthe incomingmessage. Whenamessageissubmitted,itmustprovidetheroutinglistenerwithsender,receiver, andmessagetypevalues.Thesender,receiver,andmessagetypevaluescontainthe followinginformation: Value sender receiver message type Description Anarbitrarystringthatindicateswhosentthemessage. Anarbitrarystringthatindicatesthemessagesdestination. Identifiesthetypeofinformationthemessagecontains(for example:apurchaseorder,acreditmemo,aninvoice,andso forth)
130
Overview
Note: FortheMessagetypesORDERSandORDRSP,asamplecontentbasedrouting serviceisshippedwiththeSAPAdapter. Thisreplacesthesender/receiverinformationfromtheIDoccontrolrecord(SNDPRNand RCVPRN)bypartnerinformationfromtheE1EDKA1segment.Ifthisisnotdesired, disablethisContentBasedRoutingfromAdapters> SAP Adapter>Routing/Mapping. Youcanwriteyourownserviceforroutingbasedonthefieldswhichareusedinyour environment.YoucanuseContentBasedRoutingforthispurpose. RefertoConstructinganIDocwiththeSAPJavaIDocClassLibraryonpage 194and Appendix D,BuiltinServicesfortheAPIstoparsetheIDoc.
Forward Confirm Event Flag

RoutingnotificationssupporttheforwardConfirmeventfeatureasdescribedatForward ConfirmEventFlagonpage 81. Acallsequenceinthiscasecouldbeasfollows: 1 2 Theclientcreatesa24alphanumericGUID(orcallspub.sap.client:createTIDtoobtainone fromtheR/3system). TheclientsendsthedocumenttooneoftheInboundProcesses(forexampleanIDoc XMLtothepub.sap.transport.ALE:InboundProcess)andpassestheTIDalongintheheader fieldX-TID: <tid>.Theroutingnotificationwhichprocessesthismessageshould havetheForward ConfirmTID Event flagsettotrue. Ifandonlyiftheclientreceivesareturncode200fromtheSAPAdapterinstep2,it callsthesameInboundProcessagainwith$actionsetto4(Confirm)likethis:
GET /invoke/pub.sap.transport.ALE/InboundProcess?$tid=<tid>&$action=4 HTTP/1.0
Thisachievestwothings:ThestateintheSAPAdapterstransactionstoreissetto Confirmed,andtheentryinthereceivingSAPsystemstRFCchecktable (ARFCRSTATE)iscleanedup.ThismaybeimportantfortRFCperformance,ifthe SAPsystemreceiveslargenumbersofdocuments. 4 Iftheclientreceivesanerrorreturncodeinstep 2ornoresponseatall,itmaylater resubmitthesamedocument(usingthesameTID)withoutneedingtofearduplicate processing.Then,afteroneofthesubsequenttrieshasfinallysucceeded,theTIDcan beconfirmedasdescribedinstep 3.
Note: IfthedocumentissentanothertimeaftertheConfirmeventhasalreadybeen executed,thiswillleadtoaduplicatedocument!TheConfirmeventshouldonlybecalled iftheclientknowsthatthedocumenthasbeenprocessedwithouterrorandwilltherefore neverresubmitthisdocumentagain.
131
Routing Notification Order

AroutingnotificationisexecutedwhenitsSender,Receiver,andMessage Typevaluesmatch anincomingdocumentsvalues.Whenoneormoreofthosevaluesisawildcard(*),then theroutingnotificationismatchedandexecutedbasedonitsvalueprecedence. Youcanchangethisprecedenceorderbymodifyingthenotificationorderdefinedforthe routinglistener.
Considerations for Routing Notifications

Fortheroutinglistener,configureadefaultnotificationthatprocessesallmessagesthat arenotassociatedwithanyothertypeofSAPAdapternotification.Fromthe Administrator,edittheroutinglistenersnotificationorderlistandplacethedefault notificationlast.Forinstructionsonhowtoconfigureanotification,seeRouting Notificationsonpage 134.Forinstructionsonhowtoeditthenotificationorderlist,see RoutingNotificationOrderonpage 132.
Using Wildcards as Routing Criteria

Youcanuseasingleasteriskcharacter(*),knownasawildcard,fortheSender,Receiver,and Message Typevaluesinaroutingnotification.Awildcardmatchesanyvaluethatmaybe submittedwithanincomingdocument.Youcan: UseawildcardfortheSenderparametertoserveasacatchallroutingnotification foraspecificcompany.Forexample,supposethatyouwanttoexecuteaparticular routingnotificationforalldocumentsfromXYZCompany.Youdonotnecessarily wanttodefineroutingrulesforeachmessagetypethatmightbesentfromXYZ Company,soyouusethewildcardcharacter(*)fortheMessage Type. Useawildcardforallparameters(Sender,Receiver,andMessage Type)toserveasalast resortroutingrule.Thisroutingrulewillbeexecutedwhennootherroutingrules matchtheincomingdocument.
Example
Supposethatyouhaveroutingnotificationssetupwiththefollowingvaluesand notificationorder: Sender
1 2 3
Receiver partner1 partner1 *
msgType ORDERS ORDERS ORDERS
CERCLNT800 * CERCLNT750
Ifamessagearriveswiththefollowingvalues:
132
Overview
Sender=CERCLNT800 Receiver=partner1 msgType=ORDERS itwillberoutedaccordingtothefirstroutingnotificationasithasahigherranking comparedtothesecondroutingnotification. Analogously,amessagewiththevalues: Sender=CERCLNT750 Receiver=partner1 msgType=ORDERS wouldberoutedaccordingtothesecondnotification,notthethird. To edit the notification order of a listener 1 2 3 IntheAdaptersmenuinthenavigationareaoftheadministrator,clickSAP Adapter. IntheSAP Adaptermenu,clickListeners. Selecttheroutinglistener(wm.sap.internal.ls:routingListener)andchangetheStateto Disabled. ClicktheEditicon fortheroutinglistener.
4 5 6 7 8 9
OntheEditListenerscreen,clickEdit Notification Order. OntheEditNotificationOrder screen,usetheUpandDown buttonstodeterminethe processingorderinwhichtheSAPAdapterinvokesthenotifications. ClickSave Changestosavethenotificationorderofthelistener. Click Return to Edit ListenerstoreturntotheEditListenersscreen. ClickReturn to SAP Adapter ListenerstoreturntotheListenersscreen.
10 ChangetheStateoftheroutinglistenertoEnabled.
133
Routing the Message (Transport)

ThetransportindicateshowtheSAPAdapterwillroutethemessage(forexample,routeit toaserviceonthelocaloraremotehost).Thetransportcanbeoneofthefollowing: Transport IS ALE RFC XML BAPI Description RoutesthemessagetoaserviceonthelocalIntegrationServer. RoutesanIDoctoanSAPsystemviatRFC. RoutesanRFCtoanSAPsystemviaRFCortRFC. PostsabXML,IDocorRFCXMLtoaURL. RoutesaBAPItoanSAPsystemviaRFCortRFC.
Basedonthetransportyouselect,theNotificationEditordisplaysadditionalfields requiredbytheselectedtransport.
Routing Notifications
Configuring a Routing Notification
Usethefollowingproceduretocreatearoutingnotification. To create a routing notification 1 2 3 4 5 6 7 8 OpentheDeveloperandselectNew Adapter Notification.ClickNext.
SelectSAP Adapterfromthelistofavailableadaptertypes.ClickNext. Fromthelistofavailabletemplates,selectRouting Notification.ClickNext. Selecttheroutinglistenerwm.sap.internal.ls:routingListener.ClickNext. Enteranameandselectafolderwheretheroutingnotificationshouldbestored.Click Next. Selecttheservicethatshouldbeinvokedbythisroutingnotification.ClickNextand thenclickFinish. TypeinvaluesforfieldsSender,Receiver,andMessage Typetoassigntherouting notificationforcorrespondinginboundmessages. SelectoneofthefollowingtransportsfromtheTransportfieldandspecifythe additionalinformationthatisspecifictothetypeoftransportyouselect.For informationabouttheadditionalparametersthatyouneedtosupplyforeach transport,refertothepageindicatedbelow.
134
Select this transport... IS ALE RFC BAPI XML
To... Routethemessagetoaservice. RouteanIDoctoanSAPsystem RouteanRFCtoanSAPsystem RouteaBAPItoanSAPsystem PostabXML,IDocorRFCXMLoranyarbitrary XMLdocumenttoaURL.
Page 135 136 136 137 138
Note: AllbuttheIStransportwilloverridetheserviceyouassignedtotherouting notificationinstep 6. 9 ClickSaveontheDevelopertosavetheroutingnotification.
10 EnabletheroutingnotificationthroughtheIntegrationServerAdministrator.
IS Transport
Usethistransporttoroutemessagestoanotherservicethatexecutesonthelocalmachine oronaremoteIntegrationServer.Theentirepipelineissubmittedtothespecifiedrouting notificationservice.IfyouconnecttoaremoteIntegrationServer,youshouldeditthe assignedserviceofthisroutingnotificationandaddaMAPstepbeforetheinvokestep pub.remote:invoke,whereyoudropallunnecessaryparametersfromthepipelineso thattheamountofdatasentoverthenetworkisassmallaspossible.TheISTransport supportstheForwardConfirmeventfeature.Incaseof$actionsetto4(Confirmevent), theassignedserviceiscalledasecondtime.Youcanaddpreandpostprocessingstepsto thepipelineifyouwraptheserviceyouwantinvokeandassignthewrapperservicetothe routingnotification. Tip! WhensendinganIDocoranRFCbetweentwoSAPAdaptersusingtheIStransport,if thereceivingSAPAdapterisofalowerreleasethan6.5andyouaresendinganIDoc,you needtoaddasanadditionalinvokesteptheservicepub.sap.idoc:iDocToTables.Thisis becauseolderSAPAdapterreleasesdonotunderstandthenewinternalIDocformat,but insteadexpectthetwotablesIDOC_CONTROL_REC_40 and IDOC_DATA_REC_40.
135
ALE Transport
UsethistransporttorouteanIDoctoanSAPsystemviatRFC.Beforeyoucanroutean IDoctoanSAPsystem,youmustdefinetheRFCconnectiontothatSAPsystem.For instructions,refertoConfiguringAdapterConnectionsonpage 56. SettheConfigureALETransportparametersasfollows: Key serverName Value NameoftheSAPsystemtowhichyouwanttoroutetheIDoc. SelectanRFCconnectionaliasfromthedropdownlist. ThedropdownlistcontainstheRFCconnectionaliasesasdefined ontheSAPAdapter.ForinstructionsonhowtodefineanRFC connectiontoanSAPsystem,refertoConfiguringAdapter Connectionsonpage 56.
RFC Transport
UsethistransporttorouteanRFCtoanSAPsystemviaRFCortRFC. Setthetransportparametersasfollows: Key serverName Value NameoftheSAPsystemtowhichyouwanttoroutetheRFC. SelectanRFCconnectionaliasfromthedropdownlist. ThedropdownlistcontainstheRFCconnectionaliasesasdefined ontheSAPAdapter.ForinstructionsonhowtodefineanRFC connectiontoanSAPsystem,refertoConfiguringAdapter Connectionsonpage 56.
136
BAPI Transport
UsethistransporttorouteanBAPItoanSAPsystemviaRFCortRFC. Setthetransportparametersasfollows: Key serverName Value NameoftheSAPsystemtowhichyouwanttoroutetheBAPI. SelectanRFCconnectionaliasfromthedropdownlist. ThedropdownlistcontainstheRFCconnectionaliasesasdefined ontheSAPAdapter.ForinstructionsonhowtodefineanRFC connectiontoanSAPsystem,refertoConfiguringAdapter Connectionsonpage 56. Processing restrictions Processingrestrictions:SomeBAPIscanbecalledbothsynchronouslyand asynchronously.Callerscanchoosehowtheywanttoexecuteacallbyspecifyinga transactionidintheXMLheader(seeAppendix G,UsingBizTalkEnvelopeswiththe SAPAdapter).Ifyouonlywanttoallowonespecifictypeofcall(forexamplefor performancereasonsonlyasynchronouscalls,orforadministrationreasonsonly synchronouscalls).Youcandefinerestrictionsusingthedropdownlist: no restrictions synchronous only Callermaydecidetosendbothsynchronous andasynchronouscalls. Callermayonlysendcallswithouta transactionID.MessageswithatransactionID (asynchronousmessages)arerejectedandan XMLerrormessageisreturned. Callermayonlysendcallswithatransaction ID.MessageswithoutatransactionID (synchronousmessages)arerejectedandan XMLerrormessageisreturned.
asynchronous only
137
XML Transport
UsethistransporttopostanSAPIDocorRFCXMLtoaURL. Setthetransportparametersasfollows: Key url xmlType Value URLtowhichyouwanttoposttheXMLmessage. SelectbetweentheXMLdialectsSAPXML,bXML,ValuesXML, ArbitraryXMLorSOAPXRFC(XRFCwithSOAPenvelope). IfyouselectSAP-XMLthecontenttypeissettoapplication/xsap.idoc (respectively .rfc).Thereforethereceivingserverhas tounderstandthiscontenttype.(Thiscanbeoverriddenusingthe followingflag.) IfArbitrary XMLisselected,thetransportexpectstheXML documentasstringinthevariablexmlData. useTextXml FlagthatallowsyoutooverwritethecontenttypeofbXML,SAP XMLtotext/xml,ifsettotrue.Thecheckboxisdisabledforother dialects. FlagthatallowsyoutoforcetherenderersofbXML,SAPXMLto usetheencodingutf8,ifsettotrue.Thecheckboxisdisabledfor otherdialects. SetthisflagifyouwanttousetheBAPIXMLformat.(Thisfieldis onlyactivewhenusingthebXMLdialect.) Thenameofthebusinessobjecttowhichthecallshouldbe mapped.Thisvalueiscasesensitive.(Availableonlywhenusing thebXMLdialectandtheBAPIformat.) ThenameoftheBAPImethod,towhichthecallshouldbe mapped.Thisvalueiscasesensitive.(Availableonlywhenusing thebXMLdialectandtheBAPIformat.) Anoptionalparameterthatallowsyoutospecifyausernamefor authenticationontheremoteWebsystem. Anoptionalparameterthatallowsyoutospecifyapasswordfor authenticationontheremoteWebsystem.
useUTF8
useBAPI objectName
bapiName
httpUser httoPassword
138
Tip! WhensendinganIDocbetweentwoSAPAdaptersviaXMLtransport,use
http://<hostname>:<port>/invoke/pub.sap.transport.ALE/InboundProcessas
URL. WhensendinganRFCtoasecondSAPAdapteroverHTTP,use
http://<hostname>:<port>/invoke/pub.sap.transport.RFC/InboundProcessas
URL. Whentheroutinglistenerreceivesamessageforwhichitcannotlocatearouting notification,itlogsthemessageinitstransactionstoreandthrowsanException.
Disabling Routing Notifications

Usethefollowingproceduretodisablearoutingnotification.Whenyoudisablearouting notification,allroutingserviceandruleinformationispreserveduntilyoureenableit. Butincomingmessagesforthissender/receiver/msgTypecombinationwillnotberouted bytheSAPAdapteraslongastheroutingnotificationisdisabled. To disable a routing notification 1 2 3 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickListener Notifications. Locatetheroutingnotificationthatyouwanttodisable.UnderEnabled,clickYesuntil itturnstoNo.
Deleting Routing Notifications

Whenyounolongerneedaroutingnotification,youcandeleteit.Performthefollowing proceduretodeletearoutingnotification. Note: Whenyoudeletearoutingnotification,theSAPAdapterdoesnotdeletetheservice thatisassociatedwiththeroutingnotification.
To delete a routing notification 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickListener Notifications.
139
Selecttheroutingnotificationyouwanttodeleteandclickthe column.
iconintheDelete
Editing a Routing Service

Whennecessary,youcanwrapthetransportserviceintoacustomizedservicebefore assigningittoaroutingnotification.Youcanedityourwrapperservicetoincorporate additionaloperationsbeforeorafterthetransportdeliversthemessage.Forexample,you caninsertapostprocessingorpreprocessingservice,oryoucanincludesomeerror handlingoperationsafterthetransportservice. Youcanupdatetheflowservicetodigitallysignamessagebeforeitisrouted.Or,ifyou wanttoFTPanIDocinEDIflatfileformat,youwouldinsertthestep pub.sap.idoc:encodeString.IftheoutbounddatashouldbeanXMLdocument,youwoulduse pub.sap.idoc:encodeinstead,oryourownmappingservicethatcreatestheformatofyour choice.
Sending an RFC from an SAP System to the SAP Adapter

YoucanonlyrouteanRFCifyouprovideavalidSBCHEADERwithyourfunctioncall.To routeRFCsthroughtheroutinglistener,youmustincludeaheadertablethatcontains informationthattheroutinglistenerusestoroutetheRFC. Note: BeforetheroutinglistenercanreceiveanRFC,youmustdefineanRFClistenerfor theRFCdestinationdefinedatthecallingSAPsystem.Forinstructions,referto Listenersonpage 87. TosendanRFCtotheroutinglistener,youmustconfiguretheSAPsystemtoregisterthe RFClistenerasanRFCdestination.ForinstructionsonhowtocreateanRFCDestination, refertoCreatinganRFCDestinationonanSAPSystemonpage 84.
The SBCHEADER Table

YoucanwriteanABAPwrapperthatcallsafunctionmodulewithanRFCdestinationand addanadditionaltabletothecallstatement. Note: Thistablemustnotbedefinedinthefunctioninterface.
140
ThenameofthetablemustbeSBCHEADERanditmusthavethefollowingstructure. Component NAME VALUE Component type SBCNAME SBCVALUE DTyp CHAR CHAR Length 32 255 Dec. places 0 0 Short text SBCrouting table,Keyfield SBCrouting table,valueof Keyfield
ThisstructureisdefinedintheSAPsystemstartingwithrelease4.6Aunderthename SBCCALLENV.Ifyoudonothavethisstructureinyoursystem,pleasedefineasimilar oneasabove. Theheadertablecancontainanarbitrarynumberofkey/valuepairs.Ifyouwanttopass additionalkeystotheSAPAdapter,youcandefineyourownname/valuepairsandinsert themintotheSBCHEADERtable. YouwouldreadoutthesefieldsinsideajavamoduleintheSAPAdapterwiththe followingstatements(casesensitive):

IDataCursor idc = pipeline.getCursor(); IData sbcHeader = IDataUtil.getIData( idc, "sbcHeader"); if (sbcHeader != null) { IDataCursor headerCursor = sbcHeader.getCursor(); String property = IDataUtil.getString( headerCursor, "myProperty"); headerCursor.destroy(); System.out.println("Property was "+property); } idc.destroy();
IfyouwanttheSAPAdaptertoinvokearoutingnotificationtoroutetheRFC,theheader tablemustcontainthesenderandreceiverfortheRFC.Whendeterminingtherouting notificationtoinvoke,theroutinglistenerusesthesenderandreceiveryouspecifyinthe headertableandmatchesmessagetypesagainsttheRFCnameinplaceofamessagetype. TohavetheSAPAdapterusearoutingnotification,includethefollowinginformationin theheadertable: Key

sender
Value Nameofthesender.Thisnameshouldmatchthenameofasender intheroutingnotificationyouwanttheroutinglistenertouseto routetheRFC. Nameofthereceivingpartner.Thisnameshouldmatchthename ofthereceiverintheroutingnotificationyouwanttherouting listenertousetoroutetheRFC.
receiver
141
IfyouwanttocontroltheroutingofanRFCfromtheSAPsystemdirectly(without requiringaroutingnotificationontheSAPAdapter),youcanincludetransport informationintheheadertable.ThetransportindicateswheretheSAPAdapteristoroute theincomingRFC.WhentheSAPAdapterreceivesanRFCthatspecifiesthetransport,it doesnotinvokearoutingnotificationbutdirectlypassestheRFCtothespecified transport.Thetransportsthatyoucanidentifyinaheadertabletodynamicallyroutean RFCthroughtheSAPAdapterare: RoutetheRFCtoanIntegrationServerservice RoutetheRFCtoanSAPsystem PosttheRFCXMLtoaURL Thefollowingdescribesthekey/valuepairsyoumustspecifyforeachtransportyoucan specify. To route the RFC to an Integration Server service, use the Integration Server service transport. Key
transport
Value
IS
Thisvalueidentifiesthetransport.Specifythevalueexactlyas specifiedabove
serverAlias
NameoftheIntegrationServeronwhichtheservicetoinvoke resides.Iftheserviceresidesontheserverthatroutesthe message,specify(local).Otherwise,specifyanaliasfora remoteserver.Fortheroutingtobesuccessful,theserver routingtheRFCmusthavethedefinedaliasfortheremote server. Nameofthefolderinwhichtheserviceresides.Thefolder nameiscasesensitive;usetheexactcombinationofupperand lowercaseletters. NameoftheservicetowhichtopasstheRFC.Theservice nameiscasesensitive;usetheexactcombinationofupperand lowercaseletters. WhereyouwanttheSAPAdaptertostoretheconnectionto theremoteserver. Tosavetheconnectioninyourownsession,specifySESSION. UseSESSIONwhentheworkbeingperformedrequiresstatebe maintained. Tosavetheconnectioninasharedarea,specifyGLOBAL.Use GLOBALwhentheworkbeingperformedisstateless.
folderName
serviceName
valueScope
142
To route the RFC to an SAP system, use the RFC transport. Key
transport
Value
RFC
serverName
RFCConnectionaliastowhichyouwanttheRFCrouted.
To post the RFC-XML to a URL, use the XML transport. Key

transport
Value
XML
url xmlType
URLtowhichyouwanttoposttheRFC. TheXMLformatyouwanttheroutinglistenertouseforthe RFC.SpecifySAPXMLifyouwanttheRFCinanXMLformat thatiscompliantwiththeSAPXMLspecification.Specify Values-XMLifyouwanttheRFCinwebMethodsnativeXML format. Usernametosupplyforausername/passwordauthentication challenge(optionally) Passwordtosupplyforausername/passwordauthentication challenge(optionally)
httpUser
httpPassword
ForsendingRFCsasbXML,pleaserefertoRFCBasedXMLMessagesUsingIFRFormat onpage 150.
Example of Using an SBCHEADER Table

Totestafunctionmodulewiththefunctionbuilder,writeawrappermodule.The wrappermodulecallsyourRFCfunctionmodule. Note: TheSBCHEADERtablecannotbeaddedinthefunctionbuilderdirectlyandmust notbepartofthefunctioninterfaceofthemoduleyouwanttocallremotely. Forexample,youwanttoinvokeafunctionmodulecalledZ_DEMO_COPY.Itechoesthe inputoftypeCHAR255receivedintheINPUTparametertotheOUTPUTparameter.In thewrappermoduleZ_WRAPPER_DEMO_COPY,youwoulddefineanadditionalinput parameternamedDESTINATIONandatablenamedSBCHEADER.
143
AwrapperforZ_DEMO_COPYcouldlooklikethis:
FUNCTION Z_WRAPPER_DEMO_COPY. *"-----------------------------------------------------------------*"*"Lokale Schnittstelle: *" IMPORTING *" VALUE(INPUT) TYPE CHAR255 OPTIONAL *" VALUE(DESTINATION) TYPE CHAR32 *" EXPORTING *" VALUE(OUTPUT) TYPE CHAR255 *" TABLES *" SBCHEADER STRUCTURE SBCCALLENV *"-----------------------------------------------------------------data: msg TYPE CHAR1024. CALL FUNCTION 'Z_DEMO_COPY' DESTINATION destination EXPORTING input = input IMPORTING output = output TABLES sbcheader = sbcheader EXCEPTIONS no_input_given = 1 communication_failure = 2 message msg system_failure = 3 message msg OTHERS = 4. CASE sy-subrc. WHEN 1. output = 'Exception received: NO_INPUT_GIVEN' . WHEN 2. concatenate 'COMMUNICATION_FAILURE received:' msg into output separated by space. WHEN 3. concatenate 'SYSTEM_FAILURE received:' msg into output separated by space. WHEN 4. output = 'Exception received: OTHERS'. ENDCASE. IF sy-subrc <> 0. WRITE output. ENDIF. ENDFUNCTION.
ThefollowingexampleillustrateshowtoroutetheZ_DEMO_COPYfunctionmoduleto theSAPAdapterandinvokearoutingnotificationtoroutethemessage.Whentestingthe functionmodulefromtheSAPGui,providethefollowinginputvalues:
144
INPUT DESTINATION SBCHEADER
Hello...! ISCER sender CERCLNT800 receiver DELL
TheSAPsystemroutestheRFCtothespecifiedRFCDestinationISCER(which correspondstothenameoftheRFClistener).IntheSAPAdapter,theroutinglistener invokestheroutingnotificationthatcorrespondstothesenderCERCLNT800,receiver DELL,andmessagetypeZ_DEMO_COPY.TodeterminehowtheSAPAdapterroutes Z_DEMO_COPYfunctionmodule,youwouldneedtoinspectthecorrespondingrouting notificationthattheroutinglistenerinvokes. ThefollowingexampleillustrateshowtoroutetheZ_DEMO_COPYfunctionmoduleto theSAPAdapteranddirectlyinvokinganoutboundtransport.Whentestingthefunction modulefromtheSAPGUI,providethefollowinginputvalues: INPUT DESTINATION SBCHEADER Hello...! ISCER transport RFC serverName CERCLNT750 Inthiscase,theSAPsystemroutestheRFCtothespecifiedRFCDestinationISCER.Inthe SAPAdapter,theheadertablegetsinterpreteddirectlytodeterminehowtoroutethe RFC.TheSAPAdapterroutesthemessagetotheSAPsystemknownasCERCLNT750on theSAPAdapterusingtransportRFC.NotethatCERCLNT750mustcorrespondtothe connectionaliasofanRFCconnectionthatisconfiguredintheSAPAdapter.
145
Sending a BAPI from an SAP System to the SAP Adapter

Overview
SAPsystemscommunicatewiththeSAPAdapteronanimplementationlevelwhen callingBAPIs.Thismeans,theytrytocalltheimplementingfunctionmoduledirectlyvia RFCor,ifasynchronousprocessingisused,theysendanIDoc. TheSAPAdapterhasabuiltinconvertertoautomaticallyrebuildtheoriginalobject basedBAPImethodcallandrepresentitasanXMLmessage.Therefore,theXML transportcanhandlethesemessagesusingtheXMLdialectbXML,tobuildaBAPIstyle XMLmessage. Toactivatethisfunction,youhavetospecifyaroutingnotificationthatmapstheBAPIcall totheXMLtransport.Themessagetypesusedintheroutingnotificationforroutingare basedontheBAPIimplementation.FormessagesreceivedfromanSAPsystem,this means: theRFCnameoftheBAPIimplementationisusedforsynchronouscalls thecorrespondingALEmessagetypeisusedforasynchronouscalls ThesemessagetypescanbefoundusingthebuiltinBAPIbrowser.Attherouting notificationsetup,youhavetospecifythenameofthebusinessobjectandBAPItowhich thecallshouldbemapped.
Setting Up a Routing Notification for the XML Transport

Toenablethisfunction,youwillfirsthavetosetupanRFCListenerfortherelevantSAP systems(seeChapter 6,AdapterNotifications) To create a routing notification with the following values set 1 2 3 4 5 6 OpentheDeveloperandselectNew Adapter Notification.ClickNext.
SelectSAP Adapterfromthelistofavailableadaptertypes.ClickNext. Fromthelistofavailabletemplates,selectRouting Notification.ClickNext. Selecttheroutinglistenerwm.sap.internal.ls:routingListener.ClickNext. Enteranameandselectafolderwheretheroutingnotificationshouldbestored. Selectanyservicethatshouldbeinvokedbythisnotification.ClickNextandthen Finish.
146
Sending a BAPI from an SAP System to the SAP Adapter
Note: Theserviceyouselectedinstep 6willonlybeusediftheoutboundtransport thatischoseninyourroutingnotificationisIS.Forallotheroutboundtransports, thisselectionwillbeoverriddenbyatransportspecificservice. 7 8 9 SelectXMLintheTransportfieldtoselecttheXMLtransport. SelectbXML DialectforthexmlTypefield. EnteraURLasdestinationoftheXMLcall.ToposttheXMLtoanotherSAPAdapter, youcanpostthemessagetoitsBAPIinboundprocess.Forthis,youcanpostittothe URL.
http://<host>:<port>/invoke/pub.sap.transport.BAPI/InboundProcess.
10 SelectYesfortheuseBapifield. 11 EntertheobjectnameintheobjectNamefield.Forexample:CompanyCode. 12 EntertheBAPImethodthatyouwanttouseinthebapiNamefield.Forexample: GetList. 13 Optionallyyoucanspecifyausernameandpasswordforuserauthenticationonthe remotehost. Note: YoucanselectadditionaloptionsfortheXMLtransportconfiguration: Use text/xml as content type:FlagthatallowstooverwritethecontenttypeofbXML,SAP XMLtotext/xml,ifsettotrue.Thecheckboxisdisabledforotherdialects. Use utf-8 as encoding:FlagthatallowstoforcetherenderersofbXML,SAPXMLtouse theencodingutf8,ifsettotrue.Thecheckboxisdisabledforotherdialects. SOAP XRFCcanbeselectedasadditionalXMLdialect.ThisisequivalenttoXRFC(RFC XML)withaSOAPenvelope(higherthanSOAP1.1).
Dynamic Routing Using the XML Transport

Itisnotalwaysnecessarytospecifyroutingnotifications.IfyouwanttocallaBAPIfrom anABAPreportinyourSAPsystem,youcanalsoaddtheSBCHEADERparameterto yourfunctionmodulecall.Thisparametercanbefilledwithkeyvaluepairsthatdescribe indetailhowthemessageshouldberouted.Atthemoment,itisonlypossibletoroute BAPIcallstotheXMLtransport.Todothis,usethefollowingkeypairsinthe SBCHEADERtable:
147
Name Transport url xmlType httpUser (optional) httpPassword (optional) useBAPI
Value XML ThedestinationURLfortheHTTPpostoperation bXML Anoptionalparameterthatallowsyoutospecifyausernamefor authenticationontheremotewebsystem Anoptionalparameterwhichallowsyoutospecifyapasswordfor authenticationontheremotewebsystem SetthisvaluetoYESifyouwanttousetheBAPIXMLformat.If youomitthisvalueorsetittosomethingdifferentthanYES,the messagewillbesentasRFCbasedXMLinaBizTalkXML envelope Thenameofthebusinessobject,towhichthecallshouldbe mapped.Thisvaluehastobecasesensitive. ThenameoftheBAPImethod,towhichthecallshouldbe mapped.Thisvalueiscasesensitive Avaluethatshouldbeputintheheaderelement <from> <address>.SeesenderTypeforfurtherdetails Anoptionalformatdescriptor,definingthesenderaddresstype. DefaultisLogSysforlogicalsystems.Logicalsystemnamesare automaticallyconvertedtoanURNbyanSAPdefinedschema. Alternatively,youcansetsenderType Avaluethatshouldbeputintheheaderelement<to> <address>. SeereceiverTypeforfurtherdetails Anoptionalformatdescriptor,definingthereceiveraddresstype. DefaultisLogSysforlogicalsystems.Logicalsystemnamesare automaticallyconvertedtoanURNbyanSAPdefinedschema. Alternatively,youcansetreceiverType Flagthatallowstooverwritethecontenttypetotext/xml,ifsetto Yes(forSAPXMLandbXML). Flagthatallowstoforcetherendererstousetheencodingutf8,if settoYes(forSAPXMLandbXML).
objectName bapiName xsender senderType (optional)
xreceiver receiverType (optional)
useTextXml useUTF8
ForsendingRFCbasedXMLmessages,onlythefirstfiveparametersaresupported.You canspecifythisparametertoyourABAPRFCasfollows:
DATA header like SBCCALLENV occurs 1 with header line. *... some code lines omitted CALL FUNCTION 'BAPI_COMPANYCODE_GETLIST' DESTINATION 'ISCER'
148
Sending IDocs with ALE from an SAP System to an SAP Adapter
IMPORTING RETURN = returnCode TABLES COMPANYCODE_LIST = companyCodes SBCHEADER = header .
Forasynchronousexample,seeCallingaBAPISynchronouslyfromanSAPSystemon page 197.Foranasynchronousexample,seeCallingaBAPIAsynchronouslyfroman SAPSystemonpage 201.
Sending IDocs with ALE from an SAP System to an SAP Adapter

TheroutinglistenerreceivesIDocsfromanSAPsystemifthetRFC (INBOUND_IDOC_PROCESSorIDOC_INBOUND_ASYNCHRONOUS)hasnoRFC adapterserviceassociatedwithit.WhentheroutinglistenerreceivestheIDoc,thesender, receiverandmessagetypeareextractedfromtheIDocitself.Theroutinglistenerusesthis informationwhendeterminingwheretoroutetheIDoc. Important! BeforetheSAPAdaptercanreceivetheIDoc,youmustdefineanRFClistener forthecorrespondingRFCdestinationdefinedatthecallingSAPsystem.Forinstructions, refertoListenersonpage 87. Note: ForinformationabouthowtomaptheIDocinformationintoanotherformatforuse byanotherapplication,refertoMappingIDocstoOtherFormatsonpage 159.
Routing RFCs Through the SAP Adapter

Posting RFC Based IFR-compatible XML Messages
SAPAdaptersupportstheXMLformatforusewitharbitraryRFCfunctionmodules.By usingthenewcontenttype application/x-sap.busdoc,whichisalsousedforBAPIs, youcaneasilypostRFCfunctioncallstotheSAPAdapter. TheseXMLmessagesmustprovideaBizTalkXMLenvelope(forfurtherinformation,see Appendix G,UsingBizTalkEnvelopeswiththeSAPAdapter).Thecallofthe correspondingbusinessdocumentfortheRFCfunctioncanbeputinthebodyofthe BizTalkmessage. ByusingtheBizTalkXMLenvelopeandthiscontenttype,youalsoenablethesupportfor thenewapplicationspecificXMLerrordocuments,whicharedefinedintheSAP InterfaceRepository.
149
YoucanposttothegeneratedproxyservicesURLfortheRFCfunctionmodules,ortothe RFCroutinggateway
http://<server>:<port>/invoke/pub.sap.transport.RFC/InboundProcess
RFC Based XML Messages Using IFR Format

YoucanalsogenerateXMLcallsforRFCfunctionmodulesthatarebasedontheIFRXML format.Todothis,selectbXMLastheXMLTypeattheroutingnotificationforRFCmessages, andensurethatuseBAPIissettoNo.
Posting RFCs via FTP

PerformthefollowingstepstoFTPanRFCXMLdocumenttotheroutinglistener:
open <Integration Server host> <port of ftp listener> username: Administrator password: manage cd ns/pub/sap/transport/RFC/InboundProcess bin put example.xrfc
TheFTPclientshouldcheckthereturncodetofindoutwhetherthedocumentprocessed properly. Note: IfyouarepostingRFCXML,thefilenameneedstoendwith.xrfc.
Posting RFCs in an E-mail Message

TosendanRFCXMLdocumenttotheroutinglistenerinanemailmessage,putthe documentintoanattachmentwhosenameendswith.xrfc.Inthesubjectlineofthee mailspecifypub.sap.transport.RFC:InboundProcess.
Routing BAPIs Through the SAP Adapter

Setting Up a Routing Notification and the BAPI Transport
InboundmessagesintheBAPIbasedXMLformatcanbeeasilydispatchedusingrouting notifications. ForeachBAPIsentviaXMLtotheSAPAdapter,acorrespondingroutingnotification shouldexist.Ifnoentryexists,themessagewillnotbeexecutedandtheSAPAdapterwill throwanexception.
150
ThemessagetypeusedintheroutingnotificationforBAPIsisconstructedfromthe concatenationofthebusinessobjectnameandtheBAPIname,whichareseparatedbya dot.(thesyntaxis<BusinessObject>.<BAPImethodname>). TheonlytransportapplicabletoinboundBAPIcallsistheBAPItransport.
Posting BAPI-based XML IFR-Compatible XML Messages

Toapplytheroutingnotification,theXMLmessageshouldbepostedtotheSAPAdapter. Thereceivingserviceshouldbepub.sap.transport.BAPI:InboundProcess. ExecuteanHTTPpostoperationto:
http://<host>:<port>/invoke/pub.sap.transport.BAPI/InboundProcess
IntheHTTPbody,anXMLmessagespecifyingtheBAPIcallasdescribedabovemustbe sent.YouhavetousetheHTTPcontenttypeapplication/x-sap.busdocwhenposting totheSAPAdapter.

POST /invoke/pub.sap.transport.BAPI/InboundProcess HTTP/1.0 Content-Type: application/x-sap.busdoc User-Agent: Java1.1.8 Host: localhost:5555 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-length: 817 <?xml version=1.0 encoding=iso-8859-1?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <message> <messageID>0A125F1315B3D24B0000001E</messageID> <sent>2000-06-20T09:58:00</sent> </message> <to> <address>urn:sap-com:logical-system:SAPSYS0001</address> </to> <from> <address>urn:sap-com:logical-system:SAPADA0001</address> </from> </delivery> </header> <body> <doc:CompanyCode.GetList xmlns:doc="urn:sapcom: document:sap:business" xmlns=""> <CompanyCodeList> <item> <COMP_CODE></COMP_CODE> <COMP_NAME></COMP_NAME> </item> </CompanyCodeList> </doc:CompanyCode.GetList>
151
</body> </biztalk_1>
Transaction Control
YoucancontrolwhethertheBAPIshouldbecalledsynchronouslyviaRFCor asynchronouslyviaALEbythe <referenceID>elementintheBizTalkheader. Ifthe<referenceID>elementisspecifiedandcontainsavalidSAPtransactionID(TID), theBAPIoutboundprocessautomaticallychoosestheALEformat,otherwise,ifthe elementisomitted,themessagewillbeprocessedsynchronously. Forbothsynchronousandasynchronouscalls,technicalprocessingerrorsarereportedby anXMLresponsedocumentcontainingafaultdescriptor.
BAPI XML Transaction Commit

WhenrunningaBAPIcallwithSAPAdapterinsomecasestheSAPsystemexpectsa commitcommandtoexecutethecall.TocommitthetransactiondirectlyoverHTTPdothe following: 1 2 3 4 CalllockSessionwithemptyPOSToverHTTP
http://<host>:<port>/invoke/pub.sap.client/lockSession
CalltheBAPIinthesamesessionusingHTTP CommittheservicewithanemptyPOSTusingHTTP
http://<host>:<port>/invoke/pub.sap.bapi/commit
ReleasethesessionbysendinganemptyPOSTusingHTTP
http://<host>:<port>/invoke/pub.sap.client/releaseSession
Note: WiththeHTTPrequestsinsteps24youneedtoresubmitthecookiethatyougot withtheresponseinstep1.Otherwise,theIntegrationServercannotassignthese requeststothesameusersessionandthecommitdoesnotknowwhichtransaction tocommit.
152
Synchronous Calls
ApplicationlevelresponsestosynchronousXMLrequestsarereportedusingaresponse businessdocumentintheHTTPresponse.Theresponsebusinessdocumentsfor synchronouscallsaredocumentedintheSAPInterfaceRepositoryandcontaina serializationofallexportingandchangingparametersoftheBAPIorfunctionmodule.
Example
SendingasynchronouscalltoanSAPsystem
153
Itreturnsaresponsebusinessdocument
Asynchronous Calls
AnasynchronouscallcanbeexecutedbyspecifyingatransactionIDintheBizTalkheader oftheXMLdocument.TheXMLelementusedisthe<referenceID>element(see descriptionoftheBizTalkXMLenvelope)inthe<receiver>sectionoftheBizTalk header. AtransactionIDshouldbeaglobaluniqueIDexpressedinhexadecimallettersand24 letterslong,forexample0A11449F652C394A34DE042F.Ifanasynchronousrequestcanbe transmittedwithouterrorsinsidetheSAPsystem,theSAPAdapterwillreturnaBizTalk envelopewithanemptybodyasconfirmationdocument.Iftherewereanyprocessing errors,thebodywillcontainafaultdescriptorelement.Theresultofanasynchronouscall canbecheckedinsidethetargetsystembyusingtheALEmonitoringservices(BD87)ina 4.6SAPsystem.PleaserefertoyourSAPsystemdocumentationforfurtherinformation onALEservices.
154
Example
SendinganasynchronousrequesttoanSAPsystembyspecifyingatransactionID
155
ReceivinganXMLconfirmationdocument
CheckingthecorrectapplicationlevelprocessinginsidethetargetSAPsystem(BD87 ina4.6systemorusetheIDoclistWE05):
156
Routing IDocs Through the SAP Adapter
Routing IDocs Through the SAP Adapter

IfyousubmitanIDocXMLdocumentinoneofthefollowingways,itwillautomatically bepassedtotheroutinglistener.
Posting an IDoc-XML Document from an HTTP Client

UsethefollowingguidelinestosubmitanIDocXMLdocumentviaanyHTTPclient:
POST /invoke/pub.sap.transport.ALE/InboundProcess HTTP/1.1\r\n Host: <hostname of client>\r\n Content-Type: application/x-sap.idoc\r\n Authorization: Basic <base64-encoded user:password>\r\n Content-Length: <number of bytes in XML document>\r\n \r\n <?>xml version="1.0"?> <MATMAS02> ... </MATMAS02>
Note: Thevalueforthecontentlengthhastobereplacedbytheactuallengthofcontent. Tip! TosimulateanHTTPclientfortestingpurposes,youcanusetheservicepub.client:http. 1UsingtheDeveloper,navigatetotheservicepub.client:http. 2SelectTest Run.
3SpecifytheURLoftheIDocXMLhandlerservice.Forexample, http://localhost:5555/invoke/pub.sap.transport.ALE/InboundProcess. 4SpecifyPostasthemethod. 5Addoneentryinthefieldheaders: Name:Content-type Value:application/x-sap.idoc 6 CopyasampleIdocXMLdocumentintothefield data string
157
Posting an IDoc via FTP

PerformthefollowingstepstoFTPanIDocdocumenttotheroutinglistener:
open <Integration Server host> <port of ftp listener> username: Administrator password: manage cd ns/pub/sap/transport/ALE/InboundProcess bin put example.idocxml
TheFTPclientshouldcheckthereturncodetofindoutwetherprocessingofthe documentwasok. Note: Itisimportantthatthefilenameofthedocumentendswith.idocxml.
Posting an IDoc in an E-mail Message

TosendanIDocdocumenttotheroutinglistenerinanemailmessage,putthedocument intoanattachmentwhosenameendswith .idocxml.Inthesubjectlineoftheemail specifypub.sap.transport.ALE:InboundProcess.
Posting an IDoc from a Web Browser

Note: TopostanIDocXMLdocumentintotheroutinglistener,youcansubmititviaaWeb pageoryoucancreateanHTTPclientthatperformsthepost.Thissectiondescribeshow topostIDocXMLdocumentsfromawebbrowser. YoucansubmitanIDocXMLforanyIDoctypetotheroutinglistenerfromaWeb browserusingthefollowingpage:
http://<host>:<port>/WmSAP/submitIDocXML.html
Thissamplepagecanbeusedasatesttool.IfyouplantosubmitIDocsfromanHTML form,youcanusethispageassamplecode.
158
Mapping IDocs to Other Formats
Transmitting IDocs between Two Integration Servers

TosendIDocsovertheInternet,usethefollowingproceduretoestablishtheconnection betweentwoIntegrationServers(forexample:yourownandonebelongingtoyour BusinessPartner). 1 OnthesendingIntegrationServer,createaRemoteServerthatpointstothereceiving IntegrationServer.FormoreinformationoncreatingRemoteServersseewebMethods IntegrationServerAdministratorsGuide.Ifyouareinsideafirewallmakesurethatyour HTTPproxyserverisconfiguredunderSettings Proxy Servers. OnthesendingIntegrationServer,createanewroutingnotificationthathasanew emptyflowserviceassigned. SetTransporttoIS. Edittheserviceassignedtotheroutingnotificationandaddaflowstepinvoking service pub.remote:invoke.Settheinputvaluesforthisflowstepasfollows: a b c 5 $alias:RemoteServernameofyourtradingpartner $service:pub.sap.transport.IS:InboundProcess $scope:selectthedefaultvalue
2 3 4
Edittheserviceassignedtotheroutingnotificationanddropallunnecessary parametersinaMAPlocatedbeforethestepinvokingthepub.remote:invokeservice. Thisreducestheamountofdatasentoverthenetwork.IfthereceivingIntegration Serverisofrelease4.6orlower,youneedtoinvokeanotherservicebeforethefinal remoteinvokestep:pub.sap.idoc:iDocToTables.ThisserviceconvertstheIDocintothe formatexpectedbyolderreleases.
Tip! Onemoretiptoincreaseperformance:askyourcommunicationpartnertoalsodrop allunnecessaryparametersattheendoftheroutingnotificationwhichreceivesthis document.Thisreducestheamountofdatasentbackintheresponse.

IfyouneedtousetheinformationcontainedinanIDocindocumentsofanotherformat, youbuildaservicethatmapstheinformationfromfieldsintheIDoctothevariables usedbytheotherapplication.Forexample,totransferapurchaseorderfroman ORDERS02IDoctoanEDIsystem,youcreateaflowservicethatmapsinformationfrom theIDocfieldstofieldswithintheEDIsystemspurchaseorderdocument.Then,you definearoutingnotificationthattriggersthisflowservice. Thefollowinginstructionswillshowyouhowtodothisindetail: 1 2 CreatinganEmptyFlowService CreatingtheRoutingNotification
159
3 4 5 6
CreatingaDocumentTypeforYourIDoc TransformingtheIDoctoaHierarchicalFormat MappingIDocInformationtoPipelineVariables TestingtheMappingService
Creating an Empty Flow Service

Usethefollowingproceduretocreateaflowservicenamedapp.idocs:mapOrders02with Developer(thisistheservicethattheroutinglistenerwillinvokebasedontherouting rulecreatedinthenextstage). To create an empty flow service OntheFilemenu,clickNewandcreateanemptyflowservice.Youwillselectthisservice whencreatingaroutingnotification.
Creating the Routing Notification

ThefirststepinbuildinganapplicationthatmapsinformationfromanIDocistocreatea routingnotificationthatinvokestheflowservicethatwillperformthemapping. Whenyoucreatetheroutingnotification,selecttheserviceyouhavepreviouslycreated formappingtheIDoc,andasthetransport,selectISService. ThefollowingexampleshowstheroutingnotificationyouwouldcreatetopasstheIDoc toaservicecalledapp.idocs:mapOrders02.
Creating a Document Type for Your IDoc

RegardlessofthewayinwhichyoupasstheIDoctotheflow,youneedtocreatea documentdescribingthecontentandstructureoftheIDoc.Therearethreewaystocreate thisdocument: YoucangenerateitdirectlybyreceivingtheIDocmetadatainformationformanSAP systemyouhaveanRFCconnectionto.SeeCreateanIDocDocumentTypeUsing theDDIConpage 122formoreinformation. YoucangenerateitfromtheDTDfortheIDoc.SeeGeneratinganIDocDocument TypefromaDTDonpage 123formoreinformation. YoucangenerateitfromasampleIDocthatyoucapturewiththeDeveloperat designtime.SeeGeneratingaDocumentTypefromaSampleIDoconpage 124for moreinformation.
160
Thefirsttwooptionsproducethemostcompletedocumentbecausetheyarebasedonthe IDocsmetadatadefinedattheSAPsystemoraDTD,whichdescribesallpossiblefieldsin theIDoc.Useoneofthefirsttwooptionswheneverpossible. UsethethirdoptiononlyifaDTDisnotavailablefortheIDocwithwhichyouare working.Becausethisoptionderivesadocumentfromasampledocument,thereisno assurancethatthedocumentwillincludeallpossiblefields.Fieldsthatarenotusedinthe sampledocumentwillnotappearinthedocumenttype.
Transforming the IDoc to a Hierarchical Format

ToextractinformationfromanIDoc,yourflowservicemusttransformtheIDocintoa hierarchicalstructureandgenerateadocumentadocumenttypewhoseelements correspondtothefieldsintheIDoc.Todothis,eitherusetheiDocToDocumentservice(ifthe IDocwillbereceivedbytheSAPAdapterrviatRFCorviahttpPOSTwithContentType: application/x-sap.idoc)orthexmlNodeToDocumentservice(iftheIDocwillbereceived viahttpPOSTwithContentType: text/xml). To transform the IDoc to hierarchical format 1 Click ontheFlowPanetoolbarandselectthepub.sap.idoc:iDocToDocument service orthepub.web:xmlNodeToDocument service.(Ifthisservicedoesnotappearinthelist, selectBrowse tolocateit.)EitherservicetransformstheIDocintoadocument variable,whichcontainsthecontentsoftheIDocinaformatthatyoucanmaptoother pipelinevariables. Click tosavethisflowservice.
Mapping IDoc Information to Pipeline Variables

AftertransformingtheIDocintoadocument,youcanmapthefieldsoftheIDoctoother variablesinthepipeline(forexample,tovariablesinacXMLorOAGdocument).Todo this,youmustaddaMAPoperationtotheflow,insertdocumenttypesfortheIDocand thetargetdocument,andthenmapfieldsintheIDoctotheappropriatevariablesinthe otherdocument. ThefollowingproceduredescribeshowtoaddtheMAPoperationtotheserviceand configuretheMAPoperationtocopyvaluesfromtheIDoctoothervariablesinthe pipeline.
161
To map the IDoc to variables in the pipeline PerformthefollowingstepstoaddaDocumentTypedescribingthecontentandstructure oftheIDoc. 1 2 3 4 5 6 7 IntheDeveloper,selecttheFlowtab. IntheFlowPane,selecttheiDocToDocument / xmlNodeToDocumentoperation. SelectthePipelinetabandselectthedocumentvariableunderPipeline Out. Click onthetoolbarandselectDocument.
IntheNamefield,typethefullyqualifiednameofthedocumenttypeyoucreatedin CreatingaDocumentTypeforYourIDoconpage 160,orselectitintheFoldertree. ClickOK. TypeanameforthisdocumentandpressENTER.(YoucangivethisDocumentany nameyoulike,butwesuggestthatyouidentifytheIDocinthename.) Whenyoufinishthisstep,Pipeline Out shouldcontainadocumentthatdefinesthe structureofyourIDoc.(Donotsavetheflowatthisstage,becauseifyoudo,theyet unuseddocumentwillbedeletedagainfromtheservice...)
8 9
Takethefollowingstepstomapthedocumentvariabletothedocumentyoujust created. InService Out,selectthedocumentvariable.
10 InPipeline Out,selecttheIDocdocumentandclickMap,ormapdocumenttotheIDoc documentusingdragandrelate: 11 ThePipelineEditorwillshowaconnectinglinebetweendocumentandtheIDoc documentyoucreatedinthepreviousprocedure. Performthefollowingstepstodefinethevariable(s)towhichyouwanttomap informationfromtheIDoc. To define the variable(s) to which you want to map information from the IDoc 1 SelectMaponthe Flow Panetoolbar. Note: MakesuretheMAPoperationappearsimmediatelyaftertheiDocToDocument / xmlNodeToDocumentoperation.Ifnecessary,usethearrowbuttonsonthetoolbarto moveittothecorrectposition. 2 3 SelectthePipelinetab. InPipeline Out,selectthebottommostvariable,andthen
162
4 5 6
Click
onthetoolbar,andselecttheDocumentReference.
IntheNamefield,typethefullyqualifiednameofthedocumentdefinitionyouwant tomaptheIDocto,orselectitintheFoldertree.ClickOK. TypeanameforthisDocumentandpressENTER. Whenyoufinishthisstep,PipelineOutshouldcontainadocumentthatdefinesthe structureofyourtargetdocumenttype.(Donotsavetheflowatthisstage,becauseif youdo,theyetunuseddocumentReferencewillbedeletedagainfromtheservice.)
UseMaptomapfieldsfromtheIDocDocumentinPipeline Intotheappropriatetarget variablesinPipeline Out.Ifyouneedadditionalinformationaboutthisstep,seethe webMethodsDeveloperUsersGuide. ThefollowingexampleshowsavariablemappedfromtheORDERS02IDoctoa StringvariableinDocumentcalledPurchaseOrder.
Note: Youcanfindadocumenttypefortheexamplepurchaseordershownabovein sample.sap.records:PurchaseOrder.
Testing the Mapping Service

Totesttheflowserviceyoucreated,usetheSAPGuiorthe /WmSAP/submitIDocXML.htmlutilitytosubmityoursampleIDoctotheSAPAdapter. Makesuretospecifythesender,receiver,andmessagetypethatyouusedfortherouting rulethatyoucreatedinConfiguringaRoutingNotificationonpage 134. ChecktheresultsoftheservicetoensurethattheIDocisbeingmappedcorrectly. IfyouwanttodebugyourserviceintheDeveloper,youcanusethesavePipelineToFileand restorePipelineFromFileservicestocaptureasubmittedIDoc 1 UsetheSAPGuiorthe/WmSAP/submitIDocXML.htmlutilitytosubmitanIDocto yourflowservice.Whentheserviceexecutes,thesavePipelineToFileoperationwillmake acopyofthepipeline(whichwillincludeyourIDoc)andsaveittofile. DeletethesavePipelineToFileserviceandinserttherestorePipelineFromFileservice. SelecttheTest Runcommandtoexecutetheflowservice.Whenitexecutes,the restorePipelineFromFileservicewillretrievethecopyofthepipelinecontainingyour IDoc,whichtheremainderoftheflowwilloperateon.
2 3
Whenyouarefinishedtesting,deletetherestorePipelineFromFileserviceandsavethe finishedflow.
163
Content-Based Routing and Mapping for IDocs

Occasionally,youmustdosomemanipulationonIDocsbeforeprocessingtheminthe SAPAdapterorbeforesendingthemtoanSAPsystem.Thiswillhappenwithcustomized IDocsthatneedspecificprocessing.Thetwomostcommonmanipulationsarecontent basedroutingandmapping.BothmechanismscanbeperformedonIDocsroutedthrough theSAPAdapter.ForIDocsgoingtoanSAPsystem,onlymappingmanipulationapplies. Note: Contentbasedroutingenablesyoutospecifyroutingparameters(sender,receiver andmsgType)thatoverrideparametersintheheaderoftheincomingIDocs.You determinesuchheadersfromthecontentoftheIDocitself.Forexample,youwantto provideroutingparameterslikevendororsalesorganizationinaPOasinformationfor thereceivingsystem(insteadofjustthelogicalsystemsname). Mappingisthemechanismthatadds(orremoves)datasegmentsto(from)adocument. UsethisifyouwanttoincludetheparametersalesorganizationintheORDERSIDoc. Apracticalexampleforusingthepreroutingmechanismsfeaturesisifyouhaveaspecial OrdersIDocthatcontainsitsreceiverandsenderinformationinspecificfieldsintheIDoc itself.Italsocontainsextrafieldsthatyouwantremoved,oradded,beforeyouprocessthe IDocasanORDER02IDoc.Youregisterspecialpreroutingservicesbasedonmessage types.Youalsocancreateastandardprocessingservicetobeexecutedforallmessage typesandprovidesdefaultroutinginformation. Youcanregisterbothinboundandoutboundmanipulationservices.Theinboundservices areexecutedforinboundIDocsreceived bytheSAPAdapterviaaRFCListenerorby invokingthepub.sap.transport.ALE:InboundProcessservice(forexample:overHTTP).The outboundservicesareexecutedbeforeanIDocissenttoanSAPsystemby pub.sap.transport.ALE:OutboundProcess. To register an inbound or outbound mapping service 1 Fortheinboundcase,createoneormoreservicesthatimplementthe pub.sap.transport.ALE:aleRoutingInfoand/orpub.sap.transport.ALE:aleRoutingInfo_Default specification.Fortheoutboundcase,theservicesneedtoimplementeitherthe pub.sap.transport.ALE:aleMappingInfoand/orpub.sap.transport.ALE:aleMappingInfo_Default specification. Afterhavingimplementedaservice,youstillhavetomakeitknowntotheIDoc transport.GotoAdapters SAP Adapter Routing/Mapping. FollowthelinkRegister New User Exit ServiceandthenselectoneALE Routing/MappingInfo*type.
2 3
164
Content-Based Routing and Mapping for IDocs
Providethefullservicenameandthemessagetypeintheinputfield,andthenclick Register.
Arouting/mappingservicehastousethefollowingspecificationsforproperbehavior: Specification pub.sap.transport.ALE:aleRoutingInfo pub.sap.transport.ALE:aleRoutingInfo _Default pub.sap.transport.ALE:aleMappingInfo pub.sap.transport.ALE:aleMappingInfo _Default Description Specificationthatshouldbeusedforserviceswhich provideaninboundcontentbasedrouting/mapping. Specificationthatshouldbeusedforserviceswhich provideadefaultinboundrouting/mapping Specificationthatshouldbeusedforserviceswhich provideanoutboundcontentbasedmapping. Specificationthatshouldbeusedforserviceswhich provideadefaultoutboundmapping.
Afteryouregisteredyourroutingservicesyoucanassociatethemwithmessagetypesvia theAdministratorUI(Adapters>SAP Adapter>Routing/Mapping): Important! IntheSAPRouting/MappingscreenoftheAdministratorUItherearetwo sectionstoselectservices:amessage type independentsection(defaulthandlingsection)and amessage type dependentsection. Adefaulthandlingservice(inboundoroutbound)isexecutedforallmessagetypes.Ifthere areservicesselectedinthemessage type dependent section,theywillbeexecutedforthe correspondingmessagetypeinadditiontothedefaultservice.Ifthespecialvalue$none is selected,allregisteredservicesaresettoinactive. Note: Theservicesforcontentbasedroutinghavetoberegisteredbyyourselfbeforethey canbeselectedviatheAdministratorUI. Important! Ifyoucreateyourowndefaultinboundroutingservice,youmustsetthe parameterssender,receiverandmsgType.Thoseparametersarepartofthespecification.If youdonotsetthem,youcouldreceiveanerrormessage. Note: Thesettingofthedefaultservicesworksthesamewayasthesettingofregular services.Youneedtoregisteraservicebeforeyoucanselectit.Ifno*Default Routing/Mappingtypehasbeenregistered,thenyouwillnothaveachoiceforselecting oneatall,whichisthecasewiththeadapteroutofthebox.$nonechoiceisonlythereif oneormoreservicesareregistered.
165
ForallincomingIDocswithanORDERSmessagetype,thesample.sap.idoc.Mappings:orders servicewillbeexecuted.TheservicemayaltertheIDocaswellastheroutingparameters fortheIDoc.ForIDocsgoingtotheSAPsystemwithORDRSPmessagetype,the sample.sap.idoc.Mappings:ordrspservicewillbeexecuted.ThisservicecanaltertheIDocby addingorremovingfields.
Routing Arbitrary XML Documents Through the SAP Adapter

ItispossibletouseXMLInboundProcesstoforwardarbitraryXMLdocumentstothe routinglistenerbyusingtheInboundProcessmechanismoftheXMLtransport. ForthispurposeyoucanconfigureasocalledinboundroutinginfoserviceforyourXML transport.Thisserviceshouldimplementthespecification pub.sap.transport.XML:xmlRoutingInfo,usingthefollowingparameters: Input Parameters This key document Must specify ThisfieldcontainstheXMLdocumentasitwouldlooklikeafter havingbeenprocessedbypub.xml:xmlNodeToDocument.Yourservice shouldextracttheroutingdatafromyourspecificdocuments. Alternatively,youcanprovideyourdocumentasanodeasusedin thepub.xml:xmlNodeToDocumentserviceasaninputfield.
node
Return Values This key sender receiver msgType $tid(optional) $action(optional) Must specify Senderusedforfindingthematchingroutingnotification. Receiverusedforfindingthematchingroutingnotification. Messagetypeusedforfindingthematchingroutingnotification. TransactionIDfoundinthedocument,ifclientwantstoexecutea transactiononceandonlyonce. Oneofthefollowingtransactioncodes: Code
1 4
Meaning Execute(default) Confirm
166
Routing Arbitrary XML Documents Through the SAP Adapter
ToconfiguretheInboundProcessmechanismoftheXMLtransport,performthe followingsteps: 1 2 3 4 CreateaninboundroutinginfoserviceforyourXMLtransport.Itextractsallrequired parameterssothattheroutinglistenercanhandletherequest. Afterhavingimplementedaservice,youmustmakeitknowntotheXMLtransport. GototheAdapters SAP Adapter Routing/Mappingpage. FollowthelinkRegister New User Exit ServiceandthenselectXML Routing Info. Providethefullservicenameintheinputfield,andclickRegister:
NowyouarereadytodoroutingusingXMLInboundProcessforarbitraryXML documents.
167
168
CHAPTER
Transaction Handling
Managing Transactions and the Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Viewing Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Deleting Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Automatic Cleanup of the Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Configuration Parameters for the Transaction Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Using the ALE Monitoring Features Via the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . 175 Centralized Transaction Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
169
C H A P T E R 9 Tr a n s a c t i o n H a n d l i n g
Managing Transactions and the Transaction Store

TheSAPAdaptercomeswithatransactionmanagerthatallowsyoutomonitorthe transactionstateforallmessagesassociatedwithatransactionIDthatuniquelyidentifies thetransaction.ThetransactionIDcanbeupto24alphanumericcharactersinlength.If theSAPAdapterreceivesamessagewithoutatransactionID,itcancreateoneforthe message. Themessageitselfcanbestoredintothetransactionstore.Bydefault,thetransactionstore islocatedontheIntegrationServeronwhichanindividualSAPAdapterisinstalled. Alternatively,itcanbecentrallylocatedonanIntegrationServeronwhichoneSAP Adapterisdesignatedastheserver,andisavailabletoagroupofSAPAdapters.For completeinformationaboutconfiguringandworkingwiththeCentralizedTransaction Store,seeCentralizedTransactionStoreonpage 181. UsetheTransactionsscreenstoviewandmanagethetransactionsthattheSAPAdapter recordsinitstransactionstore.Hereyoucanviewtransactionsandtheirprocessinglogas wellasdeletetransactionsthatarenolongerneeded.
Viewing Transactions
YouviewtransactionsforalocalTransactionStoreandaCentralizedTransactionStore (CTS)inthesameway.InalocalTransactionStore,youcanviewonlythetransactions executedbythatindividualadapter;inaCTS,youcanviewthestatusofallthe transactionsexecutedbyanyadapterinthegroup. To view the transactions in the transaction store 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickTransactions. TheSAPAdapterdisplaystransactionsinpagesof20,toavoidatimeoutoroutof memoryofthewebbrowserincasethereisalargenumberoftransactionsinthe store. 3 Toviewdetailinformationforatransaction,clickonthetransactionIDintheTID column. Thisscreenallowsyoutoviewthedetailsofeachtransaction,includingthesender, receiver,messagetype,transactionID,timewhenthistransactionwasfirstreceived bytheSAPAdapter,currentstate,thetimewhenthisstatewasset,lasterror(ifany), andanaudittrailthatshowsstatechanges,errormessagesandthevariousstepsthat haveprocessedthemessage. TheCurrent Statefieldcontainsthetransactionstate.Theinformationinthisfield correspondstothedifferentstatesofthetRFCprotocol.Ifthemessagewasnot
170
Viewing Transactions
receivedviatRFCbutviaadifferentprotocol(likehttp),thetransactionstoretriesto imitatethetRFCstatushandling,butthemeaningofthesinglestatesisslightly differentinthiscase.ThefollowingdescribesthevalidstatesofatRFCtransaction: Status Created Meaning (tRFC) Thesenderhassenda transactionID,whichwas acceptedbytheSAP Adaptertransaction manager.(Nodatasent yet.) Executionofthe transactionhasfailed.The sendermayretrythe transactionagainata latertime. TheAdministratorshould manuallyfollowup transactionsinstatus Rolled backasfollows: Trytofindandeliminate thereasonoffailureand then: Resendthe transactionfrom SM58,ifitoriginally camefromanSAP system Askyourpartnerto resendthe transaction,ifit originallycameinvia FTPorHTTP. Ifthetransactionwas initiatedbyalocal service,reinvokethe service. Meaning (other protocols) Thesenderhassendatransaction IDanddata,whichwas forwardedtothetransaction store.
Rolledback
Executionofthetransactionhas failed.Thesendermayretrythe transactionagainatalatertime.
171
Status Committed
Meaning (tRFC) Thesenderhas acknowledged,thathe knows,thatthe transactionexecuted successfully. Thesenderhaspromised nevertosendthis transactionagain.Sothe TIDmaybedeleted,as thereisnoneedanymore toprotectagainst duplicateprocessingof thesametransaction.
Meaning (other protocols) Executionofthetransactionon theSAPAdapterfinishedwitha successmessage.
Confirmed
Thisisusedonlyiftheexternal clientinvokestheservice pub.sap.transport.*:InboundProcess again,with$actionset4,afterthe transactionhasbeenexecuted successfully.Inthiscaseandif thetransportsupportsit,the Confirm eventhasbeenforwarded tothefinalreceiver,sothatitis abletocleanupitsARFCRSTATE tableandremovetheTIDfromit.
IfthestoringofmessagebodieshasnotbeendisabledontheRoutingorRFClistener,itis alsopossibletoviewthepipelineorthemessagebodyofthetransactionfromthisscreen. Youcanviewthefollowing: messagebodyasXML messagebodyasHTML(IDoconly) completepipeline
Deleting Transactions
YoudeletetransactionsfromalocalTransactionStoreandaCentralizedTransactionStore (CTS)inthesameway.Ifatransactionstorecontainstransactionsthatarenolonger needed,youcandeletethem.InalocalTransactionStore,youcandeleteonlythe transactionsexecutedbythatindividualadapter;inaCTS,youcandeleteanytransaction executedbyanyadapterinthegroup. Important! IfyoudeleteatransactioninaCTS,thetransactionwillnotbeavailableforall theadaptersinthegroup.Makesureyoudeleteonlythetransactionsthatarenotneeded byanyadaptersinthegroup.
172
Automatic Cleanup of the Transaction Store
To delete transactions from the transaction store 1 2 3 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. IntheSAP Adaptermenu,clickTransactions. Clickthe iconintheDelete columnforthetransactionthatyouwanttodelete.
Automatic Cleanup of the Transaction Store

Asthesizeofthetransactionstoreincreases,youshouldconsidercreatingaflowservice thatperiodicallypurgesthestoreoftransactionsthatarenolongerneeded. TocleanupalocalTransactionStore,configuretheflowserviceoneachadapter. TocleanupaCentralizedTransactionStore,configuretheflowserviceononlyoneof theSAPAdaptersintheadaptergroup.ForbestperformancethisshouldbetheSAP Adapterthatistheserver. To purge certain transactions from the transaction store periodically 1 2 IntheDeveloper,createaflowservicethatinvokesthepub.sap.transaction:sweepservice. PassthefollowingparameterstothesweepserviceusingtheSet Valuemodifierinthe pipeline. For this parameter state elapsedTime maxTrxCount Specify Thetransactionstate. Thenumberofminutesthatthetransactionhasbeenin statusstate. Themaximumnumberoftransactionstodeleteeachtime thatpub.sap.transaction:sweepruns.
Forinformationaboutthesweepservice,seepub.sap.transaction:sweeponpage 265. 3 IntheAdministratorUIgotoServer periodically. Schedulerandschedulethisflowservicetorun
173
Example
ToperiodicallypurgealltransactionsthathavebeenintheConfirmedstateforlongerthan 30minutes,youcancreateaservicecalledapp:purgeConfirmedTRXwiththosestateandtime parameters.Youalsospecifyhowmanytransactionseveryinvocationoftheservicewill purge.Thisissoyoucancontrolthepaceofyourmaintenancejobswithoutputtingto muchloadontheIntegrationServeratonesingletime.Itisalsoagoodideatoschedule thejobattimeswhenthereisnotmuchloadontheIntegrationServer.
Configuration Parameters for the Transaction Manager

Thetransactionstorereactstothefollowingconfigurationparameters,whichcanbesetin thefile<install_dir>/config/server.cnforperrouting/RFClisteneroronthenotification levelforalocalTransactionStoreandforaCentralizedTransactionStoreServeronly. Someofthesesettingsinfluencetheperformanceofthetransactionstore. Note: Thetransactionstoreperformancewillinfluencethegeneralperformanceofthe IntegrationServerdependingonthetransactionalthroughput,thatis,sizeofthedocsand docspersecond. OneachRFCListenerandontheroutinglisteneryoucansetfieldStoremessage bodytoOnorOff. IfthisparameterissettoOff,theSAPAdapterdoesnotsavethemessagebodyof incomingtransactions. OneachRFCListenerandontheroutinglisteneryoucansetfieldLogtransaction statustoOnorOff. IfthisparameterissettoOff,theSAPAdapterdoesnotmaintainanytransaction andstatusinformationinthetransactionstore. OneachALENotificationandfortheRoutingNotificationyoucansetfieldMonitor IDocstoOnorOff. IfthisparameterissettoOn,theSAPAdapterlinkstheIDocpacketsTIDwiththe DOCNUMsoftheIDocsinthatpacket,sothatlaterALEIDocMonitoringispossible. SeeUsingtheALEMonitoringFeaturesViatheSAPAdapteronpage 175formore information. watt.sap.xtn.cacheFlushPeriod Thispropertyspecifies,inminutes,howoftentheSAPAdapterwillflushtheunsaved changesinthetransactioncachetothefilesystem.Thedefaultis5minutes.Ifa transactioninthecachehasbeenmodified(forexample:newstateornewauditlog), itwillbepersistedtothetransactionstoreaftercacheFlushPeriodhasexpiredand nofurthermodificationshavehappened.Afterthat,thetransactionremainsinthe
174
Using the ALE Monitoring Features Via the SAP Adapter
cacheuntilthecacheTimeToLiveperiodhasexpired,orlongerifitwasmodified again. Important! ForaCentralizedTransactionStore,theSAPAdapterwillsetthevalueto 1000ifthevaluesetislessthanthat. watt.sap.xtn.cacheTimeToLive Thetransactioncacheworksbothasareadandawritecache.Afteratransactionis readthefirsttime,itiskeptinthecacheforaspecificamountoftime (cacheTimeToLive).Ifthetransactionisnotaccessedduringthistime,itisremoved fromthecacheafterthisperiodhasended.Thiskeepsthecachefromgrowing indefinitely. Important! ForaCentralizedTransactionStore,theSAPAdapterwillsetthevalueto 1000ifthevaluesetislessthanthat. watt.sap.xtn.fastAsyncMode Thisproperty,whensettotrue,enablesthesynchronouswritecacheandwhenset tofalsedisablesthecache.Thispropertyworkstogetherwiththe watt.sap.xtn.cacheFlushPeriodandwatt.sap.xtn.cacheTimeToLive.Settingthisfeaturetotrue willforcethetransactionmanagernottopersisteachupdateofatransactionbutwill keepthestatechangesinmemoryandpersistitperiodically. Important! ForaCentralizedTransactionStore,youcannotsetthisparametertotrue.

YoucanmonitortheALEtransactionsforalocalTransactionStoreandforaCentralized TransactionStore(CTS)inthesameway,asdescribedbelow.Thebehaviorofmonitoring willnotchangebecausethetransactionsareexecutedbyindividualadaptersevenina CTSsetup.OnlythetransactionresultsarestoredinaCTSserver. WhenanIDocissentfromanSAPsystemtotheSAPAdapter,thestatusoftheIDoc(as displayedinWE02)willalwaysbe03,DatapassedtoportOK(passedtothetRFC queueoftheSAPsystem).However,thisstatusdoesnotprovideanyinformation regardingwhethertheIDoccouldbeprocessedsuccessfullybytheSAPAdapterandwho thefinalrecipientwas.Togetthiskindofinformation,theSAPAdapteroffersthree options:IDocTrace,ALEAUDIDocandSYSTATIDoc. TheIDocTracefeatureshouldbeusedifyousporadicallywanttolookupthestatusof certainIDocs.ThelookupisdonemanuallyandonlyforaspecificselectionofIDocs.If youwantautomaticstatusupdate,youshoulduseoneoftheothertwooptionsdescribed below.
175
StatusupdateviaALEAUDIDoccanbeusedifthefinalrecipientisagainanotherSAP system.ThemostcommoncasewillbetheconnectionoftwoSAPsystemsviatheInternet likethis: SAPsystem(sender)>IntegrationServer1>Internet(http)>IntegrationServer2> SAPsystem(receiver). InallothercasesstatusupdateviaSYSTATIDocshouldbeused.IntegrationServeracts herelikeanEDISubsystemandreturnsstatusinformationandinformationaboutthe finalreceiver(receivingemailaddress,WebServerURL,FTPServer,thirdpartysystem, etc.)tothesender. Thesethreeoptionsarenowdescribedindetail:
IDoc Trace
Overview
TheALEMonitorallowsyoutomakeinquiriesabouttheprocessingstatusofanIDocin thereceivingsystemactivelyfromwithinthesendingsystem.InSAPsystemsofrelease< 4.6CthiscanbedonewiththetransactionBDM2(CrossSystemIDocReporting)andfrom release4.6ConwithtransactionBD87(StatusMonitorforALEMessages).Asinputsyoucan specifycertainselectioncriteria,likeDocumentNumber,MessageType,LSofreceiver anddateranges.ThesystemthenmakesasynchronousRFCcall (IDOC_DATE_TIME_GET)totheLSthatreceivedtheIDocs,withalistofDOCNUMs correspondingtotheselectedIDocs.(FromtransactionBD87youhavetohitthetoolbar buttonTraceIDocsaftertheselectionoftheIDocs.)Thisfunctioncallreturnsforeach IDoctheDOCNUM,underwhichitwassavedinthereceivingsystem,thereceivingtime andthecurrentprocessingstatusinthereceivingsystem.
Prerequisites
TheIDocTracefunctionalityonlyworksforIDocsexchangedbetweenpartnersof PartnerTypeLS(LogicalSystem). InordertobeabletomakethissynchronousRFC,thepartnerprofileoftheLS,which representstheIntegrationServer,mustcontainanoutboundparameterwithmessage typeSYNCH. AlsotheFunctionCalltoanLSoftypetRFCPort,liketheIntegrationServer,isonly executediftheSAPsystemisofrelease4.6Dorhigher.Forolderreleasesyouhaveto applythefollowinghotpackages: R/3 Release 3.1I 4.0B Hot Package SAPKH31I67 SAPKH40B56
176
R/3 Release 4.5B 4.6B 4.6C
Hot Package SAPKH45B35 SAPKB46B22andSAPKH46B22 SAPKB46C11andSAPKH46C11
Prepare the SAP Adapter for IDoc Trace

TosetuptheSAPAdapterforIDoctracingproceedalongthefollowingsteps: 1 2 ForyourroutingnotificationorALEadapternotificationyouwanttomonitorIDocs, setthevalueforfieldMonitorIDocstoOnusingtheDeveloper. ForeachSAPsystemfromwhichyouwanttoreceiveandtraceIDocs,createanRFC adapternotificationforIDOC_DATE_TIME_GETandassignservice pub.sap.monitor.idoc:trace.
Note: DependingonhowtheSAPAdapterprocessestheIDocitreceives,different informationwillbereturned.Bydefault,thecreationdateandtimeatthereceiving systemandthestatuswillbereturned.IftheIDocwillnotbeforwardedtoanotherSAP system,theSAPAdapteristhereceivingsystem. However,iftheIDocisforwardedtoanSAPsystem(eitherbyinvokingarouting notificationwithoutboundtransportsettoALEorbyinvoking pub.sap.transport.ALE:OutboundProcessorpub.sap.client:sendIDocdirectlyorfromaremote IntegrationServer)theSAPAdapterinvokesIDOC_DATE_TIME_GETdirectlyagainst thereceivingSAPsystem.Thisactionreturnsadditionalinformation,liketheIDoc number,fromthereceivingSAPsystem.AllremoteIntegrationServersthatreceiveIDocs viaaremoteinvocationofpub.sap.transport.ALE:InboundProcessshouldthereforealsosupport IDocTracing.
Status Update Via ALEAUD IDoc

Preparation
IfthefinalreceiverisanSAPsystem,theIDocALEAUDcanbeusedtoreportstatus informationfromthereceiverbacktothesender.Tosetupthisscenario,thefollowing settingshavetobecreatedinthedistributionmodelsoftheparticipatingSystems: (MATMASisusedinthisexample) Sending SAP System: FortheLSthatrepresentsthereceiver,setupapartnerprofile, thathasMATMASasanoutboundparameterandALEAUDwithprocesscodeAUD1 asaninboundparameter.
177
Receiving SAP System: FortheLSthatrepresentsthesender,setupapartnerprofile withanoutboundparameterALEAUDandaninboundparameterMATMAS.Alsoin thedistributionmodelthefollowingmodelviewhastobecreated: Sender:T90CLNT090(orLS,whichreceivedtheIDoc,ifdifferent) Receiver: LSofsender Message type:ALEAUD HereaddaFilterwithvalueMATMAS. Nextyouhavetoscheduleajob,whichexecutesavariantofthereportRBDSTATE.The varianthastoincludetheLSofthesenderasselectionparameter.Thisshouldsendoutan ALEAUDIDoctotheIntegrationServer.
Further Setup in the SAP Adapter

To set up the SAP Adapter for status update via ALEAUD proceed along the following steps 1 2 FortheroutingnotificationorALEadapternotificationyouwanttousetomonitor IDocs,setthevaluefortheMonitor IDocsfieldtoOnusingtheDeveloper. Afterallthishasbeensetup,theALEAUDIDoccanberoutedasusuallikea normalIDoc.Hereandinallothercases,wheresender/receiverinformationinthe IDocControlHeaderhasbeenchangedbyamappingonlyonethinghastobetaken intoaccount:thelastIntegrationServer,whichpushestheALEAUDintotheoriginal sendingsystem,hastosetthevaluesofEDI_DC40SNDPRNandEDI_DC40 RCVPRNtotheinverseoftheiroriginalvalues. Forexample:IfyouroriginalIDocwentoutwithaheadersegmentsuchas:
SENDER LS T90CLNT090 Receiver LS XYZCLNT123
ThentheALEAUDhastobepushedinwiththisheader:
EDI_DC40-SNDPRN = XYZCLNT123 EDI_DC40-RCVPRN = T90CLNT090
Thiscanbeachievedbyaddingtheservicepub.sap.monitor.aleaud01:swapSenderReceiverLS aspreprocessingservicetotheroutingnotificationservice.
178
Status Update Via SYSTAT IDoc

Overview
InthiscasetheIntegrationServercanbeconsideredasakindofEDISubsystem.Ifthe SYSTATfeatureisenabled,itautomaticallysendsacustomaryEDISubsystemStatusand someadditionalinformationforeachIDocitreceivedbacktotheoriginalsender.Youcan decideforeachroutingnotificationorALEadapternotificationwhetherSYSTAT informationshouldbereportedtothesenderornot.Thefollowinginformationisthen reportedinadditiontothestatus: Programthatsetthestatus(SAPAdapter) routingnotificationorALEadapternotificationthatprocessedtheIDoc Thekey(TID)underwhichtheIDoccanbefoundintheSAPAdapter Dateandtimeofstatuschange Incaseofanerrorstatus:expliciterrormessage Incaseofasuccessstatus:explicitinformationaboutthefinalreceiver TheSAPAdaptersendsthefollowingstatus: Ifeverythingwentokthefirsttime:06 Translation OKand12 Dispatch OK Ifanerrorhasoccurredthefirsttime:11 Error during dispatch Ifeverythingwentokatalaterretrial:13 Retransmission OK Iftherewasstillanerroratalaterretrial:23 Error during retransmission IfnoinformationontheIDoccouldbedetermined:04 Error within control information of EDI subsystem
Setup the participating SAP Systems

IneachSAPsystemthatistoreceiveSYSTATIDocsfromtheIntegrationServer,youneed toconfigurethefollowingsettings: InSAPsystemsofRelease3.1H3.1Iyouneedtoperformthefollowingadditionalstep, beforecontinuingwiththegeneralsetup: GotoWE42(Processcodes,inbound)andopenthetwotreebranchesInbound with ALE service Processing by task and Inbound without ALE service Processing by task.Youneedto reassigntheprocesscodeSTA1fromwithout ALE servicetowith ALE service,ifthishasnot alreadybeendone.Todothis,proceedasfollows: 1 2 MarkthenodeInbound without ALE service Processing by task IDocwiththecursorandthenpresstheReassignbutton(F6). Confirmthepopup STA1 Status record from
179
3 4 1
DoubleclickonthenodeInbound with ALE service _ Processing by task InthefollowingscreenpresstheSavebutton(F11). OpenSALE(Distribution(ALE))andselectBasis configuration Set up logical system Maintain logical systemstoaddanewlogicalsystemfortheIntegrationServerifyou donothaveoneyet.IfyounameitBUSCON,theIntegrationServerwillrecognizeit automatically;otherwise,youwillhavetomakethenameknowntotheIntegration Serverasdescribedlater. InWE20(PartnerProfiles),createapartnerprofilewithPartn.number = thenameyou choseinstep1(BUSCON)andPartn.type = LS.Afteryousavedit,addanInbound Parametertoitasfollows: Message type=STATUS Process code=STA1
Generalsetup:
Prepare the Integration Server for Automatic SYSTAT IDoc

IntheIntegrationServer,youhavetosetuptheseelementstoenableautomaticstatus updateviaSYSTAT: 1 IfyouchoseadifferentnamefromBUSCONforthelogicalsystemabove,shutdownthe IntegrationServerandaddthefollowingparameterto ...\IntegrationServer\config\server.cnf:
watt.sap.systat01.partnerNumber=<NameOfLogicalSystem>.
StarttheIntegrationServeragain. WithBUSCONyoucanomitthisstep. 2 3 TomarkaroutingnotificationorALEadapternotificationforautomaticstatus update,editthenotificationandsetthevalueforfieldMonitorIDocstoOn. GotoServer Scheduler Create a scheduled taskandscheduletheservice pub.sap.monitor.systat01:report. HereyouspecifytimeintervalsfortheService.Youshouldtrytoscheduleitfortimes whenyouknowthatthereislittleloadonthesystem.Ontheotherhand,inorderto preventtheresultingSYSTATIDocsfromgettingtoobig,youshouldscheduleitoften enough,sothatatmostaround2000IDocshavebeenreceivedbytheSAPAdapter sincethelastrunofthereportservice. Thisservicecollectsallthenecessaryinformationanderror/successmessagesfor thoseIDocs,whichthenotificationschoseninstep2haveprocessedsincethelastrun. ForeachSAPsystemthathassentanysuchIDocstotheSAPAdapter,itcreatesand submitsoneSYSTATIDoccontainingallthisinformation.
180

Asanalternativetostoringtransactioninformationlocally,theSAPAdapterprovidesa CentralizedTransactionStore(CTS)thatenablesyoutorunseveralSAPAdaptersin paralleltoimprovereliability.TheCTSmanagesthetransactionstatesformultipleSAP Adapters,andcanbeusedwitheitheranIntegrationServerclusterorwithagroupof SAPAdaptersonindependentIntegrationServers.Byprovidingacentrallocationin whichtostoretransactioninformation,aCTSensuresthatthestatusofincomingtRFCs willremainvalidandconsistentthroughouttheclusteroradaptergroup.Formore informationaboutusingthetransactionstores,seeConsiderationsaboutSAPAdapter CentralizedTransactionStoreonpage 53. AnSAPAdaptergroupreferstoanumberofSAPAdaptersthatbelonglogicallytogether, thatshareasingleCTSand,bysharingtheCTS,allowreliabletRFC/IDocloadbalancing. TherecanbeonlyoneCTSperadaptergroup.AllSAPAdaptersthatareconfiguredto shareaspecificCTSareconsideredtobeinthesamegroup. TousetheCentralizedTransactionStore,configureoneoftheSAPAdaptersasthe CentralizedTransactionStoreServerandconfiguretherestoftheSAPAdaptersinthe groupasCentralizedTransactionStoreClients.YouconfiguretheRemoteServerwithan aliasofSAPGroupStoreforeachSAPAdapterofyouradaptergroup(andinexactlythe sameway).Forconfigurationinstructions,seeConfiguringaCentralizedTransaction Storeonpage 182. WhenatransactionisprocessedeitherbytheCentralizedTransactionStoreServerorby anyoftheCentralizedTransactionStoreClients,theadapterstoresthetransactionstatus intheserver,whichcanaccessedbytheadapterserverandalltheadapterclients.Note thatthewayinwhichthetransactionsareprocessedisthesameasiftheywerestored locally,butthestatusoftheprocessedtransactionsisstoredintheCentralizedTransaction StoreServerinsteadofstoringthestatuslocallyoneachadapterinthegroup. UsetheTransactionsscreenstoviewandmanagethetransactionsthattheSAPAdapter recordsintheCTS.Formoreinformation,see: ViewingTransactionsonpage 170 DeletingTransactionsonpage 172
181
Foradditionalperformanceandconfigurationtasks,see: AutomaticCleanupoftheTransactionStoreonpage 173 ConfigurationParametersfortheTransactionManageronpage 174 UsingtheALEMonitoringFeaturesViatheSAPAdapteronpage 175 ConfiguringaCentralizedTransactionStoreonpage 182 ViewingCentralizedStoreConfigurationandStatusonpage 185 RemovingtheConfigurationofaCentralizedTransactionStoreonpage 186
Configuring a Centralized Transaction Store

UsethefollowinginstructionstoconfigureaCentralizedTransactionStoreServerand CentralizedTransactionStoreClients. To configure the Centralized Transaction Store (Server) Note: PerformthisprocedurefortheSAPAdapterthatistobetheCTSServer. 1 2 3 IntheSettingsmenuintheIntegrationServerAdministratornavigationarea,click Remote Servers. IntheRemote Serverspage,clickCreate Remote Server Alias. IntheRemote Server Alias Properties,specifyvaluesforthefollowingfields: Field Alias Description ThisisthenamebywhichtheSAPAdapterwillidentifythe CentralizedTransactionStoreconfiguration. YoumustenterSAPGroupStoreinthisfield. Host Name or IP Address ThisisusedtoidentifytheIntegrationServeronwhichthe CentralizedTransactionStoreishosted. YoumustenterthehostnameorIPaddressoftheIntegration ServerhostingtheCentralizedTransactionStore,orlocalhostor 127.0.0.1ifitisthelocalIntegrationServer. Port Number User Name EntertheportnumberonwhichtheIntegrationServeris running. EntertheusernametologontotheIntegrationServeron whichtheCentralizedTransactionStoreishosted.
182
Field Password Execute ACL
Description EnterthepasswordtologontotheIntegrationServeron whichtheCentralizedTransactionStoreishosted. SelecttherequiredACLtypefromthedropdownlist. Default:Internal FormoreinformationaboutassigningandmanagingACLs, seethewebMethodsDeveloperUsersGuide.
Idle Timeout (minutes)
DelaytimeuntilanunusedrepositoryconnectiontoSAP Adapteristimedout. Default:0
Use SSL
SelectifyouwanttousetheSSLprotocol. Default:No
Private Key
ToestablishaSecureSocketLayer(SSL)connectionbetween anIntegrationServerandaSAPServer.Eachservermusthave accesstoitsownprivatekey. ToestablishaSecureSocketLayer(SSL)connectionbetween anIntegrationServerandaSAPServer.Eachservermusthave accesstoitspartnerscertificate(s). ThisfieldwillnotbeusedbytheCentralizedTransaction Store.
Certificates
Retry Server
4 5
ClickSave Changes. ReloadtheWmSAPpackage.
Toviewtheconfigurationandthestatusofthestore,seeViewingCentralizedStore ConfigurationandStatusonpage 185.
183
To configure the Centralized Transaction Store (Client) Note: PerformthisprocedureforeachSAPAdapterthatistobeaCTSclient. 1 2 3 IntheSettingsmenuintheIntegrationServerAdministratornavigationarea,click Remote Servers. IntheRemote Serverspage,clickCreate Remote Server Alias. IntheRemote Server Alias Properties,specifyvaluesforthefollowingfields: Field Alias Description ThisisthenamebywhichtheSAPAdapterwillidentifythe CentralizedTransactionStoreconfiguration. YoumustenterSAPGroupStoreinthisfield. Host Name or IP Address ThisisusedtoidentifytheIntegrationServeronwhichthe CentralizedTransactionStoreServerishosted. YoumustentertheserverIPaddressorthehostnameofthe CentralizedTransactionStore. Port Number User Name Password Execute ACL EntertheCentralizedTransactionStoreServerportnumber. EntertheusernametologontotheIntegrationServeron whichtheCentralizedTransactionStoreServerishosted. EnterthepasswordtologontotheIntegrationServeron whichtheCentralizedTransactionStoreServerishosted. SelecttherequiredACLtypefromthedropdownlist. Default:Internal ForgeneralinformationaboutassigningandmanagingACLs, seethewebMethodsDeveloperUsersGuide. Idle Timeout (minutes) DelaytimeuntilanunusedrepositoryconnectiontoSAP Adapteristimedout. Default:0 Use SSL SelectifyouwanttousetheSSLprotocol. Default:No Private Key ToestablishaSecureSocketLayer(SSL)connectionbetween anIntegrationServerandaSAPServer.Eachservermusthave accesstoitsownprivatekey.
184
Field Certificates
Description ToestablishaSecureSocketLayer(SSL)connectionbetween anIntegrationServerandaSAPServer.Eachservermusthave accesstoitspartnerscertificate(s). ThisfieldwillnotbeusedbytheCentralizedTransaction Store.
Retry Server
4 5
ClickSave Changes. ReloadtheWmSAPpackage.
Toviewtheconfigurationandthestatusofthestore,seeViewingCentralizedStore ConfigurationandStatusonpage 185.
Viewing Centralized Store Configuration and Status

1 2 IntheAdaptersmenuinthenavigationareaoftheAdministrator,clickSAP Adapter. IntheSAP AdaptermenuinthenavigationareaoftheSAPAdapter,clickSettings.
Atthebottomofthepage,youcanviewtheconfigurationdetailsoftheSAP AdapterGroup. TheCentralized StorefieldmustdisplayLocal File SystemforCentralizedTransactionStore ServerandRemote File system <server IP Address>forCentralizedTransactionStoreClients. Important! EnsurethattheIntegrationServerthathoststheCentralizedTransactionStoreis alwaysstartedfirst,beforestartinganyotherSAPAdapterintheSAPAdaptergroup.If theCentralizedTransactionStoreClientscannotfindoraccesstheCentralized TransactionStoreServerduringadapterstartup,theywillnotbeabletostartandwillshut downwithfailure.Inthesameway,itisalsoimportanttoalwaysshutdownall CentralizedTransactionStoreClientsbeforeshuttingdowntheCentralizedTransaction StoreServer.TheCentralizedTransactionStoreClientswillotherwisedisplayruntime errorswhiletryingtopersisttransactionstatusinformation,andtransactionsor transactionchangeswillbelost.
185
Removing the Configuration of a Centralized Transaction Store

IfyounolongerwantaparticularSAPAdaptertousetheCentralizedTransactionStore (CTS),youcanremoveorrenametheadaptersRemoteServerwithaliasSAPGroupStoreby followingtheinstructionsinthissection. IfyouremovetheRemoteserverforanSAPAdapterthatisaCTSClient,theCTSServer willdisplaythatparticularclientsstatusasInactiveintheadaptersSettingspage.After reloadingtheWmSAPpackageorrestartingtheIntegrationServer,theSAPAdapter,the adapterwilluseitslocalTransactionStoretopersisttransactioninformation. Important! webMethodsdoesnotrecommendremovingtheCTSServer.However,ifyou doremovethealiasforanSAPAdapterthatistheCTSServer,noneoftheCTSClients willbeabletoprocessanytransactionsandamessageisdisplayedontheconsole indicatingthattheCTSServerisnotaccessible.WhenanSAPAdapterthatisconfigured asaCTSclientcannotconnecttotheCTSServerduringstartup,anerrormessageis displayed,theadapterwillonlybepartiallyloaded,andtransactionsarenotpersisted. DonotremoveorrenametheRemoteServerAliasforSAPGroupStorewhiletheSAP Adapterisstillprocessingmessages.Otherwisethetransactionstatusofthesemessages couldbelostorbecomeinvalid.
From the SAP Adapter that you want to remove from the CTS 1 IntheSettingsmenuintheIntegrationServerAdministratornavigationarea,click Remote Servers. OntheRemote Serversscreen,click fortheRemoteServerAliasoftheSAP AdapterthatyounolongerwanttousetheCTS. TheSAPAdapterremovestheRemoteServerAlias. 3 ReloadtheWmSAPPackage. TheaffectedSAPAdapterdoesnotregisteritselfwiththeCTSserverduringadapter startup,andwillnowuseitslocalTransactionStoreinsteadoftheCTStopersistall transactions.Bydoingso,theadapteriseffectivelynolongerpartofthelogicalgroup ofadapters.
186
CHAPTER
10
Logging and Monitoring

Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Monitoring SAP Adapter Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
187
CHAPTER 10 Logging and Monitoring
Logging
InthedevelopmentandtestphaseitissometimeshelpfultoviewRFCtracesifthereare problemswiththefunctionmodulesyouaretryingtocall.Inordertoavoidtheneedto accessthefilesystemofthemachineonwhichtheIntegrationServerisrunning,youcan viewanddeleteRFCtracefilesandSAPlogfilesfromtheAdministratorUI. AllSAPlogfiles,aswellastheRFCtracefilesarestoredinthepackages/WmSAP/logs directory.AspartoftheSAPAdapterinstallation,instructionswereprovidedtosetthe RFC_TRACE_DIRenvironmentvariabletopointtothatdirectory.(SeethewebMethods SAPAdapterInstallationGuideforinformationaboutsettingthedirectoryfortracefiles.) IftheRFC_TRACE_DIRenvironmentvariablewasnotsetduringadapterinstallation,the SAPAdaptertracefileswillbestoredintherootdirectoryoftheIntegrationServer.You willnotbeabletoviewthetracefilesintheAdministratorUI.
Viewing and Deleting RFC Trace Files and SAP Log Files
To view and delete RFC trace files and SAP log files 1 2 IntheAdministratorUI,browsetoAdapters SAP Adapter Logging.
TheLoggingscreenappears.ThisscreenliststheRFCtracefilesandSAPlogfiles,and showseachfilessizeandcreationdate. RFCtracefilesaresplitintoseveralparts,eachofthemcontainingonetraceentry alongwiththedateandtimeitwascreated.Toviewthelogentriesforaspecific TraceFile,clicktheTraceFilename. LargeSAPlogfilesaresplitintoseveralpartsofabout500K.Toviewthelog entriesforaspecificSAPlogFile,clicktheSAPLogFilename. Inthiswayitisavoidedthatthebrowserhastoloadtoolargedocuments,which wouldtakealongtimeorevencauseatimeout.UsingtheBackbuttonofyour browser,youcanreturnfromthedisplayofoneparttothelistofpartsforthat file.Ifyoutrytodeleteafilethatisstillopen(forexample,becausetheServeris stillwritingtoit),youwillreceiveamessage,andthefilewillnotbedeleted.
Youcandeletefilesthatyounolongerneed: TodeleteanindividualtracefileorSAPlogfile,clickthe delete. iconforthefileto
ToquicklydeletealltracefilesorallSAPlogfiles,clickDelete All.
188
Monitoring SAP Adapter Performance
Monitoring SAP Adapter Performance

Performance Output Information in the SAP Log File
Fromdebuglevel7orhigheryoucanviewperformanceoutputinformationfortheSAP AdapterintheSAPlogfile.Thecorrespondingtermsaredescribedbelow: The term
1 2 3
Specifies TimeneededfortransferringthedatafromIData (pipelinerepresentation)toJCoObjects. TimeneededfortransferringthedatafromJCoObjects toIData(pipelinerepresentation). Timeneededforpreparingexecutionofafunction module(outboundcalls)orinvocationofaservice.This includesrepositoryqueriesforthedatastructuresand thefunctioninterface,openingconnectionstothe involvedsystems,etc. TimeneededintheJColayerforoutboundcalls. Timeneededfortheinvocationofaservicetohandlean inboundrequestintheSAPAdapterafter preparing/marshallingandbeforeunmarshallingthe data.(Listenerperformancedata). Totaltimeneededforhandlinginbound/outboundcalls inSAPAdapterlayer.
Time for marshalling (ms) Time for unmarshalling (ms) Time for preparing (ms)
4 5
Time for rfc calls (ms) Time for SAP Adapter service calls (ms)
Total time for function calls (ms)
Component Response Time Measurement

Withthiskindofmonitoring,anapplicationgetssplitintoseveralcomponentsandthe responsetimegetsmeasuredpercomponent.Youwillfindthisinformationon Adapters SAP Adapter Monitoring: Atthebottomofthisscreen,youwillfindthefollowingmonitoringinformation:
Monitoring information
The term Requests total Request rate Requests ok Requests with errors
Specifies Numberofrequestsexecutedsofar. Requestspersecondsincemonitoringwasenabled. Numberofsuccessfulrequests. Numberofrequestswitherrors.
189
CHAPTER 10 Logging and Monitoring
The term Components total Components per request Total time Average time Query Requests
Specifies Numberofcomponentsusedinrequests. Averagenumberofcomponentsperrequest. Executiontimeforallrequestsinmilliseconds. Averageexecutiontimeforarequestinmilliseconds. YoucangettheTOP100requests(therequeststhat neededthelongestexecutiontimes.)Torestrictthose entries,youcanspecifytheInfo forandmax. listed RequestsinputsbeforepushingtheShowButton. Enterawildcardlikepatternfortherequestnames,for whichyouwanttheinformation.Youcanuseonlyexact patternsandpatternswithasingle*attheend,suchas client.*.Youcannotmakeentrieswiththeformat *rfc*. Limitsthenumberofrequeststothegivennumber. Afterpushingthebutton,theRequestsOverviewis displayed. Youcangetaccumulatedinformationaboutall components,thathavebeenusedinRequest.Torestrict thoseentriesyoucanspecifytheInfo forinputbefore pushingtheShowButton: EnterawildcardlikepatternfortheComponentnames, forwhichyouwanttheinformation.Youcanuseonly exactpatternsandpatternswithasingle*attheend, suchasclient.*Youcannotmakeentrieswiththe format*rfc*.Afterpushingthebutton,the ComponentOverviewisdisplayed.
Info for ...
max. listed Requests
Query Components
Info for ...
190
CHAPTER
11
Coding Client Applications and Services

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Invoking RFCs from the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Receiving IDocs from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Constructing an IDoc with the SAP Java IDoc Class Library . . . . . . . . . . . . . . . . . . . . . . . 194 Transaction Features for HTTP and SAP-XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Calling a BAPI Synchronously from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Calling a BAPI Asynchronously from an SAP System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
191
C H A P T E R 11 C o d i n g C l i e n t A p p l i c a t i o n s a n d S e r v i c e s
Overview
TheSAPAdapterhasseveralAPIsthatyoucanuseinyourclientapplicationsand services.ThischaptershowshowtousethebuiltinservicesAPItoinvokeSAPRFCs, sendIDocstoanSAPsystemandtoreceiveanIDocfromanSAPsystem.Fordescriptions oftheavailablebuiltinservices,refertoAppendix D,BuiltinServices. FormoreinformationaboutbuildingtheJavaservices,seetheonlineAPIdocumentation installedwiththeIntegrationServerat: webMethods_directory\IntegrationServer\doc\api\Java\index.html ThischapteralsoshowshowtousethewebMethodsSAPAdapterIDocJavaAPIto constructanIDoc.Forinformation,referto webMethods_directory\IntegrationServer\packages\WmSAP\pub\doc\api\index.html.
Invoking RFCs from the SAP Adapter

Calling Public SAP Adapter Services from Java Services
ThissectionshowsanexampleofhowtoinvokeanRFCfromaJavaservice.Thesample app/BAPI.java thatisshownbelowlogsontoanSAPsystemandinvokesaBAPI. Formoreinformationaboutdevelopingservices,seethewebMethodsDeveloperUsers GuideandtheonlineAPIdocumentation. To call a public SAP Adapter service from Java 1 2 StarttheDeveloperifitisnotalreadyrunning. CreateaJavaservicenamedapp.BAPI:callServiceandenterthefollowingsource:
IDataCursor idc=pipeline.getCursor(); IDataUtil.put(idc, "serverName", "CER"); IDataUtil.put(idc, "COMPANYID", "000001"); IDataUtil.put(idc, "$rfcname", "BAPI_COMPANY_GETDETAIL"); try { Service.doInvoke("pub.sap.client", "invoke", pipeline); } catch (Exception e) { throw new ServiceException(e); } finally { idc.destroy(); }
192
Receiving IDocs from an SAP System
ThisservicewillinvokeBAPI_COMPANY_GETDETAILwithacompanyIDof000001 andreturntheresults.ThelogontotheSAPsystemisdoneautomaticallyusingthe connectioninformationfortheRFCconnectionalias. Note: ChangetheRFCconnectionalias(fieldserverNameofthepublicSAPAdapter service)toyourownalias.
Receiving IDocs from an SAP System

ToreceiveanIDocfromanSAPsystemandpassittoaservice,youcansetupan synchronousALEadapternotificationoraroutingnotification.Ineithercase,youneedto assigntheserviceyouwouldliketoinvoketothenotification.Forinstructionson establishingroutingnotifications,refertoRoutingNotificationsonpage 134.When choosingthetransportfortheroutingnotification,selecttheIStransport.Forinstructions onestablishingasynchronousALElistenernotifications,refertoCreatingaSynchronous RFCAdapterNotificationonpage 110. Note: WithRelease6.5oftheSAPAdapter,youmustusetheSAPJavaIDocClassLibrary toprocessIDocs.
Accessing and Modifying Fields in IDocs

ThefollowingcodesampleshowshowtousetheSAPJavaIDocClassLibrarytoconvert anIDoctoastructureddocumentwithdirectaccesstoeachfield.Thisallowsyouto modifyanIDocscontentsonthefly.Forexample,ifyouwanttocustomizeincoming IDocsbasedonlocaldataformat,youcandoso.
IDataCursor idc=pipeline.getCursor(); IDoc.DocumentList iDocList=null; if (idc.first(iDocList)) iDocList=(IDoc.DocumentList)idc.getValue();
underShared
Imports,includethelines:
com.wm.adapter.sap.idoc.* com.sap.mw.idoc.IDoc
Note: ToresolvetheincludedJavaclasses,youmustincludetheWmSAPpackageinthe dependencysectionofyourapplicationpackage. FormoreinformationaboutusingtheSAPJavaIDocClassLibrary,refertoConstructing anIDocwiththeSAPJavaIDocClassLibraryonpage 194
193
Converting an IDoc to XML

ThefollowingcodesampleshowshowtoconvertanIDoctoXML.
String xmlData = idocList.toXML();
Constructing an IDoc with the SAP Java IDoc Class Library

ThefollowingsampleshowshowtoconstructanewMATMASIDoc. Important! Remembertoincludecom.wm.adapter.sap.idoc.* and com.sap.mw.idoc.IDocinShared Imports. Note: ThefirstthreelinesaregeneratedbytheDeveloper.
public final static void createIDoc (IData pipeline) throws ServiceException { //create a new and empty MATMAS02 document IDoc.DocumentList iDocList = new IDataDocumentList(); IDoc.Document doc=iDocList.addDocument("MATMAS02"); //set the appropriate control header data doc.setIDocNumber("0000047112211178"); doc.setClient("000"); doc.setDirection("1"); doc.setRecipientPartnerType("LS"); doc.setMessageType("MATMAS"); doc.setRecipientPartnerType("LS"); doc.setRecipientPartnerNumber("TSTCLNT000"); doc.setSenderPort("SAPBCIDOC"); doc.setSenderPartnerType("LS"); doc.setSenderPartnerNumber("SBCCLNT000"); doc.setCreationDate("20030511"); doc.setCreationTime("103051"); doc.setSerialization("20030511103051"); //get the root segment from the document //The root segment does not contain any fields or data. It is only //used as the standard parent segment and won't be transmitted when //the document is sent to an SAP system. IDoc.Segment segment = doc.getRootSegment(); //create and add a new and empty child segment of type E1MARAM //and fill the segment data segment = segment.addChild("E1MARAM"); segment.setField("MSGFN", "005"); segment.setField("MATNR", "BOXCOOKIES");
194
Constructing an IDoc with the SAP Java IDoc Class Library
segment.setField("ERSDA", segment.setField("ERNAM", segment.setField("PSTAT", segment.setField("MTART", segment.setField("MBRSH", segment.setField("MATKL", segment.setField("MEINS", segment.setField("BLANZ", segment.setField("BRGEW", segment.setField("NTGEW", segment.setField("GEWEI", segment.setField("VPSTA",
"20030303"); "TOPSI"); "KBG"); "FERT"); "L"); "G1113"); "PCE"); "000"); "0.550"); "0.000"); "KGM"); "KBG");
//create and add a new and empty child segment of type E1MAKTM //and fill the segment data segment = segment.addChild("E1MAKTM"); segment.setField("MSGFN", "005"); segment.setField("SPRAS", "D"); segment.setField("MAKTX", "Schachtel mit Keksen"); segment.setField("SPRAS_ISO", "DE"); //create and add a new and empty sibling segment of type E1MAKTM (same //type) and fill the segment data segment = segment.addSibling(); segment.setField("MSGFN", "005"); segment.setField("SPRAS", "E"); segment.setField("MAKTX", "Box of cookies"); segment.setField("SPRAS_ISO", "EN"); //create and add a new and empty sibling segment of type E1MARCM //and fill the segment data segment = segment.addSibling("E1MARCM"); segment.setField("MSGFN", "005"); segment.setField("WERKS", "0001"); segment.setField("PSTAT", "BG"); segment.setField("PLIFZ", "0"); segment.setField("WEBAZ", "0"); segment.setField("PERKZ", "M"); segment.setField("AUSSS", "0.00"); segment.setField("BESKZ", "E"); segment.setField("AUTRU", "X"); //create and add a new and empty sibling segment of type E1MBEWM //and fill the segment data segment = segment.addSibling("E1MBEWM"); segment.setField("MSGFN", "005"); segment.setField("BWKEY", "0001"); segment.setField("VPRSV", "S"); segment.setField("VERPR", "0.00"); segment.setField("STPRS", "15.50"); segment.setField("PEINH", "1");
195
segment.setField("BKLAS", segment.setField("VJVPR", segment.setField("VJVER", segment.setField("VJSTP", segment.setField("LFGJA", segment.setField("LFMON", segment.setField("PSTAT", segment.setField("KALN1", segment.setField("KALNR", segment.setField("EKALR", segment.setField("VPLPR", segment.setField("VJBKL", segment.setField("VJPEI", segment.setField("BWPEI",
"7920"); "S"); "0.00"); "15.50"); "2002"); "08"); "BG"); "000100126602"); "000100126603"); "X"); "0.00"); "7920"); "1"); "0");
IDataCursor idc=pipeline.getCursor(); IDataUtil.put(idc, "iDocList", iDocList); idc.destroy(); }
Sending IDocs to an SAP System

ThebasicstepstosendanoutboundIDocfromeitheraclientoraserviceare: 1 2 CreateatransactionIDbyinvokingthepub.sap.client:createTID service. SendtheIDoctotheSAPsystembyinvokingthepub.sap.client:sendIDocservice,passing inthecom.sap.mw.idoc.IDoc.DocumentListobject(iDocList). Ifanerroroccurs,repeatthepub.sap.client:sendIDoc serviceinvocationwiththesame transactionID.TheSAPsystemguaranteesthatthetransactionwillexecuteonly once. 3 Afterpub.sap.client:sendIDocreturnssuccessfully,invokepub.sap.client:confirmTID.
Transaction Features for HTTP and SAP-XML

WhenexecutingHTTPPostsusingIDocXMLandXRFCwithtransactions,youshould makesurethatyourclientcorrectlyhandlessuchcalls.Itshouldhavetransaction managementthatsupportsatleastthefollowingfeatures: TransactionIDgeneration ResendingdocumentswithsametransactionIDinerrorcases. Afterasuccessfulexecutionofatransaction,adocumentcannotbesentagain. TotransferthetransactionIDtotheSAPAdapter,youaddanextraheadertotheHTTP POST,xtid,thatcontainsthetransactionID.
196
Calling a BAPI Synchronously from an SAP System
Example: HTTP POST of an IDoc

POST /invoke/pub.sap.transport.ALE/InboundProcess HTTP/1.0 X-tid: 9B38FA81133A38B518A10036 Content-type: application/x-sap.idoc Content-Length: 4242 <?xml version="1.0" encoding="iso-8859-1"?> <MATMAS02> <IDOC BEGIN="1"> <EDI_DC SEGMENT="1"> <TABNAM>EDI_DC</TABNAM> <MANDT>000</MANDT> <DOCNUM>0000047112211178</DOCNUM> <DOCREL/> <STATUS/> <DOCTYP>MATMAS02</DOCTYP> <DIRECT>1</DIRECT> ...
ForXRFCdocuments,youcanalsoputthetransactionIDintheheaderofthedocument:
<?xml version="1.0"?> <sap:Envelope xmlns:sap="urn:sap-com:document:sap" version="1.0"> <sap:Header xmlns:rfcprop="urn:sap-com:document:sap:rfc:properties"> <rfcprop:Transaction>0A1104DC080C3C60F9E106A1</rfcprop:Transaction> </sap:Header> <sap:Body> <rfc:SBC_TEST_SAVE xmlns:rfc="urn:sapcom:document:sap:rfc:functions"> <INPUT>Have fun!</INPUT> </rfc:SBC_TEST_SAVE> </sap:Body> </sap:Envelope>

ThisexampledemonstrateshowtosendtheBAPICompanyCode.GetDetailfromanSAP systemtotheWebviaXML. AstheBAPIwillbehandledbyaroutingnotification,youneedtospecifysome informationtoenablecorrectrouting.Forthispurpose,youshouldusetheparameter SBCHEADERwhencallingtheRFCfunctionmodulefromtheSAPsystem.
197
To set up for the example 1 2 SetupanRFCListenerfortheSAPsystemonyourSAPAdapterasdescribedin Listenersonpage 87. SetupacorrespondingRFCdestinationonyourSAPsystemforyourRFCListener usingthetransactionSM59asdescribedinCreatinganRFCDestinationonanSAP Systemonpage 84. CreateaprogramZ_BAPI_RFC_DEMOintheSAPsystemusingthetransactionSE38 Youcanenterthefollowingsourcecode:
REPORT Z_BAPI_RFC_DEMO . *variable companyCodes will take the application result data companyCodes like BAPI0002_1 occurs 1 with header line. *variable header gives SAP Adapter instructions for routing data header like SBCCALLENV occurs 1 with header line. *variable returnCode takes the processing information after the *synchronous call data returnCode type BAPIRETURN. *Fill the SAP Adapter routing instructions header-name = 'sender'. header-value = 'CERCLNT800'. append header. header-name = 'receiver'. header-value = 'CERCLNT750'. append header. *Execute the RFC with destination ISCER CALL FUNCTION 'BAPI_COMPANYCODE_GETLIST' *->ISCER should be maintained in SM59 as alias to SAP Adapter DESTINATION 'ISCER' IMPORTING RETURN = returnCode TABLES COMPANYCODE_LIST = companyCodes SBCHEADER = header[] . *process the BAPI-Return parameter if not returnCode is initial. write: / 'BAPI return parameter:'. write: / ' Code: ' , returnCode-CODE. write: / ' Message: ' , returnCode-MESSAGE. endif. *display the application result loop at companyCodes. write: / companyCodes-COMP_CODE, ' ', companyCodes-COMP_NAME. endloop.
198
Beforeexecutingthisreport,youshouldspecifyaroutingnotificationtotheXML transport.YoucansendtheXMLmessagetoanyserverthatisabletoprocesstheHTTP Postmessageandsendbackacorrectresponse.Inthisexample,thecallwillbesentback tothelocallyinstalledIntegrationServertodemonstrateitsinboundXMLprocessing capabilities. To prepare a routing notification for the BAPI call 1 2 3 4 5 6 OpentheDeveloperandselectNew Adapter Notification.ClickNext.
SelectSAP Adapterfromthelistofavailableadaptertypes.ClickNext. Fromthelistofavailabletemplates,selectRouting Notification.ClickNext. Selecttheroutinglistenerwm.sap.internal.ls:routingListener.ClickNext. Enteranameandselectafolderwheretheroutingnotificationshouldbestored. Selectanyservicethatshouldbeinvokedbythisnotification.ClickNextandthen Finish. Note: Theserviceyouselectedinstep 6willonlybeusediftheoutboundtransport thatischoseninyourroutingnotificationisIS.Forallotheroutboundtransports, thisselectionwillbeoverriddenbyatransportspecificservice.
Intheinputfieldsatthetopofthepage,enterthefollowingdata: a b c d Sender: CERCLNT800. Receiver:CERCLNT750. msgType:BAPI_COMPANYCODE_GETLIST. SelectXMLintheTransportfield.
SpecifyaURLforthetargetsystem.Totestthefunctionalityusingyourlocal IntegrationServersInboundprocessing,enter:
http://localhost:5555/invoke/pub.sap.transport.BAPI/InboundProcess
(notethatinsomecasesyouhavetoadjusttheport5555toyourcurrentsettings). a b c d e SelectdialectbXMLforthexmlTypeparameter. SelectYesfortheuseBAPIparameter. EnterCompanyCodefortheobjectNameparameter. EnterGetListforthebapiName. ClicktheSavebutton.
TohandletheinboundXMLmessage,whichwillnowbesentbacktothelocalIntegration Server,youhavetospecifyasecondroutingnotificationfortheBAPI:
199
To specify a second routing notification for the BAPI 1 Intheinputfieldattheendofthepage,enterthefollowingdata: a b c 2 3 Sender:CERCLNT800. Receiver: CERCLNT750. msgType:CompanyCode.GetList.
SelectBAPIintheTransportfield. SelecttheSAPsystemtowhichthemessageshouldberoutedfromthedropdown list.
WhenexecutingtheprogramintheSAPsystem,theSAPAdaptersendstheHTTP Requesttotheremotehost,whichlookssimilartothefollowing:
POST /invoke/pub.sap.transport.BAPI/InboundProcess HTTP/1.0 User-Agent: Mozilla/4.0 [en] (WinNT; I) Accept: image/gif, */* Host: localhost:90 Content-type: application/x-sap.busdoc Cookie: ssnid=553891555519 Content-length: 817 <?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <message> <messageID>0A125F1315B3D24B0000001E</messageID> <sent>2000-06-20T09:58:00</sent> </message> <to> <address>urn:sap-com:logical-system:CERCLNT750</address> </to> <from> <address>urn:sap-com:logical-system:CERCLNT800</address> </from> </delivery> </header>
200
Calling a BAPI Asynchronously from an SAP System
<body> <doc:CompanyCode.GetList xmlns:doc="urn:sapcom: document:sap:business" xmlns=""> <CompanyCodeList> <item> <COMP_CODE></COMP_CODE> <COMP_NAME></COMP_NAME> </item> </CompanyCodeList> </doc:CompanyCode.GetList> </body> </biztalk_1>
WhenusingtheIntegrationServerastheremotepartnerasdescribedabove,theBAPIwill beexecutedintheselectedsystem,theexportingandchangingparameterswillbeputin anXMLresponsedocumentandsentbacktothecallingSAPsystem. Thereportwillthendisplaytheparametersreceivedfromtheremotesystem,whichin thiscaseisalistofcompanycodes.

ThisexampledemonstrateshowtocallaBAPIasynchronouslyfromanSAPsystemover theWeb.Forthispurpose,youhavetocreateanABAPprograminsidetheSAPsystem. ThisprogramcallstheproxyfunctionmoduletogenerateanALEmessageforaBAPI. AfterperformingaCOMMIT WORK command,theSAPsystemwillgenerateanIDoc throughtheALEservicelayerandsendittotheSAPAdapter.TheretheIDocwillbe transformedintotheoriginalBAPIrepresentationandsentasXMLusingHTTPtoany remotewebsystem. Note: WhileBAPIfunctionmodulenamesusuallystartwiththeprefixBAPI_,the correspondingALEproxiesareusuallynamedequallywiththeprefixALE_ Torunanexample,youshouldsetupyourSAPsystemforALEprocessingasdescribed intheSAPsystemdocumentationandinthisguide.Whendefiningthepartnerprofilefor theoutgoingIDocintheSAPsystem,ensurethattheoptionTransfer IDoc immediately is selectedbecausetheBAPIconversiontoolontheSAPAdapterdoesnotsupportIDoc packages. CreatethefollowingreportinyourSAPsystemtotesttheBAPIconversionwiththeBAPI Bank.Create (availableasofSAPrelease4.6C).
REPORT Z_BAPI_ALE_DEMO . parameters receiver like BDI_LOGSYS-LOGSYS. parameters country like BAPI1011_KEY-BANK_CTRY default 'DE'. parameters bankkey like BAPI1011_KEY-BANK_KEY default '34981255'. data: receivers like BDI_LOGSYS occurs 0 with header line, address like BAPI1011_ADDRESS.
201
*prepare the distribution information move receiver to receivers-LOGSYS. append receivers. *prepare the BANK addres parameter address-BANK_NAME = 'Demo Bank'. address-REGION = 'BW'. address-STREET = 'Neurottstr. 16'. address-CITY = 'Walldorf'. address-SWIFT_CODE = 'ABCDDE12'. address-BANK_GROUP = 'SB'. address-BANK_NO = '12345678'. address-ADDR_NO = '123'. *send data to ALE CALL FUNCTION 'ALE_BANK_CREATE' EXPORTING BANKCTRY = country BANKKEY = bankkey BANKADDRESS = address TABLES RECEIVERS = receivers EXCEPTIONS ERROR_CREATING_IDOCS = 1 OTHERS = 2 . IF SY-SUBRC <> 0. write: / 'IDoc could not be created'. ELSE. write: / 'IDoc successfully created'. ENDIF. *trigger processing commit work and wait.
To create similar routing notifications Youcancreateroutingnotificationssimilartothosedescribedinthesynchronous example. 1 Intheinputfield,enterthefollowingdata: a b c 2 Sender:enterthelogicalsystemofthesendingsystem. Receiver:enterthelogicalsystemofthetargetsystem. msgType:BANK_CREATE.
Inthetransportfield,selectXML.
202
SpecifyanURLforthetargetsystem.Totestthefunctionalityusingyourlocal IntegrationServersInboundprocessing,enter:
http://localhost:5555/invoke/pub.sap.transport.BAPI/InboundProcess
(notethatinsomecasesyouhavetoadjusttheport5555toyourcurrentsettings) 4 5 6 7 SelectdialectBizTalkforthexmlTypeparameter. SelectYesfortheuseBAPIparameter. EnterbankfortheobjectNameparameter. EnterCreateastheBAPI.
To handle the Inbound XML Message TohandletheinboundXMLmessage,whichwillnowbesentbacktothelocalIntegration Server,youhavetospecifyasecondroutingnotificationfortheBAPI: 1 Intheinputfield,enterthefollowingdata: a b c 2 3 Sender:enterthelogicalsystemofthesendingsystem. Receiver:enterthelogicalsystemofthetargetsystem. Message-type:Bank.Create.
Inthefieldtransport,selectBAPI. SelecttheSAPsystemtowhichthemessageshouldberoutedfromthedropdown list. Whenexecutingthereport,youhavetoenteraRECEIVER.Thisshouldbethename ofthelogicalsystemyouhavedefinedforyourSAPAdapter.
WhenexecutingthereportintheSAPsystem,theSAPAdapterwilltransmittheXML documentviaHTTP(namesoflogicalsystemsdependonyoursystemconfiguration). TheXMLwouldlooklikethis:

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <message> <messageID>0A125F1315B3A11B00000035</messageID> <sent>2000-06-07T09:22:40</sent> </message> <to> <address>urn:sap-com:logical-system:CERCLNT750</address> </to> <from> <address>urn:sap-com:logical-system:CERCLNT800</address> </from>
203
</delivery> </header> <body xmlns=""> <doc:Bank.Create xmlns:doc="urn:sap-com:document:sap:business"> <BankKey>34981243</BankKey> <BankCtry>DE</BankCtry> <BankAddress> <BANK_NAME>Demo Bank</BANK_NAME> <REGION>BW</REGION> <STREET>Neurottstr. 16</STREET> <CITY>Walldorf</CITY> <SWIFT_CODE>ABCDDE12</SWIFT_CODE> <BANK_GROUP>SB</BANK_GROUP> <POBK_CURAC></POBK_CURAC> <BANK_NO>12345678</BANK_NO> <POST_BANK></POST_BANK> <BANK_BRANCH></BANK_BRANCH> <ADDR_NO>123</ADDR_NO> </BankAddress> </doc:Bank.Create> </body> </biztalk_1>
YoucancheckthecorrectprocessingofyourBAPIcallintheIDocstatusmonitor.
204
InthetargetSAPsystem,youcanalsoinspectthecorrectprocessingusingtheALEstatus monitor(BD87inSAPrelease4.6C.IDoclistscanalsobedisplayedwithWE05).Ifany applicationerrorsoccurred,theyarelistedintheIDocmonitor.
205
206
CHAPTER
12
Security
SAP Adapter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 User Authentication Between the SAP Adapter and an SAP System . . . . . . . . . . . . . . . . . 208 Installing the SAP Adapter According to Your Security Policy . . . . . . . . . . . . . . . . . . . . . . . 213
207
CHAPTER 12 Security
SAP Adapter Configuration

PleaserefertothewebMethodsCertificateToolkitUsersGuideandthewebMethodsIntegration ServerAdministratorsGuideforinformationonhowtoconfigureyourIntegrationServer securely.
User Authentication Between the SAP Adapter and an SAP System

Authentication Through User Name and Password
WhenloggingonthroughanHTTPorFTPclient,standarduser/passwordauthentication isused.TheuserismappedtoanIntegrationServersession,andaservicecallinganSAP systemisexecuted.ThisserviceusesthelogonparametersassociatedwithanRFC connectionthatlikelydoesnotreflecttheidentityoftheoriginalHTTPclient.Theuser configuredfortheRFCConnectionisusuallyapoolusersharedamongseveralphysical users.Thispoolingallowsforoptimalperformance. IfyourRFCconnectionisconfiguredtouseSNC,asecureconnectiontotheSAPsystem willbeestablished.Youneedtoinstallandconfigurethecorrect*sapcrypto.*libraryfor yourplatform.ThislibrarysupportsSAPsSecureNetworkCommunication(SNC) Standard.SNCworksontopoftheRFCprotocol.
Authentication Through X.509 Certificate

AnothermethodforuserauthenticationintheIntegrationServeristhroughclient authenticationasapartoftheSSLprotocol.ThisrequiresthatthecorrespondingHTTPS listener(port)requestsaClientCertificateandthattheclientsendsatrustedcertificate thatismappedtoanexistingIntegrationServeruser.Acertificateisconsideredtrusted ifithasbeenissuedbyaCA(CertificateAuthority)andislistedinalocalCACertificate Directory. ItisthenpossibletologontotheSAPsystembymeansofthisX.509certificate.Youneed toinstallandconfigurealibrarysupportingSAPsSecureNetworkCommunication (SNC)Standard.SNCworksontopoftheRFCprotocol.Thefollowinginstructions describethesetupofthisauthenticationmethod. SeeUsingtheSAPAdapterwiththeSAPCryptographicLibraryforSNConpage 211 formoreinformationaboutSNCandSAPAdapters.
208
User Authentication via X.509 Certificate
Important! FortheauthenticationviacertificatesagainstanSAPsystem,itisrequiredto enable SNC connectionsfortheRFCConnectiondefinedattheSAPAdapterandontheSAP system.ThesesettingsarelistedinthesectionConfiguringAdapterConnectionson page 56.FordetailedinformationontheSAPsystemandRFCclientsettingsforSNCsee thecorrespondingSAPdocumentation. Important! TheHTTPSportdefinedontheIntegrationServershouldhavetheRequest Client CertificateoptionsetfortheClient Authenticationfield. Tip! FormoreinformationonportsseethewebMethodsIntegrationServerAdministrators Guide. IfyouwanttologontoanSAPsystemviaanIntegrationServerusinganySAPuseranda certificate,youcandosobyprovidingatrustedcertificatefortheIntegrationServer. Important! BeforeyoucanlogontotheIntegrationServerusingatrustedcertificate,you havetoimportthe(personalized)clientcertificateforeachuserfromalocaldirectoryto theIntegrationServerandmapittoanIntegrationServeruser. Forvalidationpurposes,youmustalsoenterthepathtotheCACertificatedirectory.The CACertificatedirectoryspecifiesthenameofyourlocaldirectorycontainingtheroot certificatesofCAsthatthisservertrusts.Youmayspecifythedirectoryusinganabsolute pathoronethatisrelativetothewebMethods_directory\IntegrationServerdirectory. Whenauserlogson(forexample,fromaWebclient)usingthiscertificate,theIntegration SerververifiestherootcertificateintheCACertificatedirectoryandthenpassestheclient certificate,includingtheusername,totheSAPsystem.However,youmustmakesure thatthisusercanaccesstheserviceshewantstoexecuteintheIntegrationServer.Thatis
209
CHAPTER 12 Security
whyyoumustmaptheclientcertificatetothecorrespondingIntegrationServeruser,or alternativelytoa(standard)IntegrationServeruser,dependingontheauthorizations required.IfyouwanttoexecuteaprotectedservicewithintheIntegrationServer,the mappedusermustbeallowedinthecorrespondingACLs(accesscontrollists).Formore informationonACLs,seethewebMethodsIntegrationServerAdministratorsGuide. Example: YouwanttoexecuteaserviceontheIntegrationServerthatretrievessalesorderdatafrom anSAPsystem.ThisserviceisprotectedbyanACL.TheIntegrationServeruserSalesis registeredinthisACLandallowedtoexecutetheservice.Ifyoumapthecertificatetothe userSales,yourSAPusercanalsoexecutetheservice.Inaddition,theSAPusermustbe authorizedtoexecutethefunctionmodulesofthecorrespondingfunctiongroup. TorestricttherightsoftheSAPlogonusersyoushouldcreatespecificuseraccountsinthe SAPsystemwiththeminimumnecessarysetofauthorizations.IfforinstancetheSAP AdapterisusedasapureRFCServer,itwillonlyperformveryfewfunctioncallbacksto thecallingSAPsystem.Thesecallbacksareneededtodeterminethefunctioninterface specification.ToallowforthisitissufficienttouseanSAPlogonuserwiththe authorizationtothefollowingSAPstandardfunctiongroups:RFC1,SDIF,SG00,SRFC. Ifthisusershallbeusedtocallotherapplicationinterfacesaswellyouneedtoaddthe respectivefunctiongroupstotheauthorizationlist.Addthisauthorizationtothe standardauthorizationobjectS_RFCandcreateanauthorizationprofilewhichonly containsthisauthorization.WhencreatingtheSAPuseryoucanthenassignthisprofileto it.FormoredetailsonauthorizationforSAPuserspleaserefertotheSAPdocumentation.
Authentication When the SAP Adapter Acts As an RFCServer

Mapping SAP User to Integration Server User
210
IftheSAPAdapteriscalledfromanSAPsystem,thecallisalwaystrusted.Therefore, onlytheusernamefromtheSAPsystemisusedforthelogon.Thisuseristheuserwho triggeredthesynchronousorasynchronouscall.Ifauserwantstoexecuteaservice protectedbyanACL(accesscontrollist),thisusermustbeenteredinthecorresponding ACLthatallowsaccesstothisservice. InboundcallscanbesecuredbySNCthesamewayasoutboundcalls.Tosecureyour inboundconnection,enableSNCforyourlistener.SeeListenersonpage 87fortheSNC parametersyouneedtoconfigureforasecurenetworkconnection. Tip! Intheuserconcept,thedefaultuseriscalledSAPUser(Password:22101999).Ifthe SAPAdapteriscalledbyanSAPuserthatdoesnotexistwithinIntegrationServer,the systemswitchesautomaticallytotheuserSAPUserasthedefaultuser. TheUserSAPUserispartoftheUserGroupSAPUsers.ItfiguresintheSAPUsersACL thatpreventsunauthorizedaccesstoallListenerNotificationsandInboundProcessesof thetransportsrelatedtoanSAPsystem. TheusercalledSAPUser,theUserGroup,andtheACLarecreatedautomaticallywhen youstarttheIntegrationServerandSAPAdapterforthefirsttime. IfanSAPuserhasbeencreatedinIntegrationServerinordertoexecuteallListener NotificationswithinIntegrationServer,youhavetoassignthisuseratleasttotheUser GroupSAPUsers. Important! IfyouwanttoavoidthatanSAPuserwhichhasnotbeencreatedwithinan IntegrationServer,canusethewholeauthorizationrangeoftheSAPUser,youshould assignthisSAPuserindividuallytothecorrespondingUserGroup(s),respectivelytothe correspondingACL(s). Important! TheusernamesintheIntegrationServerarecasesensitive.
Using the SAP Adapter with the SAP Cryptographic Library for SNC
TheSAPCryptographicLibraryisthedefaultsecurityproductdeliveredbySAPfor performingencryptionfunctionsinSAPsystems.YoucanuseitforprovidingSecure NetworkCommunications(SNC)betweenSAPsystemcomponents.Thesapcrypto.libis alsousedtoimplementSingleSignOn(SSO).Thissectiondescribestheproceduresteps thatarerequiredtoruntheSAPAdaptercommunicationusingthesapcrypto.lib.For moredetailedinformationontheinstallationofthe sapcrypto.libandthegenerationof PSE(PersonalSecurityEnvironment)seeUsingtheSAPCryptographicLibraryforSNCinthe SAPOnlineDocumentation(SAPLibrary).
211
CHAPTER 12 Security
SAP Adapter Communication Using the SAP Cryptographic Library for SNC
To use an SAP Adapter with the SAP Cryptographic Library 1 2 3 4 5 InstalltheSAPCryptographicLibrary(seetheSAPOnlineDocumentation) GenerateaPSE(PersonalSecurityEnvironment)forSNC(seetheSAPOnline Documentation) CreatetheServersCredentialsusingSAPGENPSE(seetheSAPOnline Documentation) Exchangethesecurityinformationbetweenthecommunicationpartners(servers):see theSAPOnlineDocumentation. ConfigureyourSAPAdapterandthecorrespondingSAPsystemforSNCuse(see SecurityOptionsinthesectionConfiguringAdapterConnectionsonpage 56and Listenersonpage 87). Optional:AdopttheSECUDIRenvironmentvariable(seetheSAPOnline Documentation)topointtothecorrectlocationofyourPSEfilesbymodifyingthe startupscript: Windows platforms:insertalineinserver.batasfollows:aftertheSETLOCALline setSECUDIR=<psepath> Unix platforms:insertalineinserver.shasfollowsattheverybeginningexport SECUDIR=<psepath>
212
Installing the SAP Adapter According to Your Security Policy
Installing the SAP Adapter According to Your Security Policy

TheSAPAdaptercanonlyaccessSAPsystemsforwhichanRFCconnectionaliashas beencreated.ThereisnoserviceavailablethatallowsyoutoexecuteRFCcallstoSAP systemsthatarenotdefinedthere. Inadditiontothisrestriction,youcanalsoprotectaccesstoSAPsystemsinanintranetby installinganadditionalfirewallbetweentheIntegrationServerandtheSAPsystemsor puttingtheIntegrationServerintheDMZ.Youcanconfigurethefirewalltorestrictwhich SAPsystemscanbeaccessedfromtheSAPAdapterthroughtheSAProuter. FinallyyoumightevenwanttocompletelydisallowanIntegrationServerintheDMZto activelyopenconnectionstoanSAPsystemintheintranet.Todoso,youneedtoinstall twoIntegrationServers,oneintheDMZandoneintheintranet.TheIntegrationServerin theDMZcanthanbeconfiguredasareverseinvokeserver.ThustheIntegrationServerin theintranethastoestablishtheconnectiontothereverseinvokeserverwhereasthedata stillflowssynchronouslyfromtheoutsidetotheinside.Forinformationonhowto configurereverseinvokepleaseseethewebMethodsIntegrationServerAdministrators Guide.
213
CHAPTER 12 Security
214
CHAPTER
13
Managing the DDIC Cache

Data DICtionary Cache (DDIC Cache) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Viewing Information in the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Removing Information from the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
215
CHAPTER 13 Managing the DDIC Cache
Data DICtionary Cache (DDIC Cache)

TheDataDICtionaryCache(DDIC)isacachethatholdsinformationaboutSAPfunction modules,structuredefinitions,BusinessObjects,ALEmappings,andIDocs.TheSAP AdapterretrievesthisinformationfromanSAPsystemwhenitperformsRFC,BAPI,or IDoclookups.Toimproveperformance,theSAPAdaptercachesinformationitreceives aboutfunctionmodulesandstructuredefinitions. TheSAPAdapterreceivesinformationaboutfunctionmodulesandstructurefunctions when: AnRFC,BAPI,orIDoclookupisrequestedfromtheLookupscreen TheSAPAdapterexecutesaservicethatinvokesanRFCorBAPIonanSAPsystem AnSAPsystemexecutesanRFCthatinvokesaservice AnIDocgetsprocessedbytheSAPAdapter. TheSAPAdapterkeepsseparatecachedfunctionmodules,structuredefinitions,Business Objects,ALEmappings,andIDocsforeachSAPsystem.WhentheSAPAdapterrequires specificdata,itchecksitsDDICcacheforthespecificSAPsystemtodetermineifthe informationitrequiresisincache.IftherequiredinformationisintheDDICcache,the SAPAdapterusesthecachedinformationratherthanretrievingitfromtheSAPsystem. TheDDICcacheisalwaysactive.Therearenoconfigurationtasksrequiredtoactivateit. Whenyouaredevelopingservices,theremaybetimeswhentheinformationintheDDIC cachebecomesoutdated;forexample,ifyouchangeanRFCsignatureonanSAPsystem. Inthesesituations,youcanusetheDDICcachescreenstoviewtheinformationinthe cacheandremovespecificfunctionmodulesorstructuredefinitionsfromthecacheas necessarywithouthavingtorestarttheIntegrationServer. Note: TheDDICcachedoesnotpersistthroughshutdownandrestartoftheIntegration Server.
216
Viewing Information in the DDIC Cache
Viewing Information in the DDIC Cache

Performoneofthefollowingprocedurestoviewinformationaboutthefunctionmodules, structuredefinitions,BusinessObjects,ALEmappings,andIDocsthatareintheDDIC cache. To view information in the DDIC cache 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. ClickDDIC-Cache. TheSAPRepositoryCachetableappears,showingalloftheelementtypesstoredin thecache. Note: TheSystem IDfielduniquelyidentifiesanSAPsystemwithinoneSAPdomain.If oneormoreRFCconnectionsusethesamesystemID,theywillsharethesamecache. FormoreinformationaboutdefiningRFCconnections,refertoConfiguringAdapter Connectionsonpage 56. Note: IfyourareusingtheWmSAPOptimizepackageorifyouhaveconfiguredand enabledanRFClistener,youwillalsoseeaLocalentryintheSystem ID.list.The cachedelementsofthisSystem IDcannotbedeletedormodified. 3 ToviewthenamesofcachedfunctionmodulesforanSAPsystem,clickthenumberin theFunctions columnfortheappropriateSystemID. TheCachedFunctionstableappears.Toviewmoredetailsaboutafunctionmodule: a Clickthenameofthefunctionmoduleforwhichyouwanttoseethefunction interface. TheSAPAdapterdisplaysascreenthatliststhefunctioninterfacefortheselected functionmodule. b 4 Viewthestructuredefinitionofthedisplayedparametersbyfollowingthe hyperlinkintheTablecolumn.
ToviewthenamesofthecachedstructuredefinitionsforanSAPsystem,clickthe numberintheStructures columnfortheappropriateSystemID. TheCachedStructurestableappears.Toseethestructuredefinition,clickthe structurenameofthestructureyouwanttoview. TheSAPAdapterdisplaysascreenthatliststhestructuredefinitionfortheselected functionmodule.
217
ToviewthenamesofthecachedbusinessobjectsforanSAPsystem,clickthenumber intheBusiness ObjectscolumnfortheappropriateSystemID. TheCachedBusinessObjectstableappears.
ToviewthenamesofthecachedBAPIsforanSAPsystem(forwhichALE informationofanSAPsystemhasbeencheckedandextracted),clickthenumberin theALE MappingscolumnfortheappropriateSystemID. TheCachedALEMappingstableappears.
ToviewthenamesofthecachedIDocsforanSAPsystem,clickthenumberinthe IDocscolumnfortheappropriateSystemID. TheCachedIDocstableappears. Note: ThelistalsocontainsBAPIsforwhichnoALEinterfacehasbeengeneratedin theSAPsystem,butforwhichtheavailabilityhasalreadybeenchecked.Thisis becausetheSAPAdaptertriesonlyoncetoretrieveALEinformation.Ifthisretrieval fails,theSAPAdapterretainsthisfact.
Afterenablingone(ormore)RFClisteners,anewentrynamedLOCALislistedinthe DDIC CachescreenoftheSAPAdapter.TheLOCALentrycontainsfourfunction definitions:WM_PUSH_START_EVENT,WM_PUSH_STOP_EVENT,WM_PUSH_ERROR_EVENT, andWM_PUSH_BUSINESS_DATAandtwostructuredefinitions:WMKEYVALUEand WMBUSINESSDATA.
Removing Information from the DDIC Cache

YoucancleartheentirecacheforanSAPsystem,oryoucanclearindividualelements fromthecache.Thissectiondescribeshowtodoboth.
Clearing the DDIC Cache for an SAP System

To clear the entire DDIC cache for an SAP system 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. ClickDDIC-Cache. TheSAPRepositoryCachetableappears,showingalloftheelementtypesstoredin thecache. 3 IdentifytheSystemIDoftheSAPsystemforwhichyouwanttoclearthecache,and clickthe iconintheClear CachecolumnforthatSystemID.
218
Removing Information from the DDIC Cache
Clearing Elements from the DDIC Cache

Ifafunctionmodule,structuredefinition,BusinessObject,ALEmapping,orIDocinthe DDICcachebecomesoutdatedorcorrupt,youcanusethefollowingproceduresto removeitfromtheDDICcache. To remove elements from the DDIC cache 1 2 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. ClickDDIC-Cache. TheSAPRepositoryCachetableappears,showingalloftheelementtypesstoredin thecache. ToclearanelementfromtheDDICcache: a b IdentifytheSystemIDoftheSAPsystemforwhichyouwanttoclearelementsof thecache,. ForthatSystemID,clickthenumberinthecolumnoftheelementtypeyouwant toclear.Forexample,ifyouwanttoclearafunctionmodule,clickthenumberin theFunctionscolumnfortheappropriateSystemID. Theappropriatetableforthatelementtypeappears. c Identifythespecificelementyouwanttoclear,andclickthe columnforthatelement. iconintheRemove
Note: ThedefaultentriesoftheLOCALentrycannotbedeleted. 3 ClickReturn to DDIC-CachetoreturntotheSAPRepositoryCachetable.
219
220
APPENDIX
Package Contents
Package Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
221
APPENDIX A Package Contents
Package Layout
Apartfromthenativelibraries,allofthefilesrelevanttotheSAPAdapterandits persistentstateinformationareinthe<IntegrationServer>/packages/WmSAPdirectory. ThefollowingtabledescribesthedirectoriesandfilesthatmakeuptheSAPpackage directory. Directory code config Contents ContainstheSAPAdapterlibraries,theJCoandSAPIDocClass libraryjars,andsamplesourcecode. Containsthefollowingconfigurationfile: cbr.cnf (content-based routing) logs ns pub, templates Thisfilecontainstheconfigurationparameter forcontentbasedrouting.
ContainstheSAPAdapterlogfiles. ContainsnamespaceinformationfortheSAPAdapterservices. ContainsfilesandimagescomprisingtheSAPAdapter Administrationuserinterface.AlsocontainsalluserandAPI documentation.
222
APPENDIX
Server Configuration
General SAP Adapter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 server.cnf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
223
APPENDIX B Server Configuration
General SAP Adapter Settings

ForthegeneralsettingsoftheSAPAdapter,youcanusetheAdministratorUserInterface. To change the general settings 1 2 3 IntheAdaptersmenuintheIntegrationServerAdministratornavigationarea,click SAP Adapter. ClickSettings. Youcaneditthefollowing: Setting Timeout (minutes) Description Delay(minutes)untilanunusedrepository connectiontoanSAPsystemistimedout (default:5) Timeintervalinsecondsbetweencheckswhether unusedpooledrepositoryconnectionshave timedout Maximalnumberofrepositoryconnectionsin oneRFCconnectionpooltooneSAPsystem (default:10) Delay(seconds)untilrequestswaitingfora repositoryconnectionfromapooltimeoutinthe queue Timeinterval(minutes)betweenchecksofthe listener.ItischeckedwhethertheRFCHandleis stillvalid.IftheGatewayisrunning,anyinactive Listenerisrestartedatthelatestafterthisinterval. Delay(seconds)untilalistenerrespondsatthe latesttoanincomingrequest. VersionofRFCXMLsent.Validversions:0.9and 1.0(default). PathoftheSNClibraryneededforsecureRFC connections.
Timeout check period (seconds)
Sessionpool size
Poolqueue waiting time (seconds)
Check time (minutes)
Response time (seconds) Default XRFC version SNC library path
224
server.cnf
Setting Log Throughput data
Description Flagtodecidewhethertowritebasicthroughput informationtolog.Validvalues:OnandOff (default). Flagtodecidewhetherperformancemonitoring shouldbeused.Validvalues:OnandOff (default).
Use Monitor
server.cnf
ThisfileiscreatedwhenyoustarttheIntegrationServerforthefirsttime.Someofthe followingstatementscanbeaddedmanuallyafterinstallingtheSAPAdapter. UsetheEdit Extended SettingsfeatureoftheIntegrationServerAdministratortoviewand editthekeystatements.SeethewebMethodsIntegrationServerAdministratorsGuidefor moreinformation. Tip! YoucanalsoaddandeditkeystatementsbyshuttingdowntheIntegrationServerand manuallyeditingthewebMethods_directory/IntegrationServer/config/server.cnffile. ThefollowingstatementsareaddedautomaticallywhenIntegrationServerandSAP Adapterarestartedforthefirsttime: Setting watt.sap.repo.maxPooledConnections Description Maximalnumberofrepositoryconnectionsin oneRFCconnectionpooltooneSAPsystem (default:10) Delay(minutes)untilanunusedrepository connectiontoanSAPsystemistimedout (default:5) Timeintervalinsecondsbetweenchecks (seconds)whetherunusedpooledrepository connectionshavetimedout Delay(seconds)untilrequestswaitingfora repositoryconnectionfromapooltimeoutin thequeue Timeinterval(minutes)betweenchecksofthe listener.ItischeckedwhethertheRFCHandle isstillvalid.IftheGatewayisrunning,any inactiveListenerisrestartedatthelatestafter thisinterval.
watt.sap.repo.timeout
watt.sap.repo.timeoutCheckPeriod
watt.sap.repo.maxWaitForPool
watt.sap.listener.checkTime
225
Setting watt.sap.listener.responseTime watt.sap.debug.level watt.sap.debug.facList
Description Delay(seconds)untilalistenerrespondsatthe latesttoanincomingrequest. Debuglevelfrom1to10 ListofLoggingFacilitiesfortheWmSAP Package.
Change/addthefollowingstatementstotheserver.cnftoincreaseperformance: Setting watt.sap.rfcxml.version watt.sap.idocxml.escaping watt.sap.xml.prettyPrint Description VersionofRFCXML(XRFC)sent.Validversions:0.9and 1.0(default). VersionofillegalcharacterescapinginIDocXML.Valid versions:4.6and5.0(default) FlagthatindicatesiftheSAPXMLdialectsshouldbe renderedprettyprinted.Thedefaultistrue.Setthe valuetofalsetoremoveallunnecessarywhitespace andthusimproveperformance. Settingittotrue,enablesthesynchronouswritecache. Settingittofalsedisablesthecache.Thisproperty workstogetherwiththewatt.sap.xtn.cacheFlushPeriod and watt.sap.xtn.cacheTimeToLive -properties.Settingthisfeature toOnwillforcethetransactionmanagernottopersist eachupdateofantransactionbutratherkeepthestate changesinmemoryandinsteadpersistitperiodically. Itspecifiesthetimeperiodinminutes,howoftenthe TransactionManagerwillflushyetunsavedchangesin thetransactionCachetothefilesystem. Default:every5minutes. watt.sap.xtn.cacheTimeToLive Thetransactioncacheworksbothasreadandwrite cache.Afteratransactionisreadthefirsttime,itwillbe keptinthecacheforaspecificamountoftime (cacheTimeToLive).Ifthetransactionwasnotaccessed duringthistime,itwillberemovedfromthecacheafter thisperiodhasended()inordertokeepthecachefrom growingindefinitely.
watt.sap.xtn.fastAsyncMode
watt.sap.xtn.cacheFlushPeriod
226
server.cnf
Change/addthefollowingstatementstotheserver.cnftoimprovesecurity: Setting watt.sap.snclibpath Description PathoftheSNClibraryneededforsecureRFC connections.
Change/addthefollowingstatementstotheserver.cnftospecifymonitoringoptions: Setting watt.sap.throughput watt.sap.monitor Description Flagtodecidewhethertowritebasicthroughput informationtolog.Validvalues:trueandfalse(default) SwitchtoturnComponentResponsetimeMonitoringOn (default)orOff
Change/addthefollowingstatementstotheserver.cnftospecifymiscellaneousoptions: Setting watt.sap.aclset Description Ifthispropertyinnotavailableornotsettotrue,then duringthenextstartupoftheIntegrationServer,allSAP AdapterrelevantACLsettingswillberesettotheir defaultvalues. TosendSYSTAT01IDocsfromtheSAPAdapterbackto theSAPsystem,theIntegrationServermustbe registeredasalogicalsystem.Bydefault,thename BUSCONisused.Ifyouwanttouseadifferentname, youcanoverridethedefaultvalueusingthisproperty.
watt.sap.systat01.partnerNumber
227
228
APPENDIX
ABAP Types in the SAP Adapter

ABAP Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
229
A P P E N D I X C A B A P Ty p e s i n t h e S A P A d a p t e r
ABAP Types
ABAP Type C Description character[s] Dictionary Types CHAR,CLNT, CUKY,LANG, LCHR,UNIT DATS FLOAT Java Type java.lang.String
D F
GregorianCalendar date(yyyyMMdd) IEEEdouble precision64bit floatingpoint 4bytesigned integer numeric character[s] decimalnumber time(HH.mm.ss) binaryoctets 1byteunsigned integer 2bytesigned integer variablelength string variablelength binaryoctets
java.lang.String java.lang.Double
I N P T X b s g y
INT4 NUMC,ACCP CURR,DEC, QUAN TIMS RAW INT1 INT2 STRING RAWSTRING
java.lang.Integer java.lang.String java.lang.String java.lang.String byte[] java.lang.Integer java.lang.Integer java.lang.String byte[]
230
APPENDIX
Built-in Services
SAP Client Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 XRFC Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 IDoc Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 IDoc-XML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Monitoring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 bXML Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 BAPI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Transaction Administration Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Transport Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Sample Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 SAP Listener Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 webMethods SAP Adapter IDoc Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
231
APPENDIX D Built-in Services
SAP Client Services

pub.sap.client:connect
EstablishesaconnectiontoanSAPsystem. Input Parameters serverName AliasoftheSAPsystemtowhichtheconnectionshouldbe established.ThenamemustmatchaconfiguredRFCconnection aliasattheSAPAdapter. Optional.Clientforthesession.Ifnoclientisspecified,thedefault clientisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
$client $user $pass $language
Return Values result Example Usethepub.sap.client:connect servicewhenyouwanttoestablishaconnectiontoatargetSAP system.Thismightbeusefulforcreatingasessionpool.Inthemostcommonscenarios,it isnotnecessarytoinvokethisserviceexplicitly,asitisinvokedimplicitly(forexample, whenapub.sap.client:invokeorpub.sap.client:invokeTransactionisissued). Okifconnectionwasestablishedsuccessfully.
232
SAP Client Services
pub.sap.client:lockSession
LocksanRFCconnectiontoyourIntegrationServersessionsothatyouwillalways exclusivelyusethisRFCconnectionforsubsequentcalls. Input Parameters serverName AliasoftheSAPsystemonwhichthesessionwillbelocked.The namemustmatchaconfiguredRFCconnectionaliasattheSAP Adapter. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional. Usernameforthesession.Ifnouserisspecified,theuser specifiedintheSAPsystemaliassettingsisused. Optional. Passwordforthesession.Ifnopasswordisspecified,the passwordspecifiedintheSAPsystemaliassettingsisused. Optional. Languageusedduringthesession.Ifnolanguageis specified,thelanguagespecifiedintheSAPsystemaliassettingsis used.
Return Values None. Example Thisservicelocksasessiontotriggeracommit workcommandinsidetheSAPsystem. Thiscausesadatabasecommitandthestartoftheprocessingofposteddata. Note: ThisserviceonlyworkswithSAPsystemsversion4.0AandhigherbecauseBAPIs donotwritedatadirectlytothedatabasebutusethepostingengineinsidetheSAP system. Thedatawillnotbewrittentothedatabaseuntiltheclienttriggersacommit work command.InordertocallaBAPIthatwritesdata,youmustperformthefollowingsteps ontheIntegrationServer: 1 2 3 4 Callthepub.sap.client:lockSessionserviceinordertogetanexclusiveconnectiontothe SAPsystem. PerformtheBAPIcalls. Callthepub.sap.bapi:commit orpub.sap.bapi:rollback service Callthepub.sap.client:releaseSessionserviceinordertoreleasetheexclusiveconnection totheSAPsystemandcleanupusedresourcesontheIntegrationServer.
233
pub.sap.client:releaseSession
ReleasesalockedsessiononanSAPsystem. Input Parameters serverName $client $user $pass $language SAPsystemaliasonwhichthelockedsessionislocated.Thename mustmatchaconfiguredRFCconnectionaliasattheSAPAdapter. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
Return Values Therearenoreturnvalues Example1 Theservicewillreleaseasessionafteracommit workor rollback workcommandhas beentriggeredinsidetheSAPsystem. Note: ThisserviceonlyworkswithSAPsystemsversion4.0AandhigherbecauseBAPIs donotwritedatadirectlytothedatabasebutusethepostingengineinsidetheSAP system. InordertocallaBAPIthatwritesdata,youmustperformthefollowingstepsonthe IntegrationServer: 1 2 3 4 Callthepub.sap.client:lockSessionserviceinordertogetaexclusiveconnectiontothe SAPsystem. PerformtheBAPIcalls. Callthepub.sap.bapi:commitorpub.sap.bapi:rollbackservice Callthepub.sap.client:releaseSessionserviceinordertoreleasetheexclusiveconnection totheSAPsystemandcleanupusedresourcesontheIntegrationServer.
234
SAP Client Services
Example2 Youalsoneedthisserviceifyouwanttolockandchangeacertaindatabaseobject.Todo this,pleaseproceedasfollows: 1 2 3 4 5 Callthepub.client:lockSessionserviceinordertogetanexclusiveconnectiontoanSAP system. LockanobjectbycallingaBAPI_*_ENQUEUE. MakeyourchangesbyinvokingotherBAPIs. ReleasetheobjectbycallingaBAPI_*_DEQUEUE. Callthepub.client:releaseSessionservice.
pub.sap.client:invoke
InvokesanRFCfunctionmoduleinsynchronousmodeonagivenSAPsystem. Input Parameters Thisservicealsoneedstheinputs(importsandtables)requiredbythefunctionmodule. serverName SAPsystemaliasonwhichthefunctionmodulewillbeinvoked. ThenamemustmatchaconfiguredRFCconnectionaliasatthe SAPAdapter. Nameofthefunctionmoduletobeinvoked. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
$rfcname $client $user $pass $language
Return Values Thisservicereturnstheoutputs(exportsandtables)returnedbythefunctionmodule. $rfctime $runtime Time(ms)spentwithintheRFClibrarytocompletetheinvocation. Totalinvocationtime(ms),includingprocessingtimewithinthe SAPAdapter.
235
$encoding $call
MIMEcompliantcharactersetcorrespondingtothesessionsSAP codepage. Flagindicatingwhetherthepipelinerepresentsarequest(true)or aresponse(false)ofafunctionmodule
Example ThisserviceisusedwhenyouaredirectlycallinganRFConanSAPsystemwithout creatinganRFCadapterservice.(WhenanRFCadapterserviceisused,thisserviceis invokedimplicitly.)
pub.sap.client:invokeTransaction
InvokesantRFCfunctionmoduleonagivenSAPsystem. Input Parameters serverName SAPsystemaliasonwhichyouwanttoinvokethefunction module.ThealiasmustmatchaconfiguredRFCconnectionalias attheSAPAdapter. Nameofthefunctionmoduletobeinvoked. Transactionthisinvokeisassignedto. Optional.NameoftheSAPsysteminboundqueue.Specifyavalue incaseofaqRFCscenario Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
$rfcName $tid $queueName $client $user $pass $language
236
SAP Client Services
Return Values $runtime $rfctime $encoding $call Totalinvocationtime(ms),includingprocessingtimewithinthe SAPAdapter. Time(ms)spentwithintheRFClibrarytocompletetheinvocation. MIMEcompliantcharactersetcorrespondingtothesessionsSAP codepage. Flagindicatingwhetherpipelinerepresentsarequest(true)ora response(false)ofafunctionmodule.
Example Thisserviceisusedinoutboundflowsandcanhandlebothsynchronousand transactionalRFCcalls.Therefore,itcanbeseenasagenericwrapperfor pub.sap.client:invoke,pub.sap.client:invokeTransactionandpub.sap.client:confirmTID.
pub.sap.client:createTID
CallthisserviceifyouwanttoobtainatransactionID(TID;whichisaGUID)that conformstotheformatofSAPTIDs.TheobtainedTIDcanbeusedasaninputvaluefor pub.sap.client:invokeTransaction,pub.sap.client:sendIDoc,andpub.sap.client:confirmTID. Important! IfnoTIDexistsinthepipeline,thenthepub.sap.transport.ALE:OutboundProcess serviceperformsthefunctionofboththepub.sap.client:createTIDand pub.sap.client:invokeTransactionservices.ForIDocs,itisrecommendedthatyouuseeitherthe pub.sap.transport.ALE:OutboundProcessserviceorthecallsequenceofpub.sap.client:createTIDand pub.sap.client:sendIDoc. Input Parameters serverName $client $user $pass $language AliasoftheSAPsystemthatsendstheTID.Thisnamemustmatch aconfiguredRFCconnectionaliasattheSAPAdapter. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
237
Return Values $tid Example ThisserviceisusedintRFCclientscenarios,whichrequireatransactionalID(TID) uniquelyidentifyingthetransaction.Seealsopub.sap.client:confirmTID. ContainstheTID.
pub.sap.client:confirmTID
ConfirmsthetransactionspecifiedbytheTIDonthespecifiedSAPsystem.Thisservice mustbecalledafteratransactionalinvokeinordertocompleteatransactiononthetarget system. Input Parameters serverName SAPsystemaliasonwhichthetransactionshouldbeconfirmed. ThenamemustmatchaconfiguredRFCconnectionaliasatthe SAPAdapter. TransactionIDtobeconfirmed. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
$tid $client $user $pass $language
Return Values None. Example ThisserviceisusedintRFCclientscenariosinordertoconfirmatransactionwhichhas beenexecutedcompletely. 1 Invokepub.sap.client:createTID.ThisservicecreatesanSAPconformantTID.Itis necessarytohaveone,otherwiseyoucannotinvokethefunctionmodulewith
238
SAP Client Services
pub.sap.client:invokeTransaction.IfyouhavealreadyobtainedaTID,youshouldusethat oneinordertoguaranteethatthetransactionisexecutedonlyonce. 2 Invokepub.sap.client:invokeTransaction.Thisserviceinvokesthegivenfunctionmoduleas atRFContheSAPsystemspecifiedbyserverName.TheTIDispassedasaparameter onthiscall. Invokepub.sap.client:confirmTID.Confirmsthatthetransactionhascompleted.Passthe sameserverNameand$tidvalueonthiscall.
pub.sap.client:getAttributes
ConnectstothegivenSAPsystemandreturnsinformationspecifictooneRFCclient connectionsession: Input Parameters serverName AliasoftheSAPsystemfromwhichyouwanttoreceivetheRFC connectionspecificattributes.Thenamemustmatchaconfigured RFCconnectionaliasattheSAPAdapter. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
Return Values DocumentnamedrfcAttributescontainingspecificinformationaboutoneRFCconnection session: destination ownHost partnerHost systemNumber systemID client String.Destinationoftheconnection. Hostname(orIP)ofthemachinetheIntegrationServeris runningon. Hostname(orIP)ofthemachinetheSAPsystemisrunning on. SystemnumberoftheSAPsystem. UniquethreeletterIDofSAPsystem(inlocalnetwork). Clientthesessionisconnectedto.
239
user language ISOLanguage ownCodepage partnerCodepage ownRelease partnerRelease kernelRelease partnerType trace ownType rfcRole CPICConversationID encoding charset bytesPerChar
SAPuserthathasconnectedwiththissession. Logonlanguage. ISOnameforlogonlanguage. SAPcodepagethisconnectionisusing. SAPcodepagetheSAPsystemisrunningon. VersionoftheloadedRFClibraryusedbytheSAPAdapter. ReleaseoftheSAPsystem. KernelreleaseoftheSAPsystem. RFCtypeofthepartner;R/3(3),R/2(2)orexternalRFCserver (E). Flagindicatingwhethertraceisturnedon(true)oroff(false) forthisconnection. RFCtypeoftheSAPAdapter;shouldalwaysbeE. RoleoftheSAPAdapterinthiscall;shouldalwaysbe:C(for client). CPICIDoftheconnection(lowlevelprotocolinformation). IANAencodingthatisequivalenttotheSAPcodepageused, forexample:ISO88591. CharsetthatisequivalenttotheSAPcodepageused,for example:ISO8859_1(usedinJavaconstructors). Numberofmaximumbytesusedpercharinthecodepage.
240
SAP Client Services
pub.sap.client:getFunctionInterface
LooksupthefunctioninterfacedefinitionofanRFCfunctionmoduleinthegivenSAP system. Input Parameters $rfcname serverName Functionmoduleforwhichtheinterfacedefinitionislookedup. AliasoftheSAPsystemonwhichtheRFCfunctionmoduleis defined.ThenamemustmatchaconfiguredRFCconnectionalias attheSAPAdapter.
Return Values Documentlistnamedparamsthatcontainsallparameterrelatedinformation: paramClass parameter tabName type length decimals optional Classofparameter;I(importing),E(exporting),T(table), X(exception). Nameoftheparameterinthefunctioninterface. NameofthetableintheSAPsystemtheparameterisreferringto. Typeoftheparameter(forexample:CHAR,STRUCTURE,TABLE, ...) Internallengthinbytesoftheparameter. Onlyrelevantfordecimaltypes;numberofdecimalsused. Flagindicatingwhetherparameterisoptional.
pub.sap.client:getStructureDefinition
LooksupthestructuredefinitionofanSAPstructureinthegivenSAPsystem. Input Parameters structName serverName Structurenameforwhichthedefinitionshouldbelookedup. AliasoftheSAPsystemonwhichtheRFCstructureisdefined. ThenamemustmatchaconfiguredRFCconnectionaliasatthe SAPAdapter.
241
Return Values Documentlistnamedfieldsthatcontainsallfieldrelatedinformation. tabLength Lengthofthestructurewhenusedinatable.Thismight differfromthesumofallfieldlengths,asthenumbertypes havetobealignedtomemorysegments. Key fieldName tabName position offset length decimals type Description Nameofthefield. Optional.Nameofthetable/structurein theSAPsystemthefieldisreferringto. Positionwithinstructure. Offsetinbytestothisfield. Internallengthinbytes. Onlyrelevantfordecimaltypes;number ofdecimalsused. Typeofthefield(forexample:CHAR, STRUCTURE,TABLE,...).
fields
242
SAP Client Services
pub.sap.client:sendIDoc
SendsanIDoctoagivenSAPsystem. Input Parameters serverName iDocList $tid $queueName $client $user $pass $language AliasfortheSAPsystemthatwillreceivetheIDoc.Thealiasmust matchaconfiguredRFCconnectionaliasattheSAPAdapter. ContainstheIDoc(s)asobjectofthecom.sap.mw.idoc.IDoc.DocumentList type. Transactionsthisinvokeisassignedto. Optional.NameoftheSAPsysteminboundqueue.Specifyavalue incaseofaqRFCscenario. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
243
pub.sap.client:ping
CheckstheresponsetimeofanSAPsystem. Input Parameters serverName RFCconnectionaliasfortheSAPsystemyouwanttoping.The namemustmatchaconfiguredRFCconnectionaliasattheSAP Adapter. Optional.Clientforthesession.Ifnoclientisspecified,theclient specifiedintheSAPsystemaliassettingsisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
Return Values: responseTime ResponsetimeoftheSAPsystem.
244
XRFC Services
XRFC Services
pub.sap.rfc:decode
ConvertsanRFCXML(XRFC)stringintothepipelinesothatisinaformatthatcanbe passedtoanSAPsystem. Input Parameters xmlData bytes node String.AnRFCXMLmessage. Optional.BytearraythatcontainsthedatatobedecodedasXRFC. Optional.XMLobjectthatrepresentstheXRFCdata(youwillgeta nodewhenputtinganXMLfileviaFTPwithextension.xml).The servicechecksinthatorderifaninputdocumentisavailable: xmlData,bytes,node.
Return Values $encoding Optional.Specifiestheencodingusedintheinputdocuments XMLheader,(forexample:iso88591)if$encodinghasnotbeen includedinthepipelinebefore.
Example ThisservicecanbeusedwhenanRFCXMLdocumentispostedtotheIntegrationServer inavariable.
pub.sap.rfc:encode
ConvertsanRFCcallstoredinthepipelinetoanXMLstringinaformatspecifiedbythe SAPRFCXML(XRFC)specification. Input Parameters ThisserviceneedstheRFCcallsinValuesrepresentationasinput. serverName $encoding SAPsystemusedasarepository.Thisnamemustmatcha configuredRFCconnectionaliasattheSAPAdapter. Optional.Specifiestheencodingusedintheoutputdocuments XMLheader,e.g.iso88591
245
$call $envelope
Optional.Thisflagspecifieswhetherthepipelineshouldbe interpretedasacall(true)orasaresponse(false) Optional.XRFC,bXML,orSOAP.Specifiesthetypeofdocument generated.
Return Values xmlData contentType String.ContainstheRFCXMLrepresentationoftheRFC. Thecontenttypeassociatedwiththegenerateddocument(e.g. application/xsap.rfc)
Example UsethisservicetocreateRFCXMLcorrespondingtothepipelineandperhapsforwardit toanotherserver(forexample,viaHTTP).ThisisdoneintheXMLtransportsOutbound Processforfunctionmodules.
246
XRFC Services
pub.sap.rfc:createTemplate
CreatesanRFCXML(XRFC)templateforthespecifiedfunctionmodule Input Parameters serverName $rfcname $encoding $call $envelope SAPsystemaliasthatisusedasarepository.Thealiasmustmatch aconfiguredRFCconnectionaliasattheSAPAdapter. Optional.Functionmoduleforwhichyouwanttocreatethe template. Optional.Specifiestheencodingusedintheoutputdocuments XMLheader,e.g.iso88591 Thisflagspecifieswhetheracalltemplate(true)oraresponse template(false)iscreated. Optional.XRFC,bXML,orSOAP.Specifiesthetypeoftemplate generated.
Return Values xmlData Example Usethisservicetocreatetemplatesfortestingpurposes. String.ContainstheXMLtemplatethatrepresentstheRFC.
247
IDoc Services
Note: DuetotheintegrationoftheSAPJavaIDocClassLibraryintoSAPAdapter6.5, someserviceparametersinthisparthavechanged.Theymaycontaintheadditional parameteriDocList(acom.sap.mw.idoc.IDoc.DocumentListobject)thatreplacesorextendsthe parametersIDOC_CONTROL(_REC_40)andIDOC_DATA(_REC_40).
pub.sap.idoc:encodeSDATA
ConvertseverySDATAfieldfromaDocumentobjecttoaStringobject.Thisserviceis usuallycalledpriortosendinganIDoctoanSAPsystemviapub.sap.client:invokeTransaction orbyanRFCadapterserviceforfunctionmodule IDOC_INBOUND_ASYNCHRONOUSorINBOUND_IDOC_PROCESS. Note: Thereisalsoaclientservicecalledpub.sap.client:sendIDocthatallowsyoutosendthe iDocListdirectly. Input Parameters serverName SAPsystemaliaswhichisusedasrepositoryfor structureinformationabouttheIDoc.Thenamemust matchaconfiguredRFCconnectionaliasattheSAP Adapter. BothkeysareDocumentlists(Tables)containingthe controlanddatatablesfortheIDoc. TheSDATAfieldisaDocumentobjectcontainingthe keysandvaluesfromthesegmenttable(thenameofthe segmenttableisspecifiedbytheSEGNAMfield). Note: ThisservicehandlesbothIDocversions2and3.The differencebetweenthetwoisthat,forIDocsversion2, theservicelooksforIDOC_CONTROLandIDOC_DATA inthepipeline.ForIDocsversion3,itlooksfor IDOC_CONTROL_REC_40andIDOC_DATA_REC_40. iDocList ContainstheIDoc(s)asobjectof com.sap.mw.idoc.IDoc.DocumentList.
IDOC_CONTROL IDOC_DATA OR IDOC_CONTROL_REC40 IDOC_DATA_REC40
OR $encoding Optional.Specifiestheencodingusedintheoutput documentsXMLheader,e.g.iso88591
248
IDoc Services
Return Values IDOC_CONTROL IDOC_DATA OR IDOC_CONTROL_REC40 IDOC_DATA_REC40 Bothkeysaredocumentlists(Tables)containingthe controlanddatatablesfortheIDoc. TheSDATAfieldisa1000bytefield. Atthispoint,theIDocinthepipelineisreadytobesent toanSAPsystemviaeitherpub.sap.client:invokeTransaction oranadapterserviceforoneofthefunctionmodules (IDOC_INBOUND_ASYNCHRONOUSor INBOUND_IDOC_PROCESS).
pub.sap.idoc:decodeSDATA
ConvertstheSDATAfieldfromaStringobjecttoaDocumentobjectandimmediately convertsthewholelistofIDocstoacom.sap.mw.idoc.IDoc.DocumentListobjectforfurther processing.WithRelease6.5,theserviceisonlyrequiredifyoureceiveanIDocinthe tablesrepresentationfromasendingsystem.Thatis,youhavecreatedanRFCadapter notificationforfunctionmoduleIDOC_INBOUND_ASYNCHRONOUSor INBOUND_IDOC_PROCESS. Input Parameters serverName SAPsystemaliaswhichisusedasrepositoryfor structureinformationabouttheIDoc.Thenamemust matchaconfiguredRFCconnectionaliasattheSAP Adapter. BothkeysareDocumentlists(tables)containingthe controlanddatatablesfortheIDoc. Atthispoint,theSDATAfieldofeachsegmentconsists ofa1000bytefield. Note: ThisservicehandlesbothIDocversions2and3. Thedifferencebetweenthetwoisthat,forIDocsversion 2,theservicelooksforIDOC_CONTROLand IDOC_DATAinthepipeline.ForIDocsversion3,it looksforIDOC_CONTROL_REC_40and IDOC_DATA_REC_40. Optional.Specifiestheencodingusedintheoutput documentsXMLheader,e.g.iso88591.
$encoding
249
Return Values iDocList ContainstheIDoc(s)asobjectof com.sap.mw.idoc.IDoc.DocumentList.
pub.sap.idoc:encodeString
EncodesanIDoctoaStringequivalent,theformatthatisusedbythefileportofanSAP system.TheservicefirstchecksfortheiDocListfield,ifthatparameterisnotpresent,it willlookfortheIDOC_*recordlists. Note: Whensavingtoafile,makesurethatStringissavedwithcorrectencoding. Input Parameters serverName SAPsystemaliaswhichisusedasrepositoryforstructure informationabouttheIDoc.Thenamemustmatcha configuredRFCconnectionaliasattheSAPAdapter. Optional.TheSAPsystemreleasethattheIDocwillbe sentto. Optional.Specifiestheencodingusedintheoutput documentsXMLheader,e.g.iso88591. ContainstheIDoc(s)asobjectof com.sap.mw.idoc.IDoc.DocumentList.
iDocRelease $encoding iDocList
OR IDOC_CONTROL IDOC_DATA OR IDOC_CONTROL_REC40 IDOC_DATA_REC40 Bothkeysaredocumentlists(tables)containingthe controlanddatatablesfortheIDoc.TheSDATAfieldisan orderlyDocumentobjectcontainingthekeysandvalues fromthesegmenttable(thenameofthesegmenttableis specifiedbytheSEGNAMfield). Note: ThisservicehandlesbothIDocsversions2and3.The differencebetweenthetwoisthat,forIDocsversion2,the servicelooksforIDOC_CONTROLandIDOC_DATAin thepipeline.ForIDocsversion3,itlooksfor IDOC_CONTROL_REC_40andIDOC_DATA_REC_40.
250
IDoc Services
Return Values iDocString String.TheIDocinthefileport.
pub.sap.idoc:decodeString
DecodesanIDocfromaStringequivalent,theformatthatisusedbythefileportofan SAPsystem. Input Parameters serverName SAPsystemaliaswhichisusedasrepositoryforstructure informationabouttheIDoc.Thenamemustmatchaconfigured RFCconnectionaliasattheSAPAdapter. String.TheiDocinthefileport. Optional.SpecifiestheencodingusedtodecodetheIDocstring, e.g.iso88591.
iDocString $encoding
Return Values iDocList ContainstheIDoc(s)asobjectof com.sap.mw.idoc.IDoc.DocumentList.
pub.sap.idoc:iDocToDocument
GeneratesaDocumentrepresentationofanIDoclisttoperformmappingsinFlow language. Input Parameters iDocList conformsTo ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. NameofthedocumentstructureoftheIDoc.Thedocument structureisusedasatemplatetodiscriminatebetweendocuments anddocumentlists.WithoutconformsTo,alltablesinthe hierarchicalstructurewillbedocumentlists.
Return Values document IDocinhierarchicalstructure.
251
pub.sap.idoc:documentToIDoc
Complementaryservicetopub.sap.idoc:iDocToDocument. Input Parameters document Return Values iDocList ContainstheIDoc(s)asobjectsofthetype com.sap.mw.idoc.IDoc.DocumentList. IDocinhierarchicalstructure.
pub.sap.idoc:iDocToTables
GeneratesthetablescompatiblewithSAPAdapterversion4.6fromanobjectcompatible withSAPAdapterversion6.5.DothisbeforesendingtheIDoctoanSAPAdapterversion 4.6inboundtransport. Input Parameters iDocList ContainstheIDoc(s)asobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
Return Values IDOC_CONTROL IDOC_DATA OR IDOC_CONTROL_REC40 IDOC_DATA_REC40 BothkeysareDocumentlists(tables)containingthe controlanddatatablesfortheIDoc.TheSDATAfieldis anorderlyDocumentcontainingthekeysandvalues fromthesegmenttable(thenameofthesegmenttableis specifiedbytheSEGNAMfield). Note: ThisservicehandlesIDocversions2and3.The differencebetweenthetwoisthat,forIDocversion2,the servicecreatesIDOC_CONTROLandIDOC_DATAin thepipeline.ForIDocversion3,itcreates IDOC_CONTROL_REC_40andIDOC_DATA_REC_40.
252
IDoc Services
pub.sap.idoc:tablesToIDoc
Complementaryservicetopub.sap.idoc:iDocToTables. Input Parameters IDOC_CONTROL IDOC_DATA OR IDOC_CONTROL_REC40 IDOC_DATA_REC40 BothkeysareDocumentlists(tables)containingthe controlanddatatablesfortheIDoc.TheSDATAfieldis anorderlyDocumentcontainingthekeysandvalues fromthesegmenttable(thenameofthesegmenttable isspecifiedbytheSEGNAMfield). Note: ThisservicehandlesIDocversions2and3.The differencebetweenthetwoisthat,forIDocversion2, theservicelooksforIDOC_CONTROLand IDOC_DATAinthepipeline.ForIDocversion3,it looksforIDOC_CONTROL_REC_40and IDOC_DATA_REC_40. Return Values iDocList ContainstheIDoc(s)asobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
253
IDoc-XML Services
pub.sap.idoc:encode
ServicethatconvertsanIDoclisttoanXMLstringinaformatspecifiedbytheSAPIDoc XMLSpecification. Input Parameters iDocList OR ContainstheIDoc(s)asobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
BothkeysareDocumentlists(tables)containingthe controlanddatatablesfortheIDoc. TheSDATAfieldisanorderlyDocumentcontainingthe keysandvaluesfromthesegmenttable(thenameofthe segmenttableisspecifiedbytheSEGNAMfield). Note: ThisservicehandlesIDocversions2and3.The differencebetweenthetwoisthat,forIDocversion2, theservicelooksforIDOC_CONTROLand IDOC_DATAinthepipeline.ForIDocversion3,itlooks forIDOC_CONTROL_REC_40and IDOC_DATA_REC_40.
$encoding
Optional.Specifiestheencodingusedintheoutput documentsXMLheader,e.g.iso88591
Return Values xmlData String. TheIDocinXML.TheXMLformatisconsistentwiththe SAPXMLspecification.
Example ThisserviceismostoftenusedwhenyouwanttoreceiveanIDocfromanSAPsystemand convertittoXML. Invokepub.sap.idoc:encode.ThistakesthepipelinecontainingtheIDocasinputand convertsittoanXMLstring.TheXMLstringisaccessibleinthepipelineviathe xmlDatakey.
254
IDoc-XML Services
pub.sap.idoc:decode
ServicethatconvertsanXMLstringinaformatspecifiedbytheSAPIDocXML SpecificationintoanIDocthatisofthetypecom.sap.mw.idoc.IDoc.DocumentListand necessaryforanRFCcall(usingpub.sap.client:sendIDoc). Input Parameters bytes Bytearray.ContainsthedatatobedecodedasIDocXML.
OR
node
XMLNodeobjectthatrepresentstheIDocXMLdata(youwillgeta node,e.g.whenputtinganXMLfileviaFTPwithextension.xml). Theservicechecksinthatorderifaninputdocumentisavailable: xmlData,bytes,node
OR String. TheIDocinXML.TheXMLformatisconsistentwiththe SAPIDocXMLspecification.
xmlData
Return Values $encoding iDocList SpecifiestheencodingfromtheinputdocumentsXMLheader, e.g.iso88591. ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
Example ThisserviceisthefirstservicecalledwhenyouwanttosendanIDocXMLdocumentto anSAPsystem.ThefollowingisasequenceofservicecallsthattakeanIDocinXML format,convertittoacom.sap.mw.idoc.IDoc.DocumentListobject,thenfireitintothe SAPsystem: 1 Invokethisservice(pub.sap.idoc:decode).ThistakestheinputxmlData(theXMLString) andcreatesancom.sap.mw.idoc.IDoc.DocumentListobjectthatisinRFCreadyform. (ThismeansthatitmatchestheRFCcallusedtosendanIDocintotheSAPsystem, andthatthepipelineisalmostintherequiredformat). Invokepub.sap.client:createTID.UsethisservicetorequestatransactionidfromanSAP systemthatcanbeusedforsendingtheIDoctotheSAPsystem.
255
Note: StorethistransactionID,sothatyoucanresendtheIDocincaseoferrorswith thesameID. 3 Invokepub.sap.client:sendIDoc.
Monitoring Services
pub.sap.monitor.aleaud01:swapSenderReceiverLS
SwitchesSenderandReceiver(logicalsystems)foralistofgivenALEAUD01IDocs. Input Parameters iDocList Return Values iDocList ListofALEAUD01IDocswithswitchedRVCPRNandSNDPRN fields. ListofALEAUD01IDocstobeswitched.
pub.sap.monitor.idoc:trace
InternalserviceusedtotracethestatusofcertainIDocsbacktoeitherthesendingSAP systemortoafurtherprocessingSAPAdapter.ThisserviceisdirectlycalledfromSAP systems. Input Parameters SELECTION_DA TE SOURCE_SYSTE M T_IDOCINFO Return Values T_IDOCINFO ListofIDocswithupdatedtraceinformation. DateparameterpassedtoIDOC_DATE_TIME_GETonthe sendingSAPsystem. ThepartnernumberofthesendingSAPsystem. ListofIDocstobetraced.
256
bXML Services
pub.sap.monitor.systat01:report
ThisservicesendsoutSYSTAT01IDocstothesendingSAPsystemforallIDocsthathave beenreceivedinMonitoringmode.CanbeexecutedexactlyoncefortheIDocsofa transaction. Input Parameters None. Return Values None.
bXML Services
pub.sap.bapi:decode
DecodesbXMLdocumentsandgeneratesacorrespondingpipeline. Input Parameters xmlData OR bytes OR node XMLNodeobjectthatrepresentsthebXMLdata(forexample,you getanodewhenputtinganXMLfileviaFTPwithextension.xml). Theservicechecksinthatorderifaninputdocumentisavailable: xmlData,bytes,node. Return Values $encoding Optional.SpecifiestheencodingfoundinthebXMLdocument, e.g.iso88591. Bytearray.ContainsthedatatobedecodedasbXML. String.AdocumentinbXMLformat.
257
pub.sap.bapi:encode
ConvertsaBAPIcallrepresentedinapipelinetoanXMLstringinaformatspecifiedby theSAPbXMLspecification. Input Parameters objectName bapiName $encoding $call Nameofthebusinessobject. NameoftheBAPI. Optional.Specifiestheencodingusedintheoutputdocuments XMLheader,e.g.iso88591. Optional.Thisflagspecifieswhetherthepipelineshouldbe interpretedasacall(true)orasaresponse(false).Thedefaultis false. Optional.Ifthisobjectisinthepipeline,anExceptiondocument willbecreated. Optional.ContainsmetadatainformationabouttheBAPI,that shouldbeencoded.
$abapexception $metabapi
Return Values xmlData AdocumentinbXMLformatasastring.
pub.sap.bapi:createTemplate
GeneratesabXMLdocumenttemplateforthedefinitionofaBAPIinanSAPsystem. Input Parameters serverName SAPsystemaliasfortheSAPsystemthatisusedasarepository. ThealiasmustmatchaconfiguredRFCconnectionaliasattheSAP Adapter. Nameofthebusinessobjecttoencode. NameoftheBAPI. Optional.Specifiestheencodingusedintheoutputdocuments XMLheader,e.g.iso88591. Optional.Thisflagspecifieswhetheracalltemplate(true)ora responsetemplate(false)iscreated.
objectName bapiName $encoding $call
258
BAPI Services
Return Values xmlData ThebXMLtemplatefortheBAPIasastring.
BAPI Services
pub.sap.bapi:commit
CommitsatransactionwithasingleormultipleBAPIcalls. Note: Youneedtousepub.sap.client:lockSession/releaseSessiontomakesuretokeepyour connectionintransactionscenariosasthetransactioncontextisstoredwiththesessionin theSAPsystem Input Parameters serverName AliasoftheSAPsystemonwhichthetransactionshouldbe committed.ThisnamemustmatchanRFCconnectionaliasatthe SAPAdapter. Optional.Clientforthesession.Ifnoclientisspecified,thedefault clientisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused. Optional.Flagindicatingifcallshouldwaituntildataisreally writtentodatabase.
$client $user $pass $language wait
Return Values Return ReturncodeinBAPIstylekeepingthesuccess/failureofthe commit.
259
pub.sap.bapi:rollback
RollsbackatransactionwithasingleormultipleBAPIcalls. Note: Youneedtousepub.sap.client:lockSessionor pub.sap.client:releaseSessiontomakesureto keepyourconnectionintransactionscenariosasthetransactioncontextisstoredwiththe sessionintheSAPsystem. Input Parameters serverName AliasoftheSAPsystemonwhichthetransactionshouldberolled back.ThisnamemustmatchanRFCconnectionaliasattheSAP Adapter. Optional.Clientforthesession.Ifnoclientisspecified,thedefault clientisused. Optional.Usernameforthesession.Ifnouserisspecified,the defaultuserisused. Optional.Passwordforthesession.Ifnopasswordisspecified,the defaultpasswordisused. Optional.Languageusedduringthesession.Ifnolanguageis specified,thedefaultlanguageisused.
Return Values Return ReturncodeinBAPIstylekeepingthesuccess/failureofthe commit.
260
Transaction Administration Services

pub.sap.transaction:list
Returnsalistoftransactionsfromthetransactionstore. Input Parameters endDate Optional.Filtercriteria:Lastcreationdateofthetransaction.The formatofthisfieldshouldbethesameastheonedefinedunder Settings Logging Log Timestamp Format. Optional.Filtercriteria:Earliestcreationdateofthetransaction. Theformatofthisfieldshouldbethesameastheonedefined underSettings Logging Log Timestamp Format. Optional.Filtercriteria:nameofthesenderofthetransaction. Optional.Filtercriteria:nameofthereceiverofthetransaction. Optional.Filtercriteria:nameofthemessagetypeofthe transaction. Optional.Filtercriteria:stateofthetransaction. Optional.Specifiesthesortkeyvalid:noSort[default],$tid, sender,receivermsgType,dateandstate.Theresulting transactionlistwillbesortedbythegivenattribute. Optional.Specifiesthesortdirection.descendingtriggersa descendingsortorder;anyothervaluetriggersascendingsort order.
startDate
sender receiver msgType state $sortKey
$dir
Return Values transactions Optional.ADocumentListcontainingonedocumentwithdetail informationforeachtransaction.Thefollowingkeysarealways included: $tid,sender,receiver,msgType,state,date(the date/time,whenthestateofthistransactionswaslastchanged, formattedintheusualLogTimestampFormat). $sortKey Optional.Specifiesthesortkeyvalid:noSort[default],$tid, sender,receivermsgType,dateandstate.Theresulting transactionlistwillbesortedbythegivenattribute. Optional.Specifiesthesortdirection.descendingtriggersa descendingsortorder;anyothervaluetriggersascendingsort order.
$dir
261
pub.sap.transaction:get
Returnsdetailinformationforasingletransaction. Input Parameters $tid Return values sender receiver msgType state date auditLog Optional.Nameofthesenderofthistransaction. Optional.Nameofthereceiverofthistransaction. Optional.Nameofthemessagetypeofthistransaction. Optional.Currentstateofthistransaction. Optional.Creationdateofthistransaction. Optional.ADocumentListcontainingthedateandmessagethat tracksofalleventsthatoccurredduringprocessingofthis transaction. TheTIDofthetransaction
pub.sap.transaction:getMessageBody
Returnsthepipelinecontainingtheactualmessagebody. Note: ThisServicewillonlyworkifthestoringofmessagebodieshasnotbeendisabled. Input Parameters $tid Return values None. TheTIDofthetransaction
262
pub.sap.transaction:log
Addsanewauditlogentrytothegiventransaction,andoptionallychangesthe transactionstatustothegivennewstate. Input Parameters $tid msg state TIDofthetransaction. Optional.Messagestringtobelogged. Optional.String.Validvaluesare: Created Executed Committed Rolledback Confirmed Return Values None.
pub.sap.transaction:setCacheParameter
Thisservicessetsnewruntimeparametersforthecacheofthetransactionstore. Input Parameters writeCache cacheTimeToLive cachFlushPeriod Optional.IfOn,thewritecacheofthetransactionwillbe switchedon.Anyothervaluewillswitchitoff. Optional.Thisvaluesetsthemaximumtimetoliveforacache entry(valueinseconds).Validrange:0100. Optional.Thisvaluesetsthetimeperiodafterwhichunmodified cacheentriesareflushed(valueinseconds).Validrange:0100.
Return Values None.
263
pub.sap.transaction:storeConfig
Returnsthecurrentconfigurationandcacheparameterofthetransactionstore. Input Parameters None. Return values storeType writeCache cacheSize cacheTimeToLive cacheFlushPeriod FileSystemforfilebasedtransactionstore. OnorOffdependingonstateofthecache. Numberofentriescurrentlyheldinthetransactioncache. Currentmaximumtimetoliveperiodforacacheentry(in seconds). Currentperiodafterwhichunmodifiedcacheentriesareflushed (inseconds).
pub.sap.transaction:delete
Deletesonetransactionfromthetransactionstore. Input Parameters $tid Return values None. TheTIDofthetransaction
pub.sap.transaction:deleteAll
Deletestheentiretransactionstore.Exercisecareifyouchoosetousethis. Input Parameters None. Return values deletedEntries Totalnumberofdeletedtransactionsthatmatchedthefilter criteria.
264
pub.sap.transaction:sweep
Thisservicecanbeusedtocleanupthetransactionstorethatmatchesthegivenfilter criteria.Forexample,setitupintheSchedulerasfollows: 1 2 3 CreateaFlowService,whichinvokespub.sap.transaction:sweep. IntheFlowService,definetheinputsusingSet Value. CreateaschedulerjobviaServer SchedulerthatexecutestheFlowService.
Input Parameters elapsedTime maxTrxCount sender receiver msgType state Filtercriteria:timeinminutessincethetransactionhasbeen modifiedthelasttime. Optional.Maximumnumberoftransactiontobedeletedinone executionoftheService. Optional.Filtercriteria:nameofthesenderofthetransaction. Optional.Filtercriteria:nameofthereceiverofthetransaction. Optional.Filtercriteria:nameofthemessagetypeofthe transaction. Optional.Filtercriteria:stateofthetransaction.Validvaluesare: Created Executed Committed Rolledback Confirmed Formoreinformationaboutcleaningthetransactionstore,seeAutomaticCleanupofthe TransactionStoreonpage 173. Return Values deletedEntries Totalnumberofdeletedtransactionsthatmatchedthefilter criteria.
265
Transport Services
pub.sap.transport.ALE:InboundProcess
ReceivesanIDocandforwardsittotheroutinglistener. Input Parameters iDocList $tid $action ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. Optional.TheTIDofthetransaction. Optional.Oneofthefollowingtransactioncodes: Code
1 4
Return Values None.
pub.sap.transport.ALE:OutboundProcess
SendsanIDoctoanSAPsystem. Important! If$actionissetto4,thisservicebehavesthesameasservice pub.sap.client:confirmTID. Input Parameters transportParams Adocumentwiththefollowingkey/valuepair. Key serverName Value AliasoftheSAPsystemtowhichyouwant tosendtheIDoc.Thealiasmustmatcha configuredRFCconnectionaliasatthe SAPAdapter.
iDocList $tid
Optional.ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. Optional.TheTIDofthetransaction.
266
Transport Services
$action
Oneofthefollowingtransactioncodes: Code
1 4
$queueName
Optional.NameoftheSAPsysteminboundqueue. SpecifyavalueincaseofaqRFCscenario.
pub.sap.transport.ALE:getRoutingInfo_Default
DefaultservicetoretrieveroutinginformationfromalistofIDocs. Note: ThisservicecanalsohandleIDOC_CONTROLandIDOC_DATArecordlists(for IDocsversion3)orIDOC_CONTROL_REC_40andIDOC_DATA_REC_40recordlists(for IDocsversion4)asIDocinputparametersinsteadofiDocList. Input Parameters iDocList ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
Return Values iDocList sender receiver msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. Retrievedfromsenderpartnernumberfromtheheaderofthefirst IDoc. Retrievedfromreceiverpartnernumberfromtheheaderofthe firstIDoc. RetrievedfrommessagetypefromtheheaderofthefirstIDoc.
267
pub.sap.transport.IS:InboundProcess
ReceivesamessagefromaremoteIntegrationServerandforwardsittotherouting listener,whichdeterminestheroutingnotificationtousetoroutethemessagebasedon thesender,receiver,andmessagetypespecifiedintheinputparameters.After determiningtheroutingnotificationtouse,itinvokestheflowservicethatprocessesthe matchingroutingnotification.Thiscanbecalledwithanarbitrarymessagetopassitonto theroutinglistener. Important! Itisrecommendedthatyouusethisserviceasthereceivingpointwhenyouare connectingtwoIntegrationServers. Input Parameters Inadditiontotheparametersspecifiedbelow,theinputparametersmustalsoincludethe messagetoberoutedthroughtheSAPAdapter.Useakeyforthemessagethatthe outboundtransportexpects. sender receiver msgType $tid $action Thesenderofamessage. Thereceiverofthemessage. Messagetypeofthemessage. Optional.TheTIDofthetransaction. Optional.Oneofthefollowingtransactioncodes: Code 1 4 Return Values Dependsontransactionandinvokedroutingnotification. Meaning Execute(default) Confirm
268
Transport Services
pub.sap.transport.IS:OutboundProcess
InvokesaserviceonalocalorremotewebMethodsIntegrationServer. Input Parameters transportParams ADocumentwiththefollowingkey/valuepairs. Key folderName serviceName serverAlias Value Foldernamefortheservicetoinvoke. Nameoftheservicetoinvoke. Optional.AliasofthewebMethods IntegrationServeronwhichtheserviceis tobeinvoked. Toinvokeaserviceonaremoteserver: Specifythealiasfortheremoteserver. Thedefaultvalueislocal,which indicatesthelocalserver.Uselocalto invokeaserviceonthelocalserver thatisnotpasswordprotected. Toinvokeapasswordprotected serviceonthelocalserver,setupan aliasforthelocalserver,specifyinga usernameandpasswordthathas accesstothepasswordprotected service.Then,specifythataliasname. valueScope Optional.Thescopeforthesession. SESSIONindicatestheconnectionistobe savedinyourownsession.GLOBAL indicatestheconnectionistobesavedin asharedarea.UseSESSIONwhenthe workbeingperformedrequiresstatebe maintained.
data
Passthemessagedatatothisrecord.Ifdataisnotset, thecompletepipelinewillbepassedtothereceiving service. Optional.ThetransactionID.SpecifyatransactionIDif thedocumentshouldbesentasatransaction.
$tid
269
$action
Optional.Oneofthefollowingtransactioncodes: Code
1 4
Return Values Thepipelinecontainstheresultoftheservicethatwasinvoked.
pub.sap. transport.RFC:InboundProcess
ReceivesaninboundRFCoranRFCXMLdocumentthatistoberoutedthroughtheSAP Adapter. Input Parameters Thisservicerequiresthefollowinginputparameters: sbcHeader Valuesobjectthatrepresentsthekey/valuepairsinthe SBCHEADERtable.Forinformationaboutwhattoincludeinthe arrayofrecords,refertoTheSBCHEADERTableonpage 140. Optional.Thenameofthefunctionmodule. Optional.TheTIDofthetransaction. IfyouwanttoprocesstheRFCcallasynchronouslyusingtRFC, specifythetransactionID.Ifyouwouldliketoperforma synchronousRFCcall,donotspecifythisparameter. $action Optional.Thetransactionstate.Specifyoneofthefollowingcodes: Code
1 4
$rfcname $tid
Return Values Dependsontransactionandinvokedroutingnotification.
270
Transport Services
pub.sap.transport.RFC:OutboundProcess
InvokesanRFConanSAPsystem.ThisservicecanhandlebothRFCandtRFCcalls. Input Parameters Thisservicerequiresthefollowinginputparameters: transportParams Adocumentwiththefollowingkey/valuepair. Key serverName Description TheSAPsystemaliasfortheSAPsystemonwhich invoketheRFC.Thealiasmustmatchaconfigured RFCconnectionaliasattheSAPAdapter.
$tid
Optional.TheTIDofthetransaction. IfyouwanttoprocesstheRFCcallasynchronouslyusingtRFC, specifythetransactionID.Ifyouwouldliketoperforma synchronousRFCcall,donotspecifythisparameter.
$action
Optional.Thetransactionstate.Specifyoneofthefollowingcodes: Code
1 4
$rfcname $queueName
Optional.RFCthatshouldbecalled Optional.NameoftheSAPsysteminboundqueue.Specifyavalue incaseofaqRFCscenario.
Return Values Thepipelinecontainstheresultoftheinvokedfunctionmodule. $runtime $rfctime $encoding $call Totalinvocationtime(ms),includingprocessingtimewithinthe SAPAdapter. Time(ms)spentwithintheRFClibrarytocompletetheinvocation. MIMEcompliantcharactersetcorrespondingtothesessionsSAP codepage. Flagindicatingwhetherpipelinerepresentsarequest(true)ora response(false)ofafunctionmodule.
271
pub.sap.transport.XML:InboundProcess
Canbecalled(e.g.usingHTTPpost)witharbitraryXMLdocumentstopassthemonto theroutinglistener. Input Parameters node $tid XMLNodeobjectthatcanbegeneratedbycalling pub.xml:xmlStringToXMLNodeandisautomaticallygenerated whenpostinganXMLdocumentviaHTTP(using text/xml). Optional.TheTIDofthetransaction. $action Optional.Thetransactionstate.Specifyoneofthe followingcodes: Code
1 4
Return Values Dependsontransactionandinvokedroutingnotification.
pub.sap.transport.XML:OutboundProcess
UsethisservicetopostanXMLdocumenttoaspecifiedURL. Thistransportserviceincludespub.client:httpthatperformsHTTPPOST.TheXMLtransport isbasicallyusedforpostingXMLdocumentstoexternalWebservers.Ifyouwantto communicatewithanotherwebMethodsIntegrationServer,youcanuse pub.remote:invoke. Input Parameters ThisservicerequiresthefollowinginputparametersfromtheValuesobject. transportParams Adocumentwiththefollowingkey/valuepair. Key url Description TheURLtowhichtopostthedocument.
272
Transport Services
xmlType
TheXMLdialecttouse.SpecifyValues-XMLifyou wanttheXMLinwebMethodsnativeXMLformat. SpecifySAP-XMLifyouwanttheXMLina formatthatiscompliantwiththeSAPXML specification.ForanIDoc,IDocXMLisused; foranRFC,RFCXML(XRFC)isused.Note thattheIDocmustbeavailableasinputtothis service.

Arbitrary XMLallowstopostanyXML
document.
SOAP XRFC canbeselectedasadditionalXML
dialect.ThisequalstoXRFC(RFCXML)with aSOAPenvelope(higherthanSOAP1.1). useTextXml Optional.Flagthatoverwritesthecontenttypeof bXML,XRFCandIDocXMLtotext/xml,ifsetto true. Optional.FlagthatallowstoforcetheXML renderingenginestouseUTF8asencodingfor theresultingdocuments. Optional.Theusernametosupplyforauser name/passwordauthenticationchallenge. Optional.Thepasswordtosupplyalongwith httpUserforausername/passwordauthentication challenge.
ONorOFF.IfsettoON,thepipelineisencodedusing bXMLforBusinessObjects.
useUTF8
httpUser httpPassword
useBAPI objectName bapiName xmlData $encoding $tid
Thenameofthebusinessobject,towhichthecall shouldbemapped. ThenameoftheBAPImethod,towhichthecall shouldbemapped
Optional.AnXMLdocumentasstring,onlyusedif transportParams/xmlTypeisArbitrary XML. Optional.TheencodingusedbytheXMLrequestdocument. Optional.ThetransactionID.SpecifyatransactionIDifthe documentshouldbesentasatransaction.
273
$action
Optional.Thetransactionstate.Specifyoneofthefollowingcodes: Code
1 4
Return Values Thereturnvaluesdependonthedocumentthatisposted.ThereturnvalueisaValues objectrepresentationoftheanswertotheposteddocument.
pub.sap.transport.BAPI:InboundProcess
WhenpostingbXMLdocumentsrepresentingaBAPIofaBusinessObjecttothisservice, itwilltakecareofpassingthedocumenttotheroutinglistener. Input Parameters sbcHeader objectName bapiName Documentthatcontainsthekey/valuepairswithrouting information.WillbegeneratedbythebXMLparser. Optional.Nameofthebusinessobjectthatisrepresentedinthe pipeline. Optional.NameoftheBAPIthatisrepresentedinthepipeline. $action Optional.Thetransactionstate.Specifyoneofthefollowingcodes: Code 1 4 $tid Return Values Dependsontransactionandinvokedroutingnotification. Meaning Execute(default) Confirm
Optional.TheTIDofthetransaction.
274
Transport Services
pub.sap.transport.BAPI:OutboundProcess
ExecutesaBAPIinanSAPsystem.Thistransportservicecanhandlebothasynchronous andsynchronousexecutionofaBAPI. Input Parameters transportParams Adocumentwiththefollowingkey/valuepair. Key serverName Description TheSAPsystemaliasonwhichtoexecutetheBAPI. ThealiasmustmatchaconfiguredRFCconnection aliasattheSAPAdapter. AllowstorestrictthewayhowtheBAPIcanbe invoked: Value
no restrictions
mode
Meaning Willbeexecutedastheclient requested Onlysynchronouscallis allowed,ifclientpassesa $tid(indicatingan asynchronouscall)an exceptionisthrown. Onlyasynchronouscallis allowed,ifclientdoesnot passa$tid(indicatinga synchronouscall)an exceptionisthrown.
synchronous only
asynchronous only
$tid $action
Optional.TheTIDofthetransaction. Optional.Thetransactionstate.Specifyoneofthefollowingcodes:. Code 1 4 Means Execute(default) Confirm
$queueName objectName bapiName
Optional.NameoftheSAPsysteminboundqueue.Specifyavalue incaseofaqRFCscenario. Optional.Thenameofthebusinessobject. Optional.ThenameoftheBAPImethod.
275
Return Values ApipelinethatrepresentstheresponseoranexceptionoftheexecutedBAPI. $runtime $rfctime $encoding $call Totalinvocationtime(ms),includingprocessingtimewithinthe SAPAdapter. Time(ms)spentwithintheRFClibrarytocompletetheinvocation. MIMEcompliantcharactersetcorrespondingtothesessionsSAP codepage. Flagindicatingwhetherpipelinerepresentsarequest(true)ora response(false)ofafunctionmodule.
Specifications
pub.sap.listener:listenerAuthorizationCheck.
ToprovideapplicationspecificauthorizationhandlingwithSNCenabledRFCservers (listeners),theusermightprovideaservicethatimplementsthisspecification.This servicewillbecalledbytheRFCserver(listener)tocheckforauthorization. ThisservicehastoreturnGrantedintheaccessfieldiftherequestshouldbeaccepted. Ifnoserviceisspecifiedaccesswillbegranted.Ifanexceptionhappensduringexecution ofthisserviceoradifferentstringthanGrantedwillbereturnedtheaccesswillbe denied. Input Parameters functionName partnerName key mode Thefunctionthathasbeencalledbyaremoteclient Thepartner(system)namewheretherequestcomesfrom Theauthorizationkeyasbinarydatadependingonthemode Themodeoftheauthorization:(SNC=SecureNetwork compliantauthorization,Basic=Basicauthorization).Currently, modewillalwaysbeSecureNetworkcompliantauthorization (SNC).
Return Values access String.Shouldbestringgrantediftherequestshouldbe accepted.
276
Specifications
pub.sap.transaport.ALE:aleRoutingInfo_Default
ToallowcontentbasedroutingforallIDocs,theusermightprovideaservicethat implementsthisspecification.Thisservicewillbecalledpriortoselectingtheright routingnotificationbytheroutinglistener. Input Parameters iDocList ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
Return Values iDocList sender receiver msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. ContainsthesendervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthereceivervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthemessagetypevalueasdeterminedbythisALE defaultroutinginfoservice.
pub.sap.transaport.ALE:aleRoutingInfo
Toallowmessagetypespecificcontentbasedrouting,theusermightprovideaservice thatimplementsthisspecification.Thisservicewillbecalledpriortoselectingtheright routingnotificationbytheroutinglistenerbutafterthedefaultALEroutinginfoservice wascalled. Input Parameters iDocList sender receiver msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. ContainsthesendervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthereceivervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthemessagetypevalueasdeterminedbythisALE defaultroutinginfoservice.
277
Return Values iDocList sender receiver msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. ContainsthesendervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthereceivervalueasdeterminedbythisALEdefault routinginfoservice. ContainsthemessagetypevalueasdeterminedbythisALE defaultroutinginfoservice.
pub.sap.transaport.ALE:aleMappingInfo_Default
ToallowmappingforallIDocs,theusermightprovideaservicethatimplementsthis specification.ThisservicewillbecalledpriortosendinganIDoctoanSAPsystemusing thepub.sap.transport.ALE:OutboundProcessservice. Input Parameters iDocList ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
Return Values iDocList msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. ContainsthemessagetypevalueasdeterminedbythisALE defaultroutinginfoservice.
pub.sap.transaport.ALE:aleMappingInfo
ToallowmessagetypespecificmappingforIDocs,theusermightprovideaservicethat implementsthisspecification.ThisservicewillbecalledpriortosendinganIDoctoan SAPsystemusingthepub.sap.transport.ALE:OutboundProcessservicebutafterthedefaultALE mappinginfoservicewascalled. Input Parameters iDocList msgType ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList. ContainsthemessagetypevalueasdeterminedbythisALE defaultroutinginfoservice.
278
Specifications
Return Values iDocList ContainstheIDoc(s)asanobjectofthetype com.sap.mw.idoc.IDoc.DocumentList.
pub.sap.transaport.XML:xmlRoutingInfo
ToallowroutingforincomingXMLdocuments,theusermustprovideaservicethat implementsthisspecification.Thisservicewillbecalledpriortoselectingtheright routingnotificationbytheroutinglistener. Input Parameters node XMLNodeobjectthatcanbegeneratedbycalling pub.xml:xmlStringToXMLNodeandisautomaticallygeneratedwhen postinganXMLdocumentviaHTTP(usingtext/xml). XMLinhierarchicalstructure.
OR document Return Values document sender receiver msgType $tid $action XMLinhierarchicalstructure. ContainsthesendervalueasdeterminedbythisXMLroutinginfo service. ContainsthereceivervalueasdeterminedbythisXMLrouting infoservice. ContainsthemessagetypevalueasdeterminedbythisXML routinginfoservice. TheTIDofthetransactionasdeterminedbythisXMLroutinginfo service. Optional.ThetransactionstateasdeterminedbythisXMLrouting infoservice.Oneofthefollowingcodes: Code 1 4 Meaning Execute(default) Confirm
279
Sample Services
sample.sap:handleIDocXMLPost
SubmitanIDocXMLmessagetoALEInboundProcessontheSAPAdapter. Input Parameters xmlData $action String.TheXMLmessageoftheIDocdocumenttobesent. Required. Optional.Thetransactionstate.Specifyoneofthefollowingcodes: Code
1 4
Return Values None.
sample.sap:handleRfcXMLPost
SubmitanRFCXMLorbXMLmessagetoanSAPsystemtoinvoketheassociatedRFC function. Input Parameters serverName StringThealiasfortheSAPsystemonwhichtoexecutetheRFC. ThealiasmustmatchaconfiguredRFCconnectionaliasattheSAP Adapter. StringTheXMLmessageoftheRFCXMLdocument. Optional.bXMLorRFCXML,documenttypeusedforthepost.
xmlData $envelope Return Values xmlData
XMLmessagerepresentingtheresponseofthefunctionmodule.
Note: Thisserviceisdesignedonlyforexecutingfunctionmodulesthatdonotrequirean explicitcommit.
280
Sample Services
sample.sap:handlebXMLPost
SubmitsabXMLmessagetoanSAPsystemtoinvoketheassociatedBAPI. Input Parameters serverName xmlData mode AliasfortheSAPsystemonwhichtoexecutetheBAPI.Thealias mustmatchaconfiguredRFCconnectionaliasattheSAPAdapter. StringXMLmessagerepresentingaBAPIrequestinbXML. AllowsyoutochoosethewayhowtheBAPIwillbeinvoked: Value
sync async routing
Meaning synchronousexecution asynchronousexecution applyroutingmatchingroutinginfointhe document
Return Values xmlData XMLdocumentrepresentingtheresponseoftheBAPI.
Note: ThisserviceisdesignedonlyforexecutingBAPIsthatdonotrequireanexplicit commit.
sample.sap.Helpers:writeSAPXMLFile
ThisservicewillconvertRFCsorIDocscomingfromanSAPsystemtoSAPXML(IDoc XMLorRFCXML)andwritetheresulttoanoutputfileintheWmSAP/pubdirectory.To callit,createaroutingnotification,andassignitthisservice. Input Parameters None. Return Values None.
281
sample.sap.Helpers:invokeBapiReturningBXml
ThisinternalserviceisinvokedbyhandleBXmlPost. Input Parameters serverName mode AliasfortheSAPsystemonwhichtoexecutetheBAPI.Thealias mustmatchaconfiguredRFCconnectionaliasattheSAPAdapter. AllowsyoutochoosethewayhowtheBAPIwillbeinvoked: Value
sync async routing
Meaning synchronousexecution asynchronousexecution applyroutingmatchingroutinginfointhe document
Return Values xmlData XMLmessagerepresentingtheresponseoftheBAPI.
sample.sap.Helpers:invokeAndReturnXml
ThisinternalserviceisinvokedbyhandleRfcXmlPost. Input Parameters serverName TheSAPconnectionaliasfortheSAPserveronwhichtoexecute thefunctionmodule.ThealiasmustmatchaconfiguredSAP connectionontheSAPAdapter. Nameofthefunctionmoduletobeinvoked. Optional.SpecifyTIDfortransactionalinvoke. Optional.SettobXMLtoencodetheresultsofthefunction modulecallinbXMLformat.
$rfcName $tid $envelope
Return Values xmlData XMLmessagerepresentingtheresponseofthefunctionmodule.
282
SAP Listener Services
sample.sap.Helpers:encodeRPCResponse
SampleserviceusedtoencodeaDocument(<key/value>pairs)asRPCXMLmessage. Input Parameters document Return Values xmlData RPCXMLstringrepresentingtheinputdocument. Documentcontainingkey/valuepairs.
sample.sap.idoc.Mappings:orders
ExampleserviceforcontentbasedroutingofORDERSIDocs.Theservicedetermines routinginformation(sender,receiver,msgType)forthegivenIDocoftypeORDERS. Forthedescriptionofinputparametersandreturnvalues,pleaseseeservicespecification pub.sap.transaport.ALE:aleRoutingInfo.
sample.sap.idoc.Mappings:ordrsp
ExampleserviceformappingORDRSPIDocs.Theservicedoessomemappingoffields forthegivenORDRSPIDoc. Forthedescriptionofinputparametersandreturnvalues,pleaseseeservicespecification pub.sap.transaport.ALE:aleMappingInfo.
SAP Listener Services

pub.sap.listener:getAttributes
ReturnsinformationspecifictooneRFCserverconnectionsession: Input Parameters None. Return Values DocumentnamedrfcAttributescontainingspecificinformationaboutoneRFCconnection session:
283
destination ownHost partnerHost systemNumber systemID client user language ISOLanguage ownCodepage partnerCodepage ownRelease partnerRelease kernelRelease partnerType trace ownType rfcRole CPICConversationID encoding charset bytesPerChar
String.Destinationoftheconnection. Hostname(orIP)ofthemachinetheIntegrationServeris runningon Hostname(orIP)ofthemachinetheSAPsystemisrunningon SystemnumberoftheSAPsystem UniquethreeletterIDofSAPsystem(inlocalnetwork) Clientthesessionisconnectedto SAPuserthathasconnectedwiththissession Logonlanguage ISOnameforlogonlanguage SAPcodepagethisconnectionisusing SAPcodepagetheSAPsystemisrunningon VersionoftheloadedRFClibraryusedbytheSAPAdapter ReleaseoftheSAPsystem KernelreleaseoftheSAPsystem RFCtypeofthepartner;R/3(3),R/2(2)orexternalRFCserver (E) Flagindicatingwhethertraceisturnedon(true)oroff(false) forthisconnection RFCtypeoftheSAPAdapter;shouldalwaysbeE RoleoftheSAPAdapterinthiscall;shouldalwaysbe:C(for client) CPICIDoftheconnection(lowlevelprotocolinformation) IANAencodingthatisequivalenttotheSAPcodepageused, e.g.ISO88591 CharsetthatisequivalenttotheSAPcodepageused,e.g. ISO8859_1(usedinJavaconstructors) Numberofmaximumbytesusedpercharinthecodepage
webMethods SAP Adapter IDoc Java API

SeewebMethods_directory\IntegrationServer\WmSAP\pub\doc\api\index.html.
284
APPENDIX
Deprecated Services
List of Deprecated Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
285
APPENDIX E Deprecated Services
List of Deprecated Services

Inthefollowingallservicesandspecificationsarelistedthathavebeenreplacedbynew onesasofrelease4.6.Theoldservicesarestillavailable,butshouldbenolongerused. Previous pub.sap.idoc:transformFlatToHierarchy pub.sap.idoc:transformHierarchyToFlat pub.sap.idoc.routing:registerService pub.sap.idoc.routing:unregisterService pub.sap.idoc:idocToString pub.sap.idoc:iDocToRecord pub.sap.idoc:recordToIDoc pub.sap.idoc.routing:inbound pub.sap.idoc.routing:inboundDefault pub.sap.idoc.routing:outbound pub.sap.idoc.routing:outboundDefault wm.PartnerMgr.gateway.transport.B2B:Inb oundProcess wm.PartnerMgr.gateway.transport.B2B:Out boundProcess wm.PartnerMgr.gateway.transport.FTPTra nsport:OutboundProcess wm.PartnerMgr.gateway.transport.EmailTr ansport:OutboundProcess New service/specification pub.sap.idoc:IDocToDocument pub.sap.idoc:documentToIDoc Use the SAP Adapter Administration UI instead. Use the SAP Adapter Administration UI instead. pub.sap.idoc:encodeString pub.sap.idoc:iDocToDocument pub.sap.idoc:documentToIDoc pub.sap.transport.ALE:aleRoutingInfo pub.sap.transport.ALE:aleRoutingInfo_Default pub.sap.transport.ALE:aleMappingInfo pub.sap.transport.ALE:aleMappingInfo_Default pub.sap.transport.IS:InboundProcess You should directly select the service to call at the routing notification. You should directly select the service to call at the routing notification. You should directly select the service to call at the routing notification.
286
APPENDIX
Working with Code Pages

Using Different Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
287
APPENDIX F Working with Code Pages
Using Different Code Pages

Usethefollowingprocedureifyouhandledatathatisencoded(orthatyouwantto encodeandsendout)inadifferentcodingfromyouroperatingsystemsdefaultcode page.
To Receive Data from HTTP, FTP, E-mail or File

YoucanusetheServicespub.client:http, pub.client:ftp,pub.client:smtpandpub.file:getFileto loadamultibytedocumentintothepipeline.AlwaysusetheoptionloadAs=bytes. ConvertthebinarydatausingtheServicespub.string:bytesToString oracombinationof pub.xml:xmlStringToXMLNode(alsoacceptsbytes)and pub.xml:xmlNodeToDocument. SettheinputparameterencodingtothemimeEncodinginwhichthebyteshavebeen encoded,(onethatissupportedbythefunctions sun.io.ByteToCharXXX.class, whereXXXstandsfortheencoding)forexample:ASCII,ISO2022orSJIS.
To Send Data Via HTTP, FTP, E-mail or Save It to a File

EnsurethatyoudonotpassanyStringobjectsintotheServicespub.client:http, pub.client:ftp, pub.client:smtporsaveaStringintoafile. Callpub.string:stringToByteswiththecorrectencodingparameter. Passthebytesintoftp/httporintoyourServicewhichwritesthefile.(Thisservice shouldusejava.io.FileOutputStreamtowritethefile,notFileWriter.)Thatwaythe messageissentoutofSAPAdapterwithproperencoding.
To Encode Data from SAP Systems

Use the following procedure if you are using pub.sap.rfc:encode TocreatethestandardSAPXMLyouwouldusetheservicepub.sap.rfc:encode,which handlesencodingautomatically. Note: IfyouwishtocreateotherXMLdocumentsfromSAPdata,youshouldbecarefulto avoidproblemswithcodepageswheneveryoureceivedatafromanSAPsystem(e.g.a responsetoanoutboundRemoteFunctionCallorviaaninboundcall). YouneedtosettheencodingattributeintheXMLdocumentmanually:
288
Using Different Code Pages
Use the following steps if you are using pub.xml:documentToXMLString 1 2 3 Extendyourdocumentbyaddingtheattribute@encodingasaStringasachildofthe rootelement. Inserttheproperdefaultvalue(e.g.ShiftJIS,ifyoursourcedataisShiftJISencoded). Inthepub.xml:documentToXMLStringService,mapyourdocumenttoinputfield document.
289
APPENDIX F Working with Code Pages
290
APPENDIX
Using BizTalk Envelopes with the SAP Adapter

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Use of the BizTalk Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
291
A P P E N D I X G U s i n g B i z Ta l k E n v e l o p e s w i t h t h e S A P A d a p t e r
Overview
TheSAPAdapterusestheBizTalkXMLenvelopeasthetransportenvelopeforthe transmissionofXMLbusinessdocuments.TheBizTalkenvelopeisimplementedonthe SAPAdapterinaccordancewiththeBizTalkFramework1.0aIndependentDocument SpecificationofJanuary,7th2000. AsBizTalkspecificationsareopentoimplementationspecificinterpretationsofsomeof theprovidedXMLelements,thischapterdescribeshowtheSAPAdaptercopeswith BizTalkenvelopetagsthatarenotspecifiedclearlyenough.BizTalkstronglydifferentiates betweenatransportheaderandanapplicationspecificbody,whichresultsinthe followingoverallstructureoftheBizTalkenvelope:
<biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml"> <header>  </header> <body>  </body> </biztalk_1>
TheBizTalkdocumentheaderinformationiscontainedwithinthe<header>element.This headercontainsinformationusedforhandlingandprocessingthedocument.The businessdocumentpassedinthemessageiscontainedwithinthe<body>element.For moredetailsconcerningthestandardBizTalkenveloperefertotheBizTalkFramework1.0a IndependentDocumentSpecification.
Use of the BizTalk Header

Introduction to Standard BizTalk Header Fields
BizTalkdefinessomestandardXMLelementsforusingwithitsenvelope.Themost importantare: The<message>elementwithitssubelements<messageID>,<sent>,<subject>canbe usedtoidentifyamessage. The<to>and<from>elementscanbeusedtoidentifythesenderandreceiverina communicationprocess.Bothmaycontainthesubelements<address>and<state>. The<manifest>elementcanbeusedtodescribethebusinessdocumentsdeliveredin thebody.
292
AfullBizTalkXMLheadermaylooklikethis(takenfromtheMicrosoftBizTalk specification):
<?xml version='1.0' ?> <biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml"> <header> <delivery> <message> <messageID>xyzzy:8</messageID> <sent>1999-01-02T19:00:01+02:00</sent> <subject>Purchase Order</subject> </message> <to> <address>http://www.fabrikam.com/recv.asp</address> <state> <referenceID/> <handle/> <process/> </state> </to> <from> <address>mailto:foo@contoso.com</address> <state> <referenceID>123</referenceID> <handle>7</handle> <process>myprocess</process> </state> </from> </delivery> <manifest> <document> <name>PO</name> <description>Purchase Order</description> </document> </manifest> </header>  <biztalk_1>
ForfurtherdetailsoftheBizTalkXMLenvelope,refertotheBizTalkFramework1.0a IndependentDocumentSpecification. TheSAPAdapteronlyusesasubsetoftheseavailableheaderelements,whichis describedinthefollowingchapters.
293
Representation of Routing and Address Information

TheSAPAdapterneedstoidentifythesenderandreceiverofanXMLmessage.Usually, thesearelogicalsystems,asdefinedinsidetheSAPsystem. ThisinformationistransportedbytheBizTalkheaderelement<delivery>.Withinthis element,thetwosubelements<to>and<from>canbedefined. TheseelementsareusedtoexchangetheroutinginformationneededbytheSAPAdapter. Thenamesofthepartnersareputintothesubelement<address>ofthe<to>or<from> element. BizTalkrequiresanURIasthecontentoftheaddresselement.ThenamesoftheSAP logicalsystemsareencodedasaUniversalResourceName(URN)byputtingtheprefix urn:sap-com:logical-system:infrontofthelogicalsystemidentifier.Forexample:The logicalsystemSAPCLNT001wouldberepresentedasurn:sapcom:logicalsystem:SAPCLNT001. Note: AlthoughtheseidentifiersareexpressedasURNs,theyarenotgloballyunique;the namesoflogicalsystemscanbesetupfreelyforeachSAPSystemdomain. ThisresultsinanXMLdocumentlikethefollowing:
<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml"> <header> <delivery> <message> <messageID>0A125F1315B3A11B00000035</messageID> <sent>2000-06-07T09:22:40</sent> </message> <to> <address>urn:sap-com:logical-system:SAPCLNT001</address> </to> <from> <address>urn:sap-com:logical-system:SAPADA0001</address> </from> </delivery> </header>  </biztalk_1>
294
Representation of SAP Transactions

WhenusingtRFCorIDocs,youhavetospecifyauniqueSAPtransactionIDforeachcall toensuredelivery.ThistransactionIDcanbeeitherresolvedfromanSAPsystemas describedinthisguideorbuiltlocally.Itshouldalwaysconsistof24hexadecimal charactersandbegloballyunique. BecauseBizTalkdoesnotsupporttransactionIDs(TIDs),theSAPAdapterusesthe <referenceID>element,whichisasubelementofthe<state>element. Note: The<state>elementcanalsobeasubelementofthe<to>or<from>element. TransactionIDsmustbeputinthe<referenceID>elementthatbelongstothereceivers addressinformation. Forexample:
<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:schemas-biztalk-org:BizTalk/biztalk-1.0.xml"> <header> <delivery> <message> <messageID>0A125F1315B3A11B00000035</messageID> <sent>2000-06-07T09:22:40</sent> </message> <to> <address>urn:sap-com:logical-system:SAPCLNT001</address> <state> <referenceID>120A135FB315A11B00003500<referenceID> </state> </to> <from> <address>urn:sap-com:logical-system:SAPADA0001</address> </from> </delivery> </header>  </biztalk_1>
295
Further BizTalk Header Fields

BizTalkrequirestheuseoftheXMLelement<message>toidentifyasinglemessage.It definesthefollowingsubelements: XML Element
<messageID>
Description Auniqueidentifier,generatedforeachexchangeddocument.The SAPAdapterwillalwaysgenerateanewmessageIDforboth requestandresponsemessages. Timestampofthemessagecreation.WhenusingBAPIswithALE, thistimestampisusedtobuildtheserializationIDoftheIDoc controlblock.Theelementmustcontaindateandtimeformatted accordingtoISO8601(firsteditionJune15,1988).Theformatto useisCalendardateandlocaltimeoftheday.Thesyntaxis:CCYYMM-DDThh:mm:ss.
<sent>
Forexample:
2000-06-19T18:59:02 describesJune19,200018hours59
minutes2seconds.
<subject>
Maybeusedtospecifyanadditionaldescriptionforthemessage. Important! ThiselementisnotusedbytheSAPAdapter.
Important! BizTalkprovidesthepossibilitytoexchangemanifestinformationintheheader. ThisfeatureisnotusedbytheSAPAdapter.
Error Handling
BizTalkdoesnotdescribeitsownerrorhandlingconceptinitscurrentspecification. However,itrecommendsthatyoudefineapplicationspecificerrordocumentstohandle applicationerrors.Forserverrelatederrors,itdescribesusingstandardizedXML exceptiondescriptors. TheSAPAdapterdistinguishesbetweentwomajorgroupsoferrors: ErrorsintheXMLprocessingandconversionlayersoftheSAPAdapter,andcritical errorsintheSAPsystemsthatcauseaterminationoftheconnection. Applicationspecificerrorssuchaserrorsthatwereforeseenbytheapplication developersandthereforedefinedattheinterfacedefinitionintheSAPsystem.For example:areceiptcouldnotbeprocessedbecauseofbusinesslevelproblems.
296
Error Handling
Thissectionincludesthefollowingtopics: RepresentationofCommunicationandProcessingErrors RepresentationofApplicationErrors
Representation of Communication and Processing Errors

ErrorswhicharecausedinsidetheSAPAdapterorbythetechnicallayersintheSAP systemarerepresentedbyauniformXMLfaultdescriptorelement.Thisfaultelementhas beendefinedfollowingthedesignprinciplesusedforSOAPandSAPXRFCerror handling. ThisfaultelementistransferredinthebodyofaBizTalkXMLenvelopeandintroducedby thefaultXMLelement(whichisdefinedinthenamespaceurn:sapcom: document:sap:businessbyapplyingaspecificprefix). Thisfaultelementhasthefollowingsubelements: XML Element
<faultcode>
Description Anumberspecifyingtheclassoferror.Compatiblewiththe MicrosoftSOAPXMLframeworkspecification.TheSAPAdapter alwayssetsthisvalueto401toindicateanapplicationspecific error. InternalSAPAdaptercodeforthisexception. Detailsofthespecifiedsubelements<name>and<message> NameofanexceptiontousewiththeSAPsystemastheABAP exceptionidentifier. Errormessagewiththespecifiedsubelement<text>.(Optional; thisisnotalwaysfullyspecified). Thetextoftheerrormessage.
<faultstring> <detail> <name>
<message>
<text>
297
Anexampleofanexceptiondocument:
<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <message> <messageID>0A125F1315B39EDB00000013</messageID> <sent>2000-06-19T18:59:02</sent> </message> <to> <address>urn:sap-com:logical-system:SAPCLNT001</address> </to> <from> <address>urn:sap-com:logical-system:SAPADA0001</address> </from> </delivery> </header> <body> <sap:Fault xmlns:sap="urn:sap-com:document:sap:business" xmlns=""> <faultcode>401</faultcode> <faultstring> com.wm.adapter.sap.error.SAPBasicException </faultstring> <detail> <name>SBC_EXCEPTION</name> <message> <text>Business object named Bank2 does not exist in SAP System U9C</text> </message> </detail> </sap:Fault> </body> </biztalk_1>
Representation of Application Errors

ApplicationspecificerrorsarealwaysdescribedasapplicationspecificXMLbusiness documents. TheseexceptiondocumentsaredescribedinAppendix H,UsingIFRXMLFormatwith theSAPAdapter.ForSAPsstandardinterfaces,therelevantexceptiondocumentsare providedintheSAPinterfacerepositoryaspartoftheXMLschemaforresponse documents. Note: Theseresponsedocumentsarealwaysexchangedasbusinessdocumentsthatare partoftheBizTalkbody.
298
APPENDIX
Using IFR-XML Format with the SAP Adapter

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 XML Format for BAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 XML Format for RFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 XML Format for IDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
299
APPENDIX H Using IFR-XML Format with the SAP Adapter
Overview
WiththeXMLformatdefinedintheInterfaceRepository,SAPestablishesastandardized exchangeofbusinessmanagementdataonasemanticlevelacrosstheweb.XML documentswhicharegeneratedaccordingtotheXMLformatanddefinedintheInterface Repositoryarecalledbusinessdocuments. Thenumberofbusinessdocumentsexchangedbetweentwopartnerstoinvokeabusiness managementfunctiondependsontheunderlyinginterfacetypeandtheusagescenario. DuringasynchronouscallofaBAPIorRFC,twobusinessdocuments(requestand responsedocument)areexchanged.Duringanasynchronouscall,onlyarequest documentisexchanged. Characteristicsofbusinessdocumentsare: UseofXMLenvelopes Commonstructureforrequestandresponsedocuments Commonwayofrepresentingparameters Commonerrorhandlingconcepts Note: IDocsdonotsupportallofthesefeatures
Use of XML Envelopes

BusinessdocumentsaretransmittedwithinanXMLenvelope.Duetothefactthatthey onlycontainbusinessmanagementdatatheycanbetransmittedviaarbitraryXML standardenvelopes(e.g.BizTalk,SOAP,). TheSAPAdaptersupportsthetransportofbusinessdocumentswithintheBizTalk envelope.MoredetailsconcerningtheuseoftheBizTalkenvelopeforthetransportof businessdocumentscanbefoundinAppendix G,UsingBizTalkEnvelopeswiththeSAP Adapter.
300
Overview
Common Structure of Request and Response Documents

Toensureastandardizedexchangeofbusinessmanagementdatatheoverallstructureof requestandresponsedocumentsisthesameregardlessofwhichinterfacetypeiscalled. Generallythreedifferenttypesofbusinessdocumentscanbedistinguished: Requestbusinessdocumentsthatareidentifiedbyarootelementthathasthesame nameasthecorrespondinginterface. Example:
<doc:InterfaceName xmlns:doc="urn:">  </doc:InterfaceName>
Responsebusinessdocumentsthataresentbackfromtheserveriftherequesthas beencorrectlyexecuted.Theyareidentifiedbyarootelementthathasthe concatenationoftheinterfacenameandthesuffix.Responseasitsname. Example:

<doc:InterfaceName.Response xmlns:doc="urn:">  </doc:InterfaceName.Response>
Exceptionbusinessdocumentsthataresentbackfromtheserverifapplicationerrors occurredduringtheexecutionoftherequest.Theyareidentifiedbyarootelement thatcarriestheconcatenationoftheinterfacenameandthesuffix.Exceptionasits name. Example:

<doc:InterfaceName.Exception xmlns:doc="urn:">  </doc:InterfaceName.Exception>
301
Common Way of Representing Parameters

Parametersaregenerallyrepresentedaschildelementsofthebusinessdocumentroot element.Whatparameternamesareusedaselementnameswithinthebusiness documentdependsontheunderlyinginterfacetype: InbusinessdocumentsforRFCs,thenamesoftheparametersofthefunctionmodule interfaceareusedintheXMLdocument. BusinessdocumentsforBAPIscontaintheparameternamesastheyaredefinedinthe businessobjectRepository(BOR). TheSAPinternaldatastructuresoftheparametersaredisplayedinaserializedform withintheparameterelementinaccordancewiththeSAPspecificationSerializationof ABAPDatainXML(forfurtherinformation,pleaserefertoRelatedDocumentationon page 13).
Common Error Handling Concepts

ThedifferenterrorhandlingconceptsofBAPIsandRFCsarepresentedattheXMLlevel inauniformway. Generally,exceptionbusinessdocumentsarestructuredasserializedABAP OOExceptionswhicharepassedwithintherootelement(InterfaceName.Exception)of theexceptiondocument.Theseserializedexceptionsareflexibleenoughtocontain differentkindsoferrorinformation.Consequently,bothBAPIreturnparametersand functionmoduleexceptionsaremappedtotherepresentationofserializedexception objects.
302
XML Format for BAPIs
TheserializedABAPOOexceptionconsistsofthefollowingXMLelements: XML Element

<Name> <Message>(optional) subelements: <ID> <Number> <Text>(optional) <Attributes>(optional) subelements:
Description Identifiestheexception.Normallyaglobalname. The<Message>elementreferencesanSAP messagethatdescribestheerrorsituation. Messageclass Messagenumber Errordescription The<Attributes>elementcontainsadditional applicationspecificinformation: Tablewithserializedexceptionsthatrepresent singleerrormessages,iferrorcollectionshaveto bereturned.Eachserializedexceptionwithinthe <Collection>elementhasthesamestructureasthe wrapperexception. Namedattributes(AttributenameX=Nameof Attribute)inwhichadditionalapplicationspecific informationcanbereturned
<Collection>(optional)
<AttributenameX> (multiplicity: 0..*)
MoredetailedinformationabouttheXMLformatdefinedintheInterfaceRepositorycan befoundathttp://ifr.sap.com.

ForeachBAPI,threedifferenttypesofbusinessdocumentsexist: Arequestbusinessdocument. Aresponsebusinessdocument(incaseofacorrectexecutionoftheBAPIcall). Anexceptionbusinessdocument(incaseofanincorrectexecutionoftheBAPIcall). Thefollowingsectionsdescribethesethreetypesofbusinessdocumentsinmoredetail.
303
Structure of Request Business Documents for BAPIs

ThisisthegeneralstructureofrequestbusinessdocumentsforBAPIs:
<doc:BusinessObjectName.MethodName xmlns:doc="urn:sap-com:document:sap:business" [Key1=, Key2=, ]> <BOR_Parameter1>...</BOR_Parameter1> ... </doc:BusinessObjektName.MethodenName>
Additionally,considerthefollowing: ThearrangementofBAPIsaccordingtoabusinessobjectisdirectlyreflectedbythe elementnamesofthebusinessdocument.TherootelementthatidentifiestheRequest businessdocumentcarriestheconcatenationofthebusinessobjectnameandtheBOR methodnameasitsname.Therootelementhasthefollowingcharacteristics: ItcontainsthenamespacereferenceofbusinessdocumentsthatrefertoBAPIs ("urn:sap-com:document:sap:business"). IftheBAPIisaninstancemethod,therootelementcontainsanattributeforeach keyfieldofthecorrespondingbusinessobjectthatisnamedlikethekeyfield. Note: Ifthebusinessobjecthasmorethanonekeyfield,thecorresponding attributesshouldappearinthesamesequenceasthekeyfieldsdefinedinthe BOR. ImportparametersoftheBAPIappearassubelementsoftherootelement.Thesesub elementsarenamedliketheparametersastheyaredefinedintheBOR.Withinthese elements,theSAPinternaldatastructuresarerepresentedinaserializedformin accordancewiththespecificationSerializationofABAPDatainXML(forfurther information,pleaserefertoRelatedDocumentationonpage 13).
Structure of Response Business Documents for BAPIs

AresponsebusinessdocumentisreturnedtothesenderiftheBAPIcallcouldbe processedwithoutapplicationerrors.ThismeansthattheBAPIreturnparameteronly containsmessagesofthetypeS,I,orW.Inthatcase,theResponsebusinessdocument containstheexportparametersoftheBAPIcall.
304
ThisisthestructureofresponsebusinessdocumentsforBAPIs:
<doc:BusinessObjektName.MethodenName.Response xmlns:doc="urn:sap-com:document:sap:business" [Key1=, Key2=, ]> <BOR_Parameter1>...</BOR_Parameter1> ... </doc:BusinessObjektName.MethodenName.Response>
Additionally,considerthefollowing: ThearrangementofBAPIsaccordingtoabusinessobjectisdirectlyreflectedbythe elementnamesofthebusinessdocument.Therootelementthatidentifiestherequest businessdocumentcarriestheconcatenationofthebusinessobjectname,theBOR methodnameandthesuffix.Responseasitsname.Therootelementhasthe followingcharacteristics: ItcontainsthenamespacereferenceofbusinessdocumentsthatrefertoBAPIs (urn:sap-com:document:sap:business). IftheBAPIisaninstancemethodorafactorymethod,therootelementcontains anattributeforeachkeyfieldofthecorrespondingbusinessobjectthathasthe samenameasthekeyfield. Important! Ifthebusinessobjecthasmorethanonekeyfield,thecorresponding attributesshouldappearinthesamesequenceasthekeyfieldsdefinedinthe BOR. ExportparametersoftheBAPIappearassubelementsoftherootelement.Thesesub elementshavethesamenameastheparametersdefinedintheBOR.Withinthese elements,theSAPinternaldatastructuresarepresentedinaserializedformin accordancewiththespecificationSerializationofABAPDatainXML(forfurther information,pleaserefertoRelatedDocumentationonpage 13). IftheBAPIisafactorymethod,possiblyonlythekeyfieldsofthecreatedinstance willbereturnedtotheclient.Inthiscase,theresponsebusinessdocumentonly consistsofattributes.
Structure of Exception Business Documents for BAPIs

AnexceptionbusinessdocumentisreturnedtothesenderiftheBAPIcallcouldnotbe processedwithoutapplicationerrors.ThismeansthattheBAPIreturnparametercontains atleastonemessageoftypeE(error)orA(abort).Inthiscase,theexceptionbusiness documentcontainsonlytheerrordescriptions.
305
Theseerrordescriptionshavethefollowingcharacteristics: ErrormessagesoftheBAPIreturnparameteraredisplayedasserializedexception objectsonXMLlevel.Sotherepresentationoftheerrordescriptionintheexception businessdocumentdiffersfromtheoriginalBAPIreturnstructure.Messagesoftype EarerepresentedasexceptionswithnameBapiError.MessagesoftypeAare representedasexceptionswiththenameBapiAbort. Statusmessages(messagesofthetypeS,I,orW)thatarealsopartoftheReturn parameterarestillreturnedasthereturnparameterstructure. Important! AllstatusmessageswillbemappedtotheBAPIRET2structure. TheexportparametersoftheBAPIarenottakenintoaccount. ThedetailedstructureoftheExceptionbusinessdocumentsdependsonwhetherthe returnparameterisastructureoratable.
Exception Document for Return Structures

Ifthereturnparameterisastructure,theexceptionbusinessdocumentcontainsonesingle exceptionthatiscreatedfromtheinformationofthereturnmessage.Theexceptionis namedBapiErrororBapiAbortdependingonwhetherthereturnmessageisoftypeEorA. TheXMLrepresentationofareturnstructureconsistsoffollowingsubelements: XML Element
<Name>
Corresponding Information from the Return Parameter BapiError,ifvalueoffieldTYPEisE. BapiAbort,ifvalueoffieldTYPEisA.
306
XML Element
<Message>
Corresponding Information from the Return Parameter
(0..1)
<ID> <Number> <Text> <Attributes>(optional) <MESSAGE_V1>(optional), <MESSAGE_V2>(optional), <MESSAGE_V3>(optional), <MESSAGE_V4>(optional) <LOG_NO>(optional) <LOG_MSG_NO> (optional) <PARAMETER>(optional) <ROW>(optional) <FIELD>(optional) <SYSTEM> (optional)
ValueoftheIDfield. ValueoftheNUMBERfield. ValueoftheMESSAGEfield. The<Attributes>elementcontainsthe informationofBAPIRET2assubelementsthat havethesamenamesasthecorrespondingfields oftheBAPIRET2structure.
Exception Document for Return Tables

Returntablesconsistofoneormorerowsthathavethesamestructureasareturn structure.IfthereturntablecontainsatleastonemessageoftypeE(error)orA(abort),an exceptionbusinessdocumentisreturnedtotheclientthathasthestructureofacollection exception.ThisexceptionisnamedBapiErrororBapiAbortdependingonwhetherthemost criticalmessageinthereturntableisoftypeEorA. Thecollectionexceptionisidentifiedbyastandardizedmessagewhichissimilarforall returntables.Themessagesofthereturntablearedisplayedwithinthe<Collection> elementofthecollectionexception,whichisasubelementofthe<Attributes>element. EachsinglemessageoftypeEorAisdisplayedasanexceptionthatisgroupedwithinthe
<Collection>elementintheformofatable.Singlemessagesaredisplayedasexceptions
inanexceptiontableinaccordancewiththespecificationSerializationofABAPDatain XML(forfurtherinformation,pleaserefertoRelatedDocumentationonpage 13). Consequently,eachexceptionisencapsulatedinan<item>elementthatcontainsthe exceptiondata.
307
If,despitetheerrormessages,thereturntablecontainsadditionalmessagesoftypeS,I,or W,thesemessagesaredisplayedinatableofrowtypeBAPIRET2withina<Status> element,whichisasubelementofthe<Attributes>element. IfaBAPIreturntablecontainserrormessages,thefollowingXMLelementscomprisethe resultingexceptionbusinessdocument: Corresponding Information from the Return Parameter BapiError,ifvalueoffieldTYPEisE. BapiAbort,ifvalueoffieldTYPEisA. Thethreesubelementscontainageneric messagethatisusedforallreturntables(for example:DuringtheexecutionoftheBAPI oneormoreerrorsoccurred). XMLrepresentationofeacherrormessage withinthereturntable.Withinthe<item> elements,thedataofasinglereturnmessage isdisplayedasaserializedexceptionobject.
XML Element
<Name>
<Message> (0..1) <ID> <Number> <Text> <Attributes> <Collection> <item> <Name></Name> <Message></Message> <Attributes> (optional) ... </Attributes> </item> <item> (optional) ... </item> ... </Collection>
308
XML Format for RFCs
XML Element
<Status> (optional) <item> <ID> (optional) <TYPE> (optional) <NUMBER> (optional) <MESSAGE> (optional) <MESSAGE_V1> (optional) <MESSAGE_V2> (optional) <MESSAGE_V3> (optional) <MESSAGE_V4> (optional) <LOG_NO> (optional) <LOG_MSG_NO> (optional) <PARAMETER> (optional) <ROW> (optional) <FIELD> (optional) <SYSTEM> (optional) </item> <item> (optional) </item> </Status>
Corresponding Information from the Return Parameter The<Status>elementcontainsaserialized tablewithrowtypeBAPIRET2.Withinthe <Status>element,allreturnmessagesoftype S,I,orWthatarealsoreturnedintheBAPI returnparameteraredisplayed.
XML Format for RFCs

JustasforBAPIs,therearethreedifferenttypesofbusinessdocumentsforeachRFC: Arequestbusinessdocument. Aresponsebusinessdocument,iftheRFCcallhasbeensuccessfullyexecuted. AnExceptionbusinessdocument,iftheRFCcallfailed. Thefollowingsectionsdescribethesethreetypesofbusinessdocumentsinmoredetail.
Structure of Request Business Documents for RFCs

ThisisthegeneralstructureofrequestbusinessdocumentsforRFCs:
<doc:FunctionModuleName xmlns:doc="urn:sapcom:document:sap:business:rfc:functions"> <FuMod_Parameter1>...</FuMod_Parameter1> ... </doc:FunctionModuleName>
309
Additionally,considerthefollowing: Therootelementthatidentifiestherequestbusinessdocumenthasthesamenameas thecorrespondingfunctionmodule.Itcontainsthenamespacereferenceofbusiness documentsthatrefertoRFCs("urn:sap-com:document:sap:business:rfc"). ImportparametersoftheRFCappearassubelementsoftherootelement.Thesesub elementshavethesamenameastheparametersastheyaredefinedinthefunction moduleinterface.Withintheseelements,theSAPinternaldatastructuresare representedinaserializedforminaccordancewiththespecificationSerializationof ABAPDatainXML(forfurtherinformation,pleaserefertoRelatedDocumentation onpage 13). Becauseitisnotpossibletodistinguishtablesinthefunctionmoduleinterfacein importtablesandexporttables,alltablesthatshouldbetakenintoaccounthavetobe representedassubelements.
Structure of Response Business Documents for RFCs

IftheRFCcanbeexecutedwithoutgettinganexception,aresponsebusinessdocumentis returnedtothesender.Itcontainstheexportdataofthefunctionmodule. ThisisthestructureofresponsebusinessdocumentsforRFCs:
<doc:FunctionModuleName.Response xmlns:doc="urn:sapcom:document:sap:business:rfc:functions"> <FuMod_Parameter1>...</FuMod_Parameter1> ... </doc:FunctionModuleName.Response>
Additionally,considerthefollowing: Thenameoftherootelementthatidentifiestheresponsebusinessdocumentis definedastheconcatenationofthenameofthecorrespondingfunctionmoduleand thesuffix.Response.Itcontainsthenamespacereferenceofbusinessdocumentsthat refertoRFCs("urn:sap-com:document:sap:business:rfc"). ExportparametersandtablesoftheRFCappearassubelementsoftherootelement. Thesesubelementshavethesamenameastheparametersdefinedinthefunction moduleinterface.Withintheseelements,theSAPinternaldatastructuresare presentedinaserializedforminaccordancewiththespecificationSerialization of ABAP Data in XML(forfurtherinformation,pleaserefertoRelatedDocumentation onpage 13).
310
XML Format for RFCs
Structure of Exception Business Documents for BAPIs

Ifthefunctionmodulecannotbeexecuted,theexecutionendswithafunctionmodule exceptionandanexceptionbusinessdocumentisreturnedtotheclient.Itdescribesonly theerrorsituation.Inthiscase,exportparametersofthefunctionmodulearenot included. ThisisthestructureofexceptionbusinessdocumentsforRFCs:
<doc:FunctionModuleName.Response xmlns:doc="urn:sap-com:document:sap:business:rfc">  ... </doc:FunctionModuleName.Response>
Therepresentationofthefunctionmoduleexceptionasaserializedexceptionconsistsof thefollowingXMLelements: XML Element

<Name> <Message>
Description Nameoftheexceptionasdefinedinthefunctionmodule interface. The<Message>elementcontainsinformationfromtheSY fields.Couldbeemptyifthemappingwasperformedon anexternalmiddlewaresystem. SYMSGID SYMSGNO Messagetext,whichisdefinedforIDandnumber.In ABAP,evaluatedwithmessage id... into.. ContainslistofSYfields,whichrepresentthevariablesof anerrormessage. SYMSGV1 SYMSGV2 SYMSGV3 SYMSGV4
(0..1)
<ID> <Number> <Text> <Attributes>(optional) <V1>(optional) <V2>(optional) <V3>(optional) <V4>(optional)
311
XML Format for IDocs

Tocreateanasynchronouscommunication,IDocsareexchangedbetweentwoSAP systems.TherearetwowaystodefineconcreteIDocstocommunicateasynchronously: AsofRelease4.0,generateanIDocfromanexistingBAPI. CreateIDocsmanually. Therefore,twodifferentwaysofrepresentingIDocsinXMLcanbedistinguished: IftheIDocwasgeneratedfromanexistingBAPI,theasynchronouscommunicationis performedbyusingtheBAPIinterface.Consequently,theexchangedbusiness documentsarecreatedfromthecorrespondingBAPI.TheIDocitselfisnotvisibleat XMLlevel. IDocsthatweredefinedmanuallyandnotgeneratedfromBAPIsrequireaseparate XMLrepresentation.Thisrepresentationisdescribedindetailbelow.
XML Format for Manually Defined IDocs

ThisisthestructureofbusinessdocumentsformanuallydefinedIDocs:
<doc:IdocTypeName> <IDOC BEGIN="1"> <EDI_DC40 SEGMENT="1">...</EDI_DC40> <E1SEGMENT1 SEGMENT="1">...</E1SEGMENT1> ... </IDOC> </doc:IDocTypeName>
Additionally,considerthefollowing: Therootelement,whichidentifiesthebusinessdocumentforanIDoc,hasthesame nameasthecorrespondingIDoctype. TheIDocitselfisencapsulatedbytheelement<IDOC BEGIN="1"> ...</IDOC>.The elementcontainstheattributeBEGINwiththefixedvalue1. TheIDoccontrolrecordisdefinedthroughtheelement<EDI_DC40 SEGMENT="1">...</ EDI_DC40>. EachIDocsegmentisrepresentedasaseparateelementthathasthesamenameas correspondingIDocsegment.SAPsegmentsusuallyhavetheprefixE1.These elementscontaintheattributeSEGMENTwiththefixedvalue1,whichdefinesthe beginningofthesegment. Theelementnameforthefieldswithinonesegmentaregivenbythenameofthe correspondingfield.AnXMLdocumentforanIDocmaycontainemptyfields.These fieldsaredisplayedaselementswiththeform<FieldName/>.
312
XML Format for IDocs
ThehierarchicalstructureofIDocsisrepresentedbythestructureoftheXML document. TheIDoccontrolrecordishandledintheXMLdocumentasacommonsegment.
313
314
Index
A
ABAP debug 60 Dictionary Type 70 program for a coded client 201 types in the adapter 230 wrapper for calling a function module 140 About page 32 Access Control Lists (ACLs), assigning 46 adapter connections built-in services 29 changing at service run time 30 clustering requirements 52 described 28 overview 28 planning for 28 adapter listener notifications. See listener notifications. adapter package 28 clustering requirements 51 loading and unloading 45 adapter services changing connection at service design time 30 changing connection at service run time 30 clustering requirements 52 create 75 description of RFC adapter service 31 function module 74 overview 30 RFC 74 RFC client connection 74 template 74 templates 31 test 76 adapter updates applied, viewing 32 adapter versions clustering requirements 51 administrative services disablng redirection 50 ALE listener notifications create asynchronous 105 create synchronous 101 description 31 Monitor IDocs 81 ALE transport 136 application server 58 authorization service 89
B
BAPI description 23 function module 74 testing connections 68 transport 137 built-in services BAPI services 259 bXML services 257 client services 232 IDoc services 248 IDoc-XML services 254 monitoring services 256 pub.art.connection:setAdapterServiceNodeConnection 29, 30 sample services 280 SAP listener services 283 specifications 276 transaction administration services 261 transport services 266 XRFC services 245
C
client 57 code clients 192 RFC 23 clustering benefits 47 cluster store 47 connection pooling enabled 53 defined 47 description 47
315
Index
disadvantages 48 failover support 47, 48 inbound RFCs 49 load balancing 47, 48 outbound RFCs 48 recommnedations for SAP Adapter 47 replicating packages in clustered environment 49 requirements 51 restrictions for SAP 48, 49 restrictions on transactions 47 scalability 47, 48 configuration disk space 34 log files 35 system memory 37 connection alias 57 connection pooling overview 29 run-time behavior 29 connections copying 65 deleting 66, 186 editing 64 enabling 63 preventing use of 66, 186 SNC connection 62 testing BAPI execution 68 testing RFC execution 67 viewing parameters 64 conventions used in this document 14
disabling redirection of administrative services in clustered environment 50 document type IDoc 122 RFC structure 122 documentation additional 15 conventions used 14 feedback 15 DTD 123
E
editing listener notifications 108 routing service 140 synchronous listener notification 103 enabling listener notifications 106 listeners 91 packages 44 exporting packages, renaming disallowed 45 external RFC server 58
F
fixes, viewing applied 32 forward confirm event flag 81, 131 function module adapter services 74 BAPIs 74 create 110 description 74 Lookup 67
D
Data Dictionary Cache 216 deleting connections 66, 186 listener notifications 109 listeners 96 routing notification 139 dependencies, package 43 disabling listener notifications 109 listeners 97 redirection of administrative services 50
G
gateway host 58, 88 gateway service 58, 88 group access control, assigning 46
I
IDoc description 24
316
generate document type from DDIC 122 generate document type from DTD 123 generate document type from sample IDoc 124 route through routing listener 129
L
language 57 LIBRFC 24 listener name 88 listener notifications behavior of 106 components 80 configuring asynchronous notifications 105 RFC asynchronous notifications 103 RFC synchronous notifications 99 synchronous notifications 101 configuring asynchronous 105 defined 31 deleting 109 disabling 109 editing 108 asynchronous publishable document type 108 notification order 94, 133 enabling 106 prerequisites for configuring 97 testing 106 testing publishable document types 107 types 31 using asynchronous and synchronous 98 viewing 107 viewing notification order 93 listeners copying 95 deleting 96 disabling 97 editing 94 enabling 91 viewing parameters using the Administrator 93 viewing parameters using the Developer 93 load balancing 47, 57 loading adapter packages 45
namespace node packages 45 WmART package 45 log files 35 log transaction status 61, 90 logging about 188 file location 188 RFC trace file 188 Logging screen 188 logon group 57 Lookup function module 67 using Lookup 67
M
Manager (webMethods), using with EJB Adapter 32 memory 37 message server 58 monitoring component response time 189 data captured 189
N
namespace node packages loading and unloading 45 package dependencies 43 notifications. See listener notifications. number of threads 88
O
overriding services default connection at run time 30
P
packages enabling and disabling 44 loading and unloading 45 management overview 28 renaming when exporting (disallowed) 45 replicating in clustered environment 49 SAP package 42 WmSAP 28 packages, adapter
317
Index
loading and unloading 45 packages, namespace node loading and unloading 45 password 57 platforms 34 preventing use of connections 66, 186 program code conventions in this document 14 program ID 58, 88 publishable document type testing in asynchronous notifications 107
R
redir.cnf file 50 replicating packages in a clustered environment 49 repository server 89 repository service 58 response time monitoring 189 RFC code library 24 configure RFC listener 87 create adapter notification 110 create RFC destination 84 description 23 generate document type for a structure 122 invoke from Java service 192 LIBRFC 24 local RFC metadata 89, 217, 218 protocol 24 route through routing listener 129 routing 140 test RFC listener 92 testing connections 67 trace file 188 transactional RFC 23 transactional RFC protocol 23 transport 136 RFC adapter service about 74 create 75 RFC client description 23 workflow 25
RFC listener 23 RFC listener notification 31, 32 RFC protocol 24 RFC server description 23 workflow 25 RFC trace 60, 90 RFC trace files, viewing and deleting 188 RFC_TRACE_DIR environment variable 188 routing RFC 140 routing directly through the adapter 129 routing listener description 24 routing notification components 130 create 134 deleting 139 description 32 transports 134 using wildcards 132 routing service 140 run-time processing connection pools 29
S
SAP code library 24 SAP log file 189 SAP log files, viewing and deleting 188 SAP router string 60 SAPGui note about screen images 15 security SAP adapter as RFC server 210 SAP cryptographic library 211 user name and password 208 X.509 certificate 208 SNC enabled 59, 89 name 59, 89 partnername 59 quality of service 59, 89 setup connection 62
318
store message body 61, 90 structures 122 supported platforms 34 synchronous listener notification editing 103 system ID 58 system memory 37 system number 58
typographical conventions in this document 14
U
unicode listener 90 unloading adapter packages 45 namespace node packages 45 WmART package 45 updates to the adapter, viewing 32 Use SAPGui 60 user name 57
T
testing listener notifications 106 publishable document types 107 TID character length 23 Confirm TID event 81 description 23 for ALE IDoc Monitoring 102 trace files, viewing and deleting 188 transaction centralized transaction store 181 configuring client 184 configuring server 182 deleting 186 considerations about centralized transaction store 53 transaction store 35 transaction ID character length 23 transaction store 35 description 24 transactions managing 170 transaction store 170 transports ALE 136 BAPI 137 for routing notification 134 IS 135 RFC 136 XML 138 tRFC 23 tRFC protocol 23 troubleshooting information 15
V
viewing adapter updates applied 32 listener notifications 107 listener parameters using the Administrator 93 listener parameters using the Developer 93
W
watt.sap.aclset 227 watt.sap.debug.facList 226 watt.sap.debug.level 226 watt.sap.idocxml.escaping 226 watt.sap.listener.checkTime 225 watt.sap.listener.responseTime 226 watt.sap.monitor 227 watt.sap.repo.maxPooledConnections 225 watt.sap.repo.maxWaitForPool 225 watt.sap.repo.timeout 225 watt.sap.repo.timeoutCheckPeriod 225 watt.sap.rfcxml.version 226 watt.sap.snclibpath 227 watt.sap.systat01.partnerNumber 227 watt.sap.throughput 227 watt.sap.xml.prettyPrint 226 watt.sap.xtn.cacheFlushPeriod 226 watt.sap.xtn.cacheTimeToLive 226 watt.sap.xtn.fastAsyncMode 226 webMethods Manager, using with EJB Adapter 32 wildcards for routing notification 132 WmART package
319
Index
load and reload order 45 loading and unloading 45 unload order 45 WmSAP pacakge 28
X
X.509 certificate 208
320

6-5-SP1 SAP Adapter Users Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

6-5-SP1 SAP Adapter Users Guide

Încărcat de

Drepturi de autor:

Formate disponibile

webMethods SAP Adapter

VERSION 6.5 SERVICE PACK 1

Chapter 1. About the webMethods SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 2. System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 3. Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 4. Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 5. Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6. Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

webMethods SAP Adapter Users Guide Version 6.5 SP1

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 7. Generating Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 8. Routing Messages Through the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . 127

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 9. Transaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 10. Logging and Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 11. Coding Client Applications and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Chapter 12. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

webMethods SAP Adapter Users Guide Version 6.5 SP1

Chapter 13. Managing the DDIC Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Appendix A. Package Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Appendix B. Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Appendix C. ABAP Types in the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Appendix D. Built-in Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Appendix E. Deprecated Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Appendix F. Working with Code Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

webMethods SAP Adapter Users Guide Version 6.5 SP1

Appendix G. Using BizTalk Envelopes with the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . 291

Appendix H. Using IFR-XML Format with the SAP Adapter . . . . . . . . . . . . . . . . . . . . . . . . 299

webMethods SAP Adapter Users Guide Version 6.5 SP1

webMethods SAP Adapter Users Guide Version 6.5 SP1

About This Guide

About This Guide

webMethods SAP Adapter Users Guide Version 6.5 SP1

Refer to this book... webMethodsBuiltIn ServicesReference Guide

For... Thisguidedescribesthebuiltinservicesprovidedwitha standardinstallationofIntegrationServerandlocatedinthe WmPublicpackage. Youwillfindthisdocumentat: webMethods_directory\Developer\doc\IntegrationServerBISRe ference.pdf

IndepthinformationabouthowABAPdataisserializedin XMLmessages.ThisserializationisusedforRFCandBAPI parameters. Youwillfindthisinformationat: http://ifr.sap.com/home/Documents/ABAP_Serialization.htm

IndepthinformationabouthowRFCs,BAPIsandIDocsare formattedinXML. Youwillfindthisguideat: http://ifr.sap.com/home/Documents/XML_index_E.htm

webMethodsSAP AdapterIDocJavaAPI Documentation

IndepthinformationaboutthewebMethodsSAPAdapter implementationoftheSAPJavaIDocClassLibrary. Youwillfindthisguideat: webMethods_directory\Integration Server\packages\WmSAP\pub\doc\api\index.html

webMethods SAP Adapter Users Guide Version 6.5 SP1

SAP System Screens and Procedures

Description Identifieskeyboardkeys.Keysthatyoumustpresssimultaneouslyare joinedwiththe+symbol. Directorypathsusethe\directorydelimiterunlessthesubjectis UNIXspecific. Optionalkeywordsorvaluesareenclosedin[].Donottypethe[] symbolsinyourowncode.

SAP System Screens and Procedures

webMethods SAP Adapter Users Guide Version 6.5 SP1

webMethods SAP Adapter Users Guide Version 6.5 SP1

About the webMethods SAP Adapter

webMethods SAP Adapter Users Guide Version 6.5 SP1

CHAPTER 1 About the webMethods SAP Adapter

What Is the webMethods SAP Adapter?

webMethods SAP Adapter Users Guide Version 6.5 SP1

Complete SAP System Integration

webMethods SAP Adapter Users Guide Version 6.5 SP1

CHAPTER 1 About the webMethods SAP Adapter

Integrating SAP Systems Over the Internet

Routing IDocs, RFCs and BAPIs

webMethods SAP Adapter Users Guide Version 6.5 SP1

Support for IDoc- and RFC-XML

Support of BizTalk XML Envelopes for BAPI and RFC Calls

webMethods SAP Adapter Users Guide Version 6.5 SP1

CHAPTER 1 About the webMethods SAP Adapter

Built-in BAPI Tools