70_DevAndExtGuide

Development andExtension Guide

SAP E-Commerce7.0 – Landscape,Basics andConcepts.

Document Version 1.0– August, 2008

SAP AGDietmar-Hopp-Allee 1669190 WalldorfGermanyT +49/18 05/34 34 24F +49/18 05/34 34 20www.sap.com

© Copyright 2004 SAP AG. All rights reserved.

No part of this publication may be reproduced or transmitted in any formor for any purpose without the express permission of SAP AG. Theinformation contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors containproprietary software components of other software vendors.

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® andSQL Server® are registered trademarks of Microsoft Corporation.

IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®,MVS/ESA, AIX®, S/390®, AS/400®, OS/390®, OS/400®, iSeries, pSeries,xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®,Tivoli®, Informix and Informix® Dynamic Server

TM are trademarks of

IBM Corp. in USA and/or other countries.

ORACLE® is a registered trademark of ORACLE Corporation.

UNIX®, X/Open®, OSF/1®, and Motif ® are registered trademarks of theOpen Group.

LINUX is a registered trademark of Linus Torvalds and others.

Citrix®, the Citrix logo, ICA®, Program Neighborhood ®, MetaFrame®,WinFrame®, VideoFrame®, MultiWin® and other Citrix product namesreferenced herein are trademarks of Citrix Systems, Inc.

HTML, DHTML, XML, XHTML are trademarks or registeredtrademarks of W3C®, World Wide Web Consortium, MassachusettsInstitute of Technology.

JAVA® is a registered trademark of Sun Microsystems,Inc.

J2EE™ is a registered trademark of Sun Microsystems,Inc.

JAVASCRIPT® is a registered trademark of SunMicrosystems, Inc., used under license for technologyinvented and implemented by Netscape.

MarketSet and Enterprise Buyer are jointly ownedtrademarks of SAP AG and Commerce One.

SAP, SAP Logo, R/2, ERP, mySAP, mySAP.com, xApps,mySAP Business Suite, and other SAP products andservices mentioned herein as well as their respective logosare trademarks or registered trademarks of SAP AG inGermany and in several other countries all over the world.All other product and service names mentioned are thetrademarks of their respective companies.

DisclaimerSome components of this product are based on Java™.Any code change in these components may causeunpredictable and severe malfunctions and is thereforeexpressively prohibited, as is any decompilation of thesecomponents.

Any Java™ Source Code delivered with this product isonly to be used by SAP’s Support Services and may notbe modified or altered in any way.

Documentation in the SAP Service MarketplaceYou can find this documentation at the following Internetaddress:service.sap.com/instguides

Typographic Conventions

Type Style Represents

Example Text Words or characters that appearon the screen. These includefield names, screen titles,pushbuttons as well as menunames, paths and options.

Cross-references to otherdocumentation

Example text Emphasized words or phrases inbody text, titles of graphics andtables

EXAMPLE TEXT Names of elements in thesystem. These include reportnames, program names,transaction codes, table names,and individual key words of aprogramming language, whensurrounded by body text, forexample, SELECT andINCLUDE.

Example text Screen output. This includes fileand directory names and theirpaths, messages, names ofvariables and parameters,source code as well as names ofinstallation, upgrade anddatabase tools.

Example text Exact user entry. These arewords or characters that youenter in the system exactly asthey appear in thedocumentation.

<Example text> Variable user entry. Pointedbrackets indicate that youreplace these words andcharacters with appropriateentries.

EXAMPLE TEXT Keys on the keyboard, forexample, function keys (such asF2) or the ENTER key.

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax

Development and Extension Guide – SAP E-Commerce 7.0

June 2008 4

Contents

Contents ...........................................................................................................4

Development and Extension Guide – SAP E-Commerce 7.0: Landscape,Basics and Concepts ....................................................................................14

General Introduction 14Where the Current Version of this Document is Located ......................................14Naming Conventions.................................................................................................14

Terminology......................................................................................................................................14Variables...........................................................................................................................................15

Structure of this Document ......................................................................................16Available Courses, Literature, Links, Notes............................................................16

Courses ............................................................................................................................................16CR800: CRM E-Commerce ............................................................................................................................16

Course Goals ..............................................................................................................................................16Course Content ...........................................................................................................................................16

CR870: CRM Channel Management ...............................................................................................................17Course Goals ..............................................................................................................................................17Course Content ...........................................................................................................................................17

CR850: Internet Sales ERP Edition .................................................................................................................17Course Goals ..............................................................................................................................................17Course Content ...........................................................................................................................................18

CR555: CRM Technology...............................................................................................................................18Course Goals ..............................................................................................................................................18Course Content ...........................................................................................................................................18

Literature ..........................................................................................................................................19Links.................................................................................................................................................19Java in General ...............................................................................................................................................19Java Tutorials .................................................................................................................................................19Java Newsgroups ............................................................................................................................................19

Introduction to SAP J2EE.............................................................................20SAP Web Application Server Java 21Web Container 21

E-Commerce Framework..............................................................................22E-Commerce Architecture Overview 23

Layered Architecture.................................................................................................25Interaction and Presentation Layer....................................................................................................26Business Object Layer (BO Layer) ....................................................................................................26Business Logic Service Layer (BLS Layer) ........................................................................................27

Presentation Layer Details 28JSPs............................................................................................................................28

Custom ISA Tags..............................................................................................................................28MimeURL ......................................................................................................................................................29WebappsURL .................................................................................................................................................30translate..........................................................................................................................................................31iterate .............................................................................................................................................................32contentType....................................................................................................................................................32


August 2008 5

moduleName ..................................................................................................................................................33message..........................................................................................................................................................33imageAttribute................................................................................................................................................33

Dynamic Field Control ..............................................................................................34Definition...........................................................................................................................................34The structure of the UI element object .............................................................................................................35The structure of the UI element group object ...................................................................................................35Configuration of fields via XCM admin...............................................................................................35Add field to the xcmadmin-config.xml ............................................................................................................36Add field to the conf-data.xml.........................................................................................................................37Usage ...............................................................................................................................................37JSP .................................................................................................................................................................37Action ............................................................................................................................................................38

Interaction Layer Details 38Overview ....................................................................................................................38UI Components ..........................................................................................................38Interaction Components ...........................................................................................39

Actions..............................................................................................................................................39Threads in Actions..........................................................................................................................................40ActionForms......................................................................................................................................41

Interaction Configuration..........................................................................................41ActionServlet.....................................................................................................................................42ActionFormBean ...............................................................................................................................42ActionMapping ..................................................................................................................................43ActionForward...................................................................................................................................43

ISA extension of Struts .............................................................................................44ISA Actions .......................................................................................................................................44com.sap.isa.core.InitAction .............................................................................................................................44com.sap.isa.core.BaseAction ...........................................................................................................................45com.sapmarkets.isa.isacore.action.EComBaseAction .......................................................................................45com.sapmarkets.isa.isacore.action.EComExtendedBaseAction.........................................................................46com.sap.isa.isacore.action.IsaCoreBaseAction.................................................................................................47com.sap.isa.core.UserSessionData...................................................................................................47Changing language dependand resource keys ..................................................................................47

Additional Information ..............................................................................................48Secure Programming 48

Input Validation..........................................................................................................48Guideline ..........................................................................................................................................48

HTTP Header Information .........................................................................................50Guideline ..........................................................................................................................................50Persistent Cookies ............................................................................................................................50Guideline ..........................................................................................................................................50

Cross Site Scripting ..................................................................................................51Guideline ..........................................................................................................................................51Error Handling...................................................................................................................................52Solution ............................................................................................................................................52

User Session/Authentication....................................................................................52Guideline ..........................................................................................................................................52Logging/Tracing ................................................................................................................................52Guideline ..........................................................................................................................................52

Comments in HTML Code.........................................................................................52Guideline ..........................................................................................................................................53

Support of Web Standards (only B2C) 53Introduction ...............................................................................................................53


August 2008 6

Frameless JSP pages................................................................................................53Introduction.......................................................................................................................................53Structure of the layout-config.xml ......................................................................................................55The structure of the UILayout tag....................................................................................................................55The structure of the Form tag ..........................................................................................................................56The structure of the HTML attribute tag ..........................................................................................................56The structure of the UIArea tag .......................................................................................................................56The structure of the UIAreaContainer tag ........................................................................................................57The structure of the UIComponent tag.............................................................................................................57The structure of the UIConfiguration tag .........................................................................................................58Create your component actions.........................................................................................................58Create your JSP includes..................................................................................................................58Control the layout..............................................................................................................................59UILayout ........................................................................................................................................................59Layout Processing...........................................................................................................................................60UIArea ...........................................................................................................................................................60UIInclude .......................................................................................................................................................61UIJSInclude....................................................................................................................................................61Dynamic change of HTML title...........................................................................................................62Dynamic changes of the layout..........................................................................................................63Support of navigation issues .............................................................................................................64UIStoreLayout & UIStoreForward ..................................................................................................................64UIStoreAction ................................................................................................................................................65UIAction ........................................................................................................................................................65UIGetLayout & UIGetForward .......................................................................................................................66Summary of the UI Commands .........................................................................................................67Global Commands ..........................................................................................................................................67Commands while Layout processing ...............................................................................................................67

Browser Back Support..............................................................................................67Usage of context values ....................................................................................................................68Registration of context values .........................................................................................................................68Getting and setting context values ...................................................................................................................69Overruling context values in an url..................................................................................................................70Rules for UI components.................................................................................................................................71Redirect after form submit .................................................................................................................71General Guidelines ...........................................................................................................................72

Bookmark Support ....................................................................................................72Business Object Layer Details 74

Design Considerations ......................................................................................................................74Additional Information ..............................................................................................76

Business Logic Service Layer Details 77Design Considerations .............................................................................................77Backend Objects .......................................................................................................77

Lifecycle of Backend Object ..............................................................................................................78Initialization of the Backend Object ................................................................................................................78Destruction of Backend Objects ......................................................................................................................79Backend Context...............................................................................................................................79

BackendObjectManager............................................................................................80Connection Management..........................................................................................80

Design Considerations ......................................................................................................................80Working with JCo Based Connectivity ...............................................................................................80Connection Types ...........................................................................................................................................81Working with JCoConnections........................................................................................................................83

Getting Default Connection Associated with a Backend Object....................................................................83Getting a Modified Connection ...................................................................................................................84Getting a New Connection from a ConnectionFactory object .......................................................................85


August 2008 7

Working with JCO.Functions .............................................................................................................85Creating JCO.Functions ..............................................................................................................................85

Executing JCo Functions.................................................................................................................................86Configuration of BLS Layer......................................................................................87

Configuring Connection Management................................................................................................87JCo Function Cache ........................................................................................................................................87Configuring Backend Objects ............................................................................................................89

Further Services 91Message Framework .................................................................................................91

Message classes ..............................................................................................................................92Message, MessageList and MessageListHolder Class ......................................................................................92Adding messages from a CRM backend ..........................................................................................................92MessageListDisplayer.....................................................................................................................................93Message Tag ....................................................................................................................................94Exception Handling ...........................................................................................................................94Backend .........................................................................................................................................................95Business Object Layer ....................................................................................................................................96Action Layer...................................................................................................................................................96Error Pages.......................................................................................................................................96appbase\backenderror.jsp ................................................................................................................................96appbase\runtimeerror.jsp.................................................................................................................................96appbase\panicexception.jsp .............................................................................................................................96appbase\relogin\invalidsession.jsp...................................................................................................................97appbase\message.jsp .......................................................................................................................................97appbase\jspruntimeerror.jsp.............................................................................................................................97appbase\accessibilitymessages.inc.jsp..............................................................................................................97Message handling in accessibility mode ............................................................................................97How to integrate the global message pages in an application ............................................................98Pre Condition check in the EComExtendedBaseAction......................................................................99

Generic Search Framework ....................................................................................101Architecture of the Generic Search Framework ...............................................................................102Main Components of the Generic search framework........................................................................103Details of component “generic-searchbackend-config.xml” ..............................................................103Details of component “GenericSearchBaseAction” ..........................................................................110Details of component “CRM_ISALES_SEARCH”.............................................................................110ESelling specific implementation of the Generic Search Framework ................................................113

Logging/Tracing ......................................................................................................115Design Consideration......................................................................................................................115Difference between Logging/Tracing ...............................................................................................115Tracing.........................................................................................................................................................115Logging........................................................................................................................................................116Summary Types of log messages....................................................................................................117Tracing ...........................................................................................................................................117APIs for Tracing: ISALocation......................................................................................................................117

Initializing Location..................................................................................................................................117Entering/exiting non trivial method ...........................................................................................................117Throwing exception ..................................................................................................................................118DEBUG....................................................................................................................................................118ERROR ....................................................................................................................................................118Coding Examples......................................................................................................................................118

APIs for Tracing: SAP Logging API .............................................................................................................119Initializing Location..................................................................................................................................119DEBUG....................................................................................................................................................119ERROR ....................................................................................................................................................120Entering/exiting non trivial method ...........................................................................................................120Throwing exception ..................................................................................................................................120

Logging...........................................................................................................................................121Usage of Categories ......................................................................................................................................121


August 2008 8

APIs for Logging: ISALocation ....................................................................................................................122ERROR ....................................................................................................................................................122FATAL.....................................................................................................................................................122INFO ........................................................................................................................................................122WARNING...............................................................................................................................................122Detailed Message Descriptions..................................................................................................................123Coding Examples......................................................................................................................................123

APIs for Logging: SAP Logging API ............................................................................................................124INFO ........................................................................................................................................................124WARNING...............................................................................................................................................124ERROR ....................................................................................................................................................124FATAL.....................................................................................................................................................124

How to Log/Trace: Usage patterns ..................................................................................................125All purpose Cache...................................................................................................131

Working with the Cache ..................................................................................................................131Initialization Handler ...............................................................................................132

Extended Configuration Management (XCM) 134Separation of Customer and SAP Configuration Files.........................................134Separation of Configuration Data and Modification Data ....................................135XCM Extension Mechanism....................................................................................136Web Application Configuration and Components................................................137

SAP Java Remote Function Call (JRFC)...................................................138Technology 138

Development Environment.........................................................................139Development Tools and Concepts 140

External documentation..........................................................................................140Overview of process ...............................................................................................140

Software Component Architecture of the CRM or Extended Ecommerce Java Applications .............141Modifications and Extensions of the Web User Interface..................................................................142Extensions of the Java Code...........................................................................................................143Merged Web Applications ...............................................................................................................144Handling of duplicate files ............................................................................................................................144Restrictions...................................................................................................................................................144

Initial Configuration of the NWDI 145Pre-requisites...........................................................................................................145

Creating a project specific Web Application with own context root 145Basic concept ..........................................................................................................146Step by step process ..............................................................................................146

Check SLD content and create a new Software Component ............................................................146Create a new Track using the Landscape Configurator....................................................................146Add Software Components to track .................................................................................................147Configure Runtime Systems in the track..........................................................................................148Import Software Components into this track ....................................................................................149Download Archives ......................................................................................................................................149Check-In archives .........................................................................................................................................149Import the checked in archives into the Development system.........................................................................150Import the checked in archives into the Consolidation system ........................................................................150Create your own Enterprise Applications.......................................................................................................150Test the CRM Java application on a local Web AS Java Engine.....................................................................151


August 2008 9

Creation or Extensions of Java Classes ...............................................................151Importing Modifications and Extensions from older Releases ...........................152

Developer Workplace 156Required tools and versions ..................................................................................157Java Development Kit .............................................................................................157

Installation of JDK 1.4.2 ..................................................................................................................157Developer Workplace for SAP NetWeaver 2004s..................................................159

Installing the Developer Workplace for SAP NetWeaver 2004s........................................................159Directory Structure of the Web AS Java 7.0.....................................................................................160TCP-Ports.......................................................................................................................................160Starting and Stopping the WebAS Java...........................................................................................161Configuration of SAP WebAS Java 7.0............................................................................................161Uninstalling the Developer Workplace for SAP NetWeaver 2004s ...................................................162

Configuring and Working with Developer Studio.................................................162Configuration of the web application................................................................................................162

Remote Debugging 163Setting up remote debugging for SAP WEB AS Java 7.0 ....................................163

Enabling/Disabling Debug Mode Permanently.................................................................................163Enabling/Disabling Debug Mode Temporarily ..................................................................................164Starting Remote Debugging ............................................................................................................165

ABAP Debugging 166Prerequesites...........................................................................................................166Activating ABAP Debugging ..................................................................................167

Java Debugging 167

Introduction to Extension Concepts .........................................................168Extensions in the ISA Framework 168

Finding the Appropriate Extension Concept ........................................................170How to use these diagrams.............................................................................................................170Overview.........................................................................................................................................170Extensions to the UI Layer ..............................................................................................................171Extensions to the Action Flow..........................................................................................................172Extensions to Exchange Additional Data .........................................................................................173Extensions to Exchange Data with the UI-Layer ............................................................................................174Extensions to Exchange Data with Backend-Systems ....................................................................................179

Extensions to the UI layer.......................................................................................190Accessing the Session Context .......................................................................................................190Accessing the Request Context.......................................................................................................190

Extensions in the Action Flow................................................................................190Create a Customer Action ...............................................................................................................191Standard Actions providing User Exits ..........................................................................................................193Accessing the Session Context ......................................................................................................................195Accessing Business Objects from Actions .....................................................................................................196Accessing the Request Context.......................................................................................................197Modifications in the Struts Configuration..........................................................................................197Version.........................................................................................................................................................197Example .......................................................................................................................................................197

Business Object Layer............................................................................................197Storing Additional Data - Extension Mechanism ..............................................................................197Version.........................................................................................................................................................198Example .......................................................................................................................................................199Extending existing Business Objects ...............................................................................................199


August 2008 10

Version.........................................................................................................................................................200Create a Customer Business Object................................................................................................200Version.........................................................................................................................................................201Example .......................................................................................................................................................201Create a Customer Business Object Manager .................................................................................201Version.........................................................................................................................................................203Example .......................................................................................................................................................204

Business Logic Service Layer................................................................................204Create a Customer Backend Object ................................................................................................204Standard Backend Objects providing User Exits ............................................................................................204Creating new Customer Backend Objects ......................................................................................................208

Create an Interface of Backend Object.......................................................................................................208Design Considerations when Creating Backend Object Interfaces ..............................................................208Create an Implementation of Backend Object ............................................................................................209Register Backend Object in backendobject-config.xml...............................................................................209Accessing Backend Objects from Business Objects ...................................................................................209

Version.........................................................................................................................................................210Example .......................................................................................................................................................211BADIs/SAP CRM Extensions ..........................................................................................................211Version.........................................................................................................................................................212ABAP Extension Structure............................................................................................................................212Supported Function Modules and Business Objects .......................................................................................212

Order ........................................................................................................................................................212User..........................................................................................................................................................212Contract....................................................................................................................................................213Shop .........................................................................................................................................................213Complaint (E-Service)...............................................................................................................................213ComplaintHeader (E-Service)....................................................................................................................213ComplaintItem (E-Service)........................................................................................................................213

Reading data from the Backend.....................................................................................................................214Writing data to the backend...........................................................................................................................215Example .......................................................................................................................................................215Enhancements for the Dynamic UI of ECO B2B ...........................................................................................216BAPIs/SAP ERP-Extensions ...........................................................................................................217Version.........................................................................................................................................................217ABAP Extension Structure (BAPIPAREX) ...................................................................................................217Supported Function Modules and Business Objects. ......................................................................................218

Order ........................................................................................................................................................218Modification of Communication Structures in SAP ERP................................................................................220Configuration of the Web Application...........................................................................................................220Reading Data from the Backend....................................................................................................................221Writing Data to the Backend .........................................................................................................................221Example .......................................................................................................................................................222Java Basket-Extensions ..................................................................................................................222Version.........................................................................................................................................................222Example .......................................................................................................................................................222

Request Context......................................................................................................222Version.........................................................................................................................................................223Example .......................................................................................................................................................223

Adding additional Function Modules (Backend System).....................................224Version ...........................................................................................................................................225

Interception of Calls to Standard Function Modules............................................225Thread Safety in Execution Listeners ..............................................................................................227Version ...........................................................................................................................................227What to Do......................................................................................................................................227Example..........................................................................................................................................227

Replacing Calls to Standard Function Modules (Backend System) ...................227Version ...........................................................................................................................................228


August 2008 11

What to Do......................................................................................................................................228Example..........................................................................................................................................229

Extension of the Web Catalog 229New Fields in the Web Catalog (SAP CRM Backend)...........................................229

Preparation .....................................................................................................................................229Show Additional Attribute in Product List .........................................................................................229Show Additional Attribute in Product Details and in Compare Products............................................230Show Additional Keys for Extended Search in B2B..........................................................................231

New Fields in the Web Catalog (SAP ERP Backend and Memory Catalog) .......231Loading additional Product Attributes from the SAP ERP Backend to the Memory Catalog..............231Version ...........................................................................................................................................231Example..........................................................................................................................................231

New Fields in the Web Catalog (SAP ERP Backend and TREX)..........................232Loading additional Product Attributes from the SAP ERP Backend to the TREX ..............................233Version ...........................................................................................................................................233Example..........................................................................................................................................233

Customer Specific Views in the Web Catalog (SAP ERP Backend and TREX)..235Version ...........................................................................................................................................236Example..........................................................................................................................................236

Extensions of the IPC 237Architecture of the IPC 5.0 UI in CRM Order Scenario .........................................237Action Flow ..............................................................................................................239Use of the E-Commerce Layout Framework .........................................................239

UI Components...............................................................................................................................239UI Layouts ......................................................................................................................................239UI Areas..........................................................................................................................................240Tiles................................................................................................................................................241Low level layouts.............................................................................................................................241

Dynamic Includes ....................................................................................................242Extension To Transfer Data To JSP ................................................................................................244

UIBeans ....................................................................................................................244Client Object Layer..................................................................................................245Finding The Appropriate Extension Concept For IPC..........................................245Static extension to UI layer.....................................................................................246

Changing Stylesheets .....................................................................................................................246Create New Layout Or Change Standard Layout.............................................................................247

Change UI Components..........................................................................................247Example: Customer Buttons and Actions.........................................................................................247Example: Adding Customer Tab To Multifunctional Area .................................................................248Example: Display Characteristic Header And Values In One Line....................................................251

Extensions To The UIBean Layer...........................................................................252Extensions In The Action Layer .............................................................................252Create Customer Backend Object..........................................................................254SCE user functions .................................................................................................255Exchange additional data with ECO ......................................................................255

Extensions of the Document Handling 256Overview ..................................................................................................................256Implementation........................................................................................................256

Example..........................................................................................................................................258Integrating own documents....................................................................................260

PrepareNewDocAction....................................................................................................................261


August 2008 12

Creating a ManagedDocument ......................................................................................................................261PrepareNewDocAction .................................................................................................................................263

Structure of the Internet Sales application ...........................................................264Enterprise Application Archive (ear file) ...........................................................................................264Web Archive (war file) .....................................................................................................................264Configuration files ...........................................................................................................................265

Source Code ............................................................................................................267General Package Structure of an E-Commerce application .............................................................267

Conventions when Enhancing the E-Commerce Application 268Separation of SAP-Software / Customer Extensions ...........................................268Naming Conventions...............................................................................................268

Java Server Pages..........................................................................................................................268Changes in config.xml (or other Struts configuration files)................................................................268Changes in bom-config.xml .............................................................................................................270Java................................................................................................................................................271Packages.......................................................................................................................................................272Java Classes..................................................................................................................................................272Resource Files ..............................................................................................................................................273

Changes in Configuration 274Application Configuration and Component Configuration..................................274Common Configuration Changes ..........................................................................274

Changes in init-config.xml ...............................................................................................................274Changes in backendobject-config.xml .............................................................................................275Changing existing Backend Object ................................................................................................................275Adding new Backend Object .........................................................................................................................276

Extending XCM with Customer Settings ...............................................................277What to Do......................................................................................................................................277Adding Parameter Name and default Value ...................................................................................................278Adding Meta data of XCM parameters ..........................................................................................................279API for reading XCM parameter Values........................................................................................................282

Configuration of Dynamic fields in E-Service.......................................................282Generic Search Framework.............................................................................................................285E-Service Extended Complaints and Returns specific implementation of the Generic SearchFramework......................................................................................................................................286

Checking configuration during runtime ................................................................288

Best Practices..............................................................................................289Getting Information about the Application 289

Getting Information about JSPs.............................................................................289Displaying Names of JSPs while Running the Application................................................................289Example .......................................................................................................................................................289Displaying Text Keys While Running the Application .......................................................................290Example .......................................................................................................................................................291Finding out Information about the Process Flow ..............................................................................291Analysing the config.xml File (or other Struts configuration files) .................................................................291

Session Tracing 292Configuring session tracing...................................................................................292Enabling session tracing........................................................................................292

Tracing Function Modules ...............................................................................................................293Additional Request Parameters 294

General Request Parameters .................................................................................294ECO Version...................................................................................................................................295


August 2008 13

Example..........................................................................................................................................295Request parameters for B2C..................................................................................295

ECO Version...................................................................................................................................295Example..........................................................................................................................................295

Single Session Trace ..............................................................................................296Passing Data between Actions 296

Action Flow Remains on the Server ......................................................................296Action Flow is Interrupted by a JSP ......................................................................297

Working with Request Parser 297Writing Thread Safe Code 298Administration Console 299

Java Connector Pools .....................................................................................................................299Getting Application Version ...................................................................................299Logging ....................................................................................................................299

Updating Application 300

Web Diagrams .............................................................................................301Syntax of Web Diagrams 301B2B - Start Page 302B2B - Create Basket 303B2B - Display Order Status 304

References ...................................................................................................305

Update History.............................................................................................305

Table Index...................................................................................................306

Figure Index .................................................................................................309


August 2008 14

Development and Extension Guide –SAP E-Commerce 7.0: Landscape, Basics andConceptsIn SAP CRM 7.0, the Development and Extension Guide for SAP E-Commerce has been splitted into twodocuments.

The document Landscape, Basics and Concepts contains information about how the SAP E-Commerceapplications are designed, how to setup the development environment and explains the extension concept ofSAP E-Commerce.

The document Examples and Tutorials contains examples and extension tutorials for SAP E-Commerce 5.0.They are enhanced by new ones and still valid for E-Commerce 7.0.

General Introduction

Where the Current Version of this Document is LocatedThe current version of this document is located on the SAP Service Marketplace quick link CRM-INST(https://service.sap.com/crm-inst) SAP CRM 7.0 CRM Core and Standalone Componentscan be downloaded from there.

Naming Conventions

TerminologyThe term SAP Service Marketplace is the same as Marketplace.

The term E-Selling is the same as Internet Sales (ISA).

The term E-Service is the same as Internet Services (ICSS).

The term E-Commerce (ECO) embraces E-Selling and E-Service.

The term Web Channel (WEC) embraces E-Selling and E-Service.

The term SAP E-Commerce for mySAP CRM is used, when the E-Commerce application isconnected to a CRM System (ECO CRM).

The term SAP E-Commerce for mySAP ERP is used, when the E-Commerce application isconnected to an ERP or R/3 system (ECO ERP).

The term command shell is the same as command prompt.

Open a command prompt in windows by pressing Start -> Run. Enter ‘cmd’ and press enter.

The term SP is an abbreviation for support pack.

https://service.sap.com/crm-inst


August 2008 15

VariablesThe following table contains a list of the variables, which are used in this guide.

Variables Description

<RELEASE> SAP CRM release you have installed (e.g. 4.0 or 5.0).

<SP_NUMBER> Number of the service pack (two decimals), you want toupgrade to (e.g ‘03’).

<DRIVE> Drive on which the software was installed (e.g. c:).

<J2EE_REL> SAP J2EE Engine release (e.g. Web AS 7.0).

<JAVA_HOME> Directory, on which the JAVA runtime is installed (e.g.c:\jdk1.4.2).

<SAP_SID> System ID you entered during installation of the SAP WebApplication Server Java with the SAPInst.

<INSTANCE_NUMBER> Instance number of your SAP Web AS, which you enteredduring installation with the SAPInst.

<INST_DIR> Installation directory for the SAP system. If you have installedthe SAP Web AS with the SAPInst, the default installation pathis:

C:\usr\sap\<SAP_SID>\JC<INSTANCE_NUMBER>

<J2EE_HOME> <INSTDIR>\j2ee

<SDM_HOME> <INSTDIR>\SDM

<APPLICATION> Name of the deployed Internet Sales application (e.g. b2b orb2c).

<APPLICATION_HOME> Directory where the application is deployed.

(e.g. <J2EE_HOME>\cluster\server0\apps\sap.com\crm~b2bservlet_jsp\b2b\root)

<BUILDTOOL_HOME> Directory where the ISA build tool is located.

(e.g. C:\isa_build_tool)

<SERVER> Server on which your Internet Sales application is installed.

<PORT> Port on which the deployed application can be reached. For more details onthe SAP J2EE Ports, please refer to the chapter Additional Information 'Figure

32: Directory Structure of Web AS Java 7.0

TCP-Ports' on page 160

Table 1: List of the variables used in this guide


August 2008 16

Structure of this DocumentBefore we start the general introduction to the various subjects covered in this document, we would like toexplain a few things about its structure and handling.

This cookbook is intended for consultants who have knowledge of the SAP CRM (ERP) environment, E-Commerce versions, and basic Java skills, and who want to understand the concepts of the E-Commerce7.0 J2EE solution and wish to set up their own local development environment. After you have read thisextension guide, you should be able to make changes to both the local E-Commerce application and performcustomer installations.

The first unit provides a short general introduction to SAP J2EE that is needed in order to understand theconcepts of the E-Commerce framework discussed in the next unit.

The next unit gives an introduction to the SAP Java Remote Funciton Call required by the E-Commerceapplication when communicating with an SAP system.

Unit four provides an introduction to handling and installing the tools required for running the E-Commerceapplication and modifying it.

Best practices useful when extendion the application can be found in the last unit.

Available Courses, Literature, Links, NotesThis unit provides an overview of important sources of Java knowledge. In particular, it introduces thestandard courses available at SAP University, names important literature sources, and lists severalinteresting links about Java. It also contains introductory information on switching platforms in the frontendarea.

Courses

CR800: CRM E-Commerce

Course GoalsThis course will prepare you to

Apply CRM E-Commerce process knowledgePerform the customizing settings for CRM E-Commerce

Course ContentE-Commerce scenarios

E-Commerce architecture and components E-Commerce in the Solution Manager Web shop management SuperUser / User Management Product Catalog (Views, Dokuments, BAdIs, Export, external Catalogs, web-based maintenance

…) Price determination using the Internet Pricing Configurator (IPC)

Marketing Featureso Up/Down, Cross Sellingo Bestsellers


August 2008 17

o Personalized Product Recommandations E-Service

o Solution Searcho Service Request Managemento Complaints and Returns Management

Additional Featureso Ebay Integrationo ATP Checko E-Analyticso Contract Negotiationo Live Web Collaborationo Guided Sellingo Batches,o Product determination,o Request for Quotation

CR870: CRM Channel Management

Course GoalsThis course will prepare you to:

Apply CRM Channel Management process knowledge Perform the customizing settings for CRM Channel Management

Course ContentChannel Management scenarios

Channel Management architecture and components Channel Management in the Solution Manager Portal Roles in Channel Management Authorizations Partner Management Channel Marketing

o Customer Segmentationo Lead Managemento Opportunity Managemento Content Management

Channel Saleso Order Managemento Business on behalf

Channel Commerceo Collaborative Showroomo Hosted Order Managemento Set up

Partner & Channel Analytics

CR850: Internet Sales ERP Edition

Course GoalsTo enable the course participants to set up business processes with the ERP Internet Sales solution andto tailor them according to their needs.


August 2008 18

Course ContentOverview, positioning and benefits

How to set up Internet Sales in ERPo User Concepto Features of the ERP Product Catalogo Shop maintenance

System landscape (ERP Plug-In, Index Server, IPC, J2EE Engine, Webserver) How to set up the front-end of ERP Internet Sales

o J2EE-Specification, JSP-Templateso Configuration of Web XML- and Shop XML-File

Comparison to SAP Online Store and to mySAP CRM Internet Sales, upgrade path from one solutionto the other and outlook.

CR555: CRM Technology

Course GoalsTo provide the course participants with an understanding of the system architecture for the mostimportant SAP CRM Business Scenarios. The main focus is the technical system landscape and theconnectivity between the systems and software components. The data flow will be analyzed withrespect to the different business scenarios by addressing the following questions:

o Which technology is used in the scenario?o Which configuration or technical Customizing affects the data flow?o How can the data flow be monitored?

Course ContentIntroduction to the architecture of SAP CRM

Connectivity between the SAP back-end system and the CRM system:o CRM Middleware/administration consoleo Messaging BDoco Initial load / delta loado Data flow, configuration and monitoring

Architecture und technical configuration of Internet Sales Architecture und technical configuration of the Interaction Center

o WebClient/WinClient Architecture and technical configuration for Field Sales

o CRM Middleware: Synchronization BDoc and Consolidated Databaseo CRM Communication Stationo Mobile Clients


August 2008 19

LiteratureTitle ISBN number Publisher Summary

Thinking in Java 0-13-659723-8 Book can be downloaded from

http://www.mindview.net/

Links

Java in GeneralLink Institution Content

http://java.sun.com/ SUN Jave home

http://www.jguru.com jGuru.com Source for any kind of Java information

Java TutorialsLink Institution Content

http://java.sun.com/ Sun Microsystems There are various tutorials for Java 2 StandardEdition as well as J2EE

Java NewsgroupsNews-Link Group Content

de.comp.lang.java German JavaNewsgroup

General Java topics.

comp.lang.java International JavaNewsgroup

General Java topics.

http://www.mindview.net/

http://java.sun.com/

http://www.jguru.com/

http://java.sun.com/

news:de.comp.lang.java

news:comp.lang.java


August 2008 20

Introduction to SAP J2EEThe SAP J2EE architecture consists of a multi-tiered distributed application model. This means that theapplication logic is divided into different components according to function. These various applicationcomponents are installed on different machines depending on which tier in the multi-tiered SAP J2EEenvironment the application component belongs to. SAP J2EE multi-tiered applications are generallyconsidered to be three-tiered applications because they are distributed over three different locations:

Client machines

SAP J2EE application server

Database or legacy systems at the backend

The next figure shows a SAP J2EE three-tier architecture described in the bullet list below.

First tier

Client components run on the client machine; serves as a user interface.

Middle tier

Web container and EJB container run on the SAP J2EE application server; offers different services.

Third tier

Enterprise information system (EIS) software runs on the EIS server (ERP systems, databasesystems, and so on)

Figure 1: SAP J2EE three-tier architecture

The main benefits of the multi-tiered distributed application model are:

Components can be reused

Availability of a unified security model

Flexible transaction control


August 2008 21

SAP Web Application Server JavaThe SAP Web Application Server Java is part of the SAP Web Application Server platform and consists ofthe Web container, the EJB container, and services. The Web container is responsible for server-sidepresentation and for flow control. It contains Java Server Pages and Servlets. The EJB container isresponsible for server-side business logic and therefore contains Enterprise Java Beans. The EJB containeris not used by our Internet Sales application, because in our case the business logic is included in the SAPCRM (ERP) system. SAP J2EE based services, for instance resource pooling, security, naming, and so on,are offered by the service component of the SAP J2EE application server.

Figure 2: Components of the SAP J2EE Application Server

Web ContainerAs mentioned before, the Web container consists of Servlets and JSPs. Servlets are Java programminglanguage classes. A Servlet can be thought of as an applet that runs on the server side, without a userinterface. Java Servlets allow clients to execute programming code on the SAP J2EE Application Server.Servlets are request/ response oriented. HTTP Servlets receive a request in the form of anHTTPServletRequest object and return a response in the form of an HTTPServletResponse. JSP pages aretext-based documents that execute as Servlets, but allow a more natural approach to creating static content.Java Server Pages cleanly separate Web content (HTML and XML) from programming code by allowingWeb developers to move programming logic into components. This means that Web application developerscan concentrate on developing components while content developers build the HTML presentation.Furthermore, Java Server Pages simplify dynamic page development with tags. Java Server Pagestechnology encapsulates much of the functionality required for dynamic content generation in easy-to-use,JSP-specific XML tags. These tags can be used to access components, download applets and perform otherfunctions that would be difficult to develop with programming code. Additionally, you can create a set ofcustom tags, for instance, that access database functions or some other business logic. Our Internet Salesapplication uses these custom tags for certain purposes, for example, translation, completion of a URL,iteration, and so on.


August 2008 22

E-Commerce FrameworkE-Commerce 7.0 is based, as the prio CRM releases 5.0 and so on, on the SAP J2EE platform designed tosupport the requirements of modern, extendable, e-business oriented, enterprise application systems. SAPJ2EE provides component-based, scalable application architecture.

This chapter gives you a rough overview of the E-Commerce Framework to help you to understand the mainframework concepts. This is a prerequisite for the following paragraphs, in which each layer is discussed inmore detail. You need this information to understand the programming model of the ECO application, as wellas possible customer-extensions to the standard application.


August 2008 23

E-Commerce Architecture OverviewThe picture below shows the SAP E-Commerce for SAP CRM architecture.

.

Figure 3: SAP E-Commerce for mySAP CRM architecture

Web Browser

Java Stack

Web AS Java

ABAP Stack

Web AS ABAP

IPC Engine

CRM System

WebServer

TREX

ERPOLTP APO BW

Optional Backends

SAP E-Commerce for mySAP CRM

SAP EP

CRM JavaComponents

BW

XI

Firewall

Firewall


August 2008 24

The picture below shows the architecture of SAP E-Commerce for mySAP ERP 2005.

Figure 4: Architecture of SAP E-Commerce for mySAP ERP 2005

In case you use an older ERP or R/3 release, the architecture of SAP E-Commerce for mySAPERP might be different, since the IPC Engine has to be installed in an SAP Web ApplicationServer ABAP 7.0, which has to be installed seperately.

The ECO architecture pictures above containe some components that are only required forspecial processes or are optional. It might be possible that some components are not required inyour system landscape.

Web Browser

Java Stack

Web AS Java

ABAP Stack

Web AS ABAP

IPC Engine

ERP System

WebServer

TREX

APO BW

SAP E-Commerce for mySAP ERP

SAP EP

ERP JavaComponents

BW

XI

Firewall

Firewall


August 2008 25

With SAP J2EE the presentation of data in E-Commerce is carried out exclusively on the client layer via theWeb Browser. The HTML data is dynamically generated via Servlets and Java Server Pages (JSPs). A SAPJ2EE Servlet Engine processes the dynamic generation of the HTML data as a server-side process. TheWeb browser is merely responsible for presenting the generated data.

The server-side interaction layer processes user requests and calls the server-side business logic and therespective business applications. The resulting data is then forwarded to the server-side presentation layer,which generates the pages to be displayed by the browser.

Communication between the SAP J2EE platform and the SAP CRM (ERP) system takes place via the SAPJava Connector.

As mentioned above, Java technology is limited to the front-end area, that is, to layout design and theinteraction logic of the Web shop. Business logic (such as order processing with partner determination, textdetermination, and so on) remains in the SAP CRM (ERP) system.

Internet Sales is a full SAP J2EE compliant application but has been released on SAP J2EE Engine only.Other runtime environments have not been tested and are therefore not supported.

Layered ArchitectureThe ISA application architecture consists of the following layers:

Server-side interaction and presentation layer

Business Object layer

Provides business functionality backend Business Objects not aware of backend system details.

Business Logic Service layer (BLS)

Manages the backend depended part of the application.

Additional generic services are used throughout all layers:

Loggon/Tracing

Extended Configuration Management

Used for configuration of the various layers. For example, connection parameters, backend objectimplementation classes, and so on.

UI / Interaction /Custom Tags

BO-Layer

Logging / XC

M

Internet Sales Framework

CRM / R3 Catalog IPC DB

JSPs

Actions

Business Objects

Backend Objects

Internet Sales Application

JCo ...Socket JDBC

...

BLS-LayerBackend Objects

Connection Handling

Figure 5: Layered Architecture


August 2008 26

Interaction and Presentation LayerThis layer is responsible for providing the user interface as well as the navigation within the application. Thislayer represents the view and the controller in a Model-View-Controller programming model.

The user interface is realized using Java Server Page technology.

The Interaction and Presentation Layer is realized using the Struts framework (see [3] Struts documentation:http://jakarta.apache.org/struts/userGuide/index.html).Struts is an open source controller frameworkproviding the Model-View-Controller programming model in a JSP/Servlet environment. It acts as aninterface between the HTTP world and the business logic, which is not aware of any user interface.

JSPs "View"

Interaction Layer"Controller"

Controller(Servlet)

Browser

ActionServlet

ViewJavaServer

Pages

Actions

BusinessObject Layer

"Model"

BO

BO

BO

BO

forw

ard

requestdispatch

response

configupdate

retrieve

Figure 6: Internal processes within the interacton and presentation layer

The above diagram gives an overview of the internal processes within the interaction and presentation layerwhen an HTTP request is sent to the ISA application by a client (usually web browser).

All client HTTP requests are routed through the central controller Servlet ActionSevlet. This Servlet actsas a central dispatcher, routing all incoming requests to appropriate Actions. The dispatching mechanismis configured externally. Actions represent a server-side processing unit and are accessed via a commoninterface. They act as a mediator between the HTTP world and the Business Objects. After calling theappropriate Business Object(s) the process control returns to the ActionServlet. Depending on the returnvalue of the called Action and the external configuration, an appropriate JSP (or other Action) is called, inorder to present the result of the calculation to the user. After mixing the static HTML content with thedynamic content the result is sent back to the client.

Business Object Layer (BO Layer)The Business Object layer hosts Java-based Business Objects used by the Interaction and Presentationlayer. Business Objects provide business functionality via well-defined interfaces in a backend-independentmanner. Business functions are either completely provided by these objects or are located in an EnterpriseInformation System (EIS). An EIS is never accessed directly from the BO layer, because Business Objectsare not aware of any backend-specific details. If they have to communicate with a backend they do so usinga set of generic interfaces provided by corresponding Backend Objects. The implementation of theseinterfaces is backend-specific but the interfaces themselves are not.


August 2008 27

Business Objects are managed by Business Object Managers (BOM). A BOM is used as a central accesspoint for accessing Business Objects. When Actions are accessing a Business Object they have to obtain areference to it from the BOM.

BO Layer

BasketOrder

Item

SessionContext

BusinessObjectManager

<<creates>>

Action

<<creates>>

Figure 7: BO Layer and the Business Object Manager

Business Logic Service Layer (BLS Layer)This layer provides access to business functions located in the various Enterprise Information Systems (EIS)(e.g. CRM, ERP)

Many Business Objects (for example, basket) in the Business Object layer have a corresponding BackendObject in the BLS layer. The functionality of a Backend Object is accessed via a well-defined Java interface(for example, BasketBackend). The implementation of such an interface is backend-dependent (forexample, BasketCRM). A Business Object obtains a reference to a backend object from the Backend ObjectManager (BEM). The BEM takes care of the lifecycle of backend objects and returns their references to theBO layer.

The ISA Framework can handle communication to various backend systems simultaneously. Depending onthe used backend, different backend object implementations have to be instantiated (for example,BasketCRM, or BasketR3). Additionally, the framework takes care that the correct connection data is used.All this is configured in Extended Configuration Management.


August 2008 28

Enterprise Application System

Business Logic Service Layer

Business Object Layer

BasketBO

BackendObject Manager

BEM

Connection Management

XCM

JCo

<< interface >>BasketBackend

BasketCRM BasketR3

CRM R3

BasketR3

R3

<<create>>

<<reference>>

<<communicate>>

<<configure>>

Figure 8: Business Logic Service Layer (BLS Layer)

Presentation Layer DetailsThe Presentation layer is a relatively thin layer in the ISA framework. It consists basically of the SAP J2EEcompliant JSP functionality and some ISA specific custom tags.

Struts tags are not used and are not supposed to be used in customer projects.

JSPsThis chapter covers the server-side aspects of the ISA framework. Besides custom tags there are no ISAspecific extensions which can be discussed here.

Custom ISA TagsSince the ISA tags are not supposed to generate HTML code (to facilitate UI adjustment), the ISA applicationwill not use this group of tags. Non UI tags, however, are provided. These are described in the followingsection.

The functions of all the tags described are packaged as static functions in the classcom.sap.isa.core.util.WebUtil. This means that you can use the functions of the tag library fromany Scriplets.


August 2008 29

MimeURLThe mimeURL is used to completely resolve the location of a Web resource (such as a script, or image).Theapplication context contains the ‘front’ part of the mime location (host: Port possibly directory structure). If noexplicit theme is specified, the system checks the session context to determine whether it contains a theme.(see below to find out how a theme gets into the session context). If this is not the case, the theme of theapplication context is used.Mimes are searched using the following pattern:

ParametersAttribute Description Requiredname Resource name yestheme Theme (default: session context / application context) nolanguage Language no

Table 2: Parameters of the MimeURL

The information on the name of the mime server is declared in the web.xml file (or in XCM in ISA 4.0 SP06or higher):

If no mime server is defined the path to the current web application context is used.

There are two additional possibilities to specify the theme parameter:

As context parameter in web.xml file:

As request parameter:http://localhost:50000/b2b/b2b/init.do?theme=<name of theme e.g. summer>

Example:

<context-param>

<param-name>theme.core.isa.sap.com</param-name>

<param-value>summer<param-value/>

</context-param>

%mimeServer%/%theme%/%language%/%name%

%mimeServer%/%theme%/%language%/%name%

<context-param>

<param-name>mimes.isa.core.sap.com</param-name>

<param-value>http://p54909:1080/isa/mimes</param-value>

</context-param>

<isa:mimeURL name=‘logo.gif’ />


August 2008 30

logo.gif is located in <APPLICATION_HOME>/b2b/mimes/images/logo.gif after deployingapplication. No mimes server was specified. When calling the application using the following URLhttp://host:50000/b2b/b2b/init.do&theme=summer

The mime is searched in the following location

http://host:50000/b2b/summer/b2b/mimes/images/logo.gif

WebappsURLA Webapps URL is used to specify a URL for the current application, and, if cookies are not used, encodethe session ID using the additional jsessionid request parameter. Whenever you have to specify anHREF in your JSP make sure to always use this tag. Only this tag will make sure that session handling stillworks if cookies are turned off.

ParametersAttribute Description RequiredName Significant part of the URL yesSecure Triggers the de-/activation of https protocol in an SSL

environment. Values: ON | OFF

If you work with HTTP/HTTPS switch make sure to define theappropriate ports in the XCM Administration UI (“GeneralApplication Settings” “Customer” “<APPLICATIONNAME>” “<APPLICATION NAME>config”):

http.port.core.isa.sap.com

Needed when switching from HTTPS to HTTP

https.port.core.isa.sap.com

Needed when switching from HTTP to HTTPS

For information about the secure requestparameter refer to chapter General RequestParameters on page 294. This parameter isneeded if you have the following infrastructure:web browser => HTTPS => web server => HTTPJ2EE engine

no

Anchor Appends an anchor to the URL nocompleteUrl Always generates the complete URL Values: ON | OFF no

Table 3: Parameters of the WebappsURL

If you have to add a number of URL parameters you have to use embedded <isa:param> tags. The valuesof the used parameters are coded for HTTP.


August 2008 31

Example:

Never use the following (concatenating request parameters):

translateThis tag is used to represent a language-dependent text. The value of the key and attributes are determinedwith the actual language-dependent text at runtime.

ParametersAttribute Description Requiredkey The key in the resource file yesarg0 First argument noarg1 Second argument noarg2 Third argument noarg3 Fourth argument noarg4 Fifth argument no

Table 4: Parameters of the translate Tag

The language keys are maintained in language-dependend resource files located is WEB-INF\classes\.Placeholders within the keys of type {0...4} are replaced by the content of the arg attributes.

For further information related to this custom tag refer to chapter 'Displaying Text Keys While Running theApplication' on page 290.

Example:

Key in your XLF file (see chapter “Changing language dependand resource keys” for more details):system.initFailed=Initalization of {0} failed

The result at runtime is as follows:Initalization of logging configuration failed

<isa:translate key=‘system.initFailed’ arg0=‘logging configuration’/>

<isa:webappsURL name =‘catalog/logon.do?para1=value1&para2&value2’ anchor=‘Mark1’>

</isa:webappsURL>

<isa:webappsURL name =‘catalog/logon.do’ anchor=‘Mark1’>

<isa:param name=‘para1’ value=‘value1’ />

<isa:param name=‘para2’ value=‘value2’ />

</isa: webappsURL>


August 2008 32

iterateIteration via a collection. The object that contains the elements to iterate has to implementcom.sap.isa.core.Iterable, or has to be one of the standard Java collection classes (List, Set), astandard Java collection iterator, a JDBC ResultSet, or any one dimensional Java language array.

When working with tables in Internet Sales you can use the classes located in thecom.sap.isa.core.util.table package. Objects of typecom.sap.isa.core.util.table.ResultData can be used together with the iterate tag.

ParametersAttribute Description RequiredName Name of object that contains data.

Implements com.sap.isa.core.Iterableyes

Id Scripting variable to create. yesType Type of scripting variable. yesresetCursor Used in scenarios where the iteration is based on

ResultSets value: true|falseno

ignoreNull Determines the behavior if an entry in the iteration set is null(default false; a null-entry will terminate the iteration withoutany other notification).value: true|false

no

Table 5: Parameters of the iterate Tag

Example:

contentTypeSpecifies the character encoding of the JSP based on the session locale. This tag is needed in order todisplay double-byte character encoding correctly.

This tag should always be entered on top of each main JSP. This is not necessary in JSPsincluded by the main JSP.

ParametersAttribute Description Requiredtype Specifies the content type (default text/html) no

Table 6: Parameters of th contentType Tag

<isa:iterate name=‘userObj’ id=‘cursor’ type=‘com.sap.isa.User’ >

<TR><TD> <%= cursor.getName() %> </TD></TR>

</isa:iterate>


August 2008 33

Example:

moduleNameThis tag is useful in the development process. It displays the name of the current JSP if the application wasstarted with the additional showmodulename=true request attribute.

This tag should always be entered on top of each main JSP.For usage of this custom tag refer to chapter 'Displaying Names of JSPs while Running the Application' onpage 289

ParametersAttribute Description RequiredName Name of the JSP yes

Table 7: Parameters ot the moduleName Tag

Example:

If the application is started as follows the name of the JSPs (/b2b/logon.jsp) is shown:

http://host:50000/b2b/b2b/init.do?showmodulename=true

messagePlease refer to chapter ‘Message Framework’ on page 91.

imageAttributeThis tag offers the option of either displaying an image associated with a product in the product catalogwhich is stored on the image server, or displaying a default image, which is considered to be a mime image,and is taken from the path where the other mimes are.

<isa:moduleName name=‘/b2b/logon.jsp’ />

<isa:contentType />


August 2008 34

Parameters:

Attribute Description Required

name The name with which the current item may be retrieved fromthe session

yes

guids A list of comma separated attribute guids. At least one ofthese guids may be associated with an attribute which store aURL for an image

yes

defaultImg In case no guid can be identified as an attribute holding avalue, the image specified as defaultImage is displayed as amime

yes

language Taking account that the defaultImage is a mime component, itmay be language-dependent

no

Table 8: Parameters of the imageAttribute Tag

Example:

Refer to chapter “Extension Demo 6 - Displaying additional Document Type on User Interface in ISA CRM”of the “Development & Extension Guide: E-Commerce 5.0 - Examples and Tutorials”.

Dynamic Field ControlThe dynamic field control offers a general functionality to hide, disable or generate fields or more generallypage elements dynamically on JSP’s.

The functionality allows also customizing the UI with the help of the XCM admin application. The neededinformation will be stored static in XML or the XCM configuration or could be changed dynamic in actions orUI classes.

You can arrange page elements in groups.

The UI elements and groups will be managed within the UI controller, which allows the access to the UIobjects in actions and the UI classes.

On the JSP you could ask the UI class about visibility and changeability of the element(s) or fragments. Allinformation which is necessary is hold within the so called UI Element.

There is a fully integration within the base UI class. You could access the UI elements via UI class in a directway.

Additional the UI Field object could hold all information to generated fields or a group of fields on the JSP.

DefinitionThe UI element and fields will be defined in the uicontrol-config.xml file.


August 2008 35

Example

The structure of the UI element objectField Descriptionname Name of UI element.

allowed With this flag you control, if a value is allowed. Only allowed field couldbe set visible. (Default: true)

hidden With this flag you change the visibility of an object. (Default: false)

Disabled With this flag you could set a flag to read only. (Default: false)

Table 9: The structure of the UI element object

The structure of the UI element group objectField Descriptionname Name of element group.

element Name of the elements included

Table 10: The structure of the UI element group object

Configuration of fields via XCM adminThe framework allows also that the UI elements could be controlled via the XCM admin tool. In the XCMadmin we have only restricted possibilities to control the fields. The customer could change between thefollowing values:

Hidden: the screen element is not visible

Visible: the screen element is visible but could not be changed

Editable: the screen element is visible and could be changed

<UiElement name = "ShipTo"

allowed = “false”

disabled = "false" />

<UiElemet name = "BillTo"

allowed = “true”

hidden = “false”

disabled = "false" />

<UiElementGroup name=”Header”>

<elememt name=”ShipTo”/>

<elememt name=”BillTo”/>

</UiElementGroup>


August 2008 36

To allow the control via XCM admin you have to perform two steps1. Add field to the xcmadmin-config.xml

2. Add the field to the conf-data.xml

Figure 9: Component configuration within XCM

Add field to the xcmadmin-config.xmlTo add a UI element to the xcmadmin-config.xml (normally you have to maintain the isa-xcmadmin-config.xml) you have to add a parameter with the name ui.fields.<name of the element>.

Example<param name="ui.fields.order.deliveryPriority"

type="singleselect"

shorttext="Visibility and availablitity of the field delivery priority">

<longtext>

Visibility and availablitity of the field delivery priority.

Note: This field is not available in the Collabrative Showroom at all!

</longtext>

<constraint>

<allowedvalue value="hidden" shorttext="The screen element is not visible"/>

<allowedvalue value="visible"

shorttext="The screen element is visible but could not be changed"/>

<allowedvalue value="editable" shorttext="The screen element is visible and

could be changed"/>

</constraint>

</param>


August 2008 37

Add field to the conf-data.xmlTo add a UI element to the conf-data.xml you have to add a parameter with the name ui.fields.<name ofthe element> in the ui component in the parameter list with the name ui-fields.

Example

Usage

JSPThe BaseUI class provides access to the UI elements:

isElementVisible return the visibility of an element

isElementEnabled, getElementDisabled return if a element is changeable

getUIGroup return the group with the given name

Example

<component id="ui">

<configs>

<config id="default">

<params id="ui-settings">

<param name="language" value="en"/>

...

</params>

<params id="ui-fields">

<param name="ui.fields.order.deliveryPriority" value="editable"/>

<param name="ui.fields.order.shippingCondition" value="hidden"/>

<param name="ui.fields.order.bomExplosion" value="visible"/>

<param name="ui.fields.order.subitemDetailView" value="hidden"/>

<param name="ui.fields.order.latestDeliveryDate" value="editable"/>

</params>

</config>

</configs>

</component>

<%-- ask UI class --%>

<% /* first example, how to calculate “col span” */

int numCol = ui.getNumberOfVisibleElements (“Group1”);

/* output of the fields */

if (ui.isElementVisible(”itemKey”) { %>

<input type=”Text” id=”key” name=”key” value=”<%=item.getKey()%>”

<%=ui.getElementDisable(”itemKey”) />

<% if (ui.isVisible(”itemName”) { %>

<input type=”Text” id=”name” name=”name” value=”<%=item.getName()%>”

<%=ui.getElementDisable(”itemName”) />

...


August 2008 38

ActionIn action you could access UI elements with the getUIElement method of the UI controller.

Example

Interaction Layer DetailsThe ISA Interaction Layer consists mainly of the Apache Struts Framework. Some Internet-Sales-specificextensions have been added to this framework. This chapter describes how this layer works. For hands-onguidelines are covered in various other chapters of this guide.

OverviewThe Struts based ISA Interaction framework helps you to develop web applications based on Servlets andJava Server Pages. It enables the development of Web applications in which presentation is separate fromthe process flow.

In the MVC (Model View Control) paradigm, Struts represents the controller part through theActionServlet. The view is mapped via the JSP files. Whereas the model is mapped by one or more JavaBeans (Business Object in ISA framework).

E-Commerce 7.0 uses Struts version 1.1 (in older releases Struts 1.0 has been used).

ECO uses only a limited set of Struts functionality (for example, no Struts custom tags are used). It istherefore not planned to upgrade to a current version of the Struts framework.

The Struts framework supports the following:

Dividing an application into logical sub-steps (Actions).

Defining the interaction of these Actions with any existing data container.

(ActionForm; rarely used in ISA)

Assuming the handling of these objects and calling the appropriate follow-on processing, orvisualization, through the provision of an ActionServlet.

Individual components and the interaction between them are described in an XML-basedconfiguration files. Different (independent) parts of the application have on configuration files (newfeature of Struts 1.1).

The following paragraphs introduce the main components of the Struts framework and ISA specificextensions to this framework.

UI ComponentsUI components are realized using Java Server Pages and HTML files. Besides using ISA specific customtags no additional Struts functions are used here. Since this chapter focuses on server-side capabilities thereis nothing further to say than what is common knowledge in the area of JSP. Further details about extensionof the ISA user interface can be found in chapter 'Introduction to Extension Concepts' on page 168.

UIController uiController = UIController.getController(userSessionData);

UIElement uiElement = uiController.getUIElement("catalog.general", userSessionData);

// disable the field for output:

uiElement.setAllowed(true, UIELEMENT.PR_AUTHORITHY);


August 2008 39

Interaction ComponentsIn addition to writing the JSP and HTML files for visualization, a web application developer is responsible forsupplying the individual Actions as well as declaring the flow sequence between the Actions.

ActionsIn the Struts environment, an Action is the smallest possible unit that is run in response to a request.Several Actions can also be combined to process a request; the current Action initiates the forwarding in thiscase.

Therefore, Actions describe the process flow that is required to respond to a related request.

Each Action that is to be created is a specialization of class org.apache.struts.action.Action.

Each Action has to overwrite the ActionForward perform(...) method. This method contains theactual code sequence executed when an Action is called by the ActionServlet. Nevertheless, you willnever derive directly from an Action, but from ISA specific base actions(com.sap.isa.core.BaseAction, or com.sap.isa.isacore.action.IsaCoreBaseAction),orby extending a customer exit from an ISA application action (see chapter 'Accessing the Session Context' onpage 190)

Figure 10: Actions within ECO Framework

Each Action ends by returning an ActionForward instance, and therefore defines what is done next.

The base class of each org.apache.struts.action.Action contains a reference to theActionServlet, which makes it possible to access Web application resources from within any Action.

The declaration of an Action is explained under ActionMapping below.

+perform()

org.apache.struts.action.Action

+doPerform()

com.sap.isa.core.BaseAction

+isaPerform()

com.sap.isa.isacore.action.IsaCoreBaseAction

+doPerform()

com.acme.isa.action.MyAction

+isaPerform()

com.sap.isa.isacore.action.b2b

Struts Framework

ECO Framework

(ISA) Application


August 2008 40

Threads in ActionsIn the ActionServlet context a maximum of one instance of each Action type exists, but can beprocessed simultaneously by multiple threads. This means that you have to pay special attention to threadsafety when implementing an Action. You should not use instance variables or static variables in an Action iftheir content is session dependent.

Design issues to remember when coding Action classes include the following:

The controller servlet creates only one instance of your Action class, and uses it for all requests.Thus, you need to code your Action class so that it operates correctly in a multi-threadedenvironment, just as you must code a servlet's service() method safely.

The most important principle that aids in thread-safe coding is to use only local variables, notinstance variables, in your Action class. Local variables are created on a stack that is assigned(by your JVM) to each request thread, so there is no need to worry about sharing them.

Example: The following action is not thread safe:

Solution: do not use instance variables!

public class myAction extends BaseAction

{

public ActionForward doPerform( ActionMapping mapping, ActionForm form,

HttpServletRequest request, HttpServletResponse response)

throws IOException, ServletException

{

ArrayList array;

// doing something with array

// no problem because array is a local variable and only visible for a single thread

}

}


{

private ArrayList mArray;




{

// doing something with mArray

// problem because mArray is an instance variable and shared among several threads

}

}


August 2008 41

If there is no way to omit an instance variable you should synchronize the access to it:

ActionFormsThe ActionForm is an optional component. It is used to accept user inputs and (optionally) save them. TheActionForm can be used to validate this data.

Each ActionForm specializes the abstract class org.apache.struts.action.ActionForm and definesits own set of data. In the Struts framework, the request parameters of any existing ActionForm are setautomatically. To achieve this, the ActionForm must provide appropriate get and set methods. Thelifetime of an ActionForm usually corresponds to that of the request or, when declared accordingly, that ofthe session. As is the case with the Action, the base class of every ActionForm contains a reference tothe ActionServlet. When validation of the data is requested, the respective ActionForm has to redefinethe ActionError validate(...) method.

The declaration of an ActionForm is described in more detail under ActionFormBean below.

ActionsForms are rarely used in ISA. In most cases data is retrieved from theHttpServletRequest directly, or by using the RequestParser provided byIsaCoreBaseAction (see chapter 'Working with Request Parser' on page 297).

Interaction ConfigurationThe interaction flow in a Struts based application is configured in an XML based configuration filedeclaratively. This chapter discusses which framework components are controlled by this file.


{

private ArrayList mArray;




{

synchronized(mArray)

{

// do something with mArray

} // synchronized(mArray)

} // public ActionForward doPerform

} // class myAction


August 2008 42

ActionServletThe ActionsServlet is the central controller instance in a Struts based application.

The ActionServlet is defined using the usual Servlet declaration:

The config attribute informs the Servlet about the name of the configuration file. You can use the <init-param> technique to specify additional information for configuring the ActionServlet. For further information,see the Struts documentation [3].

In addition, you have to tell the Web application which requests are to be processed by theActionServlet. This is achieved using the usual web.xml declaration:

In the above example an extension mapping is declared that calls the ActionServlet to process every requestwhose URL ends with .do (and runs in the corresponding Web application).

ActionFormBeanThe ActionFormBean is an auxiliary construct that you can declare as follows in the configuration file:

The ActionFormBean forms the assignment between the name, under which an ActionForm isaddressed in the configuration file, and the implementation class.

<form-beans>

<form-bean name=‘logonForm’ type=‘com.sap.isa.struts.LogonForm’ />

<form-bean name=‘catalogForm’ type=‘com.sap.isa.struts.CatalogForm’ />

</form-beans>



<servlet-mapping>

<servlet name>action</servlet name>

<url-pattern>*.do</url-pattern>

</servlet-mapping>



<servlet>

<servlet-name>action</servlet-name>

<servlet-class>org.apache.struts.action.ActionServlet</servlet-class>

<init-param>

<param-name>config</param-name>

<param-value>/WEB-INF/config.xml,/WEB-INF/xcmadmin-config.xml,

/WEB-INF/ccmsims-config.xml,/WEB-INF/ipc-config.xml,

/ipc/customer/config.xml,/WEB-INF/config_lwc_b2b.xml,

/WEB-INF/scheduler-config.xml,/WEB-INF/ipcpricing-config.xml

</param-value>

</init-param>

</servlet>


August 2008 43

ActionMappingEvery Action is embedded in an ActionMapping instance. The ActionMappings are described fully inthe configuration file and follow the pattern of the example below:

Each ActionMapping possesses, at least, the required attributes path and type, and thus assigns theimplementing class to a URL. An Action type can be assigned to different URLs, but only one instance of thisAction is used in the context of the ActionServlet.

The optional attribute unknown with value true can only be declared once. This attribute emphasizes anAction that is used when an Action is called that has not been implemented and/or declared. The defaultvalue of this attribute is false.

The optional attribute name assigns an ActionForm to the current ActionMapping.

It only makes sense to use the optional attribute validate when an ActionForm is used. This attributetells the Struts environment to perform a validation. You can use the optional attribute input to declare aform or the call of another Action that will be displayed or run if the validation fails. Finally, the optionalattribute scope declares the scope of the ActionForm. Possible values for the scope are request orsession.

You can use the optional attributes prefix and suffix to control the automatic mapping of the requestparameters to the ActionForm properties.

ActionForwardAs explained under ‘Action’ above, every Action tells the Struts environment which successive step to call.To do this, the Action tells the ActionServlet how to ‘logically’ continue when it exits the performroutine, a reference to the surrounding ActionMapping instance through a call like:

ActionForward actionForward = (mapping.findForward(‘logon’));

The forward tag in the configuration file declares the actual direction for the execution flow.

The forward tags can be used both in the individual Action tags and globally for all Actions. If global and localnames are identical, the local declaration overrides the global one.

<action-mappings>

<action path = ‘/logon’

type = ‘com.sap.isa.struts.LogonAction’

unknown = ‘false’

name = ‘logonForm’

prefix = ‘isa_’

suffix = ‘_isa’

input = ‘/Logon.jsp’

scope = ‘request’

validate = ‘true’ >

<forward name = ‘success’ path = ‘/showShops.do’ />

<forward name = ‘register’ path = ‘/register.do’ />

...

</action>

</action-mappings>


August 2008 44

Example: Global declaration

The optional attribute redirect controls whether the server will perform the forwarding (value false) orwhether the client browser has to (value true). In the latter case, the client is given a URL and is transferredto it via a request. The default setting is server-side forwarding.

ISA extension of StrutsThis chapter discusses some Internet Sales specific extensions to the struts framework. This will give you abetter understanding about the application as well as possible extensions.

ISA ActionsThe following Actions are used when developing or extending an ISA application.

com.sap.isa.core.InitActionThe InitAction should always be the first Action when starting an application. This action ensures that the ISAframework is initialized correctly when a new session is initiated.

InitAction is a special Action with the following tasks:

Checks if the given XCM configuration is already loaded

o If not, then XCM configuration is loaded.

o BLS layer for the given configuration is initialized (Backend Objects andconnections).

If a session already exists:

o Cleans up the session.

o Notifies the Business Object layer about clean up.

If no session exists yet:

o Initializes the session.

o Sets up/initializes specific objects.

Sets the session locale. This is dependent on the language request parameter, respectively the language entry from the web.xml file.

You can use the request parameter nextAction to pass the logical forward on to the InitAction. Forexample: http://localhost/isa/b2c/init.do performs the initialization and branches to the successforward defined in the InitAction. The URL http://localhost/isa/b2c/init.do?nextAction=logon performs theinitialization and branches to the logon forward (a corresponding forward must be defined in the configurationfile).

<global-forwards>

<forward name=‘logon’ path=‘/logon.jsp’ redirect=‘true’ />

<forward name=‘failure’ path=‘/error.jsp’ />

</global-forwards>

http://localhost/isa/b2c/init.do?nextAction=logon


August 2008 45

com.sap.isa.core.BaseActionAll application-specific ISA Actions specialize the abstract class BaseAction.

BaseAction itself specializes the Struts Action, and contains an abstract method doPerform from thesignature of the Action::perform(...) routine.

All ISA Actions implement the doPerform routine. BaseAction is responsible for checking whether or notthe current session is valid. If it is not, it is forwarded to session_not_valid. If the session is valid, thendoPerform (..) is called.

The perform routine is specified with final in the BaseAction to prevent it from being inadvertentlyoverwritten.

In addition, BaseAction has an auxiliary method:

protected ActionForward isStateValid(ActionMapping mapping, HttpServletRequest request)

This method checks the state of the application and returns a forward to state_not_valid should anyproblems arise.

Example:

General example for using BaseAction.

Process flow:

ActionServlet ---> calls A1Action::perform()

This method is implemented in BaseAction.

A1Action::perform()

Checks the session state.

If the session is not valid, it is forwarded to ‘session_not_valid’. This check and any forwarding aretransparent for the A1Action.

If the state is OK, then doPerform() is called and the action-specific statements are executed.

com.sapmarkets.isa.isacore.action.EComBaseActionThis Base class provides easy access to Meta Business Object Managers.

public class A1Action extends BaseAction {

public ActionForward doPerform(

ActionMapping mapping,

ActionForm form,

HttpServletRequest request,

HttpServletResponse response) throws ... {

// some logic

return mapping.findForward(‘success’);

}

}


August 2008 46

com.sapmarkets.isa.isacore.action.EComExtendedBaseActionThe EComExtendedBaseAction extends the EComBaseAction with a check if the user is logged in.

A UserBase object must exist in one of the used business object manager and the corresponding business

object manager must implement the UserBaseAware interface.

If the user is not logged in the action returns the logical forward Constants.USER_NO_LOGIN(user_no_login)

Example:

This leads to the following error message:

Figure 11: Error Message user_no_login

Extended actions can use the property checkUserIsLoggedIn to change the behavior dynamically e.g.

depending from the application in the initialize method.

/**

* Initialize the action.

* In B2C this action could be used by anonymous user.

*

* @see com.sap.isa.isacore.action.IsaCoreBaseAction#initialize()

*/

public void initialize() {

if (getApplication().equals(CONSTANTS.B2C)) {

this.checkUserIsLoggedIn = false;

}

}

<global-forwards type="org.apache.struts.action.ActionForward">

<forward name="login" path="/b2b/login/login.jsp"/>

<forward name="user_no_login" path="/appbase/error.do"/>

</global-forwards>


August 2008 47

com.sap.isa.isacore.action.IsaCoreBaseActionThis Base class provides easy access to Business Object Managers of the ISA core functionality, the IPC,and the catalog. This action is usually used when developing new functions related to the existing functions,or when extending existing functions. You have to overwrite the isaPerform() method when using thisAction as base action.

com.sap.isa.core.UserSessionDataAll the ISA attributes created in the session scope have to be addressed via an object with typeUserSessionData. An instance of this type is created for each session the first time the InitAction isrun, and this instance is recorded in the session scope. The attributes are recorded under a modified key inthe session scope through this object, and can therefore only be read again via this specific object.

The following code sequence within an Action retrieves a reference to a UserSessionData object:

Changing language dependand resource keysUsing the struts message resource concept, it is very easy to change or add resource keys in a way whichminimizes integration collision when applying patches or new service packs.

A separate project specific xlf file instead of modifying the standard file avoids integration conflictscompletely.

The following changes need to be done to add a project specific resource file to a web application:

1. Create a new xlf file for the customer project in the web applications development component or in ashared web component. Make sure, that you added the file to a source folder (e.g. src/packages orsrc).E.g. projectfile.xlf

2. Check in this file and the .properties file.3. Edit the struts config file of all applications which need to use resources from that xlf file. Add the

filename of the xlf at the first position of the message-resource elements attributeE.g.

Open WEB-INF/config.xml in crm/isa/web/shopadmin and add projectfile to the filename list of theparameter attribute

4. Check in the config file.

<message-resources

parameter ="projectfile,crm~isa~xcmadmin~resources,crm~isa~shopadmin~resources,

crm~tc~user~resources,crm~tc~appbase~resources,crm~isa~accessibility~resources,

crm~tc~core~resources,crm~isa~web~user~isar3,customizing,

crm~isa~xcmadmin~resources"

null="false" factory="com.sap.isa.core.MessageResourcesFactory"/>

// get user session data object

UserSessionData userSessionData =

UserSessionData.getUserSessionData(request.getSession());


August 2008 48

The message-resources will search a certain resource key in the first entry of the filename list first.

Look at the Netweaver IDE’s online help for more details about xlf files.

Additional InformationFor additional information about working with the Interaction Layer refer to chapter 'Introduction to ExtensionConcepts' on page 168.

Secure ProgrammingThis chapter gives some programming guidelines which help you to write robust and secure code.

This chapter contains neither a complete list of possible attacks nor a comprehensive tutorialhow to prevent them. It merely shows the most common attacks and guidelines how to andmake the life of a hacker harder. Most of the protection techniques mentioned in this chapter arenot related to Internet Sales and well coverd in books and on the web.

Input ValidationWeb applications use input from HTTP requests (and occasionally files) to determine how to respond.Attackers can manipulate fields and hidden fields, to try to bypass the applications security mechanisms

GuidelineValidate ALL parameters before using them! It does not matter whether these are fields or hidden fields

Parameters should be validated against a positive value:

Minimum and maximum length

Whether null is allowed

Whether the parameter is required or not

Numeric range

Specific legal values (enumeration)

Specific patterns (regular expressions)

First focus on data in your area which is sensitive from the security point of view. This is usually datashown/manipulated after logging on to the application (which in in B2C rather late)

Identify the actions in your coding which trigger creation of this data Identify the actions in your coding whichare used to show this data. Take a look at this actions: If data is not passed directly to JCo but furtherprocessed in Java you have to check if the data is correct.

The com.sap.isa.core.util.DataValidator class provides some methods for validation (isInRange,idEmail, matchRegexp)

Check what happens if content of data has invalid values (see next table). You will possibly have to dofurther more complex checks depending on your application logic

If all validations are handled by the backend you do not need to do the check in Java again.


August 2008 49

Input FieldSemantics

Incorrect Data / BoundaryData

Example Possible ExpectedResult

Number Field Alphabetical Entries qwert Error Message

Number Field Wrong Number Formats 123.123,123 Error Message

Number Field Numbers out of normalapplication range

4711 if range: 1 to10

Error Message

Date / Time Alphabetical Entries 1234567 Error Message

Date / Time Wrong Date Formats 01/01/04 if dateformat 01.01.2004

Error Message

Date / Time Invalid Dates 31-Feb-2003 Error Message

Search FieldCriterion

* All data


empty string none or all


Quotes "test" or 'test'

String of limitedlength

Very long string Message, eithererror or truncationwarning

String of limitedlength

Empty String valid, possibly

Mandatory Field Blank String Error Message(Based onapplication)

Field represents anid

same as limited lenght

Field is not a textarea, but input field

The character <Enter> (Based onapplication)

The basic handlingof the <Enter>character, speciallywhen encoded, it willtend to not show upat times.

Table 11: Input Validation


August 2008 50

Input FieldSemantics

Incorrect Data / BoundaryData

Example Possible ExpectedResult

General Input Fields Special characters ~!@#$%^&*()=+{}\|[],./?<>"':;<tab><enter>\u

Error Messages(Based onapplication)

Omit somecharacters if thereare cases wheresome characters areallowed, for examplea “,” or a “.” Or a “#”May be requiredunder certaincircumstances ofaddress entry.

XSS attack The following string:

"><script>window.alert('Hello');</script>

No pop up aftersubmiting therequest

Table 12: Input Validation

HTTP Header InformationSimilar to Input Validation (because part of HTTP request). Header information (e.g. mime type, encodingetc.) is read and processed by application

GuidelinePlease omit using HTTP header information

Persistent CookiesPersistent Cookies are stored in an un-encrypted format on the client side. Content of cookies can beaccessed or manipulated by unauthorized persons

GuidelinePlease omit using persitent cookies. If you plan to use persistent cookies in your extension make sure thatno action accepts cookie data without validating it. Cookies are not validated by the back-end. Introduce anadditional level of check in the cookie usage where critical data is involved

Do not store sensitive data in cookies. This type of data includes, but is not limited to:

User specific data

Internal Data

Application critical data


August 2008 51

Cross Site ScriptingCross site scripting (XSS) is a technique, where an attacker tries to insert scripting (JavaScript, ActiveX, etc.)into Web pages in order to steal user data.

Most severe attacks (general):

Disclosure of the user’s session cookie, allowing an attacker to hijack the user’s session and takeover the account

Redirecting the user to some other page or site, and modifying presentation of content

Exploitation of browser vulnerabilities by executing malicious Script

The following figure depicts a possible attack:

Web Server /J2EE Engine

WebServer

Triggers XSS attacke.g. injects malicious script in guestbook

In case ofstoredattack injectedcode is permanentlystoredRequests

infectedpage

Malicious codeis executed

e.g. sessioncookies aresend toattacker'sweb server

1

2

3

4

5

attacker

victim

hijacks session6

Shop

Shop

Figure 12: Possible Attacks

GuidelineThe fundamental issue is that XSS can happen when an unauthorized script is executed on the client sideout of a generated page on a server.

Identify JSPs for potential XSS vulnerabilities.

Within the JSPs, identify the dynamic output, typically marked by <%= %>

To protect against such an attack, encapsulate the outputted string by the methodJspUtil.encodeHtml(String input)


August 2008 52

Error HandlingIf the application encounters an error no data must be shown exposing application/infrastructure details (e.g.exceptions, stack-traces, trace/log messages). On the other hand showing such information can be usefulwhile testing the application. Which information is show in case of error should be controlled in a centralplace by one code base.

SolutionUse the central error page. See chapter Message Framework on Page 91.

User Session/AuthenticationFunctionality for authentication has to be centralized. This makes quality assurance and testing of thisfunctionality easier. Do not develop your own authentication mechanism (e.g. password change etc)

The application has to make sure that the user has a valid session and is authenticated before executingcode. => If this is overlooked, potentially a user could type in the URL and look at data not intended forhim/her.

GuidelineYour action should extend the class EComBaseAction which makes sure that a session is valid and the useris logged on.

Logging/TracingSensitive data is traced in the application coding. An attacker can scan through log/trace files and get thisinformation.

GuidelineDo not trace sensitive data in your application coding neither during normal operation nor in case of an error

Use the nolog_ prefix when naming parameters containing sensitive data e.g. nolog_myAccountNumber

Comments in HTML CodeYou do make HTML comments in JSP.

Any comments in the generated HTML can turn out to be meaningful to hackers.


August 2008 53

GuidelineUse JSP Comments or java comments.

Support of Web Standards (only B2C)

IntroductionThis chapter gives you a guideline how to write web standard compliant application which includes aframeless page structure, browser back and bookmark support.

Frameless JSP pages

IntroductionThe following is the screen layout of the current B2C solution. It is obvious that we have to render one pagewith four screen areas. We call such an arrangement of screen areas a layout. Each layout area includesone active component (like header, basket, product detail etc.).

Figure 13: Layout areas of frameless JSP pages

So a given layout with the used components in the layout areas defines a possible screen design.

The layout structure will be defined declarative in a XML-File managed by XCM.

workareaheader

navigator

minibasket

work area

<%-- print user name --%>

<%

// print user name

out.println(name);

%>


August 2008 54

Example:

Beside the layout information also components will be defined. A component includes either directly a JSP oran action which provide all the data necessary on the JSP and defines then the used page include (see theUIInlude command for details).

With this we got a strict separation between data processing and data displaying.

If you migrate an existing web application it is maybe necessary to separate the data displaying for theprocessing in new action.

The layout will be controlled in the struts configuration file with a set of commands, which can used in theforward tag. These commands allow to set the layout or to set components or component pages.

<UILayouts>

<UILayout name="basketLayout" path=”/appbase/layout/genericLayout.jsp”>

<UIArea name ="header" defaultComponent="header" cssIdName=”header” />

<UIArea name ="workarea" defaultComponent="basket" cssIdName =”workarea” />

<UIArea name ="miniBasket" defaultComponent="miniBasket"

cssIdName=”minibasket” />

</UILayout>

<UILayout name="catalogLayout” path=”/appbase/layout/genericLayout.jsp”>

<UIArea name ="header" defaultComponent="header" cssIdName =”header” />

<UIArea name ="navigator" defaultComponent="catalogcategories"

controlledArea="workarea" cssIdName =”navigator” />

<UIArea name ="workarea" defaultComponent="catalogentry"

cssIdName=”workarea” />


cssIdName=”miniBasket” />

</UILayout>

<UIComponent name="header" page="b2c/header.inc.jsp"/>

<UIComponent name="basketEmpty" page="b2c/basketEmpty.inc.jsp"/>

<UIComponent name="basket" action="b2c/showbasket.do"/>

<UIComponent name="miniBasket" action="b2c/showminibasket.do"/>

<UIComponent name="checkout1" action="b2c/showcheckout1.do"/>

<UIComponent name="confirmation" action="b2c/showconfirmation.do"/>

<UIComponent name="catalogcategories" action="catalog/showcategories.do"/>

<UIComponent name="catalogcategory" action="catalog/showcatalogentry.do"/>

<UIComponent name="catalogentry" action="catalog/showcatalogentry.do"/>

<UIComponent name="productDetail" action="catalog/showproductdetails.do"/>

</UILayouts>


August 2008 55

Example:

At all you have to process five steps to reach a frameless layout:

Defining layout in the layout-config.xml file.

Define your components in the layout-config.xml file

Create your action for your components

Create the jsp includes

Control the layout and the components within the struts config.xml file

Structure of the layout-config.xmlThe layouts are defined in the layout-config.xml file. You find this file under WEB-INF\xcm\sap\modification.You can add or extend the available layout data in the WEB-INF\xcm\sap\modification\layout-config.xml file

The structure of the UILayout tagField DescriptionName Name of the layout.

Path The forward to the corresponding layout jsp.

Title Resource key for title, which is used in the HTML title tag.

titleArea The HTML title can also depend on the component in the here defined area.In this case the title of current component in this area is used.

hotSpot This character is used as a hot spot for the top of the layout.

navigationText Contains a resource key to give a short explanation for the accessibility mode.

hotSpotBottom This character is used as a hot spot for the top of the layout.

navigationTextBottom Contains a resource key to give a short explanation for the accessibility mode.

action Action which is called before layout is displayed and all component action areperformed. The last action which is called must extend thecom.sap.isa.isacore.action.ControlLayoutAction.

BodyAttribute 0..n html attribute tags

Form 0..1 form tag

UIArea 1..n area tags

Table 13: Structure of the UILayer Tag

<action path="/base/start.do"

type="com.sapmarkets.isacore.core.b2c.action.StartAction">

<forward name="success"

path="UILayout:catalogLayout[header=header,workarea=catalogentry]"/>

<forward name="error"

path="UILayout:catalogLayout[header=header,workarea=error]"/>

...

</action>


August 2008 56

The structure of the Form tagThe form object includes a global HTML form which is using for the complete layout.

Field Descriptionname Name of the HTML form.

id Id of the HTML form.

action Action which is used in the HTML form.

method Method attribute of the HTML form tag.

Attribute 0..n html attributes tags

Table 14: Structure of the Form Tag

The structure of the HTML attribute tagThe html attribute object describes a HTML attribute.

Field Descriptionname Name of the HTML tag.

value Value of the HTML tag.

Table 15: Structure of the HTML Attribute Tag

The structure of the UIArea tagThe layout object includes a list with the existing layout area. And each layout area holds the informationover the currently used component

Field Descriptionname Name of the layout area.

defaultComponent UI component which used in this are by default.

controlledArea Allows to define an area which is controlled by this area (e.g. a navigator areacontrols the work area). The value could be used on JSP to provide the“uitarget” parameter.

cssIdName Id used within the CSS file to format the screen area

hotSpot This character is used as a hot spot for this area.

navigationText Contains a resource key to give a short explanation for the accessibility mode.

Table 16: Structure of the UIArea Tag


August 2008 57

The structure of the UIAreaContainer tagA UIAreaContainer allows grouping a sequence of areas into one „div” container. For this container an ownstyle sheet can be defined, to control the appearance and the position.

Field Descriptionname Name of the area container.

cssIdName Id used within the CSS file to format the area container

startArea The name of the first area in the container.

endArea The name of the last area in the container.

Table 17: Structure of the UIAreaContainer Tag

The structure of the UIComponent tagField DescriptionName Name of the component.

page Page to be displayed in this component

action Action to perform before display the page. The page will be set with theUIInclude command.

title Resource key for title, which is used in the HTML title tag.

jsInclude Name of a JSP include, which includes only java script coding.

You have to put your java script coding in parentheses in the includefile.

Could also be set with the UIJsInclude command in the strutsconfiguration file.

jsOnload Name of a Java script function which should be call, while the onloadevent.

Table 18: Structure of the UIComponent Tag

<UILayout name="catalogLayout” path=”/appbase/layout/genericLayout.jsp”>

<UIArea name ="header" defaultComponent="header" cssIdName =”header” />

<UIArea name ="navigator" defaultComponent="catalogcategories"

controlledArea="workarea" cssIdName =”navigator” />

<UIArea name ="miniBasket" defaultComponent="miniBasket" cssIdName=”miniBasket” />

<UIArea name ="workarea" defaultComponent="catalogentry" cssIdName=”workarea” />

<UIAreaContainer name ="toolBar" cssIdName="toolbar"

startArea=”navigator” endArea=”miniBasket” />

</UILayout>


August 2008 58

The structure of the UIConfiguration tagThe UIConfigurationobject includes a global configuration data which is valid for the complete layout.

Field Descriptiontitle Title to be used for all HTML pages, where no other title is defined.

version Version key for bookmark support. This flag allows to avoid problemswith other layout versions. Bookmarks could only be reactivated if theversion of the layout is equal.

altKeyPrefix Prefix which could be used for an alternative alt key generation.

Table 19: Structure of the UIConfiguration Tag

Create your component actions

Keep always in mind that the action should only provide the data so it can displayed within theJSP. The action should never process data.

If necessary split existing actions in two parts if they are including data processing and data providing.

The JSP include will be set in the struts configuration file. Therefore it is possible to reuse the action also inframe application.

Create your JSP includesIf you create new JSP you should separate HTML and JavaScript coding in different includes. (Contact ourJavaScript representative if you maybe can reuse some existing functionality.)

Please use the following name conventions for the includes:

JSP: <jspname>.inc.jsp

JavaScript: <javascriptname>.js.inc.jsp

If the JSP already exists make a copy or rename the file regarding the naming convention. Remove now theHTML header and body tag. Remove also the isa:contentType and the isa:include tag.

You have also to adjust the links which are used in the page.

If you plan to use the UIArea (see Control the layout on Page 59 _Control_the_layoutfor detail) you have toadd the request parameter com.sap.isa.core.Constants.RP_UITARGET.

Use always the constant instead of the value.

Example:<% MyUIClass ui = new MyUIClass() %>

<isa.webappsURL name="catalog/switchToBestseller">

<isa:param name="areaId" value="<%=aeraGuid%>"/>

<isa:param name="<%=Constants.RP_UITARGET%>" value="<%=ui.getUiTarget()%>"/>

</isa.webappsURL>


August 2008 59

Use the method getUiTarget of the BaseUI class to get the name of the current displayed layout area or thename of the controlled area (see The structure of the UIArea tag on Page 56 for details), if it is defined.

Use always this method instead of hard coded values.

Control the layoutThe layout and the components will be controlled with commands in the struts configuration file:

UILayoutThe UILayout command set the layout in the struts configuration file:

There will be the following possibilities:

1. The complete layout could be defined:

UILayout:layoutName[area1=componentX,area2=componentX]

You could pass the name of the layout and also a list with all areas and the names of the components whichshould be used within the area. If an area is not listed the currently used or the default component will beused.

Example:

2. Define only the areas in the current layout:

UILayout:[area1=componentX,area2=componentX]

You could pass also only a list with all areas and the names of the components which should be used withinthe area. If an area is not listed the currently used or the default component will be used.

Example:<action path="/base/start.do"

type="com.sapmarkets.isacore.action.StartApplicationAction">


path="UILayout:[header=header,workarea=catalogentry]"/>


path="UILayout:[header=header,workarea=error]"/>

...

</action>

<action path="/base/start.do"

type="com.sapmarkets.isacore.action.StartApplicationAction">


path="UILayout:catalogLayout[header=header,workarea=catalogentry]"/>


path="UILayout:catalogLayout[header=header,workarea=error]"/>

...

</action>


August 2008 60

3. Only the layout will be defined:

UILayout:layoutName

If you pass the name of the layout with the areas the currently used or the default component will be used.

Example:

4. Update the current layout.

UILayout

In this case no parameter will be passed to the command.

Example:

The UILayout also starts the Layout processing.

Layout ProcessingWhile the layout processing the current layout will be prepared for the display. Therefore the action assignedto the layout and all actions which are assigned to the current valid components will be performed. After thispreparation the page assigned to the layout will be displayed.

UIAreaThe UIArea command set the current layout area in the struts configuration file. The current layout area willbe set automatically within the webappsURL tag. The value is set to the name of the current area or thename of the controlled area if it is defined.

But it is also possible to overrule the context value for the used target area. See the example how to do it.Use always the constant com.sap.isa.core.Constants.CV_UITARGET instead of the value.

<action path="/base/navigate.do"

type="com com.sapmarkets.isa.isacore.action.EComGetForwardAction">

<forward name="catalog"

path="UILayout:catalogLayout"/>

<forward name="basket"

path="UILayout:basketLayout"/>

...

</action>

<action path="/base/updateBasket"

type="com.sapmarkets.isa.core.action.UpdateBasketAction">

<forward name="success" path="UILayout”>

</action>


August 2008 61

Example:

The next example shows how the UIArea command looks like in struts configuration file:

Example:

The UIArea also starts the Layout processing.

UIIncludeIf a component uses the action instead the page the used page must be delivered within in the strutsconfiguration file using the UIInclude command.

Example:

It is not allowed to combine the UILayout, UIArea and the UIInclude commands.

UIJSIncludeIf a component uses the action instead the page the used JavaScript include could be set within in the strutsconfiguration file using the UIJSInclude command.

<action path="/b2c/catalogEntry"

type="com.sapmarkets.isa.isacore.action.marketing.ShowCatalogEntryAction">

<forward name="showcatalogentry"

path="UIInclude:/b2c/marketing/catalogentry.inc.jsp"/>

</action>

<action path="/base/switchToArea.do"

type="com.sapmarkets.isacore.core.b2c.action.SetCatalogArea">

<forward name="success" path="UIArea:catalogcategories"/>

<forward name="error" path="UIArea:error"/>

...

</action>

<% String workarea = " workarea "; %>

<isa.webappsURL name="catalog/switchToBestseller">


<isa:param name="<%=Constants.CV_UITARGET%>"

value="<%=ui.getUiAreaKey(workarea)%>"

contextValue=”true”/>

</isa.webappsURL>


August 2008 62

Example:

After the UIJSInclude command must follow always a UIInclude command.

Dynamic change of HTML titleThere is the possibility to change the title of the HTML page depending of the content of a defined layoutarea. This can be done with the titleArea attribute of the UILayout object. If this attribute is set, the title istaken for the current component in this area. If this title is empty the layout title is used.

Example:

If the component basket is displayed the title b2c.title.basket is used, for confirmation b2c.title.confirmationand if the component is basketEmpty the default title b2c.title.general of the layout object is used.

In addition it is possible to define up to 4 arguments which could be used in the title with the attributestitleArg0, titleArg1, titleArg2 and titleArg3. This attribute could be used in the layout as in the component tag.

<UILayouts>

<UILayout name="basketLayout" path="/appbase/layout/genericLayout.jsp"

titleArea="workarea" title="b2c.title.general">

<UIArea name ="header" defaultComponent="header" cssIdName="header" />

<UIArea name ="workarea" defaultComponent="basket" cssIdName ="workarea" />


cssIdName="minibasket" />

</UILayout>

<Component name="basketEmpty" page="b2c/basketEmpty.inc.jsp" />

<Component name="basket" action="b2c/showbasket.do"

title="b2c.title.basket"/>

<Component name="checkout1" action="b2c/showcheckout1.do"

title="b2c.title.checkout"/>

<Component name="confirmation" action="b2c/showconfirmation.do"

title="b2c.title. confirmation"/>

</UILayouts>

<action path="/b2c/catalogEntry"

type="com.sapmarkets.isa.isacore.action.marketing.ShowCatalogEntryAction">

<forward name="showcatalogentry"

path="UIJSInclude:/b2c/marketing/catalogentry.js.inc.jsp;

UIInclude:/b2c/marketing/catalogentry.inc.jsp "/>

</action>


August 2008 63

Example:

The attributes describes the name of request attributes. Therefore the attributes must be filledwith reasonable values in actions.

Dynamic changes of the layoutUnder some circumstances it is reasonable to change the layout dynamically. It these cases one can definea controller action for the layout. This action must extend the com.sap.isa.isacor.action.ControlLayoutActionclass. (At least the last action which is called in an action chain should extend this class).

Layout changes are valid only for the current request.

Example:

<Component name="checkout1" action="b2c/showcheckout1.do"

title="b2c.title.checkout" titleArg0=”order_Number”/>

With

b2c.title.checkout=Checkout order with number:{0}

<UILayouts>

<UILayout name="basketLayout" path="/appbase/layout/genericLayout.jsp"

action="/b2c/ajustBasketLayout.do">

<UIArea name ="header" defaultComponent="header" cssIdName="header" />

<UIArea name ="workarea" defaultComponent="basket" cssIdName ="workarea" />


cssIdName="minibasket" />

</UILayout>

</UILayouts>

request.setAttribute(“order_Number”, order.getDocNumber());


August 2008 64

Support of navigation issuesThe layout and the components will be controlled with commands in the struts configuration file

Sometimes the transition from one layout to the next will be interrupted e.g. for a login request or for thedisplay of an error message. For this case we will provide an easy mechanism to handle such issues.

The idea is to introduce a stack of layouts and logical forwards. The developer could now push the currentlayout to the stack (e.g. the catalog layout) and then switch to the login layout to perform the layout. After thatthe developer pops the needed layout from the stack.

UIStoreLayout & UIStoreForwardWith the UIStoreLayout command the current layout will be stored for later use. Beyond the UIStoreLayoutcommand supports also the full syntax of the UILayout. This allows to store an arbitrary layout.

Unfortunately there is big restriction. The context values used in this layout will be lost!

Use this command only with layouts which doesn’t use context values (see chapter Usage ofcontext values on page 68 for details).

The UIStoreForward stores a given the logical forward (e.g. profile).

Following an example, which demonstrates how to handle the login before the marketing profile will bedisplayed:

Example:

public class AdjustBasketAction extends ControlLayoutAction {

public void controlLayout(

ActionMapping mapping,

ActionForm form,

HttpServletRequest request,

HttpServletResponse response,

UserSessionData userSessionData,

MetaBusinessObjectManager mbom,

UILayout layout)

throws IOException, ServletException, CommunicationException

{

// hide header

layout.getUiArea("header").setHidden(true);

}

}

<action path="/b2c/gotoProfile"

type="com.sapmarkets.isa.isacore.action.b2c.CheckLoginAction">

<forward name="login"

Path="UIStoreLayout;UIStoreForward:profile;UILayout:loginLayout"/>

<forward name="success" path="UIArea:marketingProfile"/>

</action>


August 2008 65

The UIStoreLayout and UIStoreForward can’t be the last command. There must always followthe UILayout, UIArea, UIInclude or the UIAction command.

UIStoreActionWith the UIStoreAcrtion command the current processed or a given action will be stored for later use.Beyond the UIStoreAction stores the current context.

But there is a restriction. The information is not stored stateless and therefore the information islost if you set a bookmark. Therefore you have to provide the fallback action “default” if thecontext is lost.

Following an example, which demonstrates how to handle the login before the marketing profile will bedisplayed:

Example:

Example for the fallback (see UIGetLayout & UIGetForward on Page 66)

The UIStoreAction can’t be the last command. There must always follow the UILayout, UIArea,UIInclude or the UIAction command.

UIActionWith the UIAction command you could combine a normal path value with the UI commands. This is veryuseful in combination with the UIStoreLayout and UIStoreForward commands.

<action path="/core/forwardToAction"

type="com.sap.isa.isacore.action.EComGetForwardAction">

<forward name="default"

path="UILayout:catalogLayout[workarea=catalogentry]" />

</action>

<action path="/b2c/showLogin"

type="com.sapmarkets.isa.isacore.action.b2c.DisplayLoginAction">

<forward name="succes"

path="UIStoreAction:/b2c/display.do;UILayout:loginLayout"/>

</action>


August 2008 66

Example:

UIGetLayout & UIGetForwardThe UIGetLayout take the layout which is stored with the UIStoreLayout and use this as current layout.

The UIGetForward command gets the logical “forward” and passes it to the “/base/getCoreForward” action.

Beyond the command restore the action stored with UIStoreAction

In our example this calls the marketing profile action again:

Example:

The UIGetForward commands must be the last command in the line.

<action path="/b2c/gotoProfile"

type="com.sapmarkets.isa.isacore.action.b2c.CheckLoginAction">

<forward name="login"

path="UIStoreLayout;UIStoreForward:profile;UIAction:/b2c/secureLogin.do"/>

<forward name="success" path="UIArea:marketingProfile"/>

</action>

<action path="/b2c/login" name="loginForm"

type="com.sapmarkets.isa.isacore.action.b2c.LoginAction">

<forward name="success" path="UIGetLayout;UIGetForward">

</action>



<action path="/base/getCoreForward"

type="com.sapmarkets.isa.isacore.action.EComGetForwardAction">

<forward name="profile" path="/b2c/gotoProfile.do">

</action>


August 2008 67

Summary of the UI Commands

Global Commands

Command Position in the Path Start Layout Output Redirectallowed

UILayout Last command yes no

UILayout:name Everywhere Yes, if last command no

UIArea Everywhere yes, if last command no

UIAction Always last command. No yes

UIStoreForward Not the last command No -

UIStoreLayout Not the last command No -

UIGetLayout Not the last command No -

UIGetForward Always the last command No yes

Table 20: Global UI Commands

Commands while Layout processingCommand Position in the Path Continued Layout Output Redirect

allowed

UIInclude Last command yes no

UIJSInclude Not the last command No no

Table 21: Commands while Layout Processing

Browser Back SupportTypically problems with the browser back button occur because the context on the client differs from thecontext on the application server after the customer has pressed the back button one or several times.Therefore we have to ensure that the contexts are in “sync” when the request will be processed.

First we have to distinguish between state full objects (e.g. the basket) and stateless objects (e.g. catalog).The user does not expect that his basket will be changed while he navigates with browser back and forwardbutton. But he expects that the catalog hold no information about his state (That means if the user pressesthe refresh button he expect to see the same content which was already displayed on the page).

For the stateless approach it is necessary to hold all information on the page, which is necessary to recoverthe state of the page. Our Browser Back Support provides with the Context Values such a framework, whichallows storing context information within the request context. The context values must provide all informationwhich is necessary to recover the page entirely.

The framework allows putting and getting context values to/from the request context. You must not take careof storing the context values in the request and getting the context values from the request.

Never provide context information to JSP’s without the framework.


August 2008 68

Usage of context valuesIt is possible to define a multi context value. In this case it is possible to store a list of values under the samename.

Therefore you have to register your context values first (see chapter ‘Registration of context values’ below).

Try to use as less obligatory context values as possible, because the size restriction of the HTTPheader.

There is no support of optional context values in the 7.0 release.

Registration of context valuesThe registration should be done in the static method initContextValues of some central action classes:

Usage Action

Used in all EcommerceApplications

com.sap.isa.core.InitAction

Used in B2B and B2C com.sap.isa.isacore.action.IsaCoreInitAction

Only used in B2C com.sap.isa.isacore.action.b2c.InitB2CAction

Only used in B2B com.sap.isa.isacore.action.b2b.InitB2BAction

Table 22: Registration of Context Values

Example

The constants for the context value names should be defined in one central file in the surroundingdevelopment component.

All classes which should be used in an application must be defined in int-config.xml. This allows to controlwhich Context value should be used in which application.

/**

* Initialize Context values. <br>

*/

Static public initContextValues () {

GlobalContextManager.registerValue(Constants.CV_LAYOUT_NAME, true, false);

GlobalContextManager.registerValue(Constants.CV_LAYOUT_STACK, true, true);

GlobalContextManager.registerValue(Constants.CV_FORWARD_STACK, true, true);

}


August 2008 69

Example

Use always the constants instead of the value name directly.The constants should have always the prefix CV_.

Getting and setting context valuesThe BaseAction will have methods which allow the setting, changing and getting context values (see JavaDoc for details).

Name SingleValue

MultiValue

Description

getContextValue X Return the context value from the already existing context.

setContextValue X X Set the given value for the context value.

changeContextValue X Change the context value in already existing context.

getContextValues X Return the list of context values from the already existingcontext.

resetContextValue X Delete all existent multiple values.

addContextValue X Add a value to the context values.

Table 23: Overview Context Values

There will strictly distinguish between the old and the new context. Therefore all actions, which prepare thedisplay of data, have to provide its context value again to the context.

Example

This ensures that only needed information is stored within the context.

With the changeContext method it is also possible to modify the existing context. The value will alsoautomatically transfer to the new context to allow a redirect between processing and display. The methodallows changing exiting values in one action (data processing) and use them while the data displaying.



<initialization className="com.sap.isa.core.ui.context.ContextInitHandler">

<param name="1" value="com.sap.isa.core.InitAction"/>

<param name="2" value="com.sap.isa.catalog.actions.ISAEntryAction"/>

<param name="3" value="com.sap.isa.isacore.action.b2c.InitB2CAction"/>

</initialization>

String productKey = getContextValue (Constants.CV_PRODUCT_KEY);

…

setContextValue(Constants.CT_PRODUCT_KEY, productKey);


August 2008 70

Example: Action 1: getting new product id to display

Here some examples how to introduce redirects:

Example: Action 2: displaying the current product

Overruling context values in an urlIt is also possible to overwrite obligatory context value in a URL generate with the webappsURL tag.Therefore one defines a param tag with the name of the context value and set the contextValue attribute totrue. This is by default set to false.

In the following example the catalogue area will be changed only by

Example:<% String workarea = " workarea "; %>

<isa.webappsURL name="b2c/display.do">


<isa:param name="<%=Constants.CV_UITARGET%>"

value="<%=ui.getUiAreaKey(workarea)%>"

contextValue=”true”/>

</isa.webappsURL>

<action path=”/b2c/display” forward=”UILayout” />

<action path="/b2c/addtobasket"

type="com.sap.isa.isacore.action.order.AddToBasketAction">

<forward name="success" path="/b2c/display.do" redirect=”true”/>

</action>

String productKey = getContextValue ("CV_PRODUCT_KEY");

setContextValue("CV_PRODUCT_KEY", productKey);

String productKey = (String)request.getParameter("PRODUCT_KEY");

changeContextValue(Constants.CV_PRODUCT_KEY, productKey);


August 2008 71

Rules for UI componentsIf you create a new component take care of the following rules

Set only context values in your component you really need.

Implement a fallback, if the context values could not be found. (E.g. display a message usingMessageDisplayer object.)

Set context values only in component actions.

Redirect after form submitTo avoid strange effects if the user presses the F5 button to refresh the page, it is useful to introduce aredirect after some action. E.g. the user adds a product to the basket. He doesn’t expect to add the productagain if he presses the F5 button. He rather expected that the current page will be refreshed.

If you use the post method you have to introduce a redirect in any case.

To perform a redirect the redirect flag in the struts forward have to be set to true.

Be aware that all request parameter will be lost if you perform a redirect.In contradiction the context values will be available after redirect because they are encoded inthe redirected URL.

Example: Here some examples how to introduce redirects:

<action path="/b2c/savePersonalDetails"

type="com.sap.isa.isacore.action.b2c.SavePersonalDetailsAction">


path="UIArea:addressConfirmation;UIAction:/b2c/display"

redirect="true"/>

</action>

<!—last action called after the succesful login -->

<action path="/b2c/addBusinessPartner"

type="com.sap.isa.isacore.action.order.AddBusinessPartnerToBasketAction">

<forward name="main_inner" path="UIGetForward" redirect=”true”/>

</action>

<action path=”/b2c/display” forward=”UILayout” />

<action path="/b2c/addtobasket"

type="com.sap.isa.isacore.action.order.AddToBasketAction">

<forward name="success" path="/b2c/display.do" redirect=”true”/>

</action>


August 2008 72

Redirect could be used if the last UI command is UIAction or UIGetForward.

Redirect could not be used if the last UI command is UIArea or UILayout.

General GuidelinesDon’t offer “back buttons”. If you offer back buttons use browser back to enable the functionality.

Bookmark SupportWe offer additionally a support for bookmarks. The main problem is that we have to re invoke the applicationbecause normally the session is lost when the bookmark is chosen.

Process Action

Bookmark

Request

Store context and re invokeapplication

Session isinvalid

Figure 14: Bookmark Support

We introduce the new ReInvoke command. With this command you could re invoke the session and definethe action which should be called after the application is re invoked. The command store also the availablecontext and request parameter and provide this information later on to the re invoked action.


August 2008 73

Example:

You can call the ReInvoke command also without defining an action. The action where the command iscalled will be used. For the example above one could use also:

Example:

Also in this case the /catalog/getProduct.do action is called.

Prerequisite: Because all session information is lost for invalid session the application must bestarted without any startup parameter. Therefore move all necessary parameter to XCM.

For example the shop id could now maintain in XCM admin:

Figure 15: XCM admin - defaultShopId

<action path="/catalog/getProduct.do"

type="com.sap.isa.catalog.action.GetProductAction" >

<forward name="success" path="UILayout"/>

<forward name="session_not_valid" path="ReInvoke "/>

</action>

<action path="/catalog/getProduct.do"

type="com.sap.isa.catalog.action.GetProductAction" >

<forward name="success" path="UILayout"/>

<forward name="session_not_valid" path="ReInvoke:/catalog/getProduct.do"/>

</action>


August 2008 74

Prerequisite: The application must define the re-entry point. This will be the done by calling aaction which extends the StartApplicationBaseAction..This action will forward automatically tothe action which is defined by the ReInvoke command.

In detail the re invoke of an invalid session looks like:

Init Applicatione.g. /b2c/init.do

Store context requestparameter and the action

Start Application Actione.g. /b2c/start.do

Restore Context andparameter

Action stored for Reinvoke

Figure 16: Prozess of re invoke of an invalid session

For re invoke the session the init.do is called to restart the application. The StartApplicationBaseActionshould be called after the application is initialized (e.g. shop is read, catalog is read etc). In B2C this is the/b2c/start.do action, which is called every time not only while re invoke. But while re invoke this actionredirect to the action which should be re invoked.

Business Object Layer Details

Design ConsiderationsThe Internet Sales Framework is designed to be used with any backend system. This is achieved by dividingthe business logic into a backend-independent (Business Objects) and a backend-dependent part (BackendObjects). The Business Objects (business logic objects or BOs) use a generic set of interfaces tocommunicate with the backend. Therefore, their purpose is to represent the backend-independent part of thebusiness logic.

In order to be able to maintain the application, it is important that the procedure for saving objects that livelonger than a request is as robust and transparent as possible.


August 2008 75

The standard concept for Servlets and JSPs entails storing this data in the session context. Thedisadvantage of this procedure is that the data is stored as name value pairs in a flat hierarchy (see alsojavax.servlet.http.HttpSession). This can quickly lead to naming conflicts (data in the session isoverwritten by mistake) and confusion.

BO Layer

Item

SessionContext

BusinessObjectManager

<<creates>>

Action

<<creates>>

Order Order

Catalog BOM

Meta BOM

other BOMs

<<interface>>OrderBackend

Figure 17: BO Layer Structure

To avoid these problems, all of the business logic objects are managed by a set of central objects, calledBusiness Object Managers (BOMs). There is one of these managers for each sub-project of Internet Sales.(for example, Catalog, IPC, ISA core). Each BOM has to implement the BOManager interface and to extendthe DefaultBusinessObjectManager.

To allow the centralized creation and management of the Business Object Managers, a special object,MetaBusinessObjectManager (MBOM), is used. This object acts as a factory for the BOMs and thecreated objects types can be configured using the xml file bom-config.xml. Therefore, you are able to addnew Business Object Managers to the application, or to replace an existing one with a specialized sub-classwritten by you, without changing any source code.

As already mentioned, the BOM functions as a data capsule and an administration instance for the BusinessObjects, and is exclusively used from Actions.

The MetaBusinessObjectManager is the only object that exists directly in the session context. Aconstant, SessionConst.MBOM_MANAGER, can be used to retrieve the object from the session, or aconvenience method, getMBOM(), of the UserSessionData object can also be used. To make the processeasier, you can call the getBOM() method of the MBOM directly on the UserSessionData object, whichpasses the call through to the MBOM.

The BusinessObjectManager functions as a container and factory for BOs. Only the top level BOs arestored and managed here, that is, the business objects at the top of the hierarchy. An Order, for example,consists of various components (items). Here, the Order is the top-level object and manages the componentscontained within it.


August 2008 76

Additional InformationFor information on how to work with Business Objects and Business Object Managers, see chapter'Introduction to Extension Concepts' on page 168.


August 2008 77

Business Logic Service Layer Details

Design ConsiderationsThe Backend Object Service (BLS) Layer has two main responsibilities. Firstly to manage backend-dependent Backend Objects and, secondly, to provide these Backend Objects with a unified connectionhandling to the Enterprise Application System.

«<<interface>>»BasketBackend

+myOperation()

BasketCRM

+myOperation()

BackendBusinessObjectBaseSAP

+getDefaultJCoConnection()()+initBackendObject()+destroyBackendObject()+getContext()

User definedInterface to Backend

System

Base class providingBackend Object withaccess to framework

functionality

Figure 18: Design of BLS

Business Objects (for example, Basket) communicate with the Backend System through Backend Objects(for example, BasketCRM) and through interfaces (for example, BasketBackend). This interface does notdisclose any implementation details about the used backend.

There can be multiple implementations for a Backend Object interface, for example, BasketCRM andBasketR3. The BLS framework ensures that the correct Backend Objects are instantiated and that thecorrect connections are established. All this is configured in Extended Configuration Management (XCM).

The BLS framework can run multiple configurations simultaneously, for example, to SAPCRM and SAP ERPsystem.

Backend ObjectsEach Backend Object implements the BackendBusinessObject interface. This interface defines somegeneric methods for connection handling and Backend Object lifecycle. It is usually extended by a morespecialized backend specific interface (e.g. BackendBusinessObjectSAP). This interface provides typesafe access to backend-specific connections.


August 2008 78

Depending on the backend type different base classes are used for the backend objects:

Backend type Connection type Base class

CRM; ERP RFC based communication using SAPJava Connector (JCo)

com.sap.isa.core.eai.sp.jco.BackendBusinessObjectBaseSAP

IPC Socket based communication com.sap.isa.core.eai.sp.ipc.BackendBusinessObjectIPCBase

Database JDBC based communication com.sap.isa.core.eai.sp.jdbc.BackendBusinessObjectJDBCBase

Table 24: Connection Types to Backend

Lifecycle of Backend ObjectBackend is always instantiated by the framework, never by the application programmer. The Backend ObjectManager (BEM) takes care of the lifecycle of the object.

Backend ObjectReady

Backend Objectdestroyed

Backend Objectdoes not exist

initBackendObject() destroyBackendObject()

handle request fromBusiness Object

Figure 19: Lifecycle of Backend Object

When the Backend Object is created by the Backend Object Manager, the initBackendObject() methodis called. Before the Backend Object is destroyed, the destroyBackendObject() method is called andgives the Backend Object the opportunity to perform some cleanup.

Initialization of the Backend ObjectThe initBackendObject method is used to perform one-time initialization. It has the following signature:

Each Backend Object must implement the initBackendObject() method. TheBackendObjectManager calls this method after creating the Backend Object.

The properties object holds properties associated with the Backend Object in the backendobject-config.xml configuration file.

public void initBackendObject(Properties props, BackendBusinessObjectParams params)

throws BackendException;


August 2008 79

There are two types of properties passed to the Backend Object when the initBackendObject() methodis called:

Backend Object properties defined in the eai-config.xml file are passed using the props object.

The BackendBusinessObjectParams are runtime parameters passed by the object that hasrequested a new Backend Object by calling the BackendBusinessObjectcreateBackendBusinessObject(String beBOType, BackendBusinessObjectParams params) method.When a Backend Object is created using the BackendBusinessObjectcreateBackendBusinessObject(String beBOType) method, then the value of theBackendBusinessObjectParams is nullThe params object can be an arbitrary container passed by the Business Object when the BackendObject is created. The BackendBusinessObjectParams interface is just a tag interface without anymethods.

For information about how backend objects are registered in the ISA framework refer to chapter'Configuration of BLS Layer' on page 87 and chapter 'Changes in backendobject-config.xml' on page 275.

Destruction of Backend ObjectsBefore the Backend Object Manager becomes invalidated (for example: When a client session is removedfrom memory), it notifies all of its Backend Objects by calling the destroyBackendObject() method. Thismethod can be used to clean up resources allocated by the Backend Object.

Backend ContextOne design goal of the BLS layer is to prevent backend objects from communicating directly with each other.Only this ensures a clear separation of the backend objects and encapsulation of data and businessfunctions. Nevertheless, sometimes there are cases where data should be made available to all backendobjects. In this case the Backend Context can be used.

com.sapmarkets.isa.core.eai.BackendContext

+setAttribute(name : String, value : Object)+getAttribute(name : String) : Object

The backend context is obtained as follows (this is provided by the base class of the BackendObject):

BackendContext getContext()

<businessObject type=‘BASKET’ name=‘BasketSAP’

className=‘com.sap.isa.backend.crm.basketCRM’

connectionFactoryName=‘JCO’

defaultConnectionName=‘CRMStateless’>

<params>

<param name=‘init’ value=‘value’/>

</params>

<businessObject/>


August 2008 80

BackendObjectManagerAll Backend Objects are created and destroyed by a Backend Object Manager. A Backend Object Manageris accessed using the BackendObjectManager interface. This interface provides methods for creatingBackend Objects: createBackendBusinessObject()

com.sapmarkets.isa.core.eai.BackendObjectManager

+createBackendBusinessObject()

You only get in touch with a BEM when writing your own BOMs, Business Objects, and Backend Objects.You do not create an instance of the BEM manually; this is done by the MetaBusinessObjectManager ofthe ISA framework. If your BOM implements the BackendAware interface, it automatically passes areference. Implementing the BackendAware interface indicates that a BOM manages Business Objectswhich have corresponding Backend Objects in the BLS layer.

For information about how to write BOMs, Business Objects, and Backend Objects, please see chapter'Introduction to Extension Concepts' on page 168.

Connection Management

Design ConsiderationsBackend Objects communicate with the backend system using backend-specific connectors. The BLS layermakes sure that the connection management is fully transparent to the backend objects:

Backend Objects are not aware of any connection configuration

o Connection parameter configuration takes place in XCM

Backend Objects do not have to cope with connection creation and cleanup

Backend Objects do not have to care about connection behavior. For example, whether JCoconnections are pooled or not

As you can see, there is not much you have to do for connection handling, apart from configuring theconnection parameters in XCM and using connections within backend objects.

The BLS connection management takes care of the following connection types:

RFC based connectivity using SAP Java Connector

JDBC based connectivity to a database

Working with JCo Based Connectivity

Within the BLS layer you never work directly on JCo connections (JCO.Client). Instead youwork on connections of the typ com.sap.isa.core.eai.sp.jco.JCoConnection. Onlythis ensures that the BLS layer can take care of connection handling/cleanup correctly.


August 2008 81

JCoConnection

+getJCoFunction(funcName : String)+execute(function : JCO.Function)+isValid() : boolean

BackendBusinessObjectBaseSAP

+getDefaultJCoConnection()+getModDefaultJCoConnection(conProps : Properties)+getConnectionFactory() : ConnectionFactory

0..n

ConnectionFactory

+getConnection()

1..1

0..n

MyBackendObject

Figure 20: Class Diagramm about use of JCo Connection

A reference to the JCoConnection object is obtained from the BackendObject of typecom.sap.isa.core.eai.sp.jco.BackendBusinessObjectSAP, which is the base class for allBackend Objects using JCo connectivity.

Connection TypesThere are two connection types used in the BLS layer when executing the JCo function:

Stateless connection

o These connections are pooled. That is after each function execution the connection isreturned to the pool (pools can be monitored in the ISA administation; see chapter ‘JavaConnector Pools' on page 299.)

o No context is kept on the ABAP system between the function calls

o Implementation class for this connection-type is:com.sap.isa.core.eai.sp.jco.JCoConnectionStateless

Stateful connections

o Each session has its own stateful connection. This connection is kept open for the durationof the user session

o Context is kept on the ABAP system between function calls

o Implementation class for this connection-type is:com.sap.isa.core.eai.sp.jco.JCoConnectionStateful

For further information why this is needed, please see

ABAP debugging: chapter 'ABAP Debugging' on page 166

Assigning connections to Backend Objects: chapter '


August 2008 82

Configuring Backend Objects' on page 89.


August 2008 83

Working with JCoConnectionsWhen a remote callable function module (RFC) in the SAP system has to be called, you always perform thefollowing three steps:

1. Obtain a connection (a reference of JCoConnection)

2. Do some work (for example, execute some function modules)

3. Close the connection by calling JCoConnection.close(). This should be located in the methodfinally {}

Example:

The following units provide information on the different ways of obtaining a JCoConnection.

Getting Default Connection Associated with a Backend Object

This is the most common case. Simply call:

There must be a default connection associated with the Backend Object in backendobject-config.xmlfile. For information how to register backend object refer to chapter '

JCoConnection con = null;

try {

// Step1: Obtain a connection

con = getDefaultJCoConnection();

// Step2: Do some work (e.g. execute function)

JCO.Function func = con.getJCoFunction(‘RFC_PING’);

con.execute(func);

} catch (BackendException ex) {

//... error handling of BLS layer

} catch (JCO.AbapException) {

// handling ABAP exceptions (attention!! this is a runtime exception)

} finally {

JCoConnection con = getDefaultJCoConnection();


August 2008 84

Configuring Backend Objects' on page 89.

Getting a Modified ConnectionIf you need a connection which is based on the configuration of the default connection but with differentconnection parameters, you can call the getModDefaultJCoConnection(Properties) method. Youuse a set of properties to overwrite/extend the connection definition properties used for the defaultconnection.


August 2008 85

Example:

Constants which can be used to set JCo properties are located in classcom.sap.isa.core.eai.sp.jco.JCoManagedConnectionFactory

The connection you get is not the default connection associated with the Backend Object. It issimply an additional connection based on the configuration of the default connection.

Getting a New Connection from a ConnectionFactory object

Using a connection factory you can get any connection that can be served by the BLS layer. To get aconnection based on a predefined and complete connection definition call:

Example:

You can also extend/overwrite connection definitions by passing a set of properties to the connection factory:

Working with JCO.FunctionsAfter getting a JCoConnection you use it to get/execute JCO.Functions. How this is done is described inthis chapter.

Creating JCO.FunctionsA JCO.Function is used to execute remote callable function modules in an SAP system. You obtain areference to a JCO.Function object by calling the following method:

Properties conProps = new Properties();

conProps.setProperty(‘user’, webUser);

conProps.setProperty(‘passwd’, webUserPassword);

JCoConnection mJCoCon =

(JCoConnection)getConnectionFactory().getConnection(‘JCO’, ‘CRMStateless’, conProps);

JCoConnection mJCoCon = (JCoConnection)getConnectionFactory()

// get connection from JCO connection factory

getConnection(‘JCO’, ‘CRMStateless’);

Properties props = new Properties();

props.setProperty(JCoManagedConnectionFactory.JCO_LANG, ‘de’);

JCoConnection = getModDefaultJCoConnection(props);

JCO.Function JCoConnection .getJCoFunction(String)


August 2008 86

The BLS layer serves the JCO.Function from a centralized JCO repository. This ensures the bestperformance, since each Backend Object does not have to create its own repository. Additionally, there isonly one repository per backend system.

Never create an own JCO.Repository. Let the BLS layer do it for you

Example:

Executing JCo FunctionsJCo functions are executed using the following method:

After executing the function(s) do not forget to close the connection by calling JCoConnection.close().

Take care of execptions when executing JCo functions: The signature of the execute method isas follows:execute(JCO.Function func) throws BackendException;

Besides the BackendException, a JCO.AbapException runtime (!) exception can be thrown ifthe calling function module throws an ABAP exception.Therefore, please do not forget to catch the BackendException and JCO.AbapException if youcall ABAP function modules and you expect that the Function Module throws an ABAPexceptions.

Example:

JCO.Function myFunc;


myFunc = con.getJCoFunction(‘SAP_BASKET’);

try {

con.execute(myFunc);

} catch (BackendException bex) {

// system error

} catch (JCO.AbapException abapEx) {

// application error in SAP system

} finally {

con.close();

}

JCO.Function myFunc;


myFunc = con.getJCoFunction(‘SAP_BASKET’);

JCoConnection.execute(JCO.Function);


August 2008 87

Please do not execute the JCO.Function directly on a JCO.Client. Always use JCoConnection.Only this ensures that the application can fully utilize services provided by the BLS layer (forexample, JCO.Function caching, connection lifecycle).

Configuration of BLS LayerThe main configuration files of the BLS layer are:

WEB-INF/xcm/sap/modification/eai-config.xml

o Configures the Connection Management

WEB-INF/xcm/sap/modification/backendobject-config.xml

o Registers Backend Objects to ISA framework

If you do intend to change these files in customer projects you have to take the corresponding files located inWEB-INF/xcm/customer/modification and use the XCM extension mechanism.

For information how to register backend objects in customer projects refer to chapter 'Changes inbackendobject-config.xml' on page 275.

Configuring Connection Management

This guide assumes that you do not have to change the connection management configured ineai-config.xml. If you think that this is necessary, create an OSS on component CRM-ISA-TEC explaining why do you think this is necessary.

There is one exception which makes it probably necessary to touch the eai-config.xml file: The JCofunction cache. This one is explained in the next paragraph.

JCo Function CacheWhen executing a JCO.Function (for further information about JCo see [4] SAP Java Connector: On theSAP Service Marketplace: http://service.sap.com/connectors Java Connector) in the BLS layer, the resultof the call can be either served from the SAP system or from a cache maintained by the BLS layer. Thecache is useful for function modules returning static data and long execution times.

The cache is only implemented for function modues executed with connection typecom.sap.isa.core.eai.sp.jco.JCoConnectionStateless.

An unambiguous key recognizes each JCo function served from the cache. The key is represented by aString constructed from the called JCo function. There are two key types:

Key Type A:

<logon client to SAP system e.g. 805> + <logon language to SAP system> + <string

representation of import parameters> + <JCO function name>


August 2008 88

Key Type B:

The JCo functions that have to be cached by the BLS layer are defined as name/value parameters of themanagedConnectionFactory element in the eai-config.xml file:

Cache type A:

Cache type B:

Example:

In this example you register the function 'BAPI_CUSTOMER_GETSALESAREAS to the cache in thecustomer version of eai-config.xml using the XCM extension mechanism. After the change the file looks asfollows:

The cache functions are provided by the com.sap.isa.core.cache.Cache and configuredusing the cache-config.xml file located in web-inf\cfg. If you want to change any cachesettings, you must apply these changes in the region named JCO (all numbers are in minutes).You can check if functions have been cached in the ISA Administrator area => Java ConnectorStatistics => JCo Cache Statistics.

<backend version=‘5.0’ xmlns:isa=‘com.sap.isa.core.config’

xmlns:xi=‘http://www.w3.org/2001/XInclude’ xmlns:xml=‘http://www.w3.org/XML/1998/namespace’>

<configs>

<xi:include href=‘${sap}/modification/eai-config.xml#xpointer(backend/configs/*)’/>

<config isa:extends=‘../config[@id='default']’>

<managedConnectionFactories>

<managedConnectionFactory name=‘JCO’>

<params>

<param name=‘cacheType_A’ value=‘BAPI_CUSTOMER_GETSALESAREAS’/>

</params>

</managedConnectionFactory>

<param name=‘cacheType_B’ value=‘ FUNCTION_MOD_A, FUNCTION_MOD_B, ...’/>

<param name=‘cacheType_A’ value=‘FUNCTION_MOD1, FUNCTION_MOD2, ...’/>

<logon client to SAP system e.g. 805> + <logon language to SAP system> + <logon user-name to

SAP system> + <string representation of import parameters> + <JCO function name>


August 2008 89

Configuring Backend ObjectsSAP standard Backend Objects are registered in the file WEB-INF/xcm/sap/modification/backendobject-config.xml. You can register new objects or extendexisting objects. If you do this in customer projects you have to register your objects in the customer versionof backendobject-config.xml using the XCM extension mechanism. This file is located in WEB-INF/xcm/customer/modification/backendobject-config.xml. In that case refer to chapter'Changes in backendobject-config.xml' on page 275.

Backend Objects are registered using the businessObject XML element.

The businessObject element has the following attributes:


type Specifies the type of the Backend Object, (for example,BASKET). The value of the type attribute must bepassed to the BackendObjectManager when aBackend Object is created.

Yes

name Name of Backend Object. Currently not used byframework.

Yes

className Name of implementation class of Backend Object. Yes

connectionFactoryName Name of the connection factory that provides thedefault connection used by the Backend Object. EachBackendObject provides methods likegetDefaultConnection() returning a connection of thespecified type.

The possible values are:

JCO: for RFC based connectivity with the SAPsystem using SAP Java Connector

IPC: for socket based connectivity to the IPCServer

JDBC: for JDBC based connectivity to adatabase

Connection parameters for all these types are definedin XCM.

If you omit this parameter, then null is returned whencalling getDefaultConnection().

No

Table 25: Attributes of BusinessObject elements


August 2008 90


defaultConnectionName Name of connection used as the default connection.There must be a connection with this name defined inthe connection factory whose name has been specifiedby the connectionFactoryName attribute.

The common values are:

JCO connection factory:

o ISAStateful for stateful connections(type JCoConnectionStateful)

o ISAStateless for statelessconnections (typeJCoConnectionStateless)

IPC connectiono IPC_SOCKET

JDBC connectiono JDBC_CON

no

Table 26: Attributes of BusinessObject elements

The body of the businessObject element can contain any number of name/value pairs. These propertiesare passed to the Backend Object via the initBackendObject() method when it is initialized.

Example taken from B2B:

The parameters (e.g. name=‘distributable’ value=‘NO’) can be obtained when theinitBackendObject() method is called.

<businessObject

type=‘CatalogSite’

name=‘CatalogSite’

className=‘com.sap.isa.catalog.impl.CatalogSite’


defaultConnectionName=‘ISAStateless’>

<params>

<param name=‘distributable’ value=‘NO’/>

<param name=‘catalogSiteConfigFile’ value=‘WEB-INF//cfg//catalog-site-configR3.xml’/>


August 2008 91

Further ServicesThis chapter introduces generic services used in the SAP E-Commerce 7.0 solution.

Message FrameworkThis document gives you a guideline, how to use the generic message framework in your application. Theframework consists also of global message and error pages, which should be included in own application.

The message and handling consists of three parts

Message, MessageList Class and MessageListHolder Interface

MessageTag to use on own Java Server Pages

Standardized Message and Error PagesBusiness Object can be implemented as Message Holder with no effort.

The Message class handles a message similar to R3 message. It consists of

Type (Success, Error, Warning, Info)

Description

Key (language independent resource key)

Arguments

Property (for example „Street“ for BusinessObject User)The MessageList object manages a list of messages.

A message can be added to every object which implements the MessageListHolder interface. Here a list ofobjects which already implement this interface:

MessageList,

MessageListDisplayer,

BusinessObjectBase

BusinessObjectException.

There are some steps necessary one-time to integrate the global message pages in yourapplication. See chapter ’How to integrate the global message pages in an application’ (page 98)for details.


August 2008 92

Message classes

Message, MessageList and MessageListHolder ClassThe Message class handles a message similar to R3 message. It consists of:

Type (Success, Error, Warning, Info)

Description

Key (language independent resource key)

Arguments

Property (for example „Street“ for BusinessObject User)

The MessageList object manages a list of messages.

A message can be added to every object which implements the MessageListHolder interface. Here a list ofobject which already implement this interface:MessageList, MessageListDisplayer, BusinessObjectBase and BusinessObjectException.

A business object can either hold the messages to display it in the front end or log messages to provide it inlog files. In both cases the business object will be set to “invalid” if the message is of the type “error”.

Example

Adding messages from a CRM backendFor the CRM backend the class MessageCRM is used to create messages from the ABAP Structure

CRMT_ISALES_RETURN or BAPI_RETURN.

Example

String returnCode = exportParams.getString("RETURNCODE");

JCO.Table messages =

profTemplCharGet.getTableParameterList().getTable("MESSAGES");

attributeSet.clearMessages();

if (returnCode.length() == 0) {

MessageCRM.addMessagesToBusinessObject(attributeSet,messages);

}

else{

MessageCRM.logMessagesToBusinessObject(attributeSet,messages);

throw (new BackendRuntimeException("Error while read attribute set"));

}

Message message = new Message(Message.ERROR,"shop.loadError",args,null);

Shop.addMessage(message);


August 2008 93

A message could be logged or add to the business partner depending the field TARGET of the structure

CRMT_ISALES_RETURN

“ ” not defined

“A” user message

“B” message for log file

“C” message for user and log fileThe method splitMessagesToTarget take care of the field.

Example

MessageListDisplayerThe MessageListDisplayer class is a helper class to display a message or a list of messages with thecorresponding message page. The class allows controlling the interaction flow after displaying the message.

Example

In this example a message page with the created message and a login button will be displayed. See theJavaDoc of the corresponding class for further details.

String args[]= {shopKey.getIdAsString()};

MessageListDisplayer messageDisplayer = new MessageListDisplayer();

messageDisplayer.addToRequest(request);

messageDisplayer.setOnlyLogin();

messageDisplayer.addMessage(new Message(Message.ERROR,"shop.loadError",args,null));

return mapping.findForward(“message”);

String returnCode = exportParams.getString("RETURNCODE");

JCO.Table messages =

profTemplCharGet.getTableParameterList().getTable("MESSAGES");

attributeSet.clearMessages();

MessageCRM.splitMessagesToTarget(attributeSet,messages);


August 2008 94

Example

Message TagThe MessageTag can display messages of a MessageListHolder on JSP with the dependencies from typeand property.

Example

Exception HandlingExceptions could be thrown in all level of the application. To prevent to mix up the exception in different levelthe exception should always be converting between different levels.

There exist some helper class to convert exception from a lower level to the according exception.

MessageDisplayer messageDisplayer = new MessageDisplayer();

messageDisplayer.addToRequest(request);

messageDisplayer.copyMessages(salesDoc);

// the action which is to call after the message

messageDisplayer.setAction("/b2b/documentstatusdetailprepare.do");

messageDisplayer.setActionParameter("techkey="+salesDoc.getTechKey().getIdAsString()

+"&objecttype="+mandoc.getDocType()

+"&objects_origin=&object_id=" );

return mapping.findForward("message");

<!–– all User error -->

<isa:message id=„error“ name=„User“ type=„<%=Message.ERROR%>

<%=error%>

</isa:message>

<!–- errors without a property -->

<isa:message id=„error“ name=„User“ type=„<%=Message.ERROR%>

property=„“>

<%=error%>

</isa:message>

<!–- error for a given property -->

<input type=text name=„Street“>street<input>

<isa:message id=„error“ name=„User“ type=„<%=Message.ERROR%> property=„street“>

<%=error%>

</isa:message>


August 2008 95

BackendEncapsulate the call of a function module always in an own function module.

Example

Use the method JCoHelper.splitException(ex) to convert a JCO exception to an ECommerceBackend Exception.

Ensure that the JCO Connection will be closed if you create backend exceptions.

Example

JCoConnection connection = getDefaultJCoConnection();

JCoHelper.ReturnValue retVal = crmIsaProfTemplCharGet(attributeSet,

shop,

shopConfig,

connection);

connection.close();

if (retVal.getReturnCode().length() > 0) {

// bring errors to the error page

MessageCRM.logMessagesToBusinessObject(attributeSet, retVal.getMessages());

MessageCRM.addMessagesToBusinessObject(attributeSet, retVal.getMessages());

throw (new BackendRuntimeException("Error while read attribute set"));

}

else {

MessageCRM.addMessagesToBusinessObject(attributeSet, retVal.getMessages());

}

log.entering(“call()”);

try {

JCO.Function function = connection.getJCoFunction(moduleName);

...

return new JCoHelper.ReturnValue(null, "");

}

catch (JCO.Exception ex) {

JCoHelper.splitException(ex);

}

finally {

log.exiting();

}


August 2008 96

Business Object LayerUse the method BusinessObjectHelper.splitException(ex) to convert a backend exception to anECommerce Front end Exception.

Example

Action LayerUse the EComBaseAction class as a base class for your own actions. Because this action handles allECommerce action in appropriate way and forward to the correct error pages (see next chapter). If you wantto check also if the user is logged in use the class EComExtendedBaseAction (see chapter ‘Pre Conditioncheck in the EComExtendedBaseAction’ on page 99).

Error PagesThe framework provides a set of error and message pages which could easily use in other application. Bestyou uses also the EComBaseAction as a base class for your own actions because this action handles thecommon exceptions and forward to appropriate pages (see global forwards in chapter ’How to integrate theglobal message pages in an application’ on page 98).

appbase\backenderror.jspThis page should be displayed after a CommunicationException is thrown. The exception should be stored in

the request under the name ContextConst.EXCEPTION.

appbase\runtimeerror.jspThis page should be displayed after a RuntimeException is thrown. The exception should be stored in the

request under the name ContextConst.EXCEPTION.

appbase\panicexception.jspThis page should be displayed after a PanicException is thrown. The exception should be stored in the

request under the name ContextConst.EXCEPTION.

try {

return getMyBackendService().isUserAuthorized(user);

}

catch (BackendException ex) {

BusinessObjectHelper.splitException(ex);

}

return false;


August 2008 97

appbase\relogin\invalidsession.jspThis page should be displayed after the session is invalid. The /base/relogin/getcookie.do action (see globalforwards in chapter ’How to integrate the global message pages in an application’ on page 98) should becalled before the page is displayed.

appbase\message.jspThis page can be used to display all kind of messages. The information about the page and the message willbe handled by the MessageListDisplayer class.

appbase\jspruntimeerror.jspThis page displays runtime error on a JSP’s. Without this page the J2EE engine displays only a white screenwith no information that an error occurs. Insert the following line in your JSP to get a message page insteadof a white screen.

appbase\accessibilitymessages.inc.jspThis include should be used to display messages in accessibility mode at the top of the page.

See chapter ‘Message handling in accessibility mode’ (page 97) for details.

Message handling in accessibility modeThere is some support to generate messages in the accessibility mode. With the property pageLocation of

the Message object is possible to describe on which area of the page the error occurs. Please define aresource key access.message.location.<yourLocation> for each of your page location.

Additionally with the property position it is possible to describe the absolute position of the message in thepage. This position will be interpreted as an anchor in the HTML page.

With the following HTML Coding:

Example

<a href="#" name="item_<%=JspUtil.removeNull(item.getNumberInt())%>"></a>

<a href="#" name="[location]_[position]"></a>

message.setPageLocation(ITEM);

message.setPosition(items.get(i).getNumberInt());

message.setPageLocation(SalesDocumentDataUI.HEADER);

<%@ page errorPage="/appbase/jspruntimeexception.jsp" %>


August 2008 98

The message could be displayed with the help of the include appbase\accessibilitymessages.inc.jsp.

The messages which should be displayed could be added with method addAccessibilityMessages ofthe BaseUI class. Within this include the generateAccMessages method of the BaseUI class will be called.Overwrite this method if you want to use this method to build up your messages.

How to integrate the global message pages in an applicationThere are only a few steps to include the global message pages in an application.

Define the used actions in your config.xml:

/**

* Generates all messages for accessibility.

*/

public void generateAccMessages() {

MessageList messagelist = header.getMessageList();

for(int i=0; i<messagelist.size(); i++){

Message message = messagelist.get(i);

message.setPageLocation(HEADER);

}

addAccessibilityMessages(messagelist);...

<%-- Show accessibility messages --%>

<% if (ui.isAccessible) { %>

<%@ include file="/appbase/accessibilitymessages.inc.jsp" %>

<% } %>



<action path="/base/relogin/setcookie"

type="com.sap.isa.core.action.SetReloginCookieAction">

<forward name="success" path="/user/performLogin.do"/>

</action>

<action path="/base/relogin/getcookie"

type="com.sap.isa.core.action.GetReloginCookieAction">

<forward name="success" path="/appbase/relogin/invalidsession.jsp"/>

</action>

<action path="/appbase/error"

type="com.sap.isa.isacore.action.EComDisplayErrorPageAction">

</action>




August 2008 99

Define the used global forwards in your config.xml:

Define the init action you use to start the application in the web.xml under the parameter

initAction.core.isa.sapmarkets.com (e.g. “/b2b/init.do”) or insure that the action /init.do. starts yourapplication:

If an header should be included in the message page the header include must be defined in the init-config.xml:

Pre Condition check in the EComExtendedBaseActionThe EComExtendedBaseAction extends the EComBaseAction with a check if the user is logged in.

A UserBase object must exist in one of the used business object manager and the corresponding businessobject manager must implement the UserBaseAware interface.

If the user is not logged in the action returns the logical forward Constants.USER_NO_LOGIN(user_no_login)

Example:

<global-forwards type="org.apache.struts.action.ActionForward">

<forward name="login" path="/b2b/login/login.jsp"/>

<forward name="user_no_login" path="/appbase/error.do"/>

</global-forwards>



<initialization className="com.sap.isa.ui.UIInitHandler">

<param name="simple-header" value="/shopadmin/simpleheader.inc.jsp"/>

</initialization>

<!— support of the global init action -->

<action path="/init.do" forward "/b2b/init.do"/>



<global-forwards>

<forward name="error" path="/appbase/error.do"/>

<forward name="message" path="/appbase/message.jsp"/>

<forward name="backenderror" path="/appbase/backenderror.jsp"/>

<forward name="session_not_valid" path="/base/relogin/getcookie.do"/>

<forward name="runtimeexception" path="/appbase/runtimeexception.jsp"/>

<forward name="panicexception" path="/appbase/panicexception.jsp"/>

</global-forwards>


August 2008 100

This leads to the following error message:

Extended actions can use the property checkUserIsLoggedIn to change the behavior dynamically e.g.

depending from the application in the initialize method.

Example:

/**

* Initialize the action.

* In B2C this action could be used by anonymous user.

*

* @see com.sap.isa.isacore.action.IsaCoreBaseAction#initialize()

*/

public void initialize() {

if (getApplication().equals(CONSTANTS.B2C)) {

this.checkUserIsLoggedIn = false;

}

}


August 2008 101

Generic Search FrameworkThe Generic Selection Framework provides a mechanism to build a Selection screen out of an XMLdescription. In CRM 7.0 the document selection and the customer selection (B2R scenario) are createdusing the Generic Search Framework.

B2B Document Selection Screen:

Search screen

Result list


August 2008 102

Architecture of the Generic Search Framework

JSP

SelectionCriteria

JSP

Result list

UI Class

Request Context

MaintenanceObject

(and helperclasses)

XCM

Action &BusinessobjectsSearch /GenericSearchCommand

CRM Or

JDBC …

UI Class

Class handlingthe dynamiccontent


August 2008 103

Following describes the structure of the xml and the relations of the attributes. See section “Examples ofExtensions -> Extension of the Document Search Screen“ on how to use the generic search framework tomanipulate the document search screen.

Main Components of the Generic search frameworkComponent Application layer\appbase\genericsearch.jsp Web server\xcm\sap\modification\generic-searchbackend-config.xml Web servercom.sap.isa.ui.uiclass.genericsearch.GenericSearchBaseUI.java Web servercom.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory.java Web servercom.sap.isa.isacore.action.GenericSearchBaseAction.java Web servercom.sap.isa.isacore.action.GenericSearchSortAction.java Web serverCRM_ISALES_SEARCH Application server (Dev.class)CRM_ISA_GEN_DOCUMENT_SEL Application server (func. Mod)CL_ISA_GEN_DOC_SEARCH_HELP Application server (class)

Details of component “generic-searchbackend-config.xml”Location: xcm \ sap \ modification \ generic-searchbackend-config.xml

The xml is separated for each backend and basket type (CRM, JavaBasket).

<configs id="crmdefault"> <property-group name="SearchCriteria_B2B_Sales" useSearchRequestMemory="true">

<property name="show_me" type="text" value="gs.show.me"/>

<property name="document_types" type="box" implemenationFilter="true" requestParameterName="rc_documenttypes" resultlistName="dummy" maxHitsToSelect="100" UIJScriptOnChange="GSloadNewPage(this);"> <allowedValue value="ORDER" description="b2b.status.shuffler.key1val2" resultlistName="order_resultlist_B2B" default="true"/> <allowedValue value="BACKORDER" description="gs.attr.doc.type.backorder" resultlistName="order_resultlist_B2B" maxHitsToSelect="0"/> <allowedValue value="QUOTATION" description="b2b.status.shuffler.key1val1" resultlistName="quot_resultlist_B2B"/>

IMPORTANT !! For the CRM backend all search criteria are logically linked together with AND.For example, show me all ORDERS where partner is “4711” AND status is “open” AND purchase ordernumber is “PO 0815”.But the same search criteria are logically linked together with OR.For example, show me all ORDERS where partner is “4711” AND status is “open” OR status is “completed”AND purchase order number is “PO 0815”.

The definition of a result list is also surrounded by the <property-group> tag. It describes the fields whichshould be retrieved from the backend and being displayed on the screen.

<property-group name="order_resultlist_B2B"> <property name="GUID" type="hidden" parameterType="rowkey" /> <property name="STATUS_SYSTEM" columnTitle="b2b.stat.cust.shuf.key102" translationPrefix="status.sales.status."/>


August 2008 105

Allowed attributes for tag <screen-group>Attribute Default RemarkuiClassName - Defines the UI class which should be used to build up the search

and result list screen. The class must implement InterfaceGenericSearchUIData or more easily extend classGenericSearchBaseUI.

Allowed attributes for tag <property-group> describing a search screen.Attribute Default RemarkuseSearchRequestMemory false If set to true, the last search request parameters (drop

down boxes, input fields) will be stored and after aperformed search represented to the web user.If set to false, the search screen will always be displayedaccording to default settings.

bodyInclTop - Defines the path/name of an include which will be placedright after the <body> tag of the <html> page.

bodyInclBottom - Defines the path/name of an include which will be placedright before the </body> tag of the <html> page.

maxScreenAreas 1 Number of screen areas for this search screen. This allowssplitting the search criteria into several areas. The areasare <div> blocks and can be controlled by the CascadingStyle Sheet (CSS) file.

cssBodyClassName document-search

CSS class which will be added to the <body class=”<…>”>;tag.

UIJScriptOnStartButton sendRequest(); Name of the JScript function which will be called at the'onclick' event of the “GO!” button.

linkTargetFrameName - Name of the frame where the result list should be placed.This can be used if the result list should be located intoanother frame as the search screen.

msgKeyObjectFound gs.result.msg. Resource key prefix for message of how many objectshave been foundThe key will be extended either by- 0 for no document found- 1 for exactly 1 document found- n for more than one documents found- evt.s for simple "max hits" event occurred- evt.e for enhanced "max hits" event occurredSee also <propert-group> describing a result list.

Allowed attributes for tag <property> describing a search screen.Attribute Default Remarkname - Name of the property which will be used for searching in a

backend.The name MUST be unique within one search screen definitionwhere the property appears on the screen. To separateproperties with the same name add an index in form of (1), (2) tothe property name (e.g. CREATED_AT_DATE(1),CREATED_AT_DATE(2), …)The index will be automatically removed by the framework.

type - Defines the type of the search screen property:- box (= drop down list box)- radio (= radio button)


August 2008 106

- text (= simple output text)- input (= simple input field)- dark (= programmable property)- hidden (= hidden input field)- date (= input field for single date)- daterange (= input fields for a date range in one line)- daterange2L (= input fields for a date range in two lines)

Allows also defining a subtype in form of a token. Therefore addthe word “token” to your subtype (e.g. type=”box(datetoken)”. Theinformation “datetoken” will be passed on to the backend inattribute “param_function” (see details of component“CRM_ISA_GEN_DOCUMENT_SEL”)

By appending “UI” to the type, this property will only be used onthe screen, but not send to the backend.

helpValuesMethod - Identifies a help value method defined in filesap\modification\helpvalues-config.xml. Adding the name of an<helpValuesSearch> will bring up an binocular beside of an inputfield.

implemenationFilter - If set to true the value send with the request will be used to firstidentify an backend object (see filesap\modification\backendobject-config.xml) and second to selectthe ABAP class performing the search.

resultlistName - Default name of the result list which will be used, if not otherwisespecified (see <allowedValue> tag. Only meaningful if flag“implemenationFilter” is set to “true”.

entityType - Database entity where the search will performed. (e.g. to identifywhere the entity in the CRM 1order reporting framework willsearch for this property)

tokenType - To identify an token on how to be search (e.g. an token from theCRM 1order reporting framework like “RAN”)

parameterType - Additionally describing attribute for the property which will bepassed on to the backend in attribute “param_func_type” (e.g. toidentify the partner function type of an business partner)

requestParameterName - Name which should be used for this property to build up the URL.MUST be unique within the URL which will be sent to the webserver. Since there is no further processing on this attribute, thename could be freely chosen (to be unique).

UIJScriptToCall - Defines a JScript function and event for this property (e.gonBlur=’dosomething();’)

UIJScriptOnChange - Defines a JScript function which should be called on the“onchange” event. The function will be called BEFORE thestandard JScript function of the framework will be triggered.

screenArea 1 Screen area to which this property belongs. See also attribute“maxScreenAreas” of tag <property-group>

label This will allow tagging a label to the property. The value will beinterpreted as an resource file key.

labelAlignment left Alignment of the label- left (= left of the property)- top (= above the property)

maxHitsToSelect -1 This attribute will be passed on to the backend where theselection takes place. The Framework will only return this amountof result list entries. Setting the value to “-1” will return ALL resultlist entries.


August 2008 107

Special Values for the Attributes

Some values of the attributes are having a special meaning.

Attribute Value RemarkentityType NOT_FOR_RF Properties having this value for entityType are not recognized by

the reporting framework.token REF Assuming entityType is set to NOT_FOR_RF, this indicates, that

a search by reference documents via a BAdI implementation hasto be performed.

parameterType CAMPAIGN Calls the BAdI implementation for the search by campaign id.(BAdI CRM_ISA_HLP_FILTER, implemented for ORDER only)

DELIVERY Calls the BAdI implementation for the search by a delivery. (BAdICRM_ISA_HLP_FILTER, implemented for ORDER only)

How to implement additional filters in the backend

The generic search framework is using different BAdI implementations of CRM_ISA_GEN_DOC_SEL toperform a document type specific search. The implementation is selected by a filter value, that is controlledwith the attribute implementationFilter. Possible values are e.g. ORDER, CONTRACT, QUOTATION andothers. See Details of component “CRM_ISALES_SEARCH”.

To add additional filters before and/or after the selection in such a document type specific implementation,the BAdI CMR_ISA_HLP_FILTER was introduced. This provides a method to manipulate the given selectoptions as well as a method to manipulate the list of the selected objects.

The implementation CRM_ISA_FLT_DOCFLOW_DELIVERY is an example for a filter before the selection.The document flow of the delivery is read to get the appropriate order. For the found order, an additionalselect option is generated.

The implementation CRM_ISA_FLT_DOCFLOW_CAMPAIGN is an example for a filter before and after theselection. First the given campaign is read and additional select options are generated so that only orders inthe time range of the campaign are selected by the reporting framework. After the selection the documentflow is read and all orders are filtered out, that have no assignment to the campaign.

Allowed attributes for tag <depending> describing a search screen.Attribute Default RemarkpropertyName - Name of the property of which this one should depend on.Value - Value of the property of which this one should depend on.The <depending> tag allows defining UI dependencies between search screen properties. By defining thisdependency this property will only be visible to a web user if the corresponding property is set correctly.The dependency is ONLY valid for UI and not for backend selections!!

Allowed attributes for tag <allowedValue> describing a search screen.Attribute Default Remarkvalue - Static value which will be added as select option to a <html>

select box (e.g.


August 2008 108

<select id…> <option value=”value” …)

description - Language dependent description of the value (e.g.<select id…> <option value=”value” >description</opt…

resultlistName - If the <property> where this <allowedValue> tag is assigned to,has flag “implemenationFilter” set to “true”, an specific result listis assigned. (e.g. an order document has other fields within itsresult list as an quotation)

default false Defines this entry as default (“selected”).hidden false Hide this value (not included on the <html> page)content - If this attribute is set to value ‘dynamic’ the attributes

“contentCreateClass” and “contentCreateMethod” will be used toinstantiate and perform the defined method. Within this methodthe entries of the drop down box can be generated, and by thatreflecting user settings, shop settings or other customizing.

contentCreateClass - Full qualified class namecontentCreateMethod - Method in class given by “contentCreateClass”

This tag is only allowed for properties of type “dark” and “box” !!If a <property> of type “box” has no select option after the evaluation of the <allowedValue> tag, thisproperty will not appear on the final <html> page.


August 2008 109

Allowed attributes for tag <property-group> describing a result list.Attribute Default RemarkbodyInclBeforeResult - Defines the path/name of an include which will be placed right

before the result list will be issued.bodyInclAfterResult - Defines the path/name of an include which will be placed right

after the result list.msgKeyObjectFound gs.result.msg. Resource key prefix for message of how many objects have

been foundThe key will be extended either by- 0 for no document found- 1 for exactly 1 document found- n for more than one documents found- evt.s for simple "max hits" event occurred- evt.e for enhanced "max hits" event occurredIf not set on the result list level, value from search screen willtake place.See also <property-group> describing a search screen.

expandedResultlist false If set to true, the web application will be instructed toexpanded the search area.

Allowed attributes for tag <property> describing a result list.Attribute Default Remarkname - Name of the property which will be requested in the backend for

the result list.type - Type of the result list property.

- “date”- “number”- “hidden”- “nosort”- “text”- “checkbox”

Set this attribute to “hidden” if the value is just needed forinternal purposes and not intended to be visible to the webuser.“date” and “number” mark properties which are not meant to besorted as String!“nosort” marks properties which should not have the possibilityto be sorted be the web user.“text” in conjunction with attribute “readOnly” (=false) will rendera <input> tag allowing the web user to enter some data (asurrounding <form> tag to process the data, must be renderedby using the custom includes (see attributes“bodyInclBeforeResult” and “bodyInclAfterResult”)

readOnly false Render the field as input field is set to “false”. This is possiblefor properties of type “date”, “number”, “text” and “checkbox”.

parameterType - Allows marking this property as “rowkey”.columnTitle - Language dependent header title of the property.translationPrefix - If this attribute is set, the value of the property will be

concatenated with this prefix, and translated before issued onthe <html> page

cssClassName - Assigns a special CSS class to this property. By that it is


August 2008 110

possible to control the layout of the value via the CSS class.hyperlink - Defines a hyperlink for this property value. The value will be

created with this hyperlink.(e.g. b2b/documentstatusdetail.do)To create the parameter for the hyperlink use attributes“linkParamClass” and “linkParamMethod”.

linkParamClass - Full qualified class namelinkParamMethod - Method in class given by “linkParamClass”linkTargetFrameName - Defines the target frame where the hyperlink should point to.writeUnderProperty - Allows creating multi-line result lists. This property will be

written right under the <property> specified here.defaultSortSequence - Allows to sort the initially issued result list to be sorted either

- “DESCENDING”- “ASCENDING”

It is only allowed marking one property to be sorted by default.fieldOutputHandlerClass - Defining this class and method allows controlling the value

output by program code. By that it is possible for example toissue the value as an icon.

fieldOutputHandlerMethod - See attribute “fieldOutputHandlerClass”.

Details of component “GenericSearchBaseAction”

This Struts action is responsible for processing the search request. In Internet Sales theGenericSearchISAAction is derivated from this base action to deliver ISales specific objects like BOM orUserSessionData.While this action is processed it will be decided where the search request should be processed. This couldeither be the CRM Application server or the JavaBasket. Determined for the backend is the value of theproperty where attribute “implemenationFilter” is set to “true”. The object with this type will be picked up fromthe xcm\sap\modification\backendobject-config.xml file.To communicate with the CRM or the JavaBasket the standard classes

- com.sap.isa.backend.crm.GenericSearchCRM- com.sap.isa.backend.db.order.OrderTemplateStatusDB

should be used.

Details of component “CRM_ISALES_SEARCH”

This part of the description explains how an incoming search request will be processed in the CRM backend.All communication from Java to CRM is handled by function module CRM_ISA_GEN_DOCUMENT_SEL.Basically this function module can handle multiple search requests with one call. All search request optionsare linked together with a handle. From the <html> page generated by the genericsearch.jsp only ONEsearch request at the time will be send.The function module itself is not responsible to handle the search request. It only determines the right BAdIimplementation and hands over the control to it. To determine this BAdI implementation, one of the search


August 2008 111

request entries (import table IT_SEL_OP) with key SELECT_PARAM = ‘LIST_FUNCTION’ is picked up andits value used to instantiate the BAdI.

Known standard implementations for CRM Internet Sales are:

Filter Value ABAP class RemarkORDER CL_IM_CRM_ISA_GDS_ORDER This implementation is exclusively used to select

order documents.ORDERTMP CL_IM_CRM_ISA_GDS_ORDERTMP This implementation is exclusively used to select

order templates.CONTRACT CL_IM_CRM_ISA_GDS_CONTRACT This implementation is exclusively used to select

contract documents.QUOTATION CL_IM_CRM_ISA_GDS_QUOT This implementation is exclusively used to select

quotations.BILLINGDOC CL_IM_CRM_ISA_GDS_BILLDOC This implementation is used to select billing

documents. It first decides where to read thedocuments (R/3 or CRM) and also what type ofdocuments (invoice, credit memo or downpayment).

BACKORDER CL_IM_CRM_ISA_GDS_BACKORD This implementation is exclusively used to selectbackorder documents

1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for itemswithin one sales document (1Order documents). Itreturns items instead of header objects.

BILLINGITM CL_IM_CRM_ISA_GDS_BILLDOCI This implementation is used to search for itemswithin CRM billing documents. It returns itemsinstead of header objects.

ORDERITM CL_IM_CRM_ISA_GDS_ORDERITM This implementation is used to search for items in1Order order documents. It returns items instead ofheader objects.

ORDTMPITM CL_IM_CRM_ISA_GDS_ORTMPITM This implementation is used to search for items in1Order order template documents. It returns itemsinstead of header objects.

QUOTITM CL_IM_CRM_ISA_GDS_QUOTITM This implementation is used to search for items in1Order quotation documents. It returns itemsinstead of header objects.

RETURNITM CL_IM_CRM_ESRV_RET_ITEMS This implementation is used to search for itemswithin CRM return transactions. It returns itemsinstead of header objects.

COMPLITM CL_IM_CRM_ESRV_COMPL_ITEMS This implementation is used to search for itemswithin CRM complaint transactions. It returns itemsinstead of header objects.

All of these BAdI implementations make usage of the powerful helper class“CL_ISA_GEN_DOC_SEARCH_HELP”.Orders, order templates, quotations and contracts are documents from the CRM 1order application. Toselect documents from the CRM 1order the application provides the CRM 1order reporting framework. Tocommunicate with the reporting framework the helper class provides various methods to format the incomingsearch request and convert it into a reporting framework query. The reporting framework only return the mainkey (GUID) of the found documents. Enhancing these by other attributes like document description,document creation date and so on, the help class provides also an appropriated method.All methods related to the reporting framework have the prefix ONEORDER_.


August 2008 112

Same applies to the billing documents except the prefix of the methods is BILLING_ and the selection iscovert by the function module “/1BEA/CRMB_BD_O_GETLIST” or “CRM_ISA_INVOICE_LIST_GET” for R3billing documents.If none of the prefixes is used the method has common character and can be used for reporting frameworkand billing.


August 2008 113

ESelling specific implementation of the Generic SearchFramework

The section before gave a detailed overview of the different components of the Generic Search Framework.The components are designed to work in a generically way, independent from an application. This sectionnow focuses on the integration of the Generic Search Framework into the CRM ESelling web application.

1. Known search definitions in ESelling

Search Screen Definition Scenario RemarksSearchCriteria_B2B_Sales B2B To search for sales documents.

- orders- quotations- order templatesEven billing documents are defined, onceone of those is selected, via JScript searchdefinition “SearchCriteria_B2B_Billing” iscalled. Forwarding to“SearchCriteria_B2B_Items” if itemsshould be searched.

SearchCriteria_B2B_Items B2B (CRM) To search for 1Order document items(order items, order template items,quotation items).For 1Oder document search“SearchCriteria_B2B_Sales”, via JScriptsearch definition while for Billingdocuments “SearchCriteria_B2B_Billing” iscalled

SearchCriteria_B2B_Contracts B2B To search for contract documentsSearchCriteria_B2B_Sales_OrderStatus_Items B2B To search for sales document items (used

to find items in case of large documenthandling is enabled in the shop)

SearchCriteria_B2B_Billing B2B To search for billing documents- invoices- credit memos- down paymentsEven sales documents are defined, onceone of those is selected, via JScript searchdefinition “SearchCriteria_B2B_Sales” iscalled.

SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items (usedto find items in case of large documenthandling is enabled in the shop)

SearchCriteria_B2B_Auction B2B Only describes the search criteria, but theactually search is not done by the GenericSearch Framework

SearchCriteria_BOB_Sales Business onBehalf

To search for sales documents

SearchCriteria_BOB_Customers Business onBehalf

To search for customers in a BOBscenario


August 2008 114

SearchCriteria_HOM_Sales HostedOrderManagement

To search for order document in a HOMscenario

2. Definition of the first search screen to come up in the B2B scenario on the left side of the application(Shuffler / Navigator).xcm\sap\configuration\config-data.xml

<component id="shop"> <configs> <config id="crmshop_b2b"> <params id="shopsettings"> <param name="shopscenario" value="B2B"/>

<param name="documentsearch.name" value="SearchCriteria_B2B_Sales"/>

3. Dynamically disabling document types which are not allowed by shop settings or user permissions.

Even in a search definition, for example “SearchCriteria_B2B_Sales”, all Internet Sales known documenttypes are defined, on the <html> page only appear the once allowed by the shop settings.In the <screen-group> it is possible to define a UI class, extending the base one.

<screen-group name="search_criteria" description="search.criteria"

uiClassName="com.sap.isa.ui.uiclass.genericsearch.GenericSearchISAUI" type="search">

For the standard search definitions, this class takes care to remove all document types which are not allowedby shop settings or where users permission are insufficient.

4. Adding JScript file to the genericsearch.jsp

The UI class mentioned in 3. also allows to add new JScript files to the genericsearch.jsp. Therefore method“getJScriptFilesTab” is implemented the following way.

/*** Returns the name of JScript files which should be included.* @return ResultData containing file names*/public ResultData getJScriptFilesTab() {

ResultData retObj = super.getJScriptFilesTab();

Table tab = retObj.getTable(); TableRow tabRow = tab.insertRow(); tabRow.setValue("FILENAME", "b2b/jscript/showSoldTo.jsp");


August 2008 115

Logging/TracingLogging/Tracing provides a means for the user to write structured data into a file, a console, or some otheroutput destination.

This chapter gives background information on how to use and configure logging/tracing within the InternetSales application.

Design ConsiderationWhen the first Java version of E-Commerce was released there was neither a logging API within the JavaDevelopment Kit, nor an SAP logging API. Instead, an open source LOG4J logging API was well acceptedwithin the Java community.

When designing the E-Commerce architecture it was clear that there would be a time when a new loggingAPI (either from SUN or SAP) would be released. In order to be able to switch to this logging API withoutchanging the application coding it was decided to introduce an own logging facade (API) over the existinglog4j API. Since SAP E-Commerce 4.0 exclusively the SAP logging API below the ISALocation API is used.

Figure 21: Design of Logging / Tracing

The used logging facade is represented by the class com.sap.isa.core.logging.IsaLocation.

Most of the E-Commerce coding is still using ISALocation. SAP Logging API is only used for newapplications in E-Commerce (e.g. Selling via Ebay), not for extensions on existing applications (e.g. B2B).

It is therefore recommended to stay with ISALocation in already existing coding (e.g. customer projectsmigration from ECO 4.0 to ECO 5.0).

For new customer projects it is recommended to use the SAP Logging API directly.

Difference between Logging/Tracing

TracingTrace messages are:

Usually turned off (trace level ERROR) A Mechanism for development/support

o Target group: developers and support Traces write using Locations => where did something happen?

Application classes

ISALocation

SAP Logging API

Extensions onexisting customercoding already usingISALocation

New CustomerProject


August 2008 116

A trace message can have the following content: Information about execution steps Value of important variables Important return codes Information about thrown Exceptions

LoggingLog messages are:

Always turned on (log level INFO) Mechanism of normal operation

o Target group: Administrators Logs write using Categories => what has happened?

A log message can have the following content: Description of Message Possible Impact? Possible reasons? Information about further information (notes, documentation, ...)

Logs are usually read by system administrators. It is therefore important to provide enoughinformation in order to enable the administrator to understand the message or to solve apotential problem. In order to have a uniform log output there are some helper methods in theclass com.sap.isa.core.logging.LogUtil for constructing log messages.


August 2008 117

Summary Types of log messagesMessage Type Interested Party What to usemessage customer or admin log record

message developer, support trace record

exception customer, admin log record

exception developer, support trace record

entering/exitingmethod

developer, support trace record

Table 27: Types of Log Messages

TracingUse the following severities to write trace messages:

Severity DescriptionDEBUG Developer trace. Any information useful for a

developer in order to understand programexecution path

PATH For Information on entering/exiting methods.Useful for important methods.

ERROR Exception meaningful for developer

Table 28: Types of Tracing

APIs for Tracing: ISALocation

You should only use the ISALocation if you already enhanced the E-Commerce 4.0 solution. Ifyou don’t have enhancements, or if you do enhancements for new applications, please use theSAP Logging API instead.

Initializing Location

Entering/exiting non trivial method

private static final IsaLocation log = IsaLocation.getInstance(ClassName.class.getName());

public void entering(String method)

public void exiting()


August 2008 118

Try to use only a single return statement in methods. This makes it easy to use the exiting()trace as well as debugging.

Throwing exceptionUse the following methods to write trace messages with the severity level “ERROR”:

DEBUGUse the following methods to write trace messages with the severity level “DEBUG”:

ERRORUse the following methods to write trace messages with the severity level “ERROR”:

Coding ExamplesStrings are traced as passed to the methods (no resource keys).

public void throwing(String message, Throwable th)

public void throwing(Throwable th)

public void debug(Object message)

public void debug(Object message, Throwable t)

public void error(Object message)

public void error(Object message, Object params[], Throwable t)

public void error(Object message, Throwable t)


August 2008 119

APIs for Tracing: SAP Logging API

Initializing Location

Contrary to the IsaLocation you pass the class object instead of a string

DEBUGUse the following methods to write trace messages with the severity level “DEBUG”:

private static final Location loc = Location.getLocation(Node.class);

debugT(java.lang.String msg)

debugT(java.lang.String msg, java.lang.Object[] args)

debugT(java.lang.String subloc, java.lang.String msg)

debugT(java.lang.String subloc, java.lang.String msg, java.lang.Object[] args)

protected static IsaLocation log =

IsaLocation.getInstance(ClassName.class.getName());

// simple developer trace

log.debug("This is a trace message");

// entering exiting method

log.entering("myMethod()");

log.exiting();

// Tracing when throwing exception for dev/support. PATH is internally used as severity.

// No stacktrace is printed

log.throwing(ex);

// with some additional information

log.throwing("exception trace for support", ex);

// catching exception. Trace only if relevant for support

log.error("isatest.error.exception", ex);


August 2008 120

ERRORUse the following methods to write trace messages with the severity level “ERROR”:

Entering/exiting non trivial methodUse the following methods to write trace messages with the severity level “PATH”:

Throwing exceptionUse the following methods to write trace messages when an exception is thrown, that is only relevant fordevelopers or the support:

errorT(java.lang.String msg)

errorT(java.lang.String msg, java.lang.Object[] args)

entering(java.lang.String subloc)

entering(java.lang.String subloc, java.lang.Object[] args)

exiting()

exiting(java.lang.Object res)

throwing(java.lang.Throwable exc)

throwing(java.lang.String subloc, java.lang.Throwable exc)

traceThrowableT(int severity, java.lang.String msg, java.lang.Throwable exc)

Trace message with stack trace of given exception, into this location.

traceThrowableT(int severity, java.lang.String subloc, java.lang.String msg,

java.lang.Throwable exc)


August 2008 121

LoggingUse the log levels according to the following table:

Severity DescriptionInfo Informational text to record an event, which does not have and also does not need any

follow-up activity. It should help to understand the normal operation or could providefurther information for later reviews, audits or investigations.

Warning The application processing can and will proceed, but later follow-up activity bypeople responsible for the specific category is necessary to avoid error situations in thefuture. Information of how to solve the problem in the future should be available.

Error The application processing terminates without completing the desired tasks. Theapplication is still usable, but corrective actions need to be performed to avoid theerroneous termination in the future. Information of how to solve the problem shouldbe available. If not, customers will need to open problem messages to solve theproblem.

Fatal The application processing terminates without completing the desired tasks. Theapplication is not usable anymore and cannot be started without corrective actions byexperts. Customers will normally need to open problem messages to solve the problem.

Table 29: Log Levels

Usage of CategoriesApplication categories for messages related to application operation tasks.

Predefined Application categories are written to .log/applications.

Category When to use Defined in/Applications/Common/Backup n.a. in ECO com.sap.isa.core.logging.LogUtil

/Applications/Common/Archiving n.a. in ECO com.sap.isa.core.logging.LogUtil

/Applications/Common/Configuration everything related to(mis-)configuration

com.sap.isa.core.logging.LogUtil

/Applications/Common/Security everything related tosecurity


/Applications/Common/Infrastructure everything related toinfrastructure i.e.generic services (JCo,cache, database, etc.)


/Applications/UserInterface User Interface Layer(e.g. JSPs)


/Applications/BusinessLogic functionality dealingwith business logic(e.g. E-CommerceBusiness Objects)


/Applications/Interaction classes controlling theinteraction with the user(e.g. Struts actions)


Table 30: Categories for Logs


August 2008 122

APIs for Logging: ISALocation

ERRORUse the following methods to write log messages with the severity level “ERROR”:

FATALUse the following methods to write log messages with the severity level “FATAL”:

INFOUse the following methods to write log messages with the severity level “INFO”:

WARNINGUse the following methods to write log messages with the severity level ”Warning”:

public void error(Category category, Object key)

public void error(Category category, Object key, Object[] args)

public void error(Category category, Object key, Object[] args, Throwable t)

public void error(Category category, Object key, Throwable t)

public void fatal(Category category, Object key)

public void fatal(Category category, Object key, Object[] args)

public void fatal(Category category, Object key, Object[] args, Throwable t)

public void fatal(Category category, Object key, Throwable t)

public void info(Category category, Object key)

public void info(Category category, Object key, Object[] args)

public void warn(Category category, Object key)

public void warn(Category category, Object key, Object[] args)

public void warn(Category category, Object key, Object[] args, Throwable t)

public void warn(Category category, Object key, Throwable t)


August 2008 123

Detailed Message DescriptionsIt is recommended to use detailed message descriptions. These messages can be created using thefollowing methods in the class LogUtil:

If null is passed as a parameter the parameter is omitted in the log output.

The return value can be directly passed to all logging/tracing methods.

Coding ExamplesWhen logging it is necessary to use resource keys:

public static LogMessage getLogMessage(String descriptionKey, Object[] descrParams,

String impactKey, String reasonKey, String furtherInformationKey)

public static LogMessage getLogMessage(String descriptionKey, String impactKey,

String reasonKey, String furtherInformationKey)

// log with parameters

log.info(Category.APPS_COMMON_SECURITY, "isa.security.logon.failure", new Object[]

{ userName });

// logging using detailed descriptions

// example of a log entry indicating that a user was locked

log.info(LogUtil.APPS_COMMON_SECURITY, LogUtil.getLogMessage(

"logon.failure.description", "logon.failure.description.user.locked",

"logon.failure.description.wronglogon",

"logon.failure.description.howtounlock"));


August 2008 124

APIs for Logging: SAP Logging API

INFOUse the following methods to write log messages with the severity level “INFO”:

WARNINGUse the following methods to write log messages with the severity level “WARNING”:

ERRORUse the following methods to write log messages with the severity level “ERROR”:

FATALUse the following methods to write log messages with the severity level “FATAL”:

info(Location loc, java.lang.Object msgCode)

info(Location loc, java.lang.Object msgCode, java.lang.Object[] args)

logThrowable(Severity.WARNING, Location loc, java.lang.Object msgCode,

java.lang.Object[] args, java.lang.String msgClear, java.lang.Throwable exc)

logThrowable(Severity.WARNING, Location loc, java.lang.Object msgCode,

java.lang.String msgClear, java.lang.Throwable exc)

warning(Location loc, java.lang.Object msgCode, java.lang.Object[] args)

warning(Location loc, java.lang.Object msgCode)

error(Location loc, java.lang.Object msgCode)

error(Location loc, java.lang.Object msgCode, java.lang.Object[] args)

logThrowable(Severity.ERROR, Location loc, java.lang.Object msgCode,


logThrowable(Severity.ERROR, Location loc, java.lang.Object msgCode,



August 2008 125

How to Log/Trace: Usage patterns

As a general rule, trace messages are meant for developers to understand the execution flow of theprogram. Log messages are used by system administrators to monitor the health of an application. Thefollowing guidelines define some useful patterns a developer should follow when using log and trace.

1. Define the Location which is used for your class as static final.

2. Trace the entering and exiting of important method.

The severity level is PATH.

If you do trace the entry of a method, it is required that you trace the exit too! If the method mightthrow an exception causing the execution flow to exit the method, you have to trace the exit in afinally clause.

Use a final String object to hold the name of the method you are tracing.

In general following methods must be traced:

i. All UI actions, event handlers (struts actions, do* methods) of UI layer.

ii. All methods of business objects which lead to CRUD operations on data.

iii. All methods of backend objects which trigger backend calls.

iv. All init/close start/stop methods calls.

fatal(Location loc, java.lang.Object msgCode)

fatal(Location loc, java.lang.Object msgCode, java.lang.Object[] args)

logThrowable(Severity.FATAL, Location loc, java.lang.Object msgCode,


logThrowable(Severity.FATAL, Location loc, java.lang.Object msgCode,



August 2008 126

Example

3. Trace the throwing of exceptions.

The severity level is PATH.

Use throwing (String msg, Throwable err) or throwing(Throwable err) API to trace theexception.

In general, there is no need to log the throwing of an exception. It is up to the calling layer tointerpret the raised exception for appropriate logging.

Example

// If Trace throwing exception using ISALocation

private static final ISALocation loc = ISALocation.getInstance(ClassName.class.getName());

// If Trace throwing exception using SAP logging API

private static final Location loc = Location.getLocation(ClassName.class);

// …

public void methodX() throws MyException {

//…

final String msg = “information about the exception”;

MyException err = new MyException(…);

loc.throwing(msg, err);

}

// If trace entering/exiting important method using ISALocation

private static final ISALocation loc = ISALocation.getInstance(ClassName.class);

// If trace entering/exiting important method using SAP location API


// …

public void methodX() {

final String METHOD_NAME = " methodX()";

loc.entering(METHOD_NAME);

//do some proecssing …

loc.exiting();

}


August 2008 127

4. Catching Exceptions. When catching an exception, following are some common cases which shouldbe handled differently.

Bubbling the caught exception i.e. the same exception is propagated to higher layers.

If in the catch clause, the caught exception is bubbling to the caller, in general, you should:

Log the catching exception. Use the appropriate Severity ERROR or FATAL

Trace the throwing of exception.

Example

Recover from the caught exception or perform an alternate operation or ignore the caughtexception.

In case of recovering from the exception, i.e. the exception is handled in the catch clauseand an alternative operation is chosen to replace the normal operation, you should:

Use severity level WARNING

Trace the alternative operation.

// If Log bubbling caught exception using ISALocation

private static final ISALocation log = ISALocation.getInstance(ClassName.class.getName());

// If Log bubbling caught exception SAP logging API


// …

public void methodX() throws SQLException {

//…

try {

// do something …

} catch (SQLException ex) {

// If using ISALocation

loc.error(Category.APP_COMMON_SECURITY, msg, args,ex);

// write the context information to help in error support

log.throwing(ex);

throw ex;

}

//…

}


August 2008 128

Example

Throwing a wrapper exception.

In case of throwing a wrapper exception, you should:

User severity level ERROR or FATAL

Trace the throwing exception

// If Trace recover from caught exception using ISALocation


// If Trace recover from caught exception using SAP logging API


// …

public void methodX() {

//…

try {

// do something …

} catch (InternalException ex) {

// If using ISALocation

log.warning(Category.Applications, "messageKey", args,ex);

log.info(“Do something to recover from exception”);

// perform recover/alternate operation

}

//…

}


August 2008 129

Example

5. Never hide exceptions you cannot handle.

6. To help identify problems, it is important to log context information for the error condition. Useseverity INFO for events that need to provide information about the progress of an operation. Fordetailed context information including state variables use severity DEBUG. It is especially importantthat sufficient context information is logged and traced for an error condition.

// If Trace the throwing a wrapper exception using ISALocation


// If Trace the throwing a wrapper exception using SAP logging API


// …

public void methodX() throws WrapperException {

//…

try {

// do something …

} catch (SQLException ex) { // If using ISALocation

log.error(Category.APP_COMMON_SECURITY,"messageKey", args,ex);

// log context information to help in error support

WrapperException wrapperEx = new WrapperException(ex);

log.throwing(“messageKey”,args,wrapperEx);

throw wrapperEx;

}

//…

}


August 2008 130

Example

// If Trace the throwing a wrapper exception using ISALocation


// If Trace the throwing a wrapper exception using SAP logging API


// …

public void save() throws DBException {

//…

try {

// start transaction

log.info(“started transaction for user”, new Object[]{user});

// perform some sql operation …

// commit transaction

log.info(“commited transaction”);

log.info(Category.Applications,”saved business object {0}”, new Object[]{obj});

} catch (SQLException ex) { // If using ISALocation

log.error(Category.APP_COMMON_SECURITY,”Error saving business object {0}”,

new Object[]{obj});

log.error(Category. APP_COMMON_SECURITY,”error.sqlerror”, ex);

// rollback transaction

log.info(“rollbacked transaction”);

DBException wrapperEx = new DBException(ex);

log.throwing(“messageKey”,args,wrapperEx);

throw wrapperEx;

}

//…

}


August 2008 131

All purpose CacheInternet Sales comes with an all purpose cache, which can be used to store any arbitrary data. This chapterdescribes how to use and configure the cache.

Working with the CacheThe cache is divided in so called regions. Each region represents an individual cache and the region nameis used to distinguish between caches. If you need your own cache you have to add a new region togetherwith attributes. These attributes define how the cache handles objects cached in the region. The mostcommon attributes are:

IdleTime

Sets the maximum time the object will remain in the cache without being referenced (in minutes).

TimeToLive

Sets the maximum time the object will stay in the cache before it becomes invalidated (in minutes).

Although you can initialise the cache in programming, we recommend you do it within the cache-config.xmlfile:

Example

In a customer project you have to add the cache configuration in the file

WEB-INF/xcm/customer/modification/cache-config.xml

You get an overview of existing caches in the ISA Administrator area at:http://host:port/b2b/admin => System cache statistics.

The cache is initialised when the application is started. The cache is accessed using an Access object:

The Access Object provides methods to add and remove objects from the cache:

<regions>



<xi:include href=‘${sap}/modification/cache-config.xml#xpointer(cache/regions/*)’/>



<region name=‘Z_AcmeCache’ idleTime=‘60’ timeToLive=‘300’ descr=‘Project ACME cache’/>

</regions>


August 2008 132

Example

Initialization HandlerWhen the Internet Sales application is started a number of Initialisation Handlers are executed.

Each Initialisation Handler implements the com.sap.isa.core.init.Initializable interface

«<<interface>>»Initializable

+initialize(env : InitializationEnvironment, props : Properties)+terminate()

MyInitHandler

+initialize()+terminate()

The initialize() method is called when the application is started. This gives the handler the opportunityto perform some initialisation tasks.

The terminate() method is called when the application is stopped or the SAP J2EE engine is shuttingdown. This gives the handler the opportunity to perform some clean up work.

Initialisation handlers are registered in the init-config.xml file.

The file has the following structure:

The className attribute contains the class name of the handler. Any number of parameters can be definedin the body of the initalization XML element. These parameters are passed as Properties to theinitialize() method.

<initializations>

<initialization className=‘com.sap.isa.core.cache.CacheInitHandler’>

<param name=‘paramName’ value=‘paramValue’/>

</initialization>

</initializations>

try {

// The cache is accessed using an Access object

Cache.Access access = Cache.getAccess(‘Z_AcmeCache’);

// store an object in the Cache

access.put(‘msg’, ‘This is a string’);

// getting object from Cache

System.out.println(access.get(‘msg’));

} catch (Exception ex) {

log.error(‘z_cache.error’, null, ex);

}


August 2008 133

If you write your own init handler in customer projects you have to add it to the file

WEB-INF/xcm/customer/modification/init-config.xml (as in the example bove).

If you have to change settings of existing init handlers you can also do this in the file

WEB-INF/xcm/customer/modification/init-config.xml. In this case you have to use the XCMExtension mechanism. An example is given in chapter 'Changes in init-config.xml' on page 274.


August 2008 134

Extended Configuration Management (XCM)Extended Configuration Management (XCM) is a new concept for Java applications (Internet Sales, ICSS,IPC Web Application). XCM basically separates XML based SAP settings from settings done by thecustomer.

The XCM Administrator tool has been developed for general configuration activities (for example, connectionparameters to the SAP system). The tool enables you to maintain the configuration for each deployed webapplication via the URL:

http://localhost:50000/<web application>/admin/xcm/init.do.

An XCM Administrator tutorial can be found within the ‘CRM Web Application Installation Guide’ on the SAPService Marketplace under the alias CRM-INST -> SAP CRM 4.0 -> Installation & Upgrade.

However, the XCM Administrator tool cannot be used for less common settings. In this case configurationchanges must be done manually.

Separation of Customer and SAP Configuration FilesXCM divides configuration data into two areas:

Data maintained by SAP

o This data must not be changed by the customer.

o It is located in the folder:<APPLICATION_HOME>\WEB-INF\xcm\sap

Data maintained by the customer

o Only these configuration settings should be changed by the customer.

o Changes are made using XCM extension mechanism.

o It is located in the folder:<APPLICATION_HOME>\WEB-INF\xcm\customer

The customer files consist of empty templates. XInclude is used to include SAP configuration into thecustomer template. In most cases customer changes, done by customers, take place in init-config.xmlor backendobject-config.xml

You should never change the files config-data.xml or scenario-config.xml. This is done usingXCM Administrator

http://localhost:50000/<web application>/admin/xcm/init.do


August 2008 135

Example

This is the customer version of the file init-config.xml:

The xi:include XML element includes the SAP version of configuration settings. If you want to changesettings you must use the XCM extension mechanism. The following chapter explains how the extensionmechanism works.

Separation of Configuration Data and Modification DataBesides the separation of SAP and customer data there is another separation of data. That is, data used forconfiguration of the application (for example, connection data to the SAP System; this is often changed), andmodification data (this data is rarely changed).

The location of the customer configuration data is located in the folder specified using the context parametercustomer.config.path.xcm.config.isa.sap.com. There are two files used for this kind ofconfiguration:

Configuration of scenarios (scenario-config.xml)

Configuration of components (config-data.xml)

The XCM administration UI is used for configuration of these two files.

Modification data is rarely changed and therefore not maintained in the XCM Admin tool. The customermodification data is located in <APPLICATION_HOME>\WEB-INF\xcm\customer\modification. Hereyou can:

Reassign backend classes to standard business objects, or assign backend classes to customerspecific business objects (backendobject-config.xml)

Reassign business object managers or add new BOMs (bom-config.xml)

Modfiy cache configurations (cache-config.xml)

Modify connection definitions (eai-config.xml)

Modify parameters in the standard init-config.xml (for example, change the event capturehandler to Tealeaf (init-config.xml)

Add configuration scope parameters accessible from the Interaction Layer (interaction-config.xml)

Replace function module calls in the backend system, assign event listener classes to functionmodule calls, or activate tracing for function modules in the backend system (modification-config.xml)

Customer extensions to XCM Admin meta-data (xcmadmin-config.xml); This is not covered inthis guide.

<initializations xmlns:isa=‘com.sap.isa.core.config’

xmlns:xi=‘http://www.w3.org/2001/XInclude’

xmlns:xml=‘http://www.w3.org/XML/1998/namespace’>



<xi:include href=‘${sap}/modification/init-config.xml#xpointer(initializations/*)’/>

</initializations>


August 2008 136

XCM Extension MechanismThe XCM extension mechanism enables you to manipulate XML nodes using inheritance. If you want tochange existing configuration you have to perform the following steps:

1. Use the isa:extends XML tag to inherit from the configuration you would like to change.

2. Change existing configuration.

3. Add new configuration information, where applicable.

The isa:extends XML element has the following syntax:

isa:extends=‘XPointer to base node’

The following example illustrates how the extension mechanism works:

The node with the id TestConfigData extends the node with id configdata.

You read the path to the base node as follows:

'..' means go back one node. After performing this you are in the configs node.

/config[@id='configdata'] means go to node named 'config' with attribute 'id' having value'configdata'.

<configs>

<config id=“configdata“>

<params id=“logoncrm“>

<param name=“user“ value=“john“/>

<param name=”password” value=”secret”/>

</params>

</config>

<config id=“TestConfigData“ isa:extends=”../config[@id=’configdata’]”>


<param name=“password“ value=“topsecret“/>

<param name=”language” value=”de”/>

</params>

</config>

</configs>


August 2008 137

After XCM has processed the XML document it is displayed as follows:

<param name=‘password’ value=‘topsecret’/> has extended the base node and changed the value totopsecret.

<param name=‘language’ value=‘de’/> was added by the extending node.

<param name=‘user’ value=‘john’/> was inherited from the base node.

If you only want to change certain settings from the base configuration it is sufficient to specify only thoseparameters you need to change. All other parameters can be omitted, as they will be derived.

Web Application Configuration and Components

The term web application configuration is equal to the term 'scenario' used in some releaseswithin the XCM Administrator.

The XCM Administration tool is used for creating a web application configuration. Each application providesone or more pre-defined configurations. You have to create your own configuration based on one of thedelivered configurations and then adjust it to your needs. A customer configuration consists of the following:

Configuration name

Base configuration (the SAP configuration on which the customer bases his configuration)

A number of configuration parameters with associated values

o Some of these values refer to a component configuration (e.g. the JCO componentconfigures connection parameters to the SAP system)

Refer to chapter ‘

<configs>

<config id=“configdata“>


<param name=“user“ value=“john“/>

<param name=”password” value=”secret”/>

</params>

</config>

<config id=“TestConfigData“ isa:extends=”../config[@id=’configdata’]”>


<param name=“password“ value=“topsecret“/>

<param name=”language” value=”de”/>

<param name=”user” value=”john”/>

</params>

</config>

</configs>


August 2008 138

Extending XCM with Customer Settings’ (page 277) to get information how to do customextensions in the XCM.


August 2008 139

SAP Java Remote Function Call (JRFC)The SAP Java Remote Funciton Call (JRFC) is a middleware product that enables communication betweenJava applications and any SAP systems. The JCo supports both inbound (Java calls ABAP) and outbound(ABAP calls Java) communication.

For a general introduction to the SAP JRFC, see the official Java Connector documentation [4].

Since SAP NetWeaver’04, the JCo is a component of the SAP Web Application Server and is called JRFC.

TechnologyJRFC communicates with the SAP system via Remote Function Call (RFC). The RFC is SAP’s ownrepresentation of the Remote Procedure Call (RPC). Since the RFC is an ABAP component, it is frequentlyused when at least one of the communication partners is an ABAP program.

The RFC is frequently used in the following scenarios:

Both programs are written in ABAP, and an ABAP program calls a different ABAP function (functionmodule) in a different program or SAP system

An ABAP program calls a function in a non-SAP system

A program in a non-SAP System calls a function module in an SAP system

A program in a non-SAP system calls a function in a non-SAP system

The Java developer uses the JRFC Java API to communicate with the SAP system. The JRFC middlewarelayer ensures that communication with the SAP system is transparent for the Java developer. This includes,for example, mapping ABAP data types to Java, or table handling.


August 2008 140

Development EnvironmentThis unit introduces the development tools that are required for both installing and developing all of therequired frontend components and the CRM java applications.

It describes how to use the Netweaver Development Infrastructure (NWDI) to modify or extend CRM andERP Java Web Applications.

The Netweaver Development Infrastructure supports integration of patches, Service Packs and upgrades tonew releases without loosing modifications or enhancements and it supports team development.

We will discuss the following components:

Java Development Kit (JDK)

NetWeaver’04s Java Development Infrastructure (NWDI)

NetWeaver’04s Java Integrated Development Environment (IDE)

NetWeaver’04s Java Application Server

CRM 5.0 Java Components

All examples and operating system specifications in this document refer to Windows.

The following diagram shows a typical Development landscape:

< Local Installation on Developer‘s PC > <--------------- Central Infrastructure ------------------>

NWDI – Landscape Overview

SAP NetWeaver Developer Studio

Cha

nge

Man

agem

ent S

ervi

ce(C

MS)

RunTimeJ2EE

Systems

RunTimeJ2EE

Systems

Deploy

Local FileSystem

ComponentModel

Local J2EEEngine

ComponentBuild Service

(CBS)

Design TimeRepository

(DTR)

Name Server

System LandscapeDirectory (SLD)

The first of this unit deals with installing and configuring the SAP NetWeaver Development Infrastructurewhich is a precondition for the development.

The second part handles the installation and configuration of a developer workplace.

http://help.sap.com/saphelp_nw04/helpdata/de/cb/f4bc3d42f46c33e10000000a11405a/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/bf/1eee1c0c70664c8e844c2eb9e506be/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/8d/0c3736db115f4b8ce3fc716e3a386c/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/31/ef4c4005a99523e10000000a1550b0/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/22/a7663bb3808c1fe10000000a114084/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/31/f0ff69551e4f259fdad799a229363e/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/df/2761930dd9b74a85198f9e48850046/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/69/f9bc3d52f39d33e10000000a11405a/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/c1/c6213e225f9a0be10000000a114084/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/56/d5a23fa34ffb47e10000000a114084/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/de/1c/bca99c220c0e45a1cae3c4cccf4346/frameset.htm

http://help.sap.com/

http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/frameset.htm

http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/frameset.htm


August 2008 141

Development Tools and ConceptsThe SAP NetWeaver Developer Studio provides access to the SAP NetWeaver Java DevelopmentInfrastructure. It enhances the concept of an IDE by server-side services, centrally provides the developmentteams with a consistent development environment and supports the software development during the entirelife cycle of a product.

Design Time Repository (DTR): Versioning source code management. Distributed development ofsoftware in teams. Transport and replication of sources.

Component Build Service (CBS): Central build based on the component model.

Change Management Service (CMS): Central administration of the Java development landscape andthe transports covering the entire software life cycle.

Software Deployment Manager(SDM): Manual and automatic deployment of archives in centralruntime systems.

System Landscape Directory (SLD): Information on the system landscape.

Name Service Central check instance for the uniqueness of names.

Java Dictionary: Supports the global definition of tables and data types

SAP Java Test Tools: Predefined static tests and runtime tests for the Java development

You use the development configuration to configure the development environment. The access paths forthe used services are automatically set by importing a development configuration, for example, the URI ofthe used DTR.

You can develop in the development infrastructure either according to the component model.

External documentationThis document refers to the following official documents delivered by SAP in the help portal (http://help.sap.com ) :

Administration manual of NWDI :

o http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/frameset.htm

Overview of processCRM Software Components delivered by SAP are imported in a track. Some of the components aredesigned to be modified. Others are required for compiling and building the application.


August 2008 142

Software Component Architecture of the CRM or ExtendedEcommerce Java ApplicationsThe components

SAP-SHRWEB.sca

SAP-SHRAPP.sca

SAP-CRMWEB.sca and

SAP-CRMAPP.sca

are designed to be modified and extended in the NWDI. They contain the web files for the E-CommerceApplications, the IPC Web Applications and the Workforce Management Applications.

For E-Commerce for mySAP ERP

SAP-SHRWEB.sca

SAP-SHRAPP.sca

are designed to be modified.

If you plan to extend database tables you can modify the component

SAP-CRMDIC.sca,

in the NWDI as well.

The components

sap.com~STRUTS.sca

sap.com~SAP-IPCMSA.sca

sap.com~SAP-CRMJAV.sca

sap.com~SAP-SHRJAV.sca

TEALEAF.sca

are designed not to be extended or modified in the NWDI. They are required for compiling and building theapplications.


August 2008 143

The following table shows all components at a glance:

Software Component SoftwareComponentforDevelopement

Used inERP

Used inCRM

Usage

SAP-SHRWEB.sca Yes Yes Yes Contains Web Modules for E-Selling,IPC Web Applications and WorkforceManagement

SAP-SHRAPP.sca Yes Yes Yes Contains J2EE Applications anddeployable Libraries.

SAP-CRMWEB.sca Yes No Yes Contains Web Modules for other E-Commerce Applications

SAP-CRMAPP.sca Yes No Yes Contains J2EE Applications anddeployable Libraries.

SAP-CRMDIC.sca Yes Yes Yes Contains Data DictionaryDevelopment Components

sap.com~STRUTS.sca No Yes Yes Contains required jar Files forcompiling and building

TEALEAF.sca No Yes Yes Contains required jar Files forcompiling and building

SAP-IPCMSA.sca No Yes Yes Contains required jar Files forcompiling and building

Table 31: Software Components

Thus, you must add the components SAP-SHRWEB.sca and SAP-SHRAPP.sca into the list of the SoftwareComponents for Development. The required Software Components will be selected automatically.

Modifications and Extensions of the Web User InterfaceThe web user interface of the CRM Applications is contained in the Software Components SHRWEB orCRMWEB.

For each web application there is one Development Component. The naming convention for the Web ModuleDevelopment Components is as follows:

crm/<shortcut for business scenario>/web/<application name>

where <shortcut for business scenario> is either isa (E-Commerce), ipc (Internet Pricing and Configuration)or wfd (Workforce Management), eservice (service parts management), icss (Internet Customer Self Service)

Proceed as follows to modify the Web User Interface:

Open the Netweaver IDE and connect to the CRM Track.

Open the Development Configuration Perspective:Choose Window -> Open Perspective -> -> Development Configuration in the Netweaver IDE menu.

Select the “Inactive DC’s” Panel

Open the Software Component sap.com_SAP-SHRWEB or SAP-CRMWEB

Select the Development Component of the web application you want to modify (E.g.crm/isa/web/b2b) and Choose “Create Project” from the context menu (right mouse click). Accept thelist of Components to be synched.


August 2008 144

Figure 22: Extend and Modify CRM Web Apps

• Do all modifications in SAP-CRMWEB or SAP-SHRWEB

• Put own Java classes in Development component crm/home/shr/ext or crm/home/crm/ext

• Add the used relationship to these components to all web modules which need the java extensions

• Modify the jsp‘s in the SAP original components in order to be able to do conflict resolution whenapplying new patches

Extensions of the Java CodeThe Software Component SHRWEB contains the Development Component crm/home/shr/ext. It’s designedto contain customer Extensions. By default it contains no classes. Create new Java classes as follows:

Open the Netweaver IDE and connect to the CRM Track.

Open the Development Configuration Perspective:Choose Window -> Open Perspective -> -> Development Configuration in the Netweaver IDE menu.

Select the “Inactice DC’s” Panel

Open the Software Component sap.com_SAP-SHRWEB

Select the Development Component crm/home/shr/ext and Choose “Create Project” from the contextmenu (right mouse click). Accept the list of Components to be synched.

Now you can add new classes to the Development Component in the Java Perspective of the NWDI.Refer to the NWDI Online help for more detailed informations.

The web applications Development Components have no Used Relationships to crm/home/shr/ext. If theclasses are required by a web application, the Used Relationship to the public part “assembly” must beadded for the Web Module Development Component of the application. Search for “Changing Used DC” inthe online documentation of the SAP Netweaver IDE to find out how to do this.

E.g. If crm/isa/web/b2b needs classes of crm/home/shr/ext, the Used Relationship must be created incrm/isa/web/b2b. It must refer to crm/home/shr/ext.


August 2008 145

Merged Web ApplicationsAll CRM Java applications have the same structure. There are some files which need to be available in allapplications.

For this reason, there is a shared web component DC introduced. This development component type isbased on a regular Java Development Component with a public part of purpose "compilation". Despitenormal java development components the shared web components contain web files to be shared in thesrc/packages directory. These files can be merged into other web archive Development Components bydefining a used relationship in the web module to the shared web component.

Figure 23: Merged Web Files

Shared components are java Development Components.

CRM web archive must not contain java classes, because the compile time dependancy has aspecial meaning!

Files in src/packages directory of the shared component will be merged into the web archive at buildtime

Shared files can be overwritten by files in the web archive if they have the same name and directory

Handling of duplicate filesIf the a file with the same name and directory exists in two different shared web components, it's notpredictable which version of the file will be merged into the web module.

If a file is contained in one shared web component DC and in the web module DC, the version of the file fromthe web module will be in the generated web application.

RestrictionsDue to the fact, that the used relationships to java development components are used for merging web files ,they can't be used for compiling. So, CRM java applications should not contain java source files.


August 2008 146

Initial Configuration of the NWDIThis section describes how to configure the JDI in order to start modifying the CRM software components.The steps in this chapter are relevant immediately after an installation (the next chapter describes the stepsneeded to handle a Support Package upgrade).

Pre-requisitesThis chapter assumes that you have met the following pre-requisites:

You know how to work with the NWDI. Please refer to the documentation mentioned in chapter“Centrally: SAP NetWeaver Java Development Infrastructure”, if you need more informationabout this.

NWDI has been installed

The NWDI online configuration has been executed

The System Landscape Directory (SLD) has the new content (of the Software Componentsdelivered with this release).

Creating a project specific Web Application withown context rootIn order to be able to compare the SAP standard web applications with the extended applications, it makessense to have two deployments. The first one is the one delivered by SAP, the second one contains projectspecific extensions. This chapter describes how to set up such an application.

Figure 24: Project specific application in CUSTCRMPRJ

• Copy original Software Component from SAP-SHRAPP to CUSTCRMPRJ

• Change Context Root

• Exclude SAP-SHRAPP from deployment



August 2008 147

Basic conceptCreate a new project specific software component in the SLD. Enable deployment in the track.

Add this component to your track for modification.

Create a development component of type “Enterprise Application” for each application you plan to modify

Copy all files of the SAP standard Enterprise Application to your own Software component (exceptapplication.xml).

Add the used relationship to the public part of the Web Module Development Component to the newDevelopment Component.

Check in the files.

Only the new Software Component will get the extended version of the application. These versions will bedeployed on the Web AS Java System by NWDI.

The SAP standard component SAP-CRMDIC, SAP-SHRAPP and/or SAP-CRMAPP can be deployed directlyto the Web AS Java Server.

Step by step process

Check SLD content and create a new Software ComponentIf you installed the NWDI Infrastructure by installing usage type DI, the SLD content was importedautomatically. This content may not be up-to-date.

Check whether the Software Component CRM JAVA CUSTOMER PROJECT 5.0 exists in the SLD:

If tbis component is missing, you import an update of the CIM Model from the service market place. Refer toNote 669669 for more details.

You'll find more information about SLD and maintenance of Software Dependancies at http://help.sap.com

Create a new Track using the Landscape ConfiguratorOn the “Track Data” tab of the Landscape Configurator, enter the general data as shown below:

Figure 25: Creating a new Track

Substitute the URLs with the appropriate ones from your landscape.


August 2008 148

Add Software Components to trackOn the same “Track Data” tab, add the following Software Components

CUSTCRMPRJ (Package Type: Source + Archive)

If you need to modify one or more of the components contained in SAP-SHRAPP:

SAP-SHRWEB (Package Type: Source + Archive)

SAP-SHRAPP (Package Type: Source, Exclude from Deployment)

If you need to modify one or more of the components contained in SAP-CRMAPP:

SAP-CRMWEB (Package Type: Source + Archive)

SAP-CRMAPP (Package Type: Source, Exclude from Deployment)

If you need to modify the Java Data Dictionary:

SAP-CRMDIC (Package Type: Source + Archive optional)

An example is shown below:

Figure 26: Adding Software Component

After this step, the bottom half of this tab will look as shown below:

http://help.sap.com/saphelp_nw04/helpdata/en/35/1cd66947184aa8915ca1831c59b6c1/content.htm


August 2008 149

Figure 27: Required Software Components

As shown, the following “Required Software Components” are automatically populated:

SAP_JTECHS SAP-JEE SAP_BUILDT …

Save your changes by clicking on the “Save” button on this tab.

Configure Runtime Systems in the trackConfigure your runtime systems as described in the following topic in the help portal:

http://help.sap.com/saphelp_nw04/helpdata/en/35/1cd66947184aa8915ca1831c59b6c1/content.htm

http://service.sap.com/patches


August 2008 150

Import Software Components into this track

Download ArchivesThe Software Component archives ( .sca files ) must be downloaded from the Service Marketplace (http://service.sap.com/patches ) and placed into the “inbox” folder of the CMS. (The “inbox” folder can befound under the following path: “<CMS Transport Directory>\CMS\inbox”, where the <CMS TransportDirectory> is specified in the “Domain Data” tab of the CMS Landscape Configurator).

The following .sca files must be placed into the CMS inbox folder:

o SAP_JTECHS.scao SAP_BUILDT.scao SAP-JEE.scao SAP-SHRJAV.scao SAP-SHRWEB.scao SAP-SHRAPP.scao SAP-CRMJAV.scao SAP-CRMWEB.scao SAP-CRMAPP.scao SAP-CRMDIC.scao SAP-IPCMSA.scao STRUTS.scao TEALEAF.sca

The names of .sca files could be different – they may include version numbers, vendor name,etc.

Check-In archivesIn the “Check-In” tab of the CMS Transport Studio CMS perform a “Check-In” : select each of the abovearchives and click on the “Check-In” button.

Figure 28: Check-In of the Archives


August 2008 151

Import the checked in archives into the Development systemIn the “Development” tab, select the checked-in components and click the “Import” button.

Figure 29: Development System

This import will run for several hours (if all the components are selected together). After the import the “state”(field on the extreme right in the picture above) will be shown as “Import Finished”

Import the checked in archives into the Consolidation systemRepeat the above step in the “Consolidation” tab.

Create your own Enterprise ApplicationsThe following steps need to be done:

Import the Development Configuration into your Netweaver IDE.

Create a new Enterprise Application Development Component in Software ComponentCRMCUSTPRJ.

If you want to extend crm/b2b, create a new development component home/b2b

Add the Web Module you want to extend to the Enterprise Archive

Adjust the context root

Copy all files except application.xml from the META-INF directory of SAP standard EnterpriseArchive into the META-INF directory of the new Development Component.

If you want to modify or extend the crm/b2b application, open the project for crm/b2b. A projectfor the previously created development should already be open.Open the java perspective and copy the following files from the META-INF directory of the crm/b2bcomponent to the META-INF directory of the home/b2b component:

o application-j2ee-engine.xml

o data-source-aliases.xml

o log-configuration.xml

o monitor-configuration.xml

o monitor-configuration.dtd

Check in the new Development Component.

Look at the online help of the Netweaver IDE for more details on how to execute these steps.

http://help.sap.com/saphelp_erp2005/helpdata/en/1c/bca99c220c0e45a1cae3c4cccf4346/frameset.htm


August 2008 152

Test the CRM Java application on a local Web AS Java EngineIn order to be able to run CRM Java applications you need to deploy the SAP-CRMDIC software componenton your local Web AS Java engine. It contains all required database table definitions.

Additionally you need to deploy the enterprise application of the application you want to test.

The deployment of the enterprise application Development component can be started in the Developmentconfiguation perspective of the Netweaver IDE:

Look at the online help of the Netweaver IDE for more details.

Creation or Extensions of Java ClassesThis chapter describes how to create new java classes or extend existing ones in the NWDI.

In Software Component SAP-CRMWEB and SAP-SHRJAV, java development components are prepared tobe extended in the NWDI. For SAP-CRMWEB the java DC is crm/home/crm/ext, for SAP-SHRWEB it’scrm/home/shr/ext. These components are empty when shipped.

A used relationship in the web module development components of the applications to the java developmentcomponents needs to be added, for each application which uses the new classes.

In the java development components a lot of used relationships to the most common SAP standard javadevelopment components are already defined. If a new java class needs further references to other javadevelopment components, new used relationships need to be added.

E.g. If a new class in the crm/home/shr/ext needs a class contained in crm/isa/isacorer3 for compiling, anew used relationship in crm/home/shr/ext to the public part default in crm/isa/isacorer3 needs tobe added.

More details of Used Relationships can be found athttp://help.sap.com/saphelp_erp2005/helpdata/en/1c/bca99c220c0e45a1cae3c4cccf4346/frameset.htm

or in the online help to the SAP Netweaver IDE.


http://service.sap.com/crm-inst


August 2008 153

Importing Modifications and Extensions from olderReleasesThis chapter describes how to import modifications and extensions from former Releases (CRM 3.0, 3.1 and4.0) to a NWDI track (>= CRM 5.0). It assumes that the buildtool was used to build the modified applicationand that there is a new NWDI track available to import the extensions and modifications. It further assumesthat basic knowledge about NWDI is available.

The “SAP Customer Relationship Management 5.0 Java on <Operating System> : <Database>” guidedescribes how to install the NWDI.

See http://help.sap.com for informations about administrating the NWDI

See Online help of the Netweaver IDE for informations about usage of DTR and DevelopmentConfigurations.

Importing buildtool to NWDI for releases lower CRM 5.0 to a higher releaseIn general the following steps are required for CRM 3.0, 3.1 and 4.0

1. Replace “sapmarkets” with “sap” in all source codes and web files

2. Merge the modifications of the web files to the new release in the NWDI

3. Copy the java extensions into the NWDI

4. Make source code compilable (if required)

In note 594370 is a new version of the buildtool attached. It contains an additional ant target named “nwdi”.This command executes the replacement of sapmarkets with sap and copies the result to a folder structurewhich can be imported to the NWDI track. You can call this target in the same way as you execute the othertargets like build “extract.ears”.

To install the buildtool do the following steps:

Step Description

1 Update the build toolNote 594370 contains a description of the upgrade procedure.

2 Execute target “nwdi” with the buildtoolThe documentation of the buildtool contains a description how to execute an anttarget (http://service.sap.com/crm-inst -> E-Commerce Installation Guides -> E-Selling: Building&Updating Mod. Internet Sales Web Applic. )

3 Create a java project for the Development Component from DTR.

There are two predefined development components(DC) available to import javaextensions:

1. The DC crm/home/shr/ext in Software Component SHRWEB

2. The DC crm/home/crm/ext in Software Component CRMWEB

The crm/home/shr/ext is designed to hold extensions of the java sources in SoftwareComponent SHRJAV. Crm/home/crm/ext ist designed to hold extensions of the javaclasses in Software Component CRMJAV.

Hint: It’s possible to create an own Software Component, an own Development orboth to hold the java source. In this case the required used relationships of theSoftware Components have to be setup on the nameserver and the used


August 2008 154

relationships to the Development Components need to be maintained.

Step Description

4 Copy the java code into the development component selected in the previous step.

The buildtool target nwdi created a directory <buildtool root>/nwdi/<project name>.

Where <buildtool root> stands for the installation directory of the buildtool and<project name> stands for the project name enetered in the buildtool duringinitialization.

Copy the content of this directory to the <NWDI Configuration root>/<ConfigurationNumber>/DCs/sap.com/crm/home/shr/ext/_comp or to <NWDI Configurationroot>/DCs/sap.com/crm/home/crm/ext/_comp

<NWDI Configuration root> stands for the root of the NWDI. See Windows->Preferences->Java Development Infrastructure -> Development Configuration ->root Folder in the Netweaver IDE to get this value

<Configuration Number> stands for the number of the imported DevelopmentConfiguration(normally this is 0)

5 Execute a build for the java Development Component in the IDE.

Hint: For the predefined DC’s the most important used DC relationships are alreadyestablished. However it might be necessary to add further Used Relationships tomake the extensions compilable.

6 Create a java project for the Web Module Development Component to be modifiedor extended.

The Web Module Development Components are located either in CRMWEB or inSHRWEB Software Component.

The naming convention for Development Components is as follows:

crm/<isa|ipc|wfd|eservice|icss>/web/<application name>

When the project was created, you will find the _comp folder of the component here:

<NWDI Configuration root>/<Configuration Number>/DCs/sap.com/<DevelopmentComponent name>/_comp

Hint: If the IDE will not automatically check that the new files have been added. Afterexecuting a refresh on the java project the files will be displayed and you will beasked to add them to DTR.

7 Add the new java files to an DTR activity

8 Check out the web files to be modified or extended from DTR

9 Merge the modifications and extensions of the web files to the CRM 7.0 Web Module_comp folder.

The buildtool target nwdi created a directory <buildtool root>/nwdi/<applicationname>_<project name>.

This directory has the same structure as the same directory structure as the WebModule Development Components.

Some of the files shipped in the new release might differ from the older versions ofthe files, so it’s not possible to copy the modified files into the _comp directory butthe changes need to be merged into the new version.

Step Description

10 If you added java classes and you want to use them in the modified web application, you need toadd the java Development Component to the list of Used DC’s of the Web Module. Look at the


August 2008 155

netweaver ide’s online help for the detailed procedure.

Example: If you added classes to crm/home/shr/ext and you want to use it in the b2b application,you need add the public part assembly of component crm/home/shr/ext to the list of used DC’s ofcrm/isa/web/b2b. Make sure that you created a project for the crm/isa/web/b2b component.Otherwise you are not able to add a used DC relationship.

11 Check in all activities into DTR and activate them

NWDI Release upgrade from older releases ( >= CRM 5.0) to a higher releaseFollowing you will see the steps which are necessary to do the import for sources.

1. Update CIM ModelDownload from service marketplace (Support Packages and Patches -> SAP Technology Components ->SAP CR Content) the right SAP Component Repository which fits to your configuration. It is used to informNWDI about dependencies between software components archives.

2. Change Track (Update Versions)Upload downloaded CIM model to your SLD in CMS

Update CMS in Landscape Configurator of CMS


August 2008 156

Synchronize SC Dependencies in CMS

http://help.sap.com/saphelp_nw70/helpdata/EN/4f/feda41cabae23ee10000000a155106/frameset.htm

http://xads.wdf.sap.corp:8000/sap(bD1lbiZjPTgwMA==)/bc/bsp/sap/zidesinfobase/detailareaframe.htm?theme=STANDARD&aview=1&scenario=010000005762&inframe=

http://xads.wdf.sap.corp:8000/sap(bD1lbiZjPTgwMA==)/bc/bsp/sap/zidesinfobase/detailareaframe.htm?theme=STANDARD&aview=1&scenario=010000005762&inframe=


August 2008 157

After clicking on the synchronisation button the following popup may appear if inconsistencies in theDependency Definition exist. Since the current Dependency Definition is located in the SLD, therefore usethe button ‘Accept SLD Definition’.

You can find more details about resolving the inconsistencies in the following help page:http://help.sap.com/saphelp_nw70/helpdata/EN/4f/feda41cabae23ee10000000a155106/frameset.htm

After synchronization and all lights are green you have to save. In some cases there could be yellow or redlights. In this case you have to change the XML content of the Software Component which are not OK.

3. Import Software Component Archives (SCA)In CMS open Check-In for your track and select all SCAs which should be imported.

4. Resolve integration collisions

How to do the single steps, please have a look into the SAP tutors onhttp://xads.wdf.sap.corp:8000/sap(bD1lbiZjPTgwMA==)/bc/bsp/sap/zidesinfobase/detailareaframe.htm?theme=STANDARD&aview=1&scenario=010000005762&inframe=

Developer WorkplaceWhen we look at the architecture of SAP E-Commerce 5.0 we will discuss the following components:

Java Development Kit (JDK)

SAP Web AS Java

o SAP J2EE Application Server

o SAP Java Connector (JCo)

o SAP Java Basis

http://java.sun.com/products/


August 2008 158

Internet Sales Web application (ISA) (Interaction and Presentation Layer, Business Object Layer,BLS Layer)

All examples and operating system specifications in this document refer to Windows.

InternetInternetBusinessExecutionBusinessExecution

Business ServiceBusiness Service

R/3-System

Presentation

BW

APO = Advanced Planner & OptimizerBW = Business WarehouseIPC = Internet Pricng & ConfiguratorBLS = Business Logic Service LayerJCO = Java ConnectorBP = Business PartnerPC = Product CatalogPM = Product Master

APO = Advanced Planner & OptimizerBW = Business WarehouseIPC = Internet Pricng & ConfiguratorBLS = Business Logic Service LayerJCO = Java ConnectorBP = Business PartnerPC = Product CatalogPM = Product Master

mySAP CRM

J2EE Appl.Server BrowserBrowser

BrowserBrowser

BrowserBrowser

APO

R/3 3.1H + CRM 3.0

Interaction andPresentation LayerInteraction andPresentation Layer

Business Obj. LayerBusiness Obj. Layer

BLS LayerBLS Layer

PM

BP

BPOrder

PM PC

Order

Plug In

Middlew

are

WebServerWeb

Server

IndexServerIndexServer

IPCIPC

JCO

Figure 30: Overview Developer Workplace

Required tools and versionsSAP CRM 7.0 is based on SAP NetWeaver’04s. There the following software component versions arecontained or required:

Component Version

SAP Web AS Java 7.00

JDK 1.4.2

IDE SAP NetWeaver’04s Developer Studio

Java Development KitThe Java Development Kit represents the Java Virtual Machine (JVM), which is a prerequisite for the SAPWeb AS Java (Servlet Engine). In addition, JDK offers options for compiling, executing and debugging Javaapplications.

Installation of JDK 1.4.2Download the JDK from the sun homepage http://java.sun.com/products/.

Select the version you require from the drop down list box ‘Java 2 Platform, Standard Edition (J2SE)’.

Make sure that you download the ‘SDK’ and not the ‘JRE’!


August 2008 159

Once j2sdk-1_4_2_XX-windows.exe (where XX is the number of the patch) has been downloaded, you haveto execute it. A destination location <JAVA_HOME> must be chosen and you have to select the followingcomponents for installation:

Program files

Native interface header files

Old native interface header files

Demos

Java sources

Once JDK 1.4.2 has been successfully installed, the JAVA_HOME environment variable must still be set insuch a way that the Java compiler can be found (SET JAVA_HOME=<JAVA_HOME>). You also have toappend the ‘<JAVA_HOME>\bin‘ directory to your environment variable ‘path’. These settings can beconfigured, for example, in the Windows environment in the system properties, which can be accessed viathe control panel (System Settings Control Panel) and by double clicking on the Systems icon. Pleasemake sure that the PATH environment variable is expanded to the binary directory underneath the jdk1.4.2directory. If this was not done automatically, for example, during the manual installation of JDK, you can dothis as illustrated in the graphic above or with the command:

(SET PATH = ...;%JAVA_HOME%\bin).

Then the SDK is ready to run and can be tested by typing in java – version in the command prompt.

http://service.sap.com/instguides


August 2008 160

Developer Workplace for SAP NetWeaver 2004sThe SAP Developer Workpace consists of the following Componentes:

SAP NetWeaver Developer Studio

Max DB or MS SQL Server

SAP J2EE Central Instance (J2EE dispatcher, J2EE server process, SDM)

SAP J2EE Central Service (Message Server, Enqueue Server)

Figure 31: Developer Workplace for SAP NetWeaver 2004s

Installing the Developer Workplace for SAP NetWeaver 2004sThe installation of the SAP Developer Workplace is described in the “Installation Guide - DeveloperWorkplace for NW2004s”, that is available on the SAP Service Marketplace quick link instguides(http://service.sap.com/instguides) SAP NetWeaver Release 2004s Installation (in the list 3 -Installation - Standalone Engines & Clients).


August 2008 161

Directory Structure of the Web AS Java 7.0Once it has been installed, the directory of the Web Application Server is structured as follows:

Root

SAP SID

JC<INSTANCE_NUMBER>

Visual Administrator

Server directoryContains deployed web applications

Logfile directory (also contains the ECO log entries)

SAP Web AS Configuration Tool

SDM directory

Figure 32: Directory Structure of Web AS Java 7.0

TCP-PortsThe ports used by the Central J2EE Instance are determined by the instance number, which is entered withinthe installation and can be calculated with the following formula:

<Base port> = 50000 + 100 * <INSTANCE_NUMBER>

Name Formula DescriptionHTTP <Base port> + 0 Used to access the Central J2EE Instance using a browserP4 <Base port> + 4 Used to connect to the J2EE Server Processes with the

administration tools (e.g. Visual Administrator)Telnet <Base port> + 8 Used to manually administrate the J2EE Server Processes (if you

don’t use the Visual Administrator)


August 2008 162

Example

The SAP WebAS Java has been installed on the server with instance number 00. The used HTTP port isthen 50000.The actual used ports can be checked using the configuration tool under Cluster/Dispatcher -> services ->http, p4, telnet.

Starting and Stopping the WebAS JavaSince NetWeaver’04, the SAP Management Console is used to start and stop the Web AS Java. Each WebAS Java consists of two nodes:

The Central J2EE Instance and

The database instance.

To start/stop the Web AS Java, open the SAP Management Console, select the Web AS Java Instance andpress the start/stop button in the button bar.

Figure 33: SAP Management Console

Configuration of SAP WebAS Java 7.0The SAP WebAS Java 7.0 can be configured using the configuration tool.

Central J2EE InstanceDatabase Instance

http://service.sap.com/instguides

http://localhost:50000/<APPLICATION_NAME>/admin/xcm/init.do

http://localhost:50000/b2b/admin/xcm/init.do

http://localhost:50000/b2b/b2b/init.do


August 2008 163

Uninstalling the Developer Workplace for SAP NetWeaver2004sHow to uninstall the Developer Workplace for SAP NetWeaver 2004s is described in Appendix of the“Installation Guide - Developer Workplace for NW2004s”, that is available on the SAP Service Marketplacequick link instguides (http://service.sap.com/instguides) SAP NetWeaver Release 2004s Installation(in the list 3 - Installation - Standalone Engines & Clients).

Configuring and Working with Developer StudioThis section describes manual deployment of an SAP E-Commerce web application. The focus of this guideis to enable consultants to quickly get started using the new concepts used by SAP and set up a localdevelopment landscape that enables them to implement customer requirements. This local developmentlandscape can differ from the production environment. Consultants can install variants on their laptops.

Configuration of the web applicationThis section describes the configuration of the Internet Sales application. In Internet Sales 5.0 the ExtendedConfiguration Management (XCM) is used to configure the web applications. The tool, used to configurethem, is the XCM Admin. This tool is contained in every web application. You have to configure eachapplication with it’s own XCM Admin. For more details how to configure the web applications please see the

1. To access the XCM Admin please use the following URL:http://localhost:50000/<APPLICATION_NAME>/admin/xcm/init.do (for example:http://localhost:50000/b2b/admin/xcm/init.do).

Create customer specific ‘Application Configurations’ or configuration ‘Components’ from SAPconfiguration default templates.

2. Restart the web application through the SAP J2EE Visual Administrator, for example,<J2EE_HOME>\admin\go.bat -> Server -> Services -> deploy. Click to tab strip Runtime Selectapplication and click -> Stop Application -> Start Application.

3. Create shop definitions refering the corresponding backend system using the Shoadmin webapplication.

4. You can call the application via the URL, for example, http://localhost:50000/b2b/b2b/init.do. Pleasenote that links that end in ‘.do’ are forwarded as events to the ActionServlet that is defined andconfigured in the web.xml file. The following entry is required in the web.xml file to ensure correctforwarding:

5. The servlet mappings are configured in the config.xml in the directory WEB-INF of your webapplication.

We recommend you perform all customer enhancements on a copy of the original EAR file. Youcan create a copy with the ISA Buildtool.



<servlet-mapping>

<servlet name>action</servlet name>

<url-pattern>*.do</url-pattern>

</servlet-mapping>


August 2008 164

Remote DebuggingThis unit gives you some information about remote debugging on the SAP J2EE server. This information isuseful if you extend the ISA application by writing your own Java code, and want to debug this code while itis being executed on the server.

Setting up remote debugging for SAP WEB AS Java 7.0This section describes the necessary configuration of Eclipse for remote debugging of a web applicationrunning on the SAP J2EE server.

To debug your coding, you have to:

- Enable debugging on the Web AS (either temporarily or permanently)

- Start Remote Debugging

Enabling/Disabling Debug Mode PermanentlyTo enable/disable the debug mode of the SAP Web Application Server Java 7.0 permanently, perform thefollowing steps:

1. Start the Visual Administrator by executing

<DRIVE>:\usr\sap\<SID>\JC<INSTANCE-NUMBER>\j2ee\admin\go.bat.

2. Connect to the Web AS with an user of the role Administrator.

3. Navigate to Cluster Server Services Configuration Adapter.

4. In the Display configuration tab navigate to Configurations cluster_data and select Propertysheetinstance properties IDXXXXXXX.

5. Change to the Edit mode by pressing the change/view button in the button bar of the tab andconfirm this by pressing yes.

6. Press the Edit button . A new popup will appear.

7. Select IDXXXXXXX.DebugMode, change the Custom value to ‘yes’ and press the button ‘ApplyCustom’.

You could also change the debug port by clicking on IDXXXXXXX.DebugPort.

8. Restart the server.


August 2008 165

Figure 34: Visual Admin - Setting Up Debug Mode

Enabling/Disabling Debug Mode TemporarilyTo enable/disable the debug mode of the SAP Web Application Server Java 7.0 temporarily, perform thefollowing steps:

1. Start the Net Weaver Developer Studio.

2. Switch to the J2EE Engine View (menu Window Show View Other… J2EE J2EE Engine)

3. Select the Server Node.

4. Open the context menu (by clicking the right mouse button) and select Enable Debugging ofProcesses.

Figure 35: J2EE Engine - Enabling Debugging


August 2008 166

Starting Remote DebuggingPerform the following steps in your SAP NetWeaver Developer Studio:

Open the menu Run Debug…

Select Remote Java Application and press the button New

Host name. The host, where the process being debugged runs.

Type: dt_socket

Address: the port. This has to correspond with the -Xrunjdwp:address setting.

Figure 36: Starting Remote Debugging

For further information on how to set up remote debugging on SAP NetWeaver Developer Studio (NWDS),please refer to the NWDS documentation.


August 2008 167

ABAP DebuggingSince SAP Netweaver 2004 it’s no longer possible to debug ABAP code from Java side. This chapterdescribes how to debug ABAP code in SAP E-Commerce 7.0.

In SAP E-Commerce 7.0, you have to use HTTP/external debugging to analyze ABAP code called from theJava side. The following procedure is necessary to start a debug session:

PrerequesitesTo be able to perform external debugging, the following prerequisites must be met:

- the SAPGui has to be installed on the host, where the RFC (of HTTP/HTTPS/SMTP) calls areperformed, e.g. the host, where the SAP Web AS is running on.

- Since load balancing is not supported, yu have to configure your web application to connect to asingle server. To do this perform the steps listed below:

o Open a browser and access the XCM Admin of your web application (URL:http://<hostname>:<port>/<appl-name>/admin/ xcm/init.do):

o Navigat through the tree on left to Start Components Customer and select jco

o Press the Edit button in the upper right corner.

o Enter an arbitrary name and press the Create button.

o Choose server_connect from the drop down list box as Base Configuration

o Enter the connection data of the particular server. You can get the values for the parametersashost and the system number from the SAPGui:

Start SAPGui and switch to the System tab

Press the button New Entry

Enter the System ID and double click on the particular entry in the list.

Open the properties of the message server you want to connect by double clickingon it.

Enter the message server as value of the parameter ashost.

Enter the System number

o Navigate in the tree on the left to Start Application Configuration Customer and selectthe configuration you want to use.

o Change the value of the parameter jcodata to the component you just created

o Press the Save button.

o Press the Display button in the upper right corner.


August 2008 168

Activating ABAP Debugging

1. Start the SAPGui and logon to the server you configured in the XCM

2. Go to any Development Workbench (transactions SE37, SE38, SE80).

3. Select the menu item Utilities Settings, switch the tab ABAP Editor and there the tab HTTPDebugging.

4. Enter the ID of the SU01 user, you use to logon to your webapplication

You have to maintain the ID of the SU01 user, not the alias!

For debugging the user must have debug authorizations. Please ensure this via settingappropriate roles or profiles via transaction SU01. Normally the profile “S_ENTW_SHOW”should be adequate (for detailed information see note 668252).It’s recommended to create new “Debug users” for such function. Do not add theseauthorizations to existing “productive users” because of security reasons.

5. Open your ABAP coding and set an External Breackpoint by pressing CTRL+Shift+F9 or by pressingthe button Set/Delete External Breakpoint .

6. Start your web application. When within the web application, with the specified user the ABAPcoding will be called, the set breakpoint will be executed.

For detailed information and further questions please refer to the notes 668256, 668252 and751872.

Java Debugging

If you want to debug the Java coding deliverd by SAP, but the coding has not been attached tothe .jar files, refer to note 932457. There you’ll find instructions how to attach the SAP Javacoding to the jar files.


August 2008 169

Introduction to Extension Concepts

Extensions in the ISA FrameworkThe first part of this unit gives an overview of possible extensions and extension concepts. It should help youto find an appropriate extension concept for specific requirements. The subsequent parts of the unit givetheoretical introduction to the various extension concepts of the Internet Sales framework. The concepts inthis unit provide the basis for the Examples and Tutorials provided in the ‘Development and Extension Guide:E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305).

The following table gives an overview of possible changes in different layers:

Layer Possible Extensions

Interaction Layer Action flow has to be interfered in order to get/set additional data.

Business Object Layer Custom Business Objects process additional data.

Business Logic Service Layer Custom Backend Object provides connectivity to backendfunctions

Calls to function modules are interfered (before and afterfunction call)

Custom function modules are called instead of the standardmodules

Backend (e.g. CRM) New/enhanced functions (for example, extension of existingfunction modules, new function modules).

These extensions are not covered by this document.Table 32: Overview of possible changes in different layers


August 2008 170

CustomAction

CustomBusinessObject

CustomBackendObject

CustomFunction Module

customer datahas to be entered

or displayed

Possibleextensions in

all layers

Figure 37: Flow of possible changes

The E-Service Extended Complaints and Returns application and the Remanufacturer’s Inspection uses theISA Framework and, as a consequence, supports the extensions to the ISA Framework.


August 2008 171

Finding the Appropriate Extension Concept

How to use these diagramsThe following diagrams should help you to find, step by step, the appropriate extension concept dependingon your individual requirements. Each diagram has one starting point referring to different branches. Thebranches describe different requirements (i.e. what you want do), where you have to check according to yourrequirements which branch is the right one for you. The result of each branch could be a reference toanother lower level diagram, or a description of what to do, together with a reference to the detaileddescription of the available extension concept, with examples.

OverviewStart here to find the appropriate extension concepts or just to get an overview of different categories ofextensions.

Static extensions to theUI-Layer (colors,

images, texts)

Additional data shouldbe exchanged betweendifferent layers (UI, BO,

BE)

End

Extensions toexchange additional

data

StartExtension to ISA

TerminatorReference to sub

diagram withmore details

What to do -Reference to detailed

descriptionDecision

Requirement -What you want

to do

Legend:

Action flow should bemodified or extended

Extensions to theaction flow

Static extensions tothe UI layer

Figure 38: Overview of different categories of extensions


August 2008 172

Extensions to the UI LayerThis diagram gives an overview of how to realize static extensions which only affect the UI layer.

Texts on the UI shouldbe changed/added/

removed

Colors of the UI shouldbe changed

End

StartStatic extensions to the

UI layer

Change/add text in thetext property file (language

dependent!)

Rearrange UI elementswithin JSP and/or to other

JSP

Images on the UI shouldbe changed/added/

removed

Arrangement of UIelements should be

changed (e.g. frames,texts, buttons, images)

Change colors in styledefinition (CSS)

Replace (standard) imageor add new image

Add/remove text from JSPChange colors of staticimages (e.g. buttons,

frames)

Add/remove image fromJSP

(If required) Adjust frametargets in JSP’s and in

action flow configuration.

Figure 39: Statis extensions to the UI layer

For details see:

Chapter Extensions to the UI layer on page 190

Chapter ‘Extensions Limited to the UI Layer’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305) withexamples for extension


August 2008 173

Extensions to the Action FlowThis diagram gives an overview of how to realize extensions to the action flow, like adding or replacingactions, and writing new actions.

The action flow shouldbe modified by adding/

removing other(standard or customer

specific) actions

The action flow shouldbe modified by changingthe action forward of a

specific (standard)action

End

StartExtensions to the

action flow

Modification of the actionflow in configuration3)

Derive new action fromstandard action andimplement user exit2)

Appropriate user exitavailable in standard action1)

Create new action fromstandard action2)

no

yes

Register new action flow inconfiguration3)

Figure 40: Extensions to the action flow

For details see:1) Standard Actions providing User Exits on page 1932) Create a Customer Action on page 1913) Modifications in the Struts Configuration

on page 197


August 2008 174

Extensions to Exchange Additional DataThis diagram is the entry point to all extensions related to the exchange of additional data, which are themost common types of extensions. Typically, the additional data has to be displayed on the UI and has to beretrieved from a backend system, or should be entered on the UI and have to be transferred to a backendsystem. These kind of extensions always affect all ISA layers.

Should the additional databe exchanged with a

backend system?

Additional data shouldbe displayed or shouldbe entered on the UI

Additional data shouldbe transfered between

the web applicatiion anda backend system

no

End End

yesExtensions toexchange data with

the UI-layer

Extensions toexchange data with a

backend system

StartExtensions to exchange

additional data

Figure 41: Extensions to exchange additional data


August 2008 175

Extensions to Exchange Data with the UI-LayerThis diagram shows the necessary steps to display or enter additional data on the UI and to transfer thisadditional data with the underlying action classes.

Figure 42: Extensions to exchange data with UI layer

For details see:1) ‘Extensions to the UI layer’ on page 190 and chapter ‘Extensions Limited to the UI Layer’ in the‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapterReferences on page 305).


August 2008 176

This diagram shows how to transfer additional input data from the http request (from submitting the HTMLform) to the action class and, from there, to the busines object layer.

Figure 43: Transfer additional input data to action class and business object layer

For details see:1) Standard Actions providing User Exits en page 1932) Create a Customer Action on page 1913) Create a Customer Action on page 1914) Depends on the question if the additional data should be transferred to a backend system and howthis can be performed. See also: Storing Additional Data - Extension Mechanism en page 1975) Create a Customer Business Object on page 200


August 2008 177

6) Request Context en page 2227) ’Extension Demo 1 – Add New Entry Fields’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305).


August 2008 178

This diagram shows how to transfer additional output data in the action class to the JSP.

Figure 44: Transfer additional output data from aciton class to JSP

For details see:1) Standard Actions providing User Exits on page 1932) Create a Customer Action on page 191 and Modifications in the Struts Configuration on page 197


August 2008 179

Table 38: User exits within the Remanufacturer’s Inspection ApplicationAccessing the Session Context on page 1954) Accessing the Session Context on page 1905) Request Context en page 222


August 2008 180

Extensions to Exchange Data with Backend-SystemsThis diagram is the entry point to extensions related to exchange of additional data between the businessobject layer and any backend system.

Retrieve data from abackend system

Transfer data to abackend system

End

StartExtensions to exchange data

with a backend system

Extensions toexchange data withthe Web Catalog

Extensions toexchange data with

an IPC system

Extensions to retrievedata from a R/3

system

Extensions to retrievedata from a CRM

system

End


Web Catalog


an IPC system

Extensions totransfer data to a

R/3 system

Extensions totransfer data to a

CRM system


the Java Basket


the Java Basket

Figure 45: Extensions to exchange data with the backend systems


August 2008 181

This diagram shows how to retrieve additional data from a SAP CRM system to the business object layer.

Figure 46: Retrieve additional data from SAP CRM system to business object layer

For details see:1) ‘Standard call’ means that the backend system is called via a function call within the standardprocess flow. The function module itself does not have to be a standard function call (see ReplacingCalls to Standard Function Modules (Backend System) on page 227)2) Create a Customer Business Object on page 200 and Create a Customer Business ObjectManager on page 2003) Supported Function Modules and Business Objects on page 212 Table 47: User exits for forPricing or ConfigurationCreating new Customer Backend Object on page 2085) Create a Customer Backend Object on page 2046) Interception of Calls to Standard Function Modules on page 2257) Request Context on page 222


August 2008 182

This diagram shows how to transfer additional data from the business object layer to a SAP CRMsystem.

Data stored in therequest context

Data stored in a(customer) business

object

StartExtensions to transfer data to

a CRM system

Implement JCO eventlistener class.2)

Read data from requestcontext3)

Create new backendcIass. Implement method

to call CRM functionmodule4)

Data stored within astandard business

object as extension data

yes

End

Call function modulein CRM system

No action required

Processingwith other data or

preprocessing beforetransfer required

Extension data of CRMfunction module can be

used1)

no

yes

no

Figure 47: Transfer additional data from business object layer to SAP CRM

For details see:1) Supported Function Modules and Business Objects on page 2122) Interception of Calls to Standard Function Modules on page 2253) Request Context on page 2224) Create a Customer Backend Object on page 204


August 2008 183

This diagram shows how to call a SAP CRM system from the backend layer.

No extension ofinterface or of the logicof the standard function

module required

Extension of interfaceand of the logic of the

standard functionmodule required

StartCall function module in CRM

system

No extension ofinterface but extension

of the logic of thestandard functionmodule required

Create customer functionmodule with extendedinterface of standard

function module

Create customerimplementation of BADI1)

recomm.concept

recomm.concept

Create customer functionmodule

End

Use standard backendobject and implement JCO

event listener class3)

Use standard backendobject -

no action required

Create customer backendobject.

Register new backendobject in configuration4)

Configure BADI in CRM

Assign customer functionmodule and event listenerclass to standard functionmodule in configuration3)

Create customer functionmodule with interface of

standard function module2)


no action required

Assign customer functionmodule to standardfunction module in

configuration2)

No action required

Figure 48: Call a SAP CRM system from the backend layer

For details see:1) Supported Function Modules and Business Objects on page 2122) Replacing Calls to Standard Function Modules (Backend System) on page 2273) Interception of Calls to Standard Function Modules on page 2254) Create a Customer Backend Object on page 204; it is assumed at this point, that a customerbusiness object and a customer BOM are already available.


August 2008 184

This diagram shows how to retrieve additional data from a SAP ERP system to the business object layer.

Data is retrieved withina standard call from the

backend system(e.g. at order save, at

ship to read)1)

StartExtensions to retrieve data

from a R/3 system

Configure extension data6)

Create new backendclass. Implement

method(s) to call functionmodule.5)

Data is retrieved by anew (customer specific)call from the backend

system

End

Derive new backend classfrom standard backend

class. Overwrite method(s)to call function module

and/or to process data.5)


postprocessing after transferrequired

yes

no

Extension data of R/3function module can be

used3)


Write additional data torequest context.8)

no

yes

Create new backendinterface.4)

Create new businessobject and new BOM.2)

Figure 49: Retrieve additional data from SAP ERP system to business object layer

For details see:1) ‘Standard call’ means that the backend system is called via a function call within the standardprocess flow. The function module itself does not have to be a standard function call (see ReplacingCalls to Standard Function Modules (Backend System) on page 227)2) Create a Customer Business Object on page 200 and Create a Customer Business ObjectManager on page 201Table 56: ABAP Extension Structure (ERP)Supported Function Modules and Business Objects. on page 212Table 47: User exits for for Pricing orConfigurationCreating new Customer Backend Object on page 2085) Create a Customer Backend Object on page 2046) Modification of Communication Structures in SAP and Configuration of the Web Application onpage 2207) Interception of Calls to Standard Function Modules on page 2258) Request Context on page 222


August 2008 185


August 2008 186

This diagram shows how to transfer additional data from the business object layer to a SAP ERP system.

Data stored in a requestcontainer

Data stored in a(customer) business

object

StartExtensions to transfer data to

a R/3 system


Read data from requestcontainer.3)

Create new backendclass. Implement method

to call R/3 functionmodule5)

Data stored within astandard business

object as extension data

yes

End

Call function modulein R/3 system

Configure extension data4)


preprocessing beforetransfer required

Extension data of R/3function module can be

used1)

no

yes

no

Figure 50: Transfer additional data from business object layer to SAP ERP system

For details see:Table 56: ABAP Extension Structure (ERP)Supported Function Modules and Business Objects. on page 212.2) Interception of Calls to Standard Function Modules on page 2253) Request Context en page 2224) Modification of Communication Structures in SAP and Configuration of the Web Application onpage 2205) Create a Customer Backend Object on page 204


August 2008 187

This diagram shows how to call a SAP ERP system from the backend layer.

No extension ofinterface or of the logicof the standard function

module required

Extension of interfaceand of the logic of the

standard functionmodule required

StartCall function module in R/3

system

No extension ofinterface but extension

of the logic of thestandard functionmodule required

Create customer functionmodule with extendedinterface of standard

function module

Create customer functionmodule with interface of

standard function module1)

recomm.concept

Create customer functionmodule

End

Use standard backendobject and implement JCO

event listener class2)


no action required

Create customer backendobject.

Register new backendobject in configuration3)

Assign customer functionmodule to standardfunction module in

configuration1)

Assign customer functionmodule and event listenerclass to standard functionmodule in configuration2)

No action required

Figure 51: Call a SAP ERP system from backend layer

For details see:1) Replacing Calls to Standard Function Modules (Backend System) on page 2272) Interception of Calls to Standard Function Modules on page 2253) Create a Customer Backend Object on page 204; it is assumed at this point, that a customerbusiness object and a customer BOM are already available.


August 2008 188

This diagram shows how to exchange additional data between the business object layer and an IPC system.

Additional data shouldbe transferred to the

IPC for Pricing

Additional data shouldbe transferred to theIPC for configuration


with an IPC system

End

Derive new backendobject from standard(CRM/R/3) backend

object. Implement userexit.1)

Derive new backendobject from standard(CRM/R/3) backend

object. Implement userexit.1)

Figure 52: Exchange additional data between business object layer and an IPC system

For details see:1) Standard Backend Objects providing User Exits on page 204

Example, see ’Extension within Data Processing’ of the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305).


August 2008 189

This diagram shows how to exchange additional data with the web catalog.

Figure 53: Exchange additional data with the web catalog

For details see:1) New Fields in the Web Catalog (SAP ERP Backend and Memory Catalog) on page 231 and NewFields in the Web Catalog (SAP ERP Backend and TREX) on page 2322) Show Additional Keys for Extended Search in B2B on page 2313) See note 684119 (for ISA ERP) and ‘Extensions to Exchange Additional Data’ in the ‘Developmentand Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References onpage 305).

For displaying additional data in web catalog, see Show Additional Attribute in Product List on page229 and Show Additional Attribute in Product Details and in Compare Products on page 230


August 2008 190

This diagram shows how to exchange additional data with the Java basket.

Additional data isattached as extension

data to the basketheader or to the basket

item

Additional data isattached as extensiondata to other business

objects


with the Java Basket

End

Extension data isautomatically transferred

with the header or with theitem of the Java Basket -

no action required.1)

Derive new backendobject from standard

(JDBC or DB) backendobject.2)

Overwrite method toexchange extension data.

Figure 54: Exchange additional data with the Java basket

For details see:1) Java Basket-Extensions en page 2222) Create a Customer Backend Object on page 204


August 2008 191

Extensions to the UI layerThe following list provides an overview of simple modifications related to the UI only:

Type of Extension Where Effect on other Layers

Adding/replacing Mimes On JSPs

Adding new Mimes toweb application

Replacing existing Mimes

No

Changing text displayed onthe screen

On JSP

In language dependentresource files

No

Changing colors On JSP

In cascading style sheets

No

Replacing existing JSP Register new JSP inStruts configuration file(config.xml)

Depending on the functions ofthe new JSP, changes in otherlayers could be necessary.

Table 33: Overview of simple modifications related to the UI

Changes in the UI are often necessary in order to display additional data or to enable the user to enteradditional data. Such changes are in most cases not limited to just the UI layer.

Accessing the Session ContextIn order to access the UserSessionData object from the JSP you have to do the following:

Accessing the Request ContextFor information about how to access the RequestContext within a JSP refer to chapter 'Request Context' onpage 222.

Extensions in the Action FlowThe action flow is realized using the STRUTS framework. In order to get/display additional data on the UI it isoften necessary to change the existing Action flow. This is done by adding/replacing custom Struts Actions:

<%@ page import=‘com.sap.isa.core.UserSessionData’ %>

<% UserSessionData userSessionData =

UserSessionData.getUserSessionData(pageContext.getSession());

%>


August 2008 192

Figure 55: Action flow with CustomActions

Create a Customer ActionYou would like to modify a specific interaction within the application. A reason for doing this could be that youwant to perform some additional checks that are not part of the original Actions before you continue with theprocess flow. Or you are modifying a dispatcher Action (for exampleMaintainBasketDispatcherAction) and extending its functions.

When you extend existing Actions you usually overwrite one of the methods provided by the base Action andprovide your own implementation for it.

Depending on the type of modification, you can use different possible base classes for your Action.

com.sap.isa.core.BaseAction

o Base class of all Actions. Use these Actions if you do not need to access the standard ISAfunctions (for example, you extend the functions of Internet Sales without using currentfunctions). In that case you have to overwrite doPerform().

com.sap.isa.isacore.action.IsaCoreBaseAction

o Base class providing easy access to Business Object Managers of the ISA core functions,IPC, and catalog. Extend these Actions if you write extensions to the Internet Salesapplication which use available functions. You have to overwrite the isaPerform()method.

com.sap.isa.isacore.action.EComBaseAction

o Base class providing MetaBOM.

All the action classes of the E-Service Extended Complaints and Returns application extend thecom.sapmarkets.isa.isacore.action.EComBaseAction, either directly or indirectly (through other classinheritance).

Depending on the type of modification, you can use different possible base classes for your Action in theExtended Complaints and Returns application:

com.sapmarkets.isa.isacore.action.EComBaseAction

o Base class providing MetaBOMcom.sap.eservice.common.action.CommonBaseAction

o Inherit from EComBaseAction; This base class providing access to the Common businessobject manager which handles several business objects such as user, business partnermanager, delivery, recall, generic search, etc.


August 2008 193

com.sap.eservice.common.action.CommonControlAccessBaseAction

o Inherit from CommonBaseAction; checks whether the user is properly logged in beforeproceeding to the execution of the action

com.sap.eservice.crb2b.action.EserviceBaseAction

o Inherit from CommonBaseAction; gives access to the Eservice business object managerwhich handles the Help Value Search Handler business object.

com.sap.eservice.crb2b.action.EserviceControlAccessBaseAction

o Inherit from EserviceBaseAction; checks whether the user is properly logged in beforeproceeding to the execution of the action

com.sap.eservice.crb2b.action.ComplaintBaseAction

o Inherit from CommonBaseAction; gives access to the Complaint business object managerwhich handles several business objects: complaint, complaint dynamic fields, complaintitems list.

com.sap.eservice.crb2b.action.ComplaintControlAccessBaseAction

o Inherit from ComplaintBaseAction; checks whether the user is properly logged in beforeproceeding to the execution of the action

In the Remanufacturer’s Inspection Application, you can use the following actions as base actions:

com.sapmarkets.isa.isacore.action.EComBaseAction

o Base class providing MetaBOM

com.sap.eservice.common.action.CommonBaseAction

o Inherit from EComBaseAction; This base class providing access to the Common businessobject manager which handles several business objects such as user, business partnermanager, delivery, recall, generic search, etc.

com.sap.eservice.common.action.CommonControlAccessBaseAction

o Inherit from CommonBaseAction; checks whether the user is properly logged in beforeproceeding to the execution of the action

com.sap.eservice.inspb2b.action.EserviceInspBaseAction

o Inherit from EComBaseAction

com.sap.eservice.inspb2b.action.EserviceInspControlAccessBaseAction

o Inherit from CommonControlAccessBaseAction; checks whether the user is properlylogged in before proceeding to the execution of the action

com.sap.eservice.crb2b.action.ComplaintBaseAction

o Inherit from CommonBaseAction; gives access to the Complaint business object managerwhich handles several business objects: complaint, complaint dynamic fields, complaintitems list.

com.sap.eservice.crb2b.action.ComplaintControlAccessBaseAction

o Inherit from ComplaintBaseAction; checks whether the user is properly logged in beforeproceeding to the execution of the action

com.sap.eservice.srvconfirmations.action.ConfirmationBaseAction

o Inherit from CommonBaseAction; gives access to the Confirmation business objectmanager.


August 2008 194

com.sap.eservice.srvconfirmations.action.ConfirmationControlAccessBaseAction

o Inherit from CommonControlAccessBaseAction; gives access to the Confirmationbusiness object manager and checks whether the user is properly logged in beforeproceeding to the execution of the action

Standard Actions providing User ExitsSome action classes already provide user exits in the form of predefined, but empty, methods. Forextensions only the existing empty methods have to be implemented in a new action class derived from thestandard action class. The advantage of predefined user exits is that extensions or changes in the standardaction classes by SAP within support packages or future releases are aware of user exits:

Basket

Class / Methode Description

MaintainBasketBaseAction Base action for all actions providing functions to manage theshopping basket and sales documents similar to the basket.

customerExitParseRequestHeader Modify the header data; called after the header data isparsed from the request.

customerExitParseRequestItem Modify the item data; called after the item data is parsed fromthe request.

customerExitParseRequest Modify the document; called after the header and item dataare parsed from the request.

MaintainBasketDeleteItemAction Action to delete an item from the current document.


MaintainBasketReplaceItemAction Action to replace an item of the basket with another oneduring the cross- and upselling process.


MaintainBasketNewShiptoAction Action to add a new ship to to a document.


MaintainBasketDispatcherAction Action to dispatch all requests coming from the order.jsp todifferent (specialized) actions.

customerExitDispatcher Set forward; called after standard forward is determined.




Table 34: User exits within the Basket


August 2008 195

Order


MaintainOrderBaseAction Base action for all actions providing functions to manage theshopping basket and sales documents similar to the basket.




MaintainOrderReplaceItemAction Action to replace an item of the order with another one duringthe cross- and upselling process.


MaintainOrderNewShiptoAction Action to add a new ship to to a document.


MaintainOrderSendAction Action to perform the final step in the processing of adocument (i.e. to save it in the backend).


MaintainOrderDispatcherAction Action to dispatch all requests coming from theorder_change.jsp to different (specialized) actions.


Table 35: User exits within the Order

OCI (Open Catalog Interface) (interface to external catalogs)


OciGetCatalogURLAction Action which retrieves the URL from the external catalog.


customerExitGetOCIURL Modify URL to external catalog (e.g. add user data).

OciReceiveAction Action for receiving items via the OCI.


userExitCheckRequest The result of the standard method „checkRequest’ can bemodified.

userExitModifyItemListBeforeConvertRequest

Read additional data from OCI message.

userExitModifyItemListBeforeAddToBasket

Read additional data from OCI message.

Table 36: User exits within the OCI


August 2008 196

As in the Internet Sales application, some action classes provide user exits in the form of predefined, butempty, methods.

Extended Complaints and Returns Application

Class / Method Description

ComplaintEntryBaseAction Base action for all actions providing functions to manage the entryof complaints and returns.

customerExitParseRequest This method is called when the update of a whole document isinvoked, either when the user presses the “update” or “send”button on the complaint entry or return entry. It is called beforethe document is actually updated in the CRM system.

customerExitParseRequestHeader This method is called when the update of the header is invoked,either when the user presses the “update” or “send” button on thecomplaint entry or return entry. It is called before the header isactually updated in the CRM system.

customerExitParseRequestItem This method is called when the update of an item is invoked whenthe user presses “update” or “send” on the complaint/return mainentry page, the complaint/return item entry or complaint/returnitem resubmission. It is called before the item is actually updatedin the CRM system.

Table 37: User exits within the Extended Complaints

Remanufacturer’s Inspection Application

Class / Method Description

ConfirmationEntryBaseAction Base action for all actions providing functions tocreate an inspection confirmation.

customerExitParseRequest This method is called when the user submits aninspection, before the inspection is actually created inthe CRM system.

Table 38: User exits within the Remanufacturer’s Inspection Application

Accessing the Session ContextIn most cases you need to access the session context from Actions. The base class of your Actionscom.sap.isa.core.BaseAction provides methods enabling you to communicate with the sessioncontext.

Within the ISA framework you are only allowed to communicate with the session using thecom.sap.isa.core.UserSessionData object.

The following code sequence retrieves a reference to a UserSessionData object:

After that you can get/set objects in the session using the methods Object getAttribute(Stringname) and setAttribute(String name, Object object).





August 2008 197

Accessing Business Objects from ActionsActions act as a mediator between the HTTP world and the BO Layer. Business Objects do not knowanything about HTTP. Actions are responsible for retrieving data from the HTTP-based environment andpassing this data to Business Objects when accessing business functions.

Before an Action can communicate with a Business Object it needs a reference to it. To get a reference thefollowing steps have to be performed:

If your base class is com.sap.isa.core.BaseAction

o Get a reference to the user session data. You need a reference to this object before you canget a reference to the Business Object Manager, which manages the Business Object youare interested in:

o The next step is to get a reference to the Business Object Manager. The easiest, andrecommended, way is to use the convenience method getBOM() of theUserSessionData class:

If your base class is com.sap.isa.isacore.action.IsaCoreBaseAction you get passed thereference to the Business Object Manager in the isaPerform() as a parameter (please seeJavaDoc).

Now you can use the reference to the BOM to get a reference to a Business Object or to create a BusinessObject:

Before this reference is used, you should check whether it is null or not:

The business methods can then be executed on the BO:

user.setName(‘Mueller’);

if (user == null) {

// Error

}

Basket basket = bom.getBasket();

User user = bom.createUser();

BusinessObjectManager bom =

(BusinessObjectManager)userSessionData.

getBOM(BusinessObjectManager.ISACORE_BOM);

UserSessionData userSessionData = UserSessionData.getUserSessionData(session);


August 2008 198

The Business Object Manager you get a reference to is defined in the <isa>/web-inf/cfg/bom-config.xml file:<BusinessObjectManager

name=‘ISACORE-BOM’

className = ‘com.sap.isa.businessobject.BusinessObjectManager’ />

The references to the BusinessObjectManager and the corresponding objects remain valid and can bereused within the Action as often as required. These references should never be passed onto other Actionsvia the session context, since this would undermine the purpose of the Object Manager. This rule forcesevery Action to retrieve the Business Objects using the technique described above.

Accessing the Request ContextFor information about how to access the RequestContext within an JSP refer to chapter 'Request Context' onpage 222.

Modifications in the Struts ConfigurationModifications in the struts configuration are required to

Add or remove actions in the action flow

Register customer actions in the action flow.

This file is located in <isa>\web-inf\config.xml.

In the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection, this file islocated in <esrv>\web-inf\struts-config.xml.

VersionThis feature is available in all versions of E-Commerce.

ExampleSee ‚Enhancing/Modifying the Action Flow’ and ‘Extension Demo 1 – Add New Entry Fields’ in the‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapterReferences on page 305).

Business Object Layer

Storing Additional Data - Extension MechanismThis modification concept uses the previously mentioned extension mechanism that enables you to store anydata in a Business Object. The base class of each Business Object provides this mechanism.


August 2008 199

Additionally, this data can be passed transparently to the backend system. This is the preferred extensionconcept when you have to pass data between the Business Object and the SAP CRM or the SAP ERPsystem. For further information on this concept please refer to chapters BADIs/SAP CRM Extensions onpage 211 or BAPIs/SAP ERP-Extensions on page 217.

Use only string objects with the extension data, if you want to automatically transport this data tothe backend using the Extension mechanism (see BADIs/SAP CRM Extensions).

Figure 56: BOBase class

Each Business Object extends the com.sap.isa.core.businessobject.BOBase class. This baseclass provides the following methods to store any data:

Method Name Function

addExtensionData(Object key, Object name) Stores any data within the BusinessObject.

Object getExtensionData(Object key) Retrieves extension data associated withthe Business Object.

getExtensionDataValues() Retrieves all extension data associatedwith the Business Object.

removeExtensionData(Object key) Removes extension data from theBusiness Object.

Table 39: Methods of the BOBase class

VersionThis feature is available in all versions of Internet Sales.

It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’sInspection.


August 2008 200

Example Storing additional data in the basket Business Object:

Retrieving extended data:

Extending existing Business ObjectsYou use this extension concept when you want to add functions to an existing Business Object, or if youwant to replace the functions of an existing method with your own implementation. In either case, you haveto derive from the existing Business Object and extend/replace its functions.

Figure 57: Derive own class from existing Business Object

Since every Business Object is accessed via a Business Object Manager, you have to extend the BOM thatmanages the Business Object you have extended. In order to make the new version of the Business Objectavailable for use, you have to overwrite the get/create method of the BOM that creates this Business Object.

Figure 58: Create own BOM

String extBasketHeaderData =

(String)isaBOM.getBasket().getExtensionData(‘extHeaderData’);

// set extended data as extended data of the Basket Business Object

isaBOM.getBasket().addExtensionData(‘extHeaderData’, extBasketHeaderData);


August 2008 201

The new modified version of the BOM creates an instance of the new Business Object. The return valuemust be the class which represents the old Business Object.

All existing Actions do not have to be changed:

New Actions can use the new/extended functionality of the Business Object:

VersionOwn Business Object can be extended in all versions of Internet Sales.

This feature is also available in the E-Service applications Extended Complaints and Returns andRemanufacturer’s Inspection.

Create a Customer Business ObjectThere are various reasons why you would have to write your own Business Objects:

To provide new functions (there are no suitable Business Objects that could be extended)

If you have written own remote callable function modules and would like to use them in customerextensions. Function modules are called within Backend Objects and there is always need of acorresponding Business Object

BOBase

+addExtensionData()+getExtensionData()+removeExtensionData()

Z_CustomFunc

+getInfo()

Figure 59: Creating own Business Object

Customer written Business Objects are managed by a custom Business Object Manager.

NewUser user = (NewUser)bom.getUser();

user.doNew();

User user = bom.getUser();


August 2008 202

Z_CustomFunc

+getInfo()

Z_CustomBusinessObjectManager

+ getCustomFunc()creates

DefaultBusinessObjectManager

Figure 60: Creating own BOM

To write a Business Object and add it to the BOM you have to perform the following steps:

1. Write a class which extends

o If you are writing a Business Object having a representation in the backend system which isidentified by a GUID: com.sap.isa.core.businessobject.ObjectBase.

o Otherwise extend com.sap.isa.core.businessobject.BOBase

2. If the business object has a corresponding Backend Object it should implementcom.sap.isa.core.businessobject.BackendAware

3. Place this class in a package like com.<your company>.isa.businessobject

o If you have only few Business Objects, you can place them directly under thebusinessobject package. If you have a lot of custom Business Objects, create a deeperpackage structure that reflects the business functions provided by your custom businessobjects.



Example'Extensions Demo 7: Copy –Template for Customer Actions' in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305) provides you atemplate you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

Create a Customer Business Object ManagerA Business Object Manager usually has a method to generate a BO (createXX), a method to interrogateexisting BOs (getXX), and a method to drop all references to the existing object (releaseXX).

The semantics are defined in such a way that the createXX method generates a new BO if one does notalready exist, or functions in the same way as getXX with existing BOs. Calling createXX, therefore,always returns a reference to a BO. By contrast, getXX returns null if the object has not yet beengenerated with createXX.


August 2008 203

The createXX, getXX, and releaseXX methods must be re-implemented for new BOs, whereby XX isreplaced by the exact name of the BO class in question. If the class is called User, for example, one methodis created with the signature User getUser(), one with the signature User createUser(), and onewith the signature void releaseUser().

When the BOs are created by the BOM they can be assigned a reference to the BackendObjectManager.BOs that require this information must implement the BackendAware interface, which means that they alsoimplement the setBackendObjectManager method.

BOs that do not have to communicate with the backend should not implement the interface unnecessarily.Even if it turns out later on that the BO does need to communicate with the backend, changes do not have tobe made to the BOM. In this case, it is sufficient to implement the interface on the BO side.

+ setBackendObjectManager()

«interface»BackendAware

+ setBackendObjectManager()+ setUserId(id : String)+ setPassword(pwd : String)+ login()

- bem : BackendObjectManager

User

Figure 61: Creating interface for Business Object

To make it easier to develop Business Object Managers, you can use theGenericBusinessObjectManager as a base class for your own Business Object Manager. This classcan already manage Business Objects and using it makes it easier to implement BOMs.

All you have to do is write the required method (for example, create/get), and call the corresponding genericmethods of the superclass by passing the class object of the Business Object you want to manage.

BusinessObjectManagerBase

DefaultBusinessObjectManager

+setBackendObjectManager()+assignBackendObjectManager()

GenericBusinessObjectManager

+getBusinessObject()+createBusinessObject()+releaseBusinessObject()

Z_CustomBusinessObjectManager

+getCustomFunc()

Figure 62: Creating own Business Object Manager


August 2008 204

After implementing a BOM, you have to register it in the customer version of the bom-config.xml file andadd an entry to it for the new manager.

The file is located in WEB-INF\xcm\customer\modification\bom-config.xml:



<BusinessObjectManagers>

<xi:include

href=‘${sap}/modification/bom-bonfig.xml#xpointer(BusinessObjectManagers/*)’/>

<BusinessObjectManager name=‘ Z_CUSTOM-BOM’

className=‘com.acme.isa.businessobject.Z_CustomBusinessObjectManager’ />

</BusinessObjectManagers>

public class Z_CustomBusinessObjectManager

extends DefaultBusinessObjectManager

implements BOManager, BackendAware {

....

// reference to business object

private Z_CustomFunc mCustomFunc;

// key used for the Business Object Manager in customer version of bom-config.xml

// used in Actions as a constant to identify the BOM

public static final String CUSTOM_BOM = ‘Z_CUSTOM-BOM’;

/**

* Returns custom business object

*/

public Z_CustomFunc getCustomFunc() {

if (mCustomFunc == null) {

mCustomFunc = new Z_CustomFunc();

// assigns Backend Object Manager to Business Object if

// Business Object implements the BackendAware interface

assignBackendObjectManager(mCustomFunc);

}

return mCustomFunc;

}

}


August 2008 205

Example'Extensions Demo 7: Copy-Template for Customer Extension' in ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305) provides you atemplate you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

Business Logic Service LayerMany Business Objects (e.g. basket) in the Business Object layer have a corresponding Backend Object inthe BLS layer. The functionality of a Backend Object is accessed via a well-defined Java interface (forexample: BasketBackend). The implementation of such an interface is backend-dependent (for example:BasketCRM).

Customizing of the Java part is often related to changes in the SAP CRM system. Additional functions can beprovided by the SAP CRM system in different ways:

By using BADIs

By additional function modules

By customer changes to existing function modules:

o Without changing the function module interface

o By adding optional parameters to the function module interface

Create a Customer Backend ObjectYou would like to enhance a specific processing step within the application. A reason for doing this could bethat you want to perform some additional checks that are not part of the original processing, before youcontinue with processing. Or, you want to add additional data before you continue with processing. Or, youwant to execute self written remote callable function modules in the SAP system.

In order to create a customer Backend Object the following two scenarios have to be separated:

The Backend Object extends a standard Backend Object:

Re-implement the methods which cannot be used from the standard Backend Object and/or addadditional Methods.

Overwrite customer exits

The Backend Object is needed for a customer Business Object and can not be derived from astandard Backend Object:

Standard Backend Objects providing User ExitsSome backend object classes already provide user exits in the form of predefined, in most cases empty,methods. For extensions only the existing methods have to be implemented or extended in a new backendobject class derived from the standard backend object class. The advantage of predefined user exits is thatextensions or changes in the standard backend object classes by SAP within support packages or futurereleases are aware of these user exits:


August 2008 206

In order to use a customer exit you have to perform the following steps:

Extend the standard Backend Object class and overwrite the customer exit

Register your Backend Object class in customer version of backendobject-config.xmlconfiguration file. For further information refer to 'Changes in backendobject-config.xml' on page275

Call IPC for Pricing (ISA CRM)


PriceCalculatorInitDataCRMIPC Price calculator for the SAP CRM backend. It determineslist/scale prices from catalog attributes, as well as dynamicprices through IPC, based on the settings in the web shop.

customerExitBeforeIpcDocumentCreate

Called after preparing the IPCDocumentProperties, butbefore creating the document in IPC. Overwrite this method ifyou want to add or modify document properties, for exampleto pass additional attributes to the document.

customerExitAfterIpcDocumentCreate

This exit is called after creating the IPCDocument. Overwritethis method if you want to change the IPC document in someway.

customerExitBeforeIpcItemsCreate This exit is called after preparing the IPCItemProperties, butbefore creating the items in IPC. Overwrite this method if youwant to add or modify item properties, for example to passadditional attributes to the item.

customerExitAfterIpcItemsCreate This exit is called after creating the IPCItems. Overwrite thismethod if you want to change the IPC items in some way.

customerExitCreatePrices This exit is called when creating the Prices from the IPC item.It cretaes PriceInfo Objects and stores them in a Pricesobject which is then returned. Overwrite this method if youwant to subclass PriceInfoIPC, and use your subclass.

customerExitGetPriceType This exit is called for PriceType determination. When thePriceCalculator is initialized, the price types used are readfrom eai-config.xml. For each String in that list, this method iscalled and it returns a PriceType object.

Table 40: User exits for IPC for pricing

IPC-Basket (ISA CRM)


BasketIPC Basket implementation for IPC

customerExitAfterAddBusinessPartnerInBackend

This method provides the possibility to extend or modifiy theIPC document. The exit is called within the methodaddBusinessPartnerInBackend when a user hasalready logged on, and after the basket has been created.

customerExitSetDocumentProperties This method provides the possibilty, to easily extend thedocument properties of a sales document according tospecial customer requirements. The exit is called within themethod createInBackend when a basket is created, butbefore the IPC-document is created.

Table 41: User exits for IPC basket


August 2008 207


customerExitSetItemProperties This method provides the possibilty, to easily extend the itemproperties of a sales document according to special customerrequirements. The exit is called within the methodupdate(BasketData) when a new item is created, butbefore an IPC item is created.

Table 42: User exits for IPC basket

Order and Order Status (ISA ERP)


CreateStrategyR3 Algorithms for creating and simulating an order. Both tasksare done with the function moduleSD_SALESDOCUMENT_CREATE.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function moduleSD_SALESDOCUMENT_CREATE is called.

performCustExitAfterR3SimulateCall This method can be used to set additional tables or tablefields after the function moduleSD_SALESDOCUMENT_CREATE is called. It is called afterthe ISA sales document has been filled with the functionmodule data.

ChangeStrategyR3 Algorithms used for sales document change.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function moduleSD_SALESDOCUMENT_CHANGE is called

performCustExitAfterR3Call This method can be used to modify the ISA sales documentafter the function module SD_SALESDOCUMENT_CHANGEis called. It is called only if no error messages from havebeen returned and after re-reading the ISA sales documentfrom ERP.

DetailStrategyR3 Contains the algorithms for reading an entire sales documentfrom ERP.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function moduleBAPI_ISAORDER_GETDETAILEDLIST is called.

performCustExitAfterR3Call This method can be used to set additional tables or tablefields after the function moduleBAPI_ISAORDER_GETDETAILEDLIST is called. It is calledafter the ISA sales document has been filled with the functionmodule data.

Table 43: User exits for Order and Order Status


August 2008 208


ReadStrategyR3 Contains base functionality for transferring data from functionmodule tables to the ISA sales document that is used from allother algorithm groups. For example reading the item andschedule line info is used from all strategies that deal withorder change simulation, order change, order read and ordercreate simulation.

setUpMessageMap List of ERP messages which are raised by function moduleswhen simulating or saving orders and which should bedisplayed on the UI or should be ignored (in case of errormessages).See notes 640735 and 641132.

Table 44: User exits for Order and Order Status

Web Catalog (Memory Catalog) (ISA ERP)


R3CatalogServerEngine Memory Catalog.

performCustomerExitAfterCatalogRead

Called after the catalog has been set up. Can be used to e.g.attach additional attributes to the catalog. This customer exitis only called for the standard main memory implementation.

Table 45: User exits for Web Catalog

See also: Extension of the Web Catalog on page 229.

Call IPC for Pricing or Configuration (ISA ERP)


ServiceR3IPC Provides IPC functionality for the Internet Sales ERP.Contains creation of documents and items.

customerExitAfterDocumentCreation Customer exit that is called after an IPC document is created.

customerExitBeforeItemCreation Customer exit that is called before an IPC item is created.

customerExitAfterItemCreation Customer exit that is called after an IPC item has beencreated. This customer exit can be used to set the context ifreference characteristics are involved.

customerExitBeforeItemCreation Customer exit that is called before an array of IPC items arecreated.

customerExitAfterItemCreation Customer exit that is called after an array of IPC items hasbeen created. This customer exit can be used to set thecontext if reference characteristics are involved.

customerExitBeforeHeaderAttributeCall Customer exit that is called directly beforeISA_PRICING_HDRDATA_GET is called. Can be used to setadditional parameters in table EXTENSION_IN.

Table 46: User exits for for Pricing or Configuration


August 2008 209


customerExitBeforeItemAttributeCall Customer exit that is called directly beforeISA_PRICING_ITEM_ATTRIBUTE is called.

Can be used to set additional parameters in tableEXTENSION_IN.

Note that the backend context is available here with e.g. theshop customizing.

Only relevant for the non-TREX case.

Table 47: User exits for for Pricing or Configuration

Creating new Customer Backend ObjectsWhen creating a custom Backend Object you have to perform the folling steps.

Create a Java interface that is used to access the Backend Object

Create an implementation for this interface

The implementation must implement the BackendBusinessObject interface

o If the Backend Object has to communicate with an SAP system using JCo, derive yourimplementation from the com.sap.isa.core.eai.sp.jco.BackendBusinessObjectBaseSAP class.Stateless classes should use IsaBackendBusinessObjectBaseSAP as in this case thecorrect logon language is used in the connection.

Within the Backend Object implementation, communicate with the backend system using theconnection management provided by the BLS layer

Add configuration information to the customer version of the backendobject-config.xmlconfiguration file

Create an Interface of Backend Object

The interface of the new Backend Object extends the com.sap.BackendBusinessObject interface:

Additionally, you define any set of methods needed to access business functions located in the backendsystem.

Design Considerations when Creating Backend Object InterfacesIf you need to access data located in the Business Object layer you should not pass the reference of thebusiness object to the backend object, but instead use a data access interface instead. This interface shouldprovide all necessary access methods. Place the data interface in the same package as the Backend Objectinterface.

public interface Z_CustomFuncBackend extends BackendBusinessObject {

public String getInfo();

}


August 2008 210

Create an Implementation of Backend ObjectWrite an implementation for the interface of the Backend Object. Use theBackendBusinessObjectBaseSAP class as the base class for backend objects communicating with anSAP system using the SAP Java Connector.

Register Backend Object in backendobject-config.xmlThe backend object has to be registered in the customer version of backendobject-config.xml usingXCM extension mechanism:

Accessing Backend Objects from Business ObjectsIf Backend Objects need access to the BLS layer they have to implement thecom.sap.isa.core.businessobject.BackendAware interface.

This interface defines the method:

public void setBackendObjectManager(BackendObjectManager bem);

This method is used to store a reference to the Backend Object Manager:

When the Business Object is retrieved from the Business Manager the method usually looks as follows(example from previous chapters):

....

private BackendObjectManager bem;

...

public void setBackendObjectManager(BackendObjectManager bem) {

this.bem = bem;

}

<businessObject type=‘Z_Custom’ name=‘ Z_Custom ‘

className=‘com.acme.isa.backend.crm.Z_CustomFuncCRM’


defaultConnectionName=‘CRMStateless’>

<params>

<param name=‘myinit’ value=‘myvalue’/>

</params>

public class Z_CustomFuncCRM

extends BackendBusinessObjectBaseSAP

implements BasketBackend, Z_CustomFuncBackend {

public String getInfo() {

JCO.Function func = getDefaultJCoConnection().getJCoFunction(‘Z_GETINFO’);

getDefaultJCoConnection().execute(func);

return func.getExportParameterList().getString(‘info’);

}

}


August 2008 211

The Backend Object Manager is assigned to the Business Object within theassignBackendObjectManager().

Having a reference to the Backend Object Manager enables the Business Object to create a instance of abackend object using the createBackendBusinessObject(String backendObjectType) method.The value of backendObjectType corresponds to the value of the type XML element within thebackendobject-config.xml


<businessObject type=‘Z_Custom’ name=‘Z_Custom’ ...>

...

<businessObject/>

public class Z_CustomFunc {

private Z_CustomFuncBackend mCustom;

private Z_CustomFuncBackend getCustomFuncBackend() {

if (mCustom == null) {

try {

mCustom = (Z_CustomFuncBackend)

bem.createBackendBusinessObject(‘Z_Custom’);

} catch (BackendException bex) {

log.error(‘acme.error.z_getbo’, bex);

}

}

return mCustom;

}

public String getInfo() {

return getCustomFuncBackend().getInfo();

}

....

public Z_CustomFunc getCustomFunc() {

if (mCustomFunc == null) {

mCustomFunc = new Z_CustomFunc();

// assigns Backend Object Manager to Business Object if

// Business Object implements the BackendAware interface

assignBackendObjectManager(mCustomFunc);

}

return mCustomFunc;

}


August 2008 212


Example'Extension Demo 7: Copy-Templates for Customer Extensions' in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305) provides you atemplate you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

BADIs/SAP CRM ExtensionsThis section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with SAP CRM as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer. Youonly need to extend the Interaction Layer with actions to fill your additional fields.

The solution consists of two parts: the extension concept for Business Objects in the Java layer and theBADIs and the ABAP extension structure in the SAP CRM BLS layer.

Use String objects when storing extension data, if you want to access this data from thebackend.

To extend a Business Object with your own fields, you need to implement a BADI in SAP CRM, where thefields are filled in extension structures as name value pairs. After that you can access the field using the keyfrom the extension in the Java layer. The extensions in the Java layer are also key value pairs that areassigned to the corresponding Business Objects.

Due to time constraints we couldn’t implement all of the BADIs in the first step. Therefore, you must fill theextension structure in SAP CRM as a modification of your function modules in this ‘pre BADI’ period. Afterthe BADIs exist you should move your code inside the BADIs.

If you use the Java Basket with ISA CRM, you also have to transfer the extension data to theJDBC backend objects and DB basket.

As in the Internet Sales application, the E-Service Extended Complaints and Returns application providessome BADIs that you can implement in the CRM system to let you do additional processing.

Some function modules have as a parameter an extension data structure (typeCRMT_ISALES_EXTENSION_INT). For those function modules, this data extension structure can beprocessed in the CRM system by implementing the BADI definition. Note that some function modules do notuse the extension data structure but still offer BADI methods.

This following table lists the function modules and business objects where the extension data is stored in thejava application. It also lists the BADIs method where your processing can be inserted. If there are nobusiness objects, it means that the data structure extension is not used as parameter for the functionmodule.

Note that the Complaint business object handles both complaints and returns. The separation of complaintsand returns is merely done on the user interface only: the process, and as a consequence, the businessobjects, backend objects and ABAP function modules are basically the same.


August 2008 213

VersionThis feature is available in all versions of ISA 5.0.

It is also available in the E-Service Extended Complaints and Returns application.

ABAP Extension StructureField Type Description

REF_GUID CRMT_OBJECT_GUID_C Guid of the business object.

ALT_HANDLE CHAR30 Alternative handle, if no guid exists.

Normally only used when new businessobjects are created.

NAME CRMT_ISA_EXTENSION_KEY Name of the extension.

VALUE CRMT_ISA_EXTENSION_VALUE Value of the extension.

Table 48: ABAP Extension Structure (CRM)

Take care of the field ALT_HANDLE for creating table-like objects, like the items in the basket. Since theguids are normally generated from the backend, the guids are empty when new entries are created. In thiscase, the handle is filled and, with it, you can associate the extension with the related item.

Supported Function Modules and Business Objects

OrderFunction module Business object

CRM_ISA_BASKET_GETITEMS ItemSalesDoc

CRM_ISA_BASKET_CHANGEITEMS ItemSalesDoc

CRM_ISA_BASKET_GETHEAD HeaderSalesDoc

CRM_ISA_BASKET_CHANGEHEAD HeaderSalesDoc

CRM_ISA_BASKET_STATUS HeaderSalesDoc ItemSalesDoc

CRM_ISA_SALESDOC_GETLIST OrderStatus

CRM_ISA_BASKET_STATUS_ENH OrderStatus

Table 49: CRM - Supported Function Module / Business Object - Order

UserFunction module Business object

CRM_ISA_BP_BPARTNER_GETDETAIL User

CRM_ISA_BP_CONSUMER_CHANGE User

CRM_ISA_BP_CONSUMER_CREATE User

Table 50: CRM - Supported Function Module / Business Object - User


August 2008 214

ContractFunction module Business object

CRM_ISA_CNT_GETCONTRACTS ContractHead ContractItem

Table 51: CRM - Supported Function Module / Business Object - Contract

ShopFunction module Business object

CRM_ISA_SHOP_DATA_GET Shop

CRM_ISA_SHOP_GETLIST Shop

Table 52: CRM - Supported Function Module / Business Object - Shop

Complaint (E-Service)Function module Business object

CRM_ESRV_COMPL_CREATE Complaint

CRM_ESRV_COMPL_CRT_FROM_DLVRY Complaint

CRM_ESRV_COMPL_CRT_FROM_INV Complaint

CRM_ESRV_COMPL_CRT_FROM_MKT Complaint

CRM_ESRV_COMPL_CRT_FROM_PSL Complaint

CRM_ESRV_COMPL_CRT_FROM_SORD Complaint

CRM_ESRV_COMPL_INITIALIZE Complaint

CRM_ESRV_COMPL_SAVE Complaint

CRM_ESRV_COMPL_DELETE_ITEMS Complaint

Table 53: CRM - Supported Function Module / Business Object - Complaint

ComplaintHeader (E-Service)Function module Business object

CRM_ESRV_COMPL_CHANGE_HEADER ComplaintHeader

CRM_ESRV_COMPL_GET_HEADER ComplaintHeader

Table 54: CRM - Supported Function Module / Business Object – ComplaintHeader

ComplaintItem (E-Service)Function module Business object

CRM_ESRV_COMPL_CHANGE_ITEM ComplaintItem

CRM_ESRV_COMPL_CHANGE_ITEMS ComplaintItem

CRM_ESRV_COMPL_GET_ITEM ComplaintItem

CRM_ESRV_COMPL_GET_ITEMS ComplaintItem

Table 55: CRM - Supported Function Module / Business Object – ComplaintItem


August 2008 215

Reading data from the BackendIf you are reading additional fields from the backend you have to fill the extension tables properly. Here aresome extensions for the basket, as an example:

* ls_header is a local structure with header data

ls_extension-ref_guid = ls_header-guid.

ls_extension-alt_handle = ls_header-handle.

* extension are name value pairs

ls_extension-name = ‘Z_CUSTOMER1’ ‘ name

ls_extension-value = ls_header-zcustomer1. ‘ value

APPEND ls_extension to extension_header_out

* now adding extensions to the items

LOOP AT lt_items INTO ls_item.

ls_extension-ref_guid = ls_item-guid.

ls_extension-alt_handle = ls_item-handle.

ls_extension-name = ‘Z_CUSTOMER2’ ‘name

ls_extension-value = ls_item-zcustomer2. ‘value

APPEND ls_extension to extension_item_out

ENDLOOP.


August 2008 216

Writing data to the backendThis case is little bit more complex, since we have a problem with the table-like structure at creation point. Inthis case, no guids table items exist, and we need to use the handle to identify the extensions.

Example(no example available)

* ls_header is a local structure with header data

LOOP AT extension_header_in INTO ls_extension.

* check the name to find the according field

IF ls_extension-name = ‘Z_CUSTOMER1’.

ls_header-zcustomer1 = ls_extension-value.

ENDIF.

ENDLOOP.

* sort the extension table by ref_guid and handle to obtain a better access

* with binary search.

SORT extension_item_in BY ref_guid, alt_handle.

LOOP AT lt_items INTO ls_item.

* find the starting point for a loop over extensions

* use guid and handle as one logical key to access the extension

READ TABLE extension_item_in

WITH KEY ref_guid = ls_item-guid

alt_handle = ls_item-handle

BINARY SEARCH.

IF SY-SUBRC = 0.

LOOP AT extension_item_in INTO ls_extension

FROM SY-TABIX.

* check, if the entry is relevant

IF NOT ls_extension-ref_guid = ls_item-guid

OR NOT ls_extension-alt_handle = ls_item-handle.

BREAK.

ENDIF.

IF ls_extension-key = ‘Z_CUSTOMER2’.

ls_item-zcustomer2 = ls_extension-value.

ENDIF.

ENDLOOP.

ENDIF.

ENDLOOP.


August 2008 217

Enhancements for the Dynamic UI of ECO B2BThe dynamic UI of ECO B2B enables the customer to hide or disable fields on the order screens of the ECOB2B application dynamically. It is based on the CRM Sales Order Override concept and the Dynamic FieldControl concept of CRM E-commerce (see chapter Dynamic Field Control).

The CRM order’s Sales Order Override concept allows hiding or disabling order fields during orderprocessing depending on transaction type and item category regarding the user’s authorizations.

Therefore the SAP Implementation Guid (IMG) provides the possibility to create authorization groups andassign fields to them (IMG: CRM -> Basic Functions -> Authoritizations). These authorization groups can beincorporated to the user’s authorization within the authorization object CRM_FLDCHK. Calling the CRMfunction module CRM_ORDER_FIELDCHECK the changeability of the order fields are determineddepending on the order /order item status and the user’s authorizations.

For the additional order fields, which were adopted in the extension table of the ECO APIs, the display orchange attributes of the fields must be determined separately.

The field attributes of order data are determined in the CRM via the function moduleCRM_ORDER_FIELDCHECK and transferred to the table parameter HEADER_STATUS_CHANGEABLE ofthe function module CRM_ISA_BASKET_GETHEAD and the parameter ITEM_STATUS_CHANGEABLE ofthe function module CRM_ISA_BASKET_GETITEMS.

Thus for the customer fields it is necessary to implement the corresponding methods GET_HEAD_FROM_ILof BADI CRM_ISA_BASKET_HEAD for the order header and GET_ITEMS_FROM_IL of BADICRM_ISA_BASKET_ITEMS for the order items. The BADI implementations should perform theCRM_ORDER_FIELDCHECK for these fields and the results need to be transferred to the table parameterCT_FIELD_CHANGEABLE.

The following components of the return structures need to be supplied:

Component Description

FIELDNAME Name of the field

CHANGEABLE Field is changeable

INACTIVE Field is visible or not

Since it is possible on item level, that additional fields will be displayed, e.g. when the product was changed,a further compoment ‘IS_ADDITIONAL’ is provided for the item structure. When this flag is set to true, acorresponding message will notice the user, that additional field(s) are available. In order to be able todetermine, if a visible field was hidden before the last update, it is necessary to store the hidden fields in atemporary global table and to compare them with the visible fields after the order/basket was changed.

For the empty lines those fields will not be displayed, that are hidden for every item category of the usedtransation type. If this feature should be supported for the additional item fields as well the followingenhancements are necessary in the above mentionded BADI for the order items.The relevant itemcategories can be determined by calling the function module CRM_ORDER_IT_ASS_SEL_PROC_CB. Forevery item type and object the function module CRM_FIELDCHECK_TOOL identifies the field attributeregarding the user’s authorizations. Finally the table parameter CT_FIELD_CHANGEABLE needs to beassigned to a new entry for each item field with an initial value for the component ITEM_GUID andPARENT_GUID along with the retrieved field attriubutes FIELDNAME, CHANGEABLE and INACTIVE.

In order to ensure that the attributes of the corresponding UI elements are adjusted accordingly, the mappingof the CRM field name to the UI Element of the additional fields needs to be entered in the UI elementdefinition in the XCM file uicontrol-config.xml. Thus the display attribute of the UI element will be adoptedgenerically from the table parameter HEADER_STATUS_CHANGEABLE respectivelyITEM_STATUS_CHANGEABLE. For the item fields the label of the items needs to be assigned to thedescription fields of the UI element in order to enable the display the field labels of the additional fields.

Example


August 2008 218

BAPIs/SAP ERP-ExtensionsThis section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with SAP ERP as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer. Youonly need to extend the Interaction Layer with actions to fill your additional fields.

The solution consists of two parts: the extension concept for Business Objects in the Java layer and theABAP extension structure in the SAP ERP BLS layer.

Use String objects when storing extension data, if you want to access this data from thebackend.

To extend a Business Object with your own fields, you need to implement the corresponding appendstructures in SAP ERP, where the fields are filled in extension structures as name value pairs. Furthermore,you have to declare all additional data fields transferred via the extension structure in the configuration of theweb application. After that you can access the field using the key from the extension in the Java layer. Theextensions in the Java layer are also key value pairs that are assigned to the corresponding BusinessObjects.


ABAP Extension Structure (BAPIPAREX)Field Type Description

STRUCTURE TE_STRUC Structure name of BAPI table extension.

<UIElement name = "order.item.deliveryPriority" description = "b2b.order.display.deliverPrio" allowed = "true" disabled = "false">

<backend structureName = "ORDER_ITEM" fieldName = "DLV_PRIO" />

</UIElement>


August 2008 219

VALUEPART1 VALUEPART Extension data (240 characters).




Table 56: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects.

OrderFunction module Business object

SD_SALESDOCUMENT_CREATE HeaderSalesDoc ItemSalesDoc

SD_SALESDOCUMENT_CHANGE HeaderSalesDoc ItemSalesDoc

BAPISDORDER_GETDETAILEDLIST HeaderSalesDoc

Table 57: ERP - Supported Function Module / Business Objects – Order

Please also check the chapter ‘


August 2008 220

Generic Search Framework’ (page 101).


August 2008 221

Modification of Communication Structures in SAP ERPIn contrast to the BADI/SAP CRM extension concept, where additional data are transferred by name/ valuepairs, in the BAPI/SAP ERP extension concept only values of additional data are transferred. The sequenceof data, as well as the data length of the individual data fields within the extension structure BAPIPAREX, isdefined in the SAP ERP DDIC by so-called communication structures (e.g. BAPE_VBAK).

These communication structures have to be modified/ extended by the data fields which have to betransferred between the extension structure and the data structures in SAP ERP. By default, data istransferred to specific SAP ERP data structures based on equal field names (using move-corresponding):

Communication structure ERP Data structure Description

BAPE_VBAK VBAK Order header data (default structure).

BAPE_VBAP VBAP Order item data (default structure).

BAPI_VBKD VBKD Order business data.*

Table 58: Communication Structure in SAP ERP

* If the structure BAPI_VBKD should be used for transferring data on order header and/or order item level tothe ERP data structure VBKD also parameter structure and/or structureitem has to be changed in theconfiguration backendobject-config.xml (see bellow).

If the data should be transferred to other data structures in SAP ERP you have to implement an additionalform routine for data transfer (see below).

Configuration of the Web ApplicationCorresponding to the SAP ERP system, you have to define the data definition of the communicationstructure in ISA, in configuration backendobject-config.xml (see Changes in backendobject-config.xmlon page 275), for transfer of data between the extension structure and the business object extension data.The definition of the fields must contain name/length pairs separated by comma:

<businessObject type=‘EXTENSION_DOCUMENT_CREATE’

name=‘EXTENSION_DOCUMENT_CREATE’

className=‘com.sap.isa.backend.r3base.ExtensionParameters’

attributes=‘standalone’>

<params>

<param name=‘structure’ value=‘BAPE_VBAK’/>

<param name=‘structureItem’ value=‘BAPE_VBAP’/>

<param name=‘fields’ value=‘ LIFSK,2’/>

<param name=‘fieldsItem’ value=‘ LPRIO,2,WERKS,4’/>

</params>

</businessObject>


August 2008 222

Reading Data from the BackendIf the additional data should be read from the default data structure (see above), no further activities arenecessary.

Only character type data can be transferred through this mechanism, binary data has to beconverted before transfer.

If the additional data should be read from a different data structure, an additional form routine for datatransfer has to be implemented, as shown in the following example:

Writing Data to the BackendIf the additional data should be transferred to the default data structure (see above), no further activities arenecessary.

The extension structure can only used for character type data, binary data in the data structurehas to be converted before transfer.

If the additional data should be transferred to a different data structure, an additional form routine for datatransfer has to be implemented, as shown in the following example:

* Extensiondata write - Header

MOVE SALES_DOCUMENTS TO WA_BAPE_VBAK-VBELN.

MOVE ORDER_BUSINESS_OUT-PMNTTRMS TO WA_BAPE_VBAK-ZZPMNTTRMS.

READ TABLE EXTENSION_OUT WITH KEY STRUCTURE = ’BAPE_VBAK’.

TABLE_TABIX = SY-TABIX.

IF SY-SUBRC NE 0.

CATCH SYSTEM-EXCEPTIONS CONVERSION_ERRORS = 1.

MOVE ´BAPE_VBAK´ TO EXTENSION_OUT-STRUCTURE.

MOVE WA_BAPE_VBAK TO EXTENSION_OUT+30.

ENDCATCH.

APPEND EXTENSION_OUT.

ELSE.


MOVE WA_BAPE_VBAK TO EXTENSION_OUT+30.

ENDCATCH.

MODIFY EXTENSION_OUT INDEX TABLE_TABIX.

ENDIF.


August 2008 223

ExampleChapter ‘Extensions Demo 5 – Maintain Delivery Block Indicator in ECO ERP’ of the ‘Development andExtension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 305).

Java Basket-ExtensionsThis section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with the Java basket as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer.

An automatic transfer of extension data from the Business Object to the Java Basket is onlypossible for extension data attached to the basket header or to the basket items. Extension dataattached to other business objects, for example the ship to have to transfered manually byextending the corresponding standard backend objects.


Example(no example available)

Request ContextThe request context is a container enabling you to easily exchange data between layers in an Internet Salesapplication. The context is accessible from nearly everywhere within the ISA framework, making it a verypowerful way to exchange data. Using the request context violates some rules defined for standard ISAdevelopment. It is therefore not used within the standard coding of Internet Sales.

The Request context is represented by the class com.sap.isa.core.RequestContext.

The follwing table shows how to access the Request Context in the various places:

Location Method for Accessing Request Context

* Extensiondata read - Header

READ TABLE EXTENSION_IN WITH KEY STRUCTURE = ’BAPE_VBAK’.

IF SY-SUBRC EQ 0.


MOVE EXTENSION_IN+30 TO WA_BAPE_VBAK.

ENDCATCH.

ENDIF.

MOVE _BAPE_VBAK-ZZPMNTTRMS TO ORDER_BUSINESS_IN-PMNTTRMS.


August 2008 224

JSP RequestContext.getRequestContext(request)

Action getRequestContext()

Business Object getRequestContext()

Backend Object getBackendObjectSupport().getRequestContext()

Function Moduleexecution listener

Within the connectionEvent(JCoConnectionEvent event)method of afunction module execution listener (com.sap.isa.core.eai.sp.jco.JCoConnectionEventListener)

event.getRequestContext()

For further information about execution listeners refer to chapter 'Interception of Callsto Standard Function Modules' on page 225.

Table 59: How to access the Request Context

The request context can store any type of data. The most important methods are:

addData(Object name, Object value)

o Stores any kind of data

Object getData(Object name)

o Returnes the stored data or null if not data with the given name is available in the RequestContext

For more information about the Request Context refer to the Java Doc ofcom.sap.isa.core.RequestContext

The scope of the request context is one request (usually one HTTP request). After the request is finished thecontext is cleared. If you want to store data between requests use the Business Object layer or use thesession context instead.

VersionThis feature is available in CRM ISA 5.0.

ExampleThis example demonstrates how to pass data from Function Module Execution Listener to a JSP:

You would like to pass the value of an export parameter of a function module, called by the standard to theJSP:


August 2008 225

Retrieve the value within the JSP

This function event listener must be registered in the file

/WEB-INF/xcm/customer/modification/modification-config.xml in order to be notified whenthe function module is executed.

For information how to work with function module execution listeners refer to chapter 'Interception of Calls toStandard Function Modules' on page 225.

Adding additional Function Modules (Backend System)Function modules are accessed by Backend Objects. If you have to access your own custom functionmodules you usually do it by writing a Backend Object. Backend Objects are accessed by Business Objectsvia well-defined Java interfaces.

...

<%@ page import=‘com.sap.isa.core.RequestContext’ %>

<%

String myValue = RequestContext.getRequestContext(request).getData(‘z_Value’);

%>

...

public class MyListener implements JCoConnectionEventListener {

public void connectionEvent(JCoConnectionEvent event) {

// This event listener is called twice: before the function

// module is executed and after

// we are only intersted in the event after function call

if (event.getId() == JCoConnectionEvent.AFTER_JCO_FUNCTION_CALL) {

// get reference to JCO Function

JCO.Function func = event.getJCoFunction();

// get custom value from import parameter name z_value

String z_Value = func.getExportParameterList().getString(‘z_value’);

// pass value to RequestContext

event.getRequestContext().addData(‘z_Value’, z_Value);

}

}

}


August 2008 226

Figure 63: Adding additional Function Modules

In this case you must do the following

1. Write a Business Object that is used by the Interaction/Business Object Layer to access newfunctions.

2. Write an interface that is used by the Business Object to access a corresponding Backend Object.

3. Write a backend-specific implementation of the Backend Object.

For detailed information on how to write Backend Object, see chapters:

'Business Logic Service Layer Details' on page 77.

'Create a Customer Business Object' on page 200

'Create a Customer Backend Object' on page 204



Interception of Calls to Standard Function ModulesThis concept allows you to intercept calls to remote callable function modules in a SAP CRM or SAP ERPsystem, without changing the Java coding provided.

You can use this extension concept to intercept calls

To any function module called by ISA

To function modules you have registered as described in chapter 'Replacing Calls to StandardFunction Modules (Backend System)' on page 227.

The basic idea behind this concept is to register a Java event listener, which is notified before/after a functionmodule is called. The listener can be used to manipulate the function call, and has access to theRequestContext, meaning that it can communicate with other parts of the application (Action, JSP, BusinessObject, Backend Object).

The following diagramm shows the how this concepts works at runtime:


August 2008 227

BLS ConnectionManagement

Standard ISAclass

Customer executionlistener

executeJCO.Function

notify beforeexecution

Retrieve data from RequestContext if needed

Pass additional data tofunction module if needed.

CRMor R/3

executeJCO.Function

notify afterexecution

Retrieve data from functionmodule if needed. Pass data

to Request Context ifneeded

returnJCO.Function

Figure 64: Java event listener for Standard Function Modules

This concept can also be used to extend the interface of an existing function module with optionalparameters and pass/retrieve additional data. Nevertheless, this extension concept should only be usedwhen the function module, which you would like to extend, has no extension table (see 'chapter BADIs/SAPCRM Extensions' on page 211).

Please keep in mind, when you extend these interfaces, that the interfaces of existing functionmodules can change with subsequent releases of ISA. It is also possible that the functionmodule will be replaced in subsequent releases.

A common modification is the addition of optional parameters to the interface of the function module. In thiscase you will usually perform one, or both, of the following modifications:

Provide additional data by using the optional parameters, before the function module is called. Youcan pass data to the execution listener using the RequestContext

Retrieve additional data from the optional parameters, after the function module has been called.You can pass this data to back (e.g. to Action or JSP) using RequestContext

When a function module is executed two events are triggered:

Before the function module is called

After the function module has been called

Within the event you have access to the RequestContext. This gives you the opportunity toprovide/retrieve additional data from other layers of the application (Action, JSP, Business Object, BackendObject).

Within the event you have access to the JCO.Function, which is called. This gives you the opportunity toprovide/retrieve additional data in your optional parameters.


August 2008 228

Thread Safety in Execution ListenersPlease note that every listener has configuration scope! That means that you shouldn’t define instancevariables within the listener if the data have to have session scope. If the listener wants to access session-specific data, it has to use the backend context or the RequestContext.



What to DoThe following steps describe the tasks you have to perform:

1. Write an execution event listener by implementing thecom.sap.isa.core.eai.sp.jco.JCoConnectionEventListener interface.

2. Register the listener within WEB-INF/xcm/customer/modification/modification-config.xml. You can define for which function module the exection listener should be notified

Within the listener the connectionEvent(JCoConnectionEvent event) method is called when afunction module is executed. Within this method you have the follwing possibilites:

o You can find out which function module has been called by callingevent.getJCoFunction().getName()

o You can find out if this is an event before, or after, the function call by retrieving the event idevent.getId(), and comparing with event.AFTER_JCO_FUNCTION_CALL orevent.BEFORE_JCO_FUNCTION_CALL.

o Access the RequestContext by calling event.getRequestContext()

o Pass your additional data to the function module before it is called, or retrieve additional dataafter the module has been called. Within the event handler method you have full access tothe JCO.Function object.

ExampleFor an example on this modification, see ‘Extension 5: Maintain Delivery Block Indicator for ECO ERP in the‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapterReferences on page 305).

Replacing Calls to Standard Function Modules

<function-module-listener>

<param

name=‘fmevent:NAME_OF_FUNCTION_MODULE’

value=‘ClassNameEventListener’/>

</function-module-listener>


August 2008 229

(Backend System)This concept allows you to replace calls to remote callable function modules in a SAP CRM or SAP ERPsystem without changing the Java coding provided.

You can use this extension concept to let the application call your function modules, instead of the standardfunction modules.

Prerequisite is that the interface of your function module is compatible with the interface of the standardfunction module called by ISA, that means your function module can only provide additional parameters butyou must not change/or delete parameters of the standard function module.

To allow the ISA application to call your function module you have to register it in the WEB-INF/xcm/customer/modification/modfication-config.xml

The following diagram shows the runtime behavior of this extension concept

BLS ConnectionManagement

Standard ISAclass

getJCoFunction

Z_Function inCRMor R/3

return Z_Function havingsame or compatible

interface as standard function

Check ifreplacement function

was registered inbackendobject-config.xml

fill import parametersand tables execute Z_function

performoperations

StandardFunction

call standard

performoperations

return function

Figure 65: Replacing calls to Standard Function Modules



What to Do Create an own Z_ function module having the same or an compatible interface as an function

module called by the ISA standard coding (e.g. Z_CRM_ISA_SHOP_GETLIST)


August 2008 230

Register the function module within WEB-INF/xcm/customer/modification/modfication-config.xml

Instead of the standard function module, your function module will be called during runtime

ExampleSee Customer Specific Views in the Web Catalog (SAP ERP Backend and TREX) on page 235

Extension of the Web Catalog

New Fields in the Web Catalog (SAP CRM Backend)Showing more attributes in the web catalog is very easy, since no java class needs to be touched. Just addthe attribute in product catalog maintenance in SAP CRM and adapt the JSPs accordingly.

PreparationCreate a catalog, variants, shop, and so on in SAP CRM. Go to catalog maintenance and add a list ofcharacteristics to the catalog that contains the attribute you want to add. For this example, please add anattribute Z_COLOR, for the color of the product. Ensure that this attribute is maintained for the products inyour catalog, otherwise you will only see an empty field in the web catalog. Launch an initial indexing run(replication) for the catalog variant.

Create a resource key that has the name catalog.isa.attribute.Z_COLOR with a value like color inyour language resource file ISARessources.

Show Additional Attribute in Product ListOnly some attributes of the item are displayed in the product list, due to space constraints.

The JSP responsible for the product list is /b2b/catalog/ProductsISA.inc.jsp for B2B and/b2c/catalog/ProductsB2C.jsp for B2C. Both are similar.

For this example we will use the B2B JSPs. In ProductsISA.jsp the part between <thead> and </thead> isresponsible for the table headings. For the new attribute, we need an additional heading in the area betweenthese.

For example, after:

add the line:

<function-module-replacement>

<param name=‘fm:CRM_ISA_SHOP_GETLIST’ value=‘Z_CRM_ISA_SHOP_GETLIST’/>

</function-module-replacement>

<th><isa:translate key=‘catalog.isa.description’/></th>


August 2008 231

This will ensure that the heading of the column Color is displayed.

After that, the items are iterated in the JSP and the data is displayed. We put the heading after that of thedescription, so we also need to put the content after the content of the description. The content of thedescription field is displayed with:

After this, insert the display of the content of the new attribute:

The row span is needed in B2B, because if contracts are displayed, an additional row will be displayed foreach contract. Our attribute is valid for the product in general and therefore the table cell should span overthese contract lines too.

Show Additional Attribute in Product Details and in CompareProductsThere are two types of attributes; category-specific and catalog-specific. By default, only the category-specific attributes are displayed.

The ProductDetailsISA.jsp, CompareItemsISA.jsp (for B2B), and the ProductDetailB2C.inc,CompareItemsB2C (for B2C) respectively, are designed in such a way that all catalog-specific attributes thathave a non empty description and their names conatin a “_“ (item.getAttributeDescription() !=null && item.getAttributeName().indexOf("_") != 0) are shown, or all catalog-specificattributes that have a resource key corresponding to the patterncatalog.isa.attribute.<attribute_name> are shown. This means, if an additional catalog specificattribute Z_MyAttribute should be displayed, an appropriate resource key has to be added to theISAResource file(s):catalog.isa.attribute.Z_MyAttribute=AttributeName

See also note 452751.

<td rowspan=‘<%= noOfContractItems %>‘ align=‘center’>

<%= item.getAttribute(‘Z_COLOR’) %>

</td>

<td rowspan=‘<%= noOfContractItems %>‘ align=‘center’>

<a href=‘javascript:seeSingleItem('<%= item.getItemID() %>')’ >

<%= item.getAttribute(‘OBJECT_DESCRIPTION’) %>

</a>

</td>

<th rowspan=2 align=center>

<isa:translate key=‘catalog.isa.attribute.Z_COLOR’/></th>


August 2008 232

Show Additional Keys for Extended Search in B2BThe extended search is done with respect to catalog-specific attributes. By default, only the OBJECT_ID andOBJECT_DESCRIPTION attributes are taken into consideration. However, it is very easy forbigSearch.jsp to display new search keys. Each attribute that has a resource key corresponding to thepattern catalog.isa.bigSearch.<attribute_name> gets an input field displayed, and can, therefore,be used as a search key. See also note 482338.

New Fields in the Web Catalog (SAP ERP Backend andMemory Catalog)This unit describes how additional attributes can be transfered from the SAP ERP system to the ISA productcatalog, using the memory catalog. In addition to the extensions described in this unit, the ISARessource filehas to be extended to display in ISA CRM the additional attributes in the product detail of the web catalog,and to search in the catalog. If the attributes should be displayed in the product list of the web catalog, theappropriate JSP has to be extended as for ISA CRM.

Loading additional Product Attributes from the SAP ERPBackend to the Memory CatalogAdditional product attributes can be transferred from the SAP ERP Backend to ISA using a predefinedcustomer exit performCustomerExitAfterCatalogRead in the classcom.sap.isa.backend.r3.catalog.R3CatalogServerEngine. The method is shipped empty andcalled after reading the catalog. The parameters of the method are the catalog and a JCO connection to theSAP ERP system. In the method additional data can be read from the SAP ERP system and added to thecatalog.

The following steps have to be performed:

1. Create a new class extendingcom.sap.isa.backend.r3.catalog.R3CatalogServerEngine.

2. Implement the method performCustomerExitAfterCatalogRead. Use the JCO connectionprovided as call parameter to read additional information from SAP ERP, if necessary, and add theresults to the catalog object.

3. Register your individual class instead ofcom.sap.isa.backend.r3.catalog.R3CatalogServerEngine in with the ISA extensionconcept as described in ‘ Changing existing Backend Object’ on page 275.


ExampleSee note 610393.


August 2008 233

New Fields in the Web Catalog (SAP ERP Backend andTREX)This unit describes how additional attributes can be transferred from the SAP ERP system to the ISA productcatalog, using the TREX. In addition to the extensions described in this unit, the ISARessource file has beextended as for ISA CRM for display the additional attributes in the product detail of the web catalog, and forsearching in the catalog. If the attributes should be displayed in the product list of the web catalog, theappropriate JSP has to be extended as for ISA CRM.


August 2008 234

Loading additional Product Attributes from the SAP ERPBackend to the TREXAdditional products attributes can be transferred from the SAP ERP Backend to TREX by using the methodsATTRIBUTE_NAMES_GET and NODE_GET_ATTRIBUTE_VALUES of classCL_ISA_REPLICATION_CATALOG. The first method is used to define the names and types of the attributeson TREX, the second method is called for every catalog area and item to add values for the additionalattributes. The methods are delivered empty in the standard class and have to be redefined in a customerclass inheriting from CL_ISA_REPLICATION_CATALOG. The usage of the new class is controlled by theBAdI BADI_ISA_REPL_CAT.


1. Use the class builder (transaction SE24), to create a new class named ZCL_ISA_REPLICATION_CATALOGinheriting from CL_ISA_REPLICATION_CATALOG (use the button “Define inheritance” next to the file namein the creation dialog).

2. Redefine the methods IF_ISA_REPLICATION_CATALOG~ATTRIBUTE_NAMES_GET andIF_ISA_REPLICATION_CATALOG~NODE_GET_ATTRIBUTE_VALUES. See the example below forfurther details.

3. Create a new implementation for BAdI BADI_ISA_REPL_CAT. The BAdI implementation is used to return aninstance of your catalog class instead of the standard class. The standard implementationISA_REPL_CAT_IMP_DEF can be used as a template.

After the replication using transaction ISA_CAT_REPLICATION, the new attributes are created on TREX.


ExampleThis example shows how to define the view attribute (see also chapter “Customer Specific Views in the WebCatalog (SAP ERP Backend and TREX)” on page 235) and an additional attribute MAT_GROUP that willcontain the material group of a catalog item.

The first method defines the attribute names and specifies the attribute type. Available attribute types are:I (Integer)F (Floating Point)D (Date YYYYMMDD)S (String)N (Char)T (Time)U (UTC Date-Time)

The attribute definitions must be put into the 2 separate changing parameters (tables) ITEM_ATTRIBUTESand AREA_ATTRIBUTES. This example only deals with item attributes:


August 2008 235

The second method is called once for each catalog node (i.e. for each area and each item). Therefore itsinterface contains only one parameter ATTRIBUTES with attribute assignments. The method checks if thecaller passed an area or an item. For each item, it assigns the content of field MARA-MATKL from materialmaster data to the attribute MAT_GROUP. Furthermore, it assigns the material’s industry sector (field MARA-MBRSH) to VIEWS_ID. Hence, we create one catalog view per industry sector throughout the catalog. If moreview assignments shall be made, it’s important to increase the multi-value counter per view id. See thecoding comment below.

METHOD if_isa_replication_catalog~attribute_names_get.

DATA: item_attribute LIKE LINE OF item_attributes.

item_attribute-attrname = 'VIEWS_ID'. "special attribute for views

item_attribute-attrtype = 'S'. "String

APPEND item_attribute TO item_attributes.

item_attribute-attrname = 'MAT_GROUP'. "material group

item_attribute-attrtype = 'S'. "String

APPEND item_attribute TO item_attributes.

ENDMETHOD.


August 2008 236

Customer Specific Views in the Web Catalog (SAP ERPBackend and TREX)This unit describes how to get customer specific views of the product catalog with an SAP ERP backendsystem and the TREX catalog (see also note 696095).

METHOD if_isa_replication_catalog~node_get_attribute_values.

DATA: lv_attribute LIKE LINE OF attributes,

lv_mara TYPE mara.

IF NOT item IS INITIAL. "create attribute values for the item

* read material master data for the given catalog item

CALL FUNCTION 'MARA_SINGLE_READ'

EXPORTING

matnr = item-material

IMPORTING

wmara = lv_mara

EXCEPTIONS

lock_on_material = 1

lock_system_error = 2

wrong_call = 3

not_found = 4

OTHERS = 5.

IF sy-subrc <> 0.

MESSAGE ID sy-msgid TYPE sy-msgty NUMBER sy-msgno

WITH sy-msgv1 sy-msgv2 sy-msgv3 sy-msgv4

RAISING error_in_catalog_api.

ENDIF.

* assign material group to the corresponding attribute

lv_attribute-attrname = 'MAT_GROUP'.

lv_attribute-attrvalue = lv_mara-matkl.

APPEND lv_attribute TO attributes.

* build catalog views according to industry sector

lv_attribute-attrname = 'VIEWS_ID'.

* when assigning the item to more than 1 view, each line has to use a

* different number for the multi-value counter. In this example it's

* only 1 value, therefore you could even skip the counter assignment.

lv_attribute-multatrcnt = 1. "the multi-value counter

lv_attribute-attrvalue = lv_mara-mbrsh.

APPEND lv_attribute TO attributes.

ENDIF.


August 2008 237

Customer specific views of the product catalog are created by matching ‘catalog view’ attributes, attached tothe (ECO) product catalog area/item, with the (ECO) customer. These attributes have to be transferred fromthe SAP ERP Backend to ECO via the SAP ERP function modules ISA_READ_CATALOG_COMPLETE andISA_CUSTOMER_READ_CAT_VIEWS. Neither function module retrieves any ‘catalog view’ attributes instandard, but both have to be extended due to individual requirements.


1. Create a new SAP ERP function module Z_READ_CATALOG_COMPLETE by copying the standardfunction module ISA_READ_CATALOG_COMPLETE (see note 677320).

2. Implement a new form routine to retrieve the ‘catalog view’ attributes and to fill the data to the tableATTRIBUTES.

o attributes-layout - catalog layouto attributes-area - internal area numbero attributes-item - internal item number (if required)o attributes-name – ‘VIEWS_ID’ (fix value)o attributes-value - value of ‘catalog view’ attribute

3. Register the new SAP ERP function module instead of the standard SAP ERP function moduleISA_READ_CATALOG_COMPLETE with the E-Commerce extension concept as described in Changesin Configuration on page 274.

4. Create a new SAP ERP function module Z_CUSTOMER_READ_CAT_VIEWS with an interface asdescribed in note 677319 for function module ISA_CUSTOMER_READ_CAT_VIEWS.

5. Implement a new form routine to retrieve the ‘catalog view’ attributes and to fill the data to the tableCATALOG_VIEWS.

o catalog-views-string – value of ‘catalog view’ attribute6. Register the new SAP ERP function module instead of the standard SAP ERP function module

ISA_CUSTOMER_READ_CAT_VIEWS with the E-Commerce extension concept as described inChanges in Configuration on page 274.

7. Activate catalog views in the web shop definition.

VersionThis feature is available in E-Commerce 5.0

ExampleSee note 677319 and the example in chapter “New Fields in the Web Catalog (SAP ERP Backend andTREX)” on page 232.


August 2008 238

Extensions of the IPCThe IPC (Internet Pricing And Configurator) is a reusable component for pricing and interactive configuration.It consists of the pricing engine (SPE) the sales configuration engine (SCE) and the interactive configurationuser interface. SCE and SPE are components of the SAP application server. The interactive configurationuser interface is a web application based on the E-Commerce application framework.

The main focus of this chapter is with regards to the IPC is on the Interactive Configuration user interface.SCE and SPE engines that form the IPC “server” have their own extension mechanisms (user exits asdescribed in notes 809820 and 870201).

The following unit introduces some modification concepts related to the IPC user interface as part of the E-Commerce web applications (b2b and b2c) or as a separate web application (ipc) which is used in SAPscenarios (Interactive configuration in CRM Order, Mobile Sales order, ERP order, Vehicle Manager ...).

Since the Interactive Configuration UI uses the E-Commerce framework, it also supports the modificationconcepts of the framework.

The section below explains additions and differences to the E-Commerce extension concept.

Please give your feedback (corrections, additions) about the IPC chapter to [email protected].

Architecture of the IPC 5.0 UI in CRM Order ScenarioThis unit gives an introduction to the IPC UI concepts.

SAP R/3BackofficeSystems

(SD, PLM,MM,PP...)

R/3Plug-In

Optional:

No SAP R/3 backend(data maintainanceincluding pricing andconfiguration data inSAP CRM)

SAP CRMSystem

HTML control

Customer Data

Order Data

Product Catalog

Product Master...maintain

configurationmodels

IPC

SAP J2EE Engine

Java Server Pages

UI Beans

Struts Actions

IPC Client ObjectsAPI

HTTP Server

Get and Modifyconfigurationstate

DisplayconfigurationUI

Master Data(products,

knowledge bases,pricing

TransactionData (order..)

Figure 66 The IPC and its UI in the CRM Online Landscape

The picture above shows the setup and communication of the IPC web application (above: SAP CRM orderscenario). You can find detailed descriptions in the installation documents on the SAP Service Marketplaceunder alias /crm-inst.


August 2008 239

In summary:

There is a clear separation between the IPC engines as part of the CRM or ERP system and the IPCWeb Application, which is the JSP UI used for interactive product configuration and runs on the SAPJ2EE Engine.

As of release 5.0 the IPC is not a separate server anymore. The IPC comes with the CRM or ERPand exchanges data with its client applications via RFC.

In all scenarios (including ISA CRM, ISA ERP), the IPC reads master data directly from the SAPCRM or ERP server; The former dataloader is not required anymore.

Instead of directly calling RFC function modules, the interactive configuration (JSP) UI uses anabstraction layer (Client Object API) very similar to the ISA Business Object/Backend Object APIswith Java methods.

Internet Sales; CRM online;Vehicle Management System;

ERP

JSP Pages

UIBeans UIClasses

Client Object Layer Interface

Remote Function Call TCP/IP

Virtual Machine Container MSA IPC Server

SPE/SCE Integration

Pricing Engine Configurator

Actions

SPE/SCE Integration

Pricing Engine Configurator

Mobile Sales

Figure 67 IPC Architecture more in detail

The above slide shows the layered architecture of the IPC.

The UI part (JSP, Actions, Client Object Layer Interface, …) on top of the graphic is the same in allscenarios.

The “server” part depends on the scenario in which the UI is used

1. ISA, CRM online, VMS, ERP: The IPC “lives” inside of the SAP application server. The UIcommunicates with the IPC over remote function calls

2. Mobile Sales: The IPC is a process running on the mobile client. The UI communicates with the IPCover a string based socket protocol (as in 4.0).

Design of the JSP Web Application:

The IPC UI uses the ISA Framework (Layout, Backend communication, XCM, Tags, …)

The IPC UI does not use html frames

The Javascript is separated into script files

Action Forms are not used


August 2008 240

Action Flow

Action:setCharacteristicValues

Action(s):displayLayout

Post

Forw

ard

todi

spla

yLay

out

redirect Get

Data Processing Data Display

Figure 68 General Action Flow

The slide shows the general action flow in the 5.0 UI (same as in E-Commerce applications). We can dividethe action flow into two blocks:

1. Data processing actions: Receives user input via http post request and changes the state of theconfiguration

2. Data display actions: Reads the current state of the configuration, creates the html according to thelayout and sends the response

Use of the E-Commerce Layout FrameworkThe interactive product configuration user interface takes advantage of the E-Commerce Layout Framework.For detailed explanation of the E-Commerce Layout Framework refer to chapter Error! Reference sourcenot found. for more details.

UI ComponentsThe XCM file /sap/modification/ipclayout-config.xml defines the UI Components that arecommon for SAP’s standard applications that include the interactive configuration ui (b2b; b2c; ipc).

UI LayoutsThe XCM file /sap/modification/layout-config.xml defines the layouts of the application. Thecommon UI components of the interactive configuration ui together with the UI components of the standardapplication form these layouts.


August 2008 241

Figure 69 Example for layout with UI components from both files (layout-config and ipclayout-config)

The XCM file /sap/modification/layout-config.xml includes/sap/modification/ipclayout-config.xml so that at runtime both files form one XCM file.

Technical background of this separation between layout-config and ipclayout-config is that UI componentsfrom ipclayout-config can be reused.

UI AreasThe picture below shows the partitioning of the interactive configuration UI in different UI Areas. Theses UIareas are filled with UI components at runtime.

Figure 70 UI areas of the config UI


August 2008 242

TilesThe layout of the interactive configuration is highly dynamic. The work area for example lists a variablenumber of characteristics that may differ in their presentation to the user.

In order to support modifications on such a fine-grained level of UI parts, the interactive configuration UIintroduces the concept of “tiles”.

Tiles are low level UI parts included by UI Components.

Figure 71 Example for tiles

The interactive configuration UI uses tiles mainly for rendering of characteristic values. You’ll find tiles insoftware component SAP-SHRWEB in development component crm/ipc/web/ipcshared in folder ipc/tiles.

Low level layoutsIn order to reuse tiles, the UI combines tiles with low level layouts. This low level layout technique is differentfrom the UILayouts of the E-Commerce Framework.

Low level layout pages carry only layout information. Tiles carry content.

The picture below demonstrates how layout and tiles are combined. The layout JSP page is very simple andholds only a table in which the tiles are included. You’ll find layouts in software component SAP-SHRWEB indevelopment component crm/ipc/web/ipcshared in folder ipc/layouts.


August 2008 243

Figure 72 Combining low level layout and tiles

Dynamic IncludesThe application calculates at runtime which layouts to combine with which tiles. Layouts and tiles carry keysthat the application replaces at runtime by the physical file path of the JSP page for the layout or tile. Theapplication does this with a XCM customizing table lookup in file jspinclude-config.xml for eachrequest before sending the response back to the users browser.


August 2008 244

Figure 73 JSP Key and Path

The indirection -> key -> XCM table lookup -> physical path gives application programmers the possibility toeasily replace SAP’s standard JSP pages by their own pages inxcm/customer/modification/jspinclude-config.xml. You will find an example for this techniquein Change UI Components.

The Interactive Configuration UI performs dynamic includes using static methods (“include”) of UIClasses.You’ll find UIClasses in software component SAP-SHRJAV in development component crm/ipc/ipc infolder com/sap/isa/ipc/ui/jsp/uiclass. The include methods offer a typesafe api to the page. Theymake sure that the parameters passed to the included page do not interfere with parameters used by otherincluded pages.

public static void include(

PageContext pageContext,

String characteristicController,

UIContext uiContext,

InstanceUIBean instance,

GroupUIBean charGroup,

CharacteristicUIBean cstic,

UIArea uiArea,

Hashtable customerParams) {


August 2008 245

The included page retrieves the parameters by the following call:

CharacteristicUI.IncludeParams includeParams = CharacteristicUI.getIncludeParams(pageContext);

InstanceUIBean currentInstance = includeParams.getInstance();

GroupUIBean characteristicGroup = includeParams.getCharGroup();

CharacteristicUIBean characteristicUIBean = includeParams.getCstic();

UIContext uiContext = includeParams.getIpcBaseUI();

UIArea csticsArea = includeParams.getUiArea();

Hashtable customerParams = includeParams.getCustomerParams();

You may pass parameter between jsp pages only via the session or request context. The interactiveconfiguration UI consists of recursively nested JSP pages. Include parameter are supposed to be valid onlyfor the current include method and not visible for all the included pages. The parameter stack ensures thatgetIncludeParams retrieves those parameter that are passed with the last include method. That means onthe top of each included page you need to call getIncludeParams(pageContext).

Extension To Transfer Data To JSPIn addition to the standard ways to transfer data to JSP pages described in this document, the dynamicincludes with UIClasses used in the interactive product configuration offer a possibility to pass extension datato JSP pages. All include methods of UIClasses offer a customerParams parameter. All IncludeParamsobjects have a method getCustomerParams() that returns a Hashtable.

UIBeansUIBeans form an intermediate layer between the JSP pages and the Business objects (IPC client objectlayer). Methods of UI Beans are optimized for use within the JSP pages and reduce the complexity of theJSP pages.


August 2008 246

Figure 74 Interaction of UIBeans with the JSP pages and the Busines Object Layer

Client Object LayerThe IPC client object layer is the business object layer and the backend layer of the IPC. It performs cachingand provides convenient Java API’s to its calling applications. It performs communication with the IPC in thebackend via RFC function calls or Socket commands (Mobile Sales). Please see Figure 67 IPC Architecturemore in detail.

Finding The Appropriate Extension Concept For IPCThe chapter Error! Reference source not found. applies also to the Interactive Configuration UserInterface. Specific concepts are described in this chapter.


August 2008 247

Static extension to UI layer

Changing StylesheetsIn order to define your own styles to change the appearance of the application, you will need to

1. Create your own stylesheet file as a copy of SAP’s standard stylesheet

2. Register your own stylesheet in /xcm/customer/modification/init-config.xml.You will find an example on how to do this in /xcm/customer/modification/init-config.xml.

3. Change SAP’s standard style definitions in your own stylesheet or add new styles for your own JSPpages.

IPC shared styles are located in software component SAP-SHRWEB development componentcrm/ipc/web/ipcshared/ folder ipc/mimes/style/stylesheet.css. Shared styles means thosestyles are common to b2b, b2c, and ipc web applications.


August 2008 248

Create New Layout Or Change Standard LayoutThe only thing that differs here from the E-Commerce framework is the location of UIComponents for theinteractive configuration UI. UIComponents are located in /sap/modification/ipclayout-config.xml.

Change UI Components

Example: Customer Buttons and ActionsThe interactive configuration UI gives you the possibility to add three customer buttons to the header areawithout modification to the UI component header.

In order to do this you need to define those customer buttons in the xcm customizing under componentscustomerbutton1 to customerbutton3.

Figure 75 XCM settings for customer buttons

The parameter forward is not supported in SAP’s standard UI. The parameter target allows the three valuesfor html hyperlink targets: _self, _parent, top. By default the result will be displayed in the same frame as theinteractive configuration UI.


August 2008 249

Figure 76 Customer buttons on screen

In order to display language dependend labels for the customer buttons you need to provide the appropriatelabel for the session language in the language dependent resource files. SAP provides three placeholder forcustomer button labels: ipc.customer_button1_label, … (see: Change/add text in the textproperty file (language dependent!))

The customer buttons call the actions that you have defined in the parameter customerbutton1.action. SAPprovides three placeholders for action mappings /ipc/customerButtonXAction in the ipc-config.xml.

Example: Adding Customer Tab To Multifunctional AreaThe interactive configuration UI gives you the possibility to add a customer specific tab to the multifunctionalarea (area on the right side of the standard interactive configuration UI).


August 2008 250

Figure 77 Component configuration for customer tab

You activate this area when setting the parameter “customertab.show” of the XCM componentmultifunctional area to “T”.


August 2008 251

Figure 78 Application configuration for customer tab

Figure 79 Customer tab action mapping

When you click on the customer tab, by default the system will execute the actioncom.customer.isa.ipc.ui.jsp.action.GetCustomerTabAction. This action will display the page/ipc/customer/components/customerTab.jsp in the multifunctional area. The customer tab will beactive. The example delivered by SAP displays the characteristic details in the customerTab.jsp.

You may either change the content of the action and the customerTab.jsp page or change the actionmapping to use your own action and forward to your own JSP page.


August 2008 252

Figure 80 Customer tab with characteristic details

Example: Display Characteristic Header And Values In OneLineDepending on the space on screen and your configuration model (length of characteristic names andvalues), you may want to display the name of the characteristic and its values in one line to save verticalspace. Software component SAP-SHRWEB, development component crm/ipc/web/ipcshared, folderipc/customer/tiles/characteristic.jsp shows the modified JSP page./xcm/customer/modification/jspinclude-config.xml shows an example how to include thismodified page instead of the SAP standard page.


August 2008 253

Extensions To The UIBean LayerThe interactive configuration creates UIBeans using a generic factory that you may subclass and replaceSAP’s standard UIBean factory.

You may register your own UIBeanFactory in /xcm/customer/modification/factory-config.xml.The file contains an example for registering a customer UIBeanFactory.

Figure 81 Creating UIBeans via UIBeanFactory

The customer UIBean factory in the example creates an object of typecom.customer.isa.ipc.ui.jsp.beans.ValueUIBean which in turn is a subclass ofcom.sap.isa.ipc.ui.jsp.beans.ValueUIBean and overwrites the getLanguageDependentNamemethod.

I recommend extensions to the UIBean layer if you want to:

1. Perform complex calculations in methods that are relevant for the way you display data but not thebusiness data itself. A good example is the method determineLayout() incom.sap.isa.ipc.ui.jsp.beans.CharacteristicUIBean. This method calculates thecharacteristic layout to be used from a number of characteristic attributes (multi value, intervaldomain, …). This calculation is neither business logic nor should the calculation been done on thejsp page.

2. You extended the business object layer (IPC client object layer) and want to display additional datafrom the business object layer in the JSP pages. The UIBean passes the data through.

Extensions In The Action LayerSince struts 2.1 allows the definition of multiple config-files, SAP introduced a new /customer/ipc-config.xml file.


August 2008 254

Customers may place their own action mappings there.Example:The customer replaces a tile in the application. In this tile he adds a hyperlink that requestsZ_SetCharacteristicValues.do.The action mapping for Z_SetCharacteristicValues.do can be done in /customer/ipc-config.xml

In cases where the customers wants not only to add additional action flow, but to change the action flowdelivered from SAP, those changes in /Web-inf/ipc-config.xml will be supported by the NetweaverDevelopment Infrastructure. The NWDI will support merges of SAP’s corrections and your changes of thosefiles.

You will find an example for an extension in the action layer incom.customer.isa.ipc.ui.jsp.action.GetInstancesAction. This action implements acustomerExit that shows all instance nodes of the instance tree expanded. The example how to change theaction flow is in ipc-config.xml.

Figure 82 Standard customer exit in actions

The shown standard customer exit is called at the end of every IPC action. It allows customers to readrequest parameter from request or requestParser and add, modify or remove the data in the http requestattributes, the userSessionData or mbom.


August 2008 255

Create Customer Backend ObjectTo get additional data from a backend system and to use these data in the interactive configuration UI or inconjunction with IPC pricing functions you would need to either use the E-Commerce extension frameworktechniques like function call interception, calling additional function modules or you need to extend the clientobject layer.

The IPC Client object layer is not only used by the interactive configuration UI, but also by the E-Commercecatalog and the E-Commerce b2c shopping basket for price determination and interactive configuration .

The client object layer provides you analog to the E-Commerce backend layer with connection objects tobackend systems. Using these connections you may call virtually all remote function modules in the backendsystem. You are not limited to IPC function modules. Defining your own connections in XCM, you may callother RFC enabled systems as well.

As with UI Beans, a factory creates the client objects. Analog to the UIBeans you may register your ownIPCClientObjectFactory in /xcm/customer/modification/factory-config.xml. The customerIPCClientObjectFactory should be a subclass of SAP’s standard IPCClientObjectFactory so that you need tooverwrite only those factory methods (newXXX) that create customer client objects. The file factory-config.xml contains an example how to register a customer IPCClientObjectFactory.

The example CustomerIPCClientObjectFactory overwrites the factory method newConfiguration. Theclient object class com.customer.client.object.CustomerDefaultConfiguration introduces anew method “checkAvailibility()”. This method is then used bycom.customer.isa.ipc.ui.jsp.beans.CustomerConfigUIBean in method“getAvailabilityImage()” which in turn is used byipc/customer/tiles/statusbarWithAvailibilityCheck.jsp. The private methodcallATPCheck shows you how you would call remote functions from your customer client objects.

The example shows a complete extension through different layers of the UI.

Here as summary a step by step description how to extend the client object layer by subclassing:

1. Subclass the IPCClientObjectFactory (in the example) CustomerClientObjectFactory

2. Implement the factory method for the client object that you want to modify (in the examplenewConfiguration)

3. Register your CustomerClientFactory in the customer/modification/factory-config.xml

4. Subclass the client object that you want to modify (in the example RfcDefaultConfiguration)

5. Overwrite the methods that you want to change or add new methods (in the exampleCustomerDefaultConfiguration.checkAvailability

6. Use the method of your customer object in the corresponding UIBean or any action (in the exampleCustomerConfigUIBean)

You may also use IPC client objects as container for extension data. Client objects inherit from BOBase andprovide the methods addExtensionData(…), getExtensionData() and removeExtensionData().You would typically use these methods in actions in order to transport your data to JSP pages. You mayacess these data on JSP pages with UIBean.getBusinessObject().getExtensionData().


August 2008 256

Figure 83 Handling extension data at client objects

SCE user functionsPlease refer to note 870201 for information on SCE user functions. Those user functions are independent ofthe interactive configuration UI and therefore not subject of this guide.

Exchange additional data with ECOStandard E-Commerce backend objects used by ECO CRM or ECO ERP provide different customer exits toexchange additional data between E-Commerce and the IPC for pricing, configuration or creating the IPCbasket (only ECO CRM).

For details see Standard Backend Objects providing User Exits on page 204. Examples see ’ExtendingExisting Backend Objects’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples andTutorials’ (see [1] in chapter References on page 305).

http://deigb01s56:1080/public/Doku/UI/B2B/Framestructure/framestruktur_frame.htm


August 2008 257

Extensions of the Document HandlingThis unit describes the UpdateDocumentView Module used to manage the behavior of the user interfacewith respect to the display of documents.

OverviewIn the B2B application you can have up to two active documents (documents having a tab strip in thedocuments frame, and technically with corresponding objects in the business layer); an document you canedit, and a document you cannot edit. Additionally, a catalog page can be displayed. This complexconstellation raises some questions:

Which document should be displayed, if the catalog is closed?

What should be displayed, if a document is closed?

What should be displayed, if the user presses refresh on the browser?

To solve these problems we have introduced an object, which knows the status of the graphical userinterface (GUI), the DocumentHandler. Together with some other objects and actions they form theUpdateDocumentView module.

The UpdateDocumentView module is responsible for representing the following frames:

form_inputThis is the working area. The documents and the catalog are displayed here.

documentsDisplays the tab strips of the documents.

_historyDisplays a list (history) of the last used documents.

Often these frames must be updated together. For example, if a document is opened, it will be displayed inthe form_input frame. A corresponding tab strip is displayed in the documents frame, and the documentmust be set at the beginning of the history.

ImplementationThe diagram shows the main objects of the UpdateDocumentView module:


August 2008 258

Figure 84: Main objects of the UpdateDocumentView module

The DocumentHandler stores the status of the GUI for the documents and the catalog. It knows if thecatalog, a document, or a default page must be displayed. There is only one DocumentHandler object forevery session. It is stored in the session context.

For every active document (document with a tab strip), the JSPs which display the tab strips and the historyneed additional information, for example the text which is displayed on the tab strip and in the history. Thisinformation is stored in a ManagedDocument object. Additionally, a ManagedDocument holds a referenceto the corresponding business object, for example, a reference to the Basket.

The DocumentHandler manages ManagedDocuments. For this, it is generic. You can add new types ofdocuments in the business layer, without modifying the UpdateDocumentView module.

The UpdateDocumentViewAction is responsible for updating the form_input, the documents, and the_history frame.

Since it is an Action, it must return a string for the forward mapping. The diagram shows the activities of theisaPerform() method of the UpdateDocumentViewAction.


August 2008 259

Figure 85: Activities of the isaPerform() method of the UpdateDocumentViewAction

The forward strings of the UpdateDocumentViewAction are mapped to special JSPs (Refresher JSPs) inthe file config.xml (see <action path=‘/b2b/updatedocumentview’ ...>). The file name of aRefresher JSP always has the prefix refresher_. A Refresher JSP loads with JavaScript functions thedocuments, _history, and form_input frame. The necessary Actions and JSPs are coded in therefresher JSP. Because of this, each document type needs its own refresher JSP.

ExampleThis example shows the creation of a new order. (ISA B2B).


August 2008 260

Figure 86: Creation of a new order. (ISA B2B)

The user enters the welcome page and selects Create a new basket. The CreateBasketAction is called.It performs certain preparation actions, for example, creates a new Basket object, error handling, andcreates a new ManagedDocument for the basket.


August 2008 261

UpdateDocumentViewAction is called. It asks the DocumentHandler what should be displayed andgets the ManagedDocument for the basket. It reads from the ManagedDocument thatrefresh_basket.jsp should be loaded.

The refresh_basket.jsp calls WorkAreaNavAction to update the documents frame (tab strips),and UpdateHistoryAction to update the _history frame. This should be performed in every refresherJSP. Finally, it loads the frameset_order.jsp into the form_input frame. This is document-specific.

The frameset_order.jsp calls the ShowBasketAction for the positions frame. This framedisplays header information and all positions of the basket. The ShowBasketAction reads all necessaryinformation from the Basket object and puts it in the request context. The order.jsp will display it. Theframeset_order.jsp also loads the details and the closer_details frame.

Integrating own documentsThere are two phases which must be considered when integrating new documents; prepare and display. Theprepare phase is passed if a new document is created or opened. The display phase is passed if thedocument is displayed. For a specific document, normally the prepare phase is passed only once, while thedisplay phase is passed more than once, for example if the user selects the browser refresh-button.

Figure 87: Display a new Document type with the UpdateDocumentView Module


August 2008 262

When integrating a new document, the following steps are necessary:

1. Write an action for the prepare phase. In this case, PrepareNewDocAction.

2. Write the refresher JSP. In this case, refresh_newdoc.jsp.

3. Write an Action for the display phase. In this case, DisplayNewDocAction.

4. Write a JSP which displays the new document. In this case, newdoc.jsp.

Only PrepareNewDocAction and refresh_newdoc.jsp will be described below,because theother actions are not relevant for the UpdateDocumentView module.

PrepareNewDocActionThe action for the prepare phase (PrepareNewDocAction):

Must create a new, or use an available business object, for example, by asking the BOM for it. Thisobject must implement the interface DocumentState.

Must create a new ManagedDocument object.

Must hand over this object to the DocumentHandler.

Creating a ManagedDocumentA ManagedDocument is created by calling its constructor with the following parameters:

DocumentState docReference to the corresponding business object.

String docTypeType of the document, for example, order, quotation, contract. The document type is displayed onthe tab strip for the document and in the history list. Since this string is language-dependent,docType is part of the key for the translate tag (see its usage in history.jsp, onedocnav.jsp, andtwodocnav.jsp). You have to add an entry in your project specific XLF file (see chapter “Changinglanguage dependand resource keys” for more details).

String docNumberdocNumber is a unique string, automatically assigned by the backend for every document. It isdisplayed on the tab strip for the document and in the history list. If docNumber is equal to ‘new’,then the value of b2b.docnav.new from your project specific XLF file (see chapter “Changinglanguage dependand resource keys” for more details) is displayed instead. docNumber may be null.

String refNumber, refNamerefNumber and refName are the number and name which can be assigned by the customer for thedocument. They are not displayed, but are put in the request context for history.jsp, onedocnav.jsp,and twodocnav.jsp. With some small modifications on the JSP they can be displayed. refNumberand refName may be null.

String docDatedocDate is a date, often the date when the document is created. It is displayed on the tab strip forthe document and in the history list. It is not translated and it may be null.

String forwardThis string is used by UpdateDocumentViewAction for the forward mapping. In the fileconfig.xml a path must be assigned for this string. The corresponding tag is <actionpath=‘/b2b/updatedocumentview’ ...>.If forward is null then the DocumentHandler will directly hand over the ManagedDocument to thehistory list. It is not managed by the DocumentHandler and so it will not be displayed. This meansyou have a way of adding entries to the history without displaying it.


August 2008 263

String href, hrefParameterThese strings are used by history.jsp. Every entry in the history is a link to a document. Withhref and hrefParameter the anchor of the link is built, href+’?’+hrefParameter. The result mustbe the action with the parameters for displaying the wanted document.If href is null, the document is not added to the history. So there is a way for displaying documentswithout adding themto the history. If hrefParameter is null, then no '?' is generated behind href.

Example

The business object is orderStatusDetail.(See JavaDoc for DocumentHandler, DocumentState and ManagedDocument.)

Get the DocumentHandler object from the session context.

The state of the document is set. It must be DocumentState.VIEW_DOCUMENT orDocumentState.TARGET_DOCUMENT. If the state is not set to one of these, then the document cannot beadded to the DocumentHandler.

The ManagedDocument is created.

The ManagedDocument is handed over to the DocumentHandler.

The DocumentHandler is told, that the document orderStatusDetail (the corresponding businessobject to the new ManagedDocument) should be on top of th other document. But this does not remove thecatalog if it is displayed. To remove the catalog, youmust add the additional line:

documentHandler.setCatalogOnTop(false);

documentHandler.setOnTop(orderStatusDetail);

documentHandler.add(mDoc);

ManagedDocument mDoc = new ManagedDocument(orderStatusDetail,

headerSalesDoc.getDocumentType(),

headerSalesDoc.getSalesDocNumber(),

headerSalesDoc.getPurchaseOrderExt(),

headerSalesDoc.getDescription(),

headerSalesDoc.getChangedAt(),

‘order_status’,

href_action,

href_parameter);

orderStatusDetail.setState(DocumentState.VIEW_DOCUMENT);

DocumentHandler documentHandler =

(DocumentHandler)userSessionData.getAttribute(SessionConst.DOCUMENT_HANDLER);

String href_action = ‘b2b/documentstatusdetailprepare.do’;

String href_parameter = (‘techkey=‘.concat(documentKey.getIdAsString())).concat(‘&’);


August 2008 264

PrepareNewDocActionThe refresh JSP loads the documents frame, which displays the tab strips of the documents, the_history frame, which displays the history list, and the form_input frame, which displays thedocument. The JSP should contain the following lines:

In the first script block, the JavaScript frames.js is loaded. It provides, amongst others, the functions:

documents(), which returns the address of the documents frame.

getHistoryFrame(), which returns the address of the _history frame.

form_input(), which returns the address of the form_input frame.

In the second script block, the frames are loaded. In the bold faced line, the form_input frame is loaded. Itloads the action, which is mapped to the path /b2b/displaynewdoc in the file config.xml. In thisexample it should be the action DisplayNewDocAction. If your document consists of a frameset withseveral JSPs, the frameset must be loaded. We recommend you copy an existing refresh JSP, forexample, refresh_basket.jsp, and that you change this line only.The other frames are only loaded if the user has not pushed the browser refresh button (in this case the flowis different). They load the WorkareaNavAction and the UpdateHistoryAction, which are configuredin config.xml.

<head>

<script src=‘<%=WebUtil.getMimeURL(pageContext, ‘b2b/jscript/frames.js’) %>‘

type=‘text/javascript’>

</script>

<script type=‘text/javascript’>

<% if (!refresh) { %>

documents().location.href = '<isa:webappsURL name=‘/b2b/updateworkareanav.do’/>';

getHistoryFrame().location.href='<isa:webappsURL name=‘/b2b/updatehistory.do’/>';

<% } %>

form_input().location.href = '<isa:webappsURL name=‘/b2b/displaynewdoc.do’/>';

</script>

</head>


August 2008 265

Structure of the Internet Sales applicationBefore an Internet Sales application can be extended it is necessary to know how it is structured. This unitgives an overview of the structure of the application. After reading this unit you should be able to identify thelocation of the major components of the Internet Sales application.

Enterprise Application Archive (ear file)The Internet Sales application is delivered as an Enterprise Application Archive (EAR). An EAR is a JAR(zip) file containing all components of an enterprise application. The most important part of the EAR file is theInternet Sales web archive (WAR) file.

Web Archive (war file)The web archive file is a JAR (zip) file containing all parts of the Internet Sales application. The followingtable gives an overview of the content of the archive.

Directory within the war file Description

auctionb2bcatalogecallipcMeta-infmimes

etc.

User interface components (for example, JSPs, Mimes, …).

The folder names are Internet Sales application specific.

Admin JSPs of Internet Sales administration pages and the XCMAdministrator tool. Every Internet Sales application (e.g. B2B, B2C,etc.) has this folder.

Access to the administration pages must be restricted.See note 646140 for further information .

WEB-INF Contains configuration files not accessible using HTTP.

WEB-INF\cfg SAP Internet Sales application specific configuration files (e.g.logging, catalog).

WEB-INF\cfg\cic Customer Interaction Center (CIC) specific settings for the SAPInternet Sales application.

WEB-INF\classes Internet Sales resource files contain language dependent texts usedwithin the application.

WEB-INF\doc Legal statements regarding the usage of third party products.

Application version information (Version.txt).

WEB-INF\lib SAP Internet Sales application specific libraries (e.g. Struts, core.jar,…).

WEB-INF\tlds Descriptors for custom JSP tags.

Table 60: Overview of the content of the web archive


August 2008 266

Directory within the war file Description

WEB-INF\xcm Configuration files managed by the Extended ConfigurationManagement (XCM).

WEB-INF\xcm\sap These configuration files contain default application configuration andmust not be changed by the customer.

WEB-INF\xcm\customer These configuration files are used to adjust the default application-configuration to customer needs.

WEB-INF\xcm\customer\configuration

This folder contains configuration files used for common configurationsettings. These settings are done using the XCM Administrator.

Files in this folder should never be changed manually, only usingXCM Administrator.

The files in this folder usually do not contain the actualsettings. The files in this folder are copied to a folderplaced outside the SAP J2EE Engine installation directoryduring initial deployment.

WEB-IND\xcm\customer\modification

This folder contains files used to change less common settings. Thesefiles are usually touched when extending functions of the webapplication. SAP delivered default settings are changed manuallyusing XCM extension mechanism.

Table 61: Overview of the content of the web archive

Configuration filesThe following table gives an overview of the most important configuration files and their location within theweb archive.

Folder Description

WEB-INF\web.xml Deployment descriptor of Web application.

Most settings in this file are related to the Servlet Runtime:

Session timeout

Declaration of custom tags

In contrast to previous versions of Internet Sales, thereare only a few application related parameters in this file.Most of the application specific parameters are managedby XCM.

WEB-INF\config.xml Configuration of the Struts Interaction Layer.

This file should be modified if you perform changes in the process flowof the application.

WEB-INF\xcm\customer\modification\bom-config.xml

The settings in this file are related to the Business Object Layer.

This file should be modified if you want to use your own customBusiness Object Manager.

Table 62:Overview of configuration files


August 2008 267

Folder Description

WEB-INF\xcm\customer\modification\eai-config.xml

Central file for configuration of the BLS layer. You usually do notchange this file. You only need to change it if you are using JCofunction execution cache.

See chapter 'JCo Function Cache' on page 87

WEB-INF\xcm\customer\modification\init-config.xml

This file defines a set of handlers called during the initialization ofthe application. You make settings in this file if you want to add yourown initialization handler or to change settings in the availableinitialization handlers.

See chapter 'Initialization Handler' on page 132

WEB-INF\xcm\customer\modification\cache-config.xml

Configuration for application caches. You can change settings ofexisting caches or register your own caches.

See chapter 'All purpose Cache' on page 131

WEB-INF\xcm\customer\modification\modification-config.xml

File used to register function module execution listeners, turning onABAP debugging, enabling JCo function tracing and register customfunction modules

See chapter 'Interception of Calls to Standard Function Modules' onpage 225

See chapter 'ABAP Debugging' on page 166

See chapter 'Tracing Function Modules' on page 293

See chapter 'Replacing Calls to Standard Function Modules (BackendSystem)' on page 227

WEB-INF\cfg\log-config.properties

Starting from ISA SP07 this file replaces the previously used log-config.xml configuration file.

The settings in this file configure the logging and tracing capabilitiesof the ISA application. You make changes in this file if you want tochange the logging/tracing settings.

TODO: See chapter ‘Generic Search Framework’ on page 101.

Table 63:Overview of configuration files


August 2008 268

Source Code

General Package Structure of an E-Commerce applicationThe following table shows the general ideas behind the package structure of E-Commerce.

Package structure Commentcom.sap.isa Root for all classes in the ISA application.

.<NameApplication> Subproject, for example catalog, cic,eauction.

.<NameApplication>.action Struts Actions. .<NameApplication>.actionform Struts actionsforms. .businessobject.user .businessobject.basket

.businessobject.order

Packages for business objects.

.backend.crm .backend.r3

.backend.ipc

Packages for backend-specificimplementation of the business objects.

.core Core ISA functionality (no applicationlogic).

.isacore Core application logic functionality.Table 64: Overview of the package structure of E-Commerce


August 2008 269

Conventions when Enhancing the E-CommerceApplicationThe following chapter gives recommended conventions for enhancing the E-Commerce application.

Separation of SAP-Software / Customer ExtensionsIt is necessary to strictly distinguish between the components delivered by SAP and extensions made by thecustomer.

Changes can only be made by integrating new Java code into the existing application framework. Applicationlogic extensions should be placed in customer-specific Java packages. For example, Java-side businesslogic of Internet Sales is located in the com.sap.isa.businesobject package. If the name of thecustomer is ACME, the customer should place his business objects in thecom.acme.isa.businessobject package.

The following unit gives you information on recommended conventions for customer extensions.

Naming ConventionsAll extensions made by the customer should follow naming conventions that are described in the followingunits.

Java Server PagesThe following table gives you information about some naming conventions recommended when working withJSPs.

Type of Modification Naming convention

All additional elements in JSP (for example: inputfield)

z_<name> or Z_<Name>

Example: z_extendedBasketHeaderInc

Adding a customer written JSP z_<name>.jsp of JSP or Z_<name>.jsp

Table 65: Naming conventions for JSPs

Changes in config.xml (or other Struts configuration files)The following conventions apply when the predefined flow of Actions is interfered.

The following example shows how this is done.

The original flow looks as follows:

Figure 88: Original flow of actions


August 2008 270

The config.xml for this process flow is as follows:

Example:

This process flow is interfered by introducing a customer written CustomAction.

Figure 89: Changed flow of actions

<action path=‘/firstaction’

type=‘com.sap.isa.action.FirstAction’>

<forward name=‘success’ path=‘/secondaction.do’/>

</action>



<action path=‘/Z_secondaction’

type=‘com.sap.isa.action.SecondAction’>

<forward name=‘success’ path=‘/thirdaction.do’/>

</action>



<action path=‘/secondaction’

type=‘com.acme.isa.action.Z_CustomAction’>

<forward name=‘success’ path=‘/Z_secondaction.do’/>

</action>

<action path=‘/firstaction’

type=‘com.sap.isa.action.FirstAction’>

<forward name=‘success’ path=‘/secondaction.do’/>

</action>

<action path=‘/secondaction’

type=‘com.sap.isa.action.SecondAction’>

<forward name=‘success’ path=‘/thirdaction.do’/>

</action>


August 2008 271

The original path /secondaction.do is used to route the flow to Z_CustomAction. WhenZ_CustomAction has finished, the flow continues with SecondAction. Since the original path/secondaction.do is used by Z_CustomAction, the path of SecondAction has to be changed.

The naming convention for the original path is: Z_<name of original path>

If you have a chain of custom Actions (more than one), use the following naming convention:

Z_<number starting with 2>_<name of original path>

Example:/Z_secondaction, /Z_2_thirdaction, /Z_3_fourthaction

The advantages of this naming convention are

Customer changes are easily distinguished.

It works well when original flow is intercepted by multiple custom Actions.

Some Actions are triggered by JSPs (e.g frame-sets) but it is not recommended to change JSPsin order to call custom Actions. For interfering the process it is recommended to limit changes tothe config.xml file only.

Changes in bom-config.xmlWhen you write a Business Object Manager you have to register it in the bom-config.xml file.

When you name your Business Objects Managers please use the following naming convention:

Type of Extension Naming Convention

Name of Business ObjectManager in bom-config.xml

Z_<name>-BOM

example:

Z_CUSTOM-BOM

Accessing name of new BusinessObject Manager from an Action

Place a constant containing the above name in the class of thenew BOM.example:


extends BusinessObjectManagerBase

implements BOManager, BackendAware{


Table 66: Naming conventions for Business Object Managers


August 2008 272

Example

The following example shows how these naming conventions work together:

Entry in bom-config.xml:

Definition of constant:

Accessing Custom BOM from Action:

JavaAll Java related changes to the application have to take place in customer packages.

Please only use the source code for information purposes and for debugging. Modifications inthe delivered E-Commerce source code are not allowed.

...




// gettting custom BOM

Z_CustomBusinessObjectManager myBOM =

(Z_CustomBusinessObjectManager)userSessionData.

getBOM(Z_CustomBusinessObjectManager.CUSTOM_BOM);


extends BusinessObjectManagerBase

implements BOManager, BackendAware {


...

}

<BusinessObjectManager

name=‘Z_CUSTOM-BOM’

className=‘com.acme.isa.businessobject.Z_CustomBusinessObjectManager’/>


August 2008 273

PackagesWhen Java classes are written they should be put in packages using the following naming conventions:

Type of Java Code Name of Package

Actions com.<name of your company>.isa.action

Example: com.acme.isa.action

Business Objects com.<name of yourcompany>.isa.businessobject

Example: com.acme.isa.businessobject

Backend Object Interfaces com.<name of yourcompany>.isa.backend.boi

Example: com.acme.isa.backend.boi

Implementation of Backend Objects com.<name of yourcompany>.isa.backend.<type ofbackend>

current backend-types are: <crm>,<ipc>

Example: com.acme.isa.backend.crm

Table 67: Naming conventions for packages

Java ClassesThe following naming conventions should be used when developing custom classes:

Type of Java Code Naming conventions

Action Z_<Arbitrary name>Action for selfwritten classes

Z_<Original Action name>Actionwhen deriving from existing ECO actions

Business Objects Z_<Name of BO e.g. Basket> forself-written classes

Z_<Original Business Objectname> when deriving from existing ECObusiness objects

The name of a business object should be a noun.

Do not use BO or BusinessObject in the nameof the business object.

Example:com.acme.isa.businessobject.Z_Basket

Table 68: Naming conventions for Java classes


August 2008 274

Type of Java Code Naming conventions

Business Object Manager Z_<Name of BOM e.g.CustomBusinessObjectManager> forself-written classes

Z_<Original BOM name> whenderiving from a existing ECO BusinessObject Manager

Example:com.acme.isa.businessobject.Z_BusinessObjectManager

Backend Object Interfaces Z_<Name of BusinessObject>Backend for self written classes

Z_<Original Backend Objectinterface name> when deriving fromexisting ECO business objects

Example:com.acme.isa.backend.crm.Z_OrderCRM

Implementation of Backend Objects Z_<name of BusinessObject><type of backend inupper case>

Z_<Original Backend Objectimpementation name>

Example:com.acme.isa.backend.crm.Z_CustomBasketCRM, this class provides additional basketfunctionality but does not derive from the CRMspecific ECO basket.

Table 69: Naming conventions for Java classes

Resource FilesIf you modify text keys in XLF files or add your own texts, use the following conventions:

Changes Naming convention

Changed text of an existing key Copy the key and rename it using the followingnaming convention:<name of your company>z_<key name>

Example:

original key:

b2b.header.settings=My Settings

after changing:

acme.b2b.header.z_settings=Mypersonal Settings

Table 70: : Naming conventions for resource files


August 2008 275

Changes Naming convention

Added custom key <name of your company>z_<key name>

The key name should correspond to thecomponent within the application (e.g. b2b, cic).

Example:acme.b2b.order.display.z_extheaderdata_inc

Table 71: : Naming conventions for resource files

Place all additional/changed keys at the end of the resource file. This makes it easier when you upgrade theapplication.

Changes in ConfigurationThe following chapter explains changes to the configuration using Extended Configuration Management(XCM).

Application Configuration and ComponentConfigurationApplication configuration and component configuration can be created and maintained using the XCMAdministrator tool. A detailed description can be found in the XCM Administrator tutorial which is part of themySAP CRM Java Installation Guide (see [1])

Common Configuration ChangesThis section details how you make common configuration changes to the settings in init-config.xml orbackendobject-config.xml. These changes cannot be made using the XCM Administration tool. Youcan, of course, use the same extension mechanism in other configuration files, but changes to these two filesare the most common.

Changes in init-config.xmlThe following example is taken from Internet Sales 5.0 B2C, to change the catalog cache settings.

In the SAP version of WEB-INF\xcm\sap\modification\init-config.xml the following init-handler is responsible for initializing the catalog cache:

<initialization

className=‘com.sap.isa.catalog.cache.CatalogCacheInitHandler’>

<param name=‘expiration’ value=‘24’/>



<param name=‘removal’ value=‘48’/>

</initialization>


August 2008 276

You want to change the value of the removal attribute from 48 to 4711. You make the changes in thecustomer version of init-config.xml located in the folder:

<web application>\WEB-INF\xcm\customer\modification.

Example:

Add the following code after the xi:include XML element:

In this example you are extending the catalog cache init-handler. You only need to provide theparameter you wish to change (removal), all others are inherited (for example, expiration).

Changes in backendobject-config.xmlYou use this file to register backend objects in the Business Logic Service Layer (BLS). In previous releasesthe file eai-config.xml was used for registering Backend Objects.

Changing existing Backend ObjectIf you need to change configuration for existing backend objects, and there is no appropriate switch in theXCM Administrator, you need to carry out the changes manually, using XCM extension mechanism. Allcustomer changes must be done in WEB-INF\xcm\customer\modification\backendobject-config.xml.

The following example illustrates how to change a setting in the PriceCalc Backend Object (example istaken from Internet Sales B2C).

You have to derive your changes from the base backend object, located in

WEB-INF\xcm\sap\modification\backendobject-config.xml:

<config id=‘crmdefault’>

<businessObject type=‘PriceCalc’ name=‘CatPriceCalc’

className=‘com.sap.isa.backend.crm.webcatalog.pricing.PriceCalculatorCRMIPC’


defaultConnectionName=‘ISAStateless’>

<params>

<param name=‘priceTypes’ value=‘totalGrossValue’/>



</params>

</businessObject>

</config>

<initialization isa:extends=‘../initialization

[@className='com.sap.isa.catalog.cache.CatalogCacheInitHandler']’>

<param name=‘removal’ value=‘4711’/>

</initialization>


August 2008 277

To change the value of priceTypes from totalGrossValue to netValueWithoutFreight, carry outthe following steps:

1. Locate the backend object PriceCalc in SAP configuration using the id='crmdefault'.

2. Extend this configuration using isa:extends=‘../config[@id='crmdefault'‘. In doing this youderive the complete base configuration crmdefault.

3. Make a note of the backend object you need to change. Please note, you only have to write down thoseyou are changing (in this case, priceTypes), and not all attributes (for example, name, className).You need the backend object attribute 'type', because this is the key identifying the backend object. Youneed it to tell XCM which backend object you are extending.

The following coding in the customer version of backendobject-config.xml is placed after thexi:include:

4. Check the result of this extension in the XCM cache.

Adding new Backend ObjectIf you have written a backend object you have to register it in backendobject-config.xml. Perform thefollowing step. (Example taken from ISA B2C)

You can always extend the base configuration crmdefault when registering your object. (even if you useECO ERP).The reasons is that this is the base configuration for all other configurations.



<config isa:extends=‘../config[@id='crmdefault'‘>



<businessObject type=‘Z_Custom’ name=‘z_custom’

className=‘com.acme.isa.backend.crm.Z_Custom’

connectionFactoryName=‘JCO’ defaultConnectionName=‘ISAStateless’>

<params>

<param name=‘myParam’ value=‘myValue’/>

</params>

</businessObject>

</config>

<config isa:extends=‘../config[@id='crmdefault'‘>

<businessObject type=‘PriceCalc’>

<params>

<param name=‘priceTypes’ value=‘netValueWithoutFreight’/>

</params>

</businessObject>

</config>


August 2008 278

Extending XCM with Customer SettingsIf you extend the application and would like to make your extensions configurable, you can extend the XCMconfiguration tool with your own settings.

There are two types of information you have to provide when adding new parameters to XCM:

1. The new parameter with a name and default value.

2. Meta data of the new parameter like description, allowed values etc.

What to DoThe first step consists of adding the name (myParam) and the default value (defaultValue) of the newparameter and the name of the component (project) the parameter is assigned to. In addition to that youhave to provide meta data like the descirption (custom parameter) and the type of the parameter (text).

After adding the new parameter you will be able to configure it using the XCM Admin tool as shown in thefollowing figure:

Figure 90: Adding and configuring new parameter (XCM)


August 2008 279

Adding Parameter Name and default Value The XML file used for storing the name/value of parameters is stored in the DB. You have therefor

first to download it from the Database

o Open the XCM tool (e.g. b2b/admin/xcm/init.do)

o Select 'XCM Settings' in the tree

o Click the ' Component configuration data download' button

o Store the file you have downloaded in the file system

In this step you have to add the component name the paramter name and the default value of theparamter.

Make a backup of this file before doing any changes in case you need to restrore the original file

The naming rule for the config id is is always: <component id>config e.g. projectconfig.

In the next step you have to add metdata of the paramter like descrition and typeo Open the file xcm\customer\modification\xcmadmin-config.xml

Add the metadata like shown in the following example:

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

<xcmadmin>

<componentmetadata>

<component id="project" shorttext="Project specific setting" scope="application">

<longtext>Detailed overview on parameters configured here</longtext>

<params>

<param name="myParam" type="text" shorttext="custom parameter"/>

</params>

</component>

</componentmetadata>

<scenariometadata>



</scenariometadata>

</xcmadmin>

<component id="project">

<configs>

<config id="projectconfig">

<params id="default">

<param name="myParam" value="defaultValue"/>

</params>

</config>

</configs>

</component>


August 2008 280

You have to restart the application in order to activate the setting

In the last step you have to upload the config-data.xml file back to the database:

o Start the XCM and select XCM Settings

o Click the 'Edit' button

o Select the path of your modified config-data file in the 'Path to component configuration data'entry field

By uploading the file manually you overwrite the DB content of this file. Make sure that the XMLfile is valid and well formed before uploading it to DB. Uploading invalid files can cause theapplication to not start or work properly.o Press the upload button

After uploading the file you should be able to see/changfe the new parameter in the XCM UI.

Adding Meta data of XCM parametersThis paragraph gives some information on how adding component meta data.

The component XML element has the following attributes:


id The id of the component. Used to identify the component. yes

shorttext One sentence describing what this component is good for. This will beused in a summary table giving the customer an overview on theavailable components.

yes

testclass This class is used to test the component configuration. This can bedone in the XCM Admin by the user during configuration (e.g. testingconnection to SAP system using JCO). The test class has toimplement the interfacecom.sapmarkets.isa.core.test.ComponentTest

No

longtext Provide a detailed description of the component.

What is the component good for?

yes

scope The scope of the component. Either application or session. If thisattribute is omitted the default value is 'session'

It is recommended to only use the 'application'scope in customer projects

no

status value 'obsolete’. This attribute indicates that a component isobsolete and should not be used any longer. An obsolete componentis marked with an icon in the tree. You should update the short/longtext and describe the consequences of the deprecation

See [5] Chapter Changing XCM Parameters for rules when changingconfiguration parameters

no

Table 72: Adding Meta data of XCM parameters


August 2008 281

A component is configured using parameters. Each parameter should have a one sentence long shorttextgiving information what the parameter is good for. It can also have a longtext with detailed information aboutthe parameter.

There are two types of parameter values: text and singleselect. text is used to for any kind of text,singleselect is represented by a dropdown-listbox giving the user a limited number of choices.

The screenshot below shows where the parameter shorttexts are shown. If there is a test class registered,the test can be executed using the 'run test' button. You can see entry fields of type text (e.g. mail.smtp.port)as well as one entry field of type singleselect (securemode)

Figure 91: XCM - parameter shorttexts

Example:Example of text type:

<param type="text" name="myParam" shorttext="myValue" />


August 2008 282

Example:

Example of singleselect type:

The param XML element has the following attributes.


name Name of a parameter. yes

shorttext One sentence describing what this parameter is good for.

This description is shown in the XCM Admin tool to give the useran idea what the parameter is used for as well in a printablesummary of component parameters.

If one sentence is enough to describe the meaning of theparameter then this is sufficient

yes

conversionclass A class used to convert the value. This can be used to convertthe value before it is stored. The class has to implementcom.sapmarkets.isa.core.xcm.admin.conv.ParamConverter

no

longtext If the parameter is of type text you can provide additionalinformation here helping the customer to maintain this parametercorrectly

no

type Either text or singleselect. In case of single select you have todefine the allowed values

yes

Status New in 5.0: Allowed value 'obsolete’. This attribute indicatesthat a parameter is obsolete and should not be used any longer.An obsolete parameter is marked with yellow color int the table.The short text visible in the UI has the following format:OBSOLETE <shorttext>. Please describe in the long text theconsequences of the deprecation

See [5] Chapter Changing XCM Parameters for rules whenchanging configuration parameters

No

Table 73: Attributes of the param XML element

<param name="securemode" type="singleselect"

shorttext="Enables or disables security related features">

<longtext>

When set to true, LWC features releated to security will be disabled. ActiveX controls

and document push are the features which pose threat to security.

By default, securemode is set to true.

</longtext>

<constraint>

<allowedvalue value="true" shorttext="securemode is turned on"/>

<allowedvalue value="false" shorttext="securemode is turned off"/>

</constraint>

</param>


August 2008 283

Definition of a allowedvalue located in the body of the param XML tag.


value The value of the parameter yes

shorttext One sentence describing what this parameter is good for.

This description is shown in the XCM Admin tool to givethe user an idea what the value is used for as well in aprintable summary of component parameters.

If one sentence is enough to describe the meaning of theparameter then this is sufficient

yes

longtext More details about the value. no

Table 74: Definition of a „allowedvalue“

API for reading XCM parameter ValuesThe API for getting an 'application' scope component is located in the class com.sap.isa.core.FrameworkConfigManager.XCM

Firstly get your the component configuration: FrameworkConfigManager.XCM.getApplicationScopeConfig().getComponentConfig("project","projectconfig")

The component configuration is of type com.sap.isa.core.xcm.config.ComponentConfig.Itprovides access methods for XCM parameters:getParamConfig("default").getProperty("myParam");

Configuration of Dynamic fields in E-ServiceDynamic fields are fields that a customer can add to be included in the complaints and returns. They can bedefined on the following one-order structure: CUSTOMER_I, PRICING, SHIPPING and PRODUCT_I. Thesedynamic fields can be defined in customizing: Customer Relationship Management Basic FunctionsAuthorizations Define Authorization Group and Customer Relationship Management Basic Functions

Authorizations Maintain Authorizations at Field Level.

If you have defined in the CRM Backend some dynamic fields and you wish that they appear in this webapplication, then the dynamic-fields-config.xml file must be updated. The file under the root of the application…\WEB-INF\xcm\customer\modification\dynamic-fields-config.xml is the one that must bemodified. (The delivered standard file is placed under …\WEB-INF\xcm\sap\modification\dynamic-fields-config.xml and should not be changed.)


August 2008 284

Here is an example of the dynamic-fields-config.xml file:

Immediately below the statement <xi:include…>, you will have to define a property-group namedComplaintItemDynFieldsPG and define underneath it all the properties that you want to appear in the webapplication.

<maintenance-object xmlns:isa="com.sap.isa.core.config"

xmlns:xi="http://www.w3.org/2001/XInclude" >



<xi:include href="${sap}/modification/dynamic-fields-

config.xml#xpointer(backendobject/configs/config[@id='${backendtype}']/*)"/>

<property-group name="ComplaintItemDynFieldsPG">

<property name="DANG_TO_RETURN" type="selectbox"

description="esrv.crb2b.cl.dyn.dang"

objectType="CUSTOMER_I"

fieldName="DANG_TO_RETURN">

<allowedValue value="A" description="esrv.crb2b.cl.opt.scr" />

<allowedValue value="B" description="esrv.crb2b.cl.opt.mov" />

</property>

<property name="CARRIER_CLAIM" type="checkbox"

description="esrv.crb2b.cl.dyn.car"


fieldName="CARRIER_CLAIM">

</property>

<property name="HS_OF_PRIME_QTY" type="input"

description="esrv.crb2b.cl.dyn.hsq"


fieldName="HS_OF_PRIME_QTY"

size="10">

</property>

<property name="HS_OF_PRIME_UNIT" type="input"

description="esrv.crb2b.cl.dyn.hsu"


fieldName="HS_OF_PRIME_UNIT"

helpValuesSearchName="UnitOfMeasure"

size="10">

</property>

<property name="SCRAP_VALUE" type="input"

description="ScrapValue"

objectType="PRICING"

fieldName="SCRAP_VALUE"

size="12">

</property>

</property-group>

</maintenance-object>


August 2008 285

Allowed attributes for tag <property>:

Attribute Remark

Name Name of the property.

The name must be unique within one screen group.

Type Defines the type of the search screen property:

input (= simple input field)

selectbox (= drop down list box)

checkbox (= simple checkbox)

Description The resource file key containing the field label that will be displayed on theweb application UI. This key must exist incrm~eservice~cr_b2b~resources.properties file.

objectType Database entity where this field can be found, either: CUSTOMER_I,PRICING, or PRODUCT_I.

fieldname the name of the field which must match the field in the backend system

Size The maximum length of this field on the web application UI

helpValuesMethod Identifies a help value method defined in file sap\modification\helpvalues-config.xml. Adding the name of an <helpValuesSearch> will bring up anbinocular beside of an input field.

Table 75: Allowed Attributes for the tag <property>

Allowed attributes for tag <allowedValue> for a property of type selectbox.

Attribute Default Remark

Value - Static value which will be added as select optionto a <html> select box (e.g.

<select id…>

<option value=”value” …)

Description - The resource file key containing the value thatwill be displayed on the web application UI. Thiskey must exist incrm~eservice~cr_b2b~resources.properties file.

Hidden False Hide this value (not included on the <html> page)

Table 76: Allowed Attributes for the tag <allowedValue>


August 2008 286

Generic Search FrameworkMain Components of the Generic search framework for E-Service Extended Complaints and Returns:Component Application layer Specific or

Sharedcomponent?

\appbase\genericsearch.jsp Web server Re-usefromInternetSales

\xcm\sap\modification\generic-searchbackend-config.xml Web server E-Servicespecific

com.sap.isa.ui.uiclass.genericsearch.GenericSearchBaseUI.java Web server Re-usefromInternetSales

com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory.java Web server Re-usefromInternetSales

com.sap.isa.isacore.action.GenericSearchBaseAction.java Web server Re-usefromInternetSales

com.sap.isa.isacore.action.GenericSearchSortAction.java Web server Re-usefromInternetSales

CRM_ISALES_SEARCH Application server(Dev.class)

Re-usefromInternetSales

CRM_ICSS_CR Application server(Dev. class)

E-Servicespecific

CRM_ISA_GEN_DOCUMENT_SEL Application server(func. Mod)


CL_ISA_GEN_DOC_SEARCH_HELP Application server(class)


Table 77: Main Components of the generic search framework

Details of component “generic-searchbackend-config.xml”

Location: xcm \ sap \ modification \ generic-searchbackend-config.xml.

Known standard implementations for CRM E-Service extended Complaints and Returns.


August 2008 287

BAdI Implementations in component “CRM_ICSS_CR”

Filter Value ABAP class RemarkCAMPAIGN CL_IM_CRM_ESRV_CAMPAIGN This implementation is exclusively used to

select marketing campaign elements.COMPL CL_IM_CRM_ESRV_COMPLAINT This implementation is exclusively used to

select complaints.COMPL_I CL_IM_CRM_ESRV_COMPLAINT_I This implementation is exclusively used to

select complaints. It returns items instead ofheader objects.

DELIVERY CL_IM_CRM_ESRV_DELIVERY This implementation is exclusively used toselect deliveries.

DELIVERY_I CL_IM_CRM_ESRV_DELIVERY_I This implementation is exclusively used toselect deliveries. It returns items instead ofheader objects.

PSL CL_IM_CRM_ESRV_PSL This implementation is exclusively used toselect product service letters (PSL).

REJECTED_I CL_IM_CRM_ESRV_REJECTED_I This implementation is exclusively used toselect rejected complaints and returns items.

RETURN CL_IM_CRM_ESRV_RETURN This implementation is exclusively used toselect returns.

RETURN_I CL_IM_CRM_ESRV_RETURN_I This implementation is exclusively used toselect returns. It returns items instead ofheader objects.

Table 78: BAdI Implementations in Component "CRM_ICSS_CR"

BAdI Implementations in component “CRM_ISALES_SEARCH” (Those BAdI implementations are re-usedfrom Internet Sales application).

Filter Value ABAP class RemarkBILLINGDOC CL_IM_CRM_ISA_GDS_BILLDOC This implementation is used to select billing

documents.BILLINGITM CL_IM_CRM_ISA_GDS_BILLDOCI This implementation is used to search for items

within CRM billing documents. It returns itemsinstead of header objects.

ORDER CL_IM_CRM_ISA_GDS_ORDER This implementation is exclusively used toselect order documents.

1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for itemswithin one sales document (1Order documents).It returns items instead of header objects.

Table 79: BAdI Implementations in Component “CRM_ISALES_SEARCH”

E-Service Extended Complaints and Returns specificimplementation of the Generic Search Framework

The section before gave a detailed overview of the different components of the Generic Search Framework.The components are designed to work in a generically way, independent from an application. This sectionnow focuses on the integration of the Generic Search Framework into the CRM E-Service ExtendedComplaints and Returns.


August 2008 288

1. Known search definitions in E-Service Extended Complaints and Returns

Search Screen Definition Scenario RemarksSearchCriteria_B2B_Ref B2B To search for reference documents.

- orders- invoices- deliveries- product service letters (PSL)- marketing campaign elements

SearchCriteria_B2B_Cr B2B To search for claims and returnsdocuments.

SearchCriteria_B2B_Sales_OrderStatus_Items B2B To search for sales document items(used to find items in case largedocument handling is enabled)

SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items(used to find items in case largedocument handling is enabled)

SearchCriteria_Delivery_Items B2B To search for delivery documentitems (used to find items in caselarge document handling is enabled)

SearchCriteria_B2B_Claim_Items B2B To search for claim document items(used to find items in case largedocument handling is enabled)

SearchCriteria_B2B_Return_Items B2B To search for return document items(used to find items in case largedocument handling is enabled)

SearchCriteria_RejectedItems B2B To search for complaints and returnsitems which are in status rejected.

Table 80: Search definitions in E-Service Extended Complaints and Returns

2. First search screen to come up in the B2B scenario on the left side of the application (Shuffler / Navigator).

In the E-Service Extended Complaints and Returns application, the navigator is always set to display thecomplaints and returns search (as opposed to reference documents search).

This is defined in the java class EserviceStartApplicationAction.

3. Dynamically disabling document types which are not allowed by user permissions.

All the search definition in the E-Service Extended Complaints and Returns application relate to a UI classcom.sap.eservice.crb2b.uiclass.GenericSearchCrUI. This class makes sure that the user hassufficient authority to view each document types for either his company or a company in his hierarchy beforedisplaying the search criteria.

If you wish to override these conditions, it is possible to define your own UI class, extending the base oneand specifying it in the <screen-group> of the generic-searchbackend-config.xml.


August 2008 289

Checking configuration during runtimeAfter changing configuration in customer files you need to check your extension mechanism is workingproperly. The XCM processed configuration files only exist in the memory. You must therefore check theXCM processed files using XCM Administrator:

1. Change settings in customer version of configuration files.

2. Restart web application.

3. Start the application with the XCM scenario (application configuration) you are using.

4. Access the XCM Administrator.

5. Press the button “monitoring” in the upper right corner. Select the configuration you are interested infrom the dropdown list box.

6. Open the runtime version of the configuration file you are interested in by clicking on the links.

7. Check if your change was processed correctly.


August 2008 290

Best Practices

Getting Information about the ApplicationThe following units give you hands-on information needed for performing extensions.

Getting Information about JSPs

Some applications (e.g. b2b) consist of many frames. After changing a JSP you can update thecorresponding page in the browser by placing the mouse pointer on a particular page, andselecting Refresh from the context menu.

Displaying Names of JSPs while Running the ApplicationUse this feature if you want to display the name of a JSP on the screen.

You can activate this feature in two places:

In XCM:

Navigate to the component UI and set the parameter showmodulename.core = true.

This activates the feature permanently.

You can specify the following additional request parameter when invoking the application:showmodulename=true

This activates the feature for one session

ExampleBy starting the B2B application with the following URL:

http://<host name>/b2b/b2b/init.do?showmodulename=true

You get the following screen showing the name of the JSP in the upper left corner:


August 2008 291

Figure 92: Displaying name of JSP-Files in E-Commerce Applications

Displaying Text Keys While Running the ApplicationUse this feature if you would like to find out which text displayed in the application corresponds to which keyin the resource file.

Providing an additional request parameter in the URL activates this feature. Possible values are:

Request Parameter Description

translate.show.key.only Value: <any value>The language independent resource key isdisplayed instead of the corresponding text.

translate.show.key.concat Value: <any value>The language independent resource key as wellas text is displayed in the form:<resource key>:<text>

Table 81: Displaying text of keys

http://localhost:50000/b2b/b2b/init.do?translate.show.key.concat=99


August 2008 292

ExampleBy starting the B2B application with the following URL:

http://localhost:50000/b2b/b2b/init.do?translate.show.key.concat=99

You get the following screen:

Table 82: Displaying language dependent keys

Finding out Information about the Process FlowYou need this information if you have to interfere the process flow of the application in order to provide yourcustom functionality. There are several ways of getting information on the interaction within the application.

Analysing the config.xml File (or other Struts configuration files)There is currently no tool support for analyzing the content of the config.xml file. To analyze this file youshould be familiar with the Struts framework.


August 2008 293

Session TracingSession tracing enables you to write all trace entries of a user session to a separate file, in addition to thestandard log files. The log level used for this is always DEBUG, regardless of how the other logging settingsare. Session logging offers the following:

Tracing a client session

Debug log level (highest level of detail) independent of further logging settings. This function allows adetailed tracing in a production system, whereby it is not possible to raise the log level globally

The trace messages are written in the default trace files of the SAP Web AS Java, which are located in thedirectory <DRIVE>:\usr\sap\<SID>\JC<INSTANCE_NUMBER>\j2ee\cluster\<SERVER>\log (e.g.c:\usr\sap\C51\JC10\j2ee\cluster\server0\log). There you’ll find the filesdefaultTrace.<COUNTER>.trc, where counter is a number between 1 and 20.

Configuring session tracingBefore you can make use of the session tracing, you have to configure it. To do this, perform the followingsteps:

Open the XCM UI by opening the following URL in the web browser:http:<host>:<port>/<application>/admin/xcm/init.do, where <HOST> ist the name ofthe host, your SAP Web AS Java is running on, and <PORT> is the http port of your SAP Web ASJava.

Open the application specific component in the XCM admin tree view: "General and ApplicationSettings/Customer/<APPLICATION>/<APPLICATION>config", where <APPLICATION> is thecontext root of your application

Turn on the "appinfo" feature

Turn on the "show.start.jsp" feature

Save your configuration

Restart the application in the deploy service of the visual administrator

There are various ways of enabling the Single Session Trace:

Enabling session tracingTo activate the session tracing in an E-Commerce application, proceed as described below:

The following procedure describes how to generate a session trace:

Remove unused DefaultTrace file in the log directories of your Web AS Java server node directories.

Start the application by opening this url: http:<host>:<port>/<application>

The application start page lists all application configurations you configured in the XCM and providesa "Single Session Trace" link for each of them. The application will start a web session based on theselected XCM application configuration. A second browser window will open where the session idwill be displayed.


August 2008 294

Replay the session to generate the application specific trace file content.

Open the Netweaver Administrator by opening the following URL http://<host>:<port>/nwa

Start the log viewer by:

- Click on the "Monitoring" Link

- Click on the "Logs and Traces" Link

- Select the "Default Trace" View

- Open a Search

- Search for your "Session". The session id was displayed during startup of the session via"Single Session Trace".

- Press "go down"

- Press the "Download content" button.

- Download the csv File

To be able to us the session tracing, you have to configure it as described above.

Tracing Function ModulesYou can enable tracing for any function module executed in the ECO application. This feature tracesimport/export and table parameters. It is useful if you need to know which parameters were used when thefunction module was called. Additionally, you can decide whether you want to trace the function modulebefore it is called, or after it has been executed.

The function module trace is enabled in the file WEB-INF/xcm/customer/modification/modification-config.xml

You should make sure that you do not trace sensitive data. If you have such data it is possible toomit tracing some of the parameters. For information on how to do this, please see thecomments in the file modification-config.xml

Example:For examples see comments in file modification-config.xml


August 2008 295

Additional Request Parameters

General Request ParametersThe following table gives you an overview of HTTP request parameters which can be passed to theapplication, when it is started.


Autoentry Value: Rel3.1 = X, Rel4.0 = yes (X) | no;Comes with 3.1: Until SP03, parameter allowed to automaticallypass shoplist and sold-to party selection without any user action.First entry of the shoplist or sold-to party list had been selected. ForSP04 and higher, an error page will be presented if autoentry isused, but no shop is passed via URL parameter, and a sold-toselection is necessary.

Forward The page the LoginAction should forward to.

hook_url URL for the outside page to return to Internet Sales.

Language Language to be used, for example, de, or en.

oci_version Version of the oci-interface.

opportunity_id Id of the auctions opportunity.

Password The password of the logged on user.

Portal Value: yes|no

Triggers visual modifications necessary for displaying the shop inthe portal. Also disables the display of billing documents.

scenario.xcm Value: The name of an XCM scenario, for example,CRM_Q4C_705.

Shop Shop to be used.

Theme Value: Name of the theme.

Precedes the mimes search path with the theme string.Example:theme.core.isa.sap.com=winter modfies the normalesearch path /b2b_dev/b2b/mimes/images/shopHeader.gifto /b2b_dev/winter/b2b/mimes/images/shopHeader.gif

Userid The ID of the logged on user.

Secure Possible value: on

This parameter is needed if you run the following infrastructure:

browser => HTTPS => Web Server => HTTP => J2EE Engine

Since the protocol between the web server and the SAP J2EEEngine is HTTP, the application is never accessed using HTTPS. Inorder to let the application know that HTTPS is used it should bestarted using the additional request parameter secure=on

Table 83: General Request Parameters

http://localhost:50000/b2b/b2b/init.do?shop=muster&language=en


August 2008 296

ECO VersionThis feature is available in all versions of E-Commerce.

Examplehttp://localhost:50000/b2b/b2b/init.do?shop=muster&language=en

Request parameters for B2CTo directly display the product details of a certain product, you can start the application with some extraparameters in the URL.

There are three parameters that should be in the request to display the details for a certain product. Theparameters are:


areaID This parameter specifies the GUID for the areathat contains the product. This parameter can beobtained for a certain item (WebCatItem object)by calling item.getAreaID().

productID This parameter specifies the product Id that isassociated with every product from the catalog bythe ISA B2C application. It can be obtained bycalling item.getItemID().

Shop This parameter is used to specify the shop thatcontains the desired product.

Table 84: Request parameters for B2C

ECO VersionThis feature is available in all versions of E-Commerce.

ExampleThe application can be started with the following URL:

http://<host name>/b2c/b2c/init.do?shop=<shop name>&areaID=<area Guid>&productID=<product Guid>

After execution the user is directly forwarded to the detail screen of the selected product, within the selectedshop area:


August 2008 297

Figure 93: Calling the application with additional request parameters

Single Session Trace

Passing Data between ActionsWhen you have a chain of Actions you often need to pass data from one Action to another. There are twodifferent strategies, depending on the Action flow.

Action Flow Remains on the ServerIn this scenario all the Actions operate on the same request:

Figure 94: Action flow of one request

Data can be set using:

request.setAttribute(‘Name’, value);

Data is retrieved using (for example, in the JSP):

String data = (String)request.getAttribute(‘Name’);


August 2008 298

Action Flow is Interrupted by a JSPIn this scenario a JSP (for example, frameset) interrupts the server-side Action flow.

In this case you have to interfere the Action flow after the JSP, by adding your own Action. In this Action youhave to retrieve the data from the Business Object layer and set it as a request attribute as described above.

Before

Figure 95: Original action flow

After

Figure 96: Interrupted action flow

Working with Request ParserThis unit describes the Request Parser which can be used if your Actions derive fromcom.sap.isa.isacore.action.IsaCoreBaseAction.

The Servlet concept for managing request parameters is based on strings and causes a lot of work whenconverting the data into other data types. This class is a wrapper around the request object and allows youto retrieve parameters of the right type and test them for valid values:

An additional feature is that you can use arrays in the context of form variables. You may, for example,group related variables together, or use this feature to retrieve values from a multiple select input:

RequestParser parser = new RequestParser(request);

RequestParser.Parameter price = parser.getParameter(‘price’);

RequestParser.Parameter name = parser.getParameter(‘name’);

if (price.isSet()) {

if (price.getValue().isDouble()) {

double d = price.getValue().getDouble();

}

String n = name.getValue().getString();

}


August 2008 299

The data of this form contains two associative arrays ‘personal’ and ‘beer’. You can retrieve the data usingthis wrapper class in the following way:

Writing Thread Safe CodeInternet Sales is used by many concurrent users, at the same time, during runtime. You therefore have to becareful when writing customer extensions. This chapter gives you some hints:

Writing thread safe Actions

Refer to chapter 'Threads in Actions' on page 40

Writing Execution Event Listeners

There is only one instance of an event listener for each XCM configuration. It is therefore used bymany concurrent threads from different sessions. For further information, please see chapter'Interception of Calls to Standard Function Modules' on page 225.

RequestParser parser = new RequestParser(request);

RequestParser.Parameter param = parser.getParameter(‘personal[]’);

if (param.isSet()) {

// gives you the value of personal[email]

String email = param.getValue(‘email’).getString();

String name = param.getValue(‘name’).getString();

}

param = parser.getParameter(‘beer[]’);

for (int i = 0; i < parm.getNumValues(); i++) { %>

param.getValue(i).getInt();

}

<form action=‘array.php’ method=‘post’>

Name: <input type=‘text’ name=‘personal[name]’><br>

Email: <input type=‘text’ name=‘personal[email]’><br>

Beer: <br>

<select multiple name=‘beer[]’>

<option value=‘122’>Warthog

<option value=‘33’>Guinness

<option value=‘7373’>Stuttgarter Schwabenbräu

</select>

<input type=‘submit’>

</form>


August 2008 300

Administration ConsoleThere are some administration pages which help you to administer the following technical aspects of theapplication:

Aplication Cache statistics

Catalog cache statistics

Application System Cache Statistics

Java Connector Pools

Java Connector Poolspool name Name of the connection pool

max pool size The maximum number of connections to the SAPSystem that are required per pool up to that point intime

max cons used The maximum number of connections to the SAPSystem that are required per pool up to that point intime

num current used cons The number of connections that are currentlyavailable in the pool

Table 85: Attributes of Java Connector Pool

The page displays all of the SAP Java connector pools, that are available on the applicationserver, and not just the pools of the Web application in which the administration page is.

Getting Application VersionSince the SAP Web Application Server Java provides a central web page, were the versions of all deployedcomponents are shown, the E-Commerce page has been removed. The version information was moved tohttp://<hostname>:<port>/sap/monitoring/ComponentInfo.

The following software components are contained in the SAP E-Commerce 5.0 solution:

- SAP-CRMAPP (not contained in ECOERP)

- SAP-CRMDIC

- SAP-SHRAPP

LoggingIn SAP E-Commerce 5.0, the E-Commerce logging was replaced with the standard logging of the SAP WebAS. For more information please refer to chapter Logging/Tracing on page 115.


August 2008 301

Updating ApplicationThis table gives you information about after which changes to the application you have to restart the SAPJ2EE Server.

Changes What to do

JSPs Refresh corresponding page in browser.

Configuration files Restart application through SAP J2EEadministration console.

Java files Restart application through SAP J2EEadministration console.

Table 86: Updating the application


August 2008 302

Web Diagrams

Syntax of Web Diagrams


August 2008 303

B2B - Start Page


August 2008 304

B2B - Create Basket


August 2008 305

B2B - Display Order Status




August 2008 306

References[1] “SAP E-Commerce Development and Extension Guide: Examples and Tutorials” on SAP Service

Marketplace: http://service.sap.com/crm-inst SAP CRM 7.0 CRM Core and StandaloneComponents.

[2] SAP CRM 5.0 Java. InstallationGuide on SAP Service Marketplace: http://service.sap.com/crm-instmySAP CRM 2005 CRM Core and follow the link “Installation mySAP CRM 2005 (SAP CRM 5.0)”.Follow the “Java” link that is applicable for the database and operating system, you want to use.

[3] Struts documentation: http://jakarta.apache.org/struts/userGuide/index.html

[4] SAP Java Connector: On the SAP Service Marketplace: http://service.sap.com/connectors JavaConnector

Update HistoryVersion Date Remarks

1.0 August 2008 First Version for SAP CRM Release 7.0


August 2008 307

Table IndexTable 1: List of the variables used in this guide ...........................................................................................15

Table 2: Parameters of the MimeURL .........................................................................................................29

Table 3: Parameters of the WebappsURL ...................................................................................................30

Table 4: Parameters of the translate Tag.....................................................................................................31

Table 5: Parameters of the iterate Tag ........................................................................................................32

Table 6: Parameters of th contentType Tag.................................................................................................32

Table 7: Parameters ot the moduleName Tag .............................................................................................33

Table 8: Parameters of the imageAttribute Tag ...........................................................................................34

Table 9: The structure of the UI element object ...........................................................................................35

Table 10: The structure of the UI element group object................................................................................35

Table 11: Input Validation............................................................................................................................49

Table 12: Input Validation............................................................................................................................50

Table 13: Structure of the UILayer Tag........................................................................................................55

Table 14: Structure of the Form Tag............................................................................................................56

Table 15: Structure of the HTML Attribute Tag ............................................................................................56

Table 16: Structure of the UIArea Tag.........................................................................................................56

Table 17: Structure of the UIAreaContainer Tag..........................................................................................57

Table 18: Structure of the UIComponent Tag ..............................................................................................57

Table 19: Structure of the UIConfiguration Tag............................................................................................58

Table 20: Global UI Commands ..................................................................................................................67

Table 21: Commands while Layout Processing ...........................................................................................67

Table 22: Registration of Context Values.....................................................................................................68

Table 23: Overview Context Values ............................................................................................................69

Table 24: Connection Types to Backend .....................................................................................................78

Table 25: Attributes of BusinessObject elements.........................................................................................89

Table 26: Attributes of BusinessObject elements.........................................................................................90

Table 27: Types of Log Messages.............................................................................................................117

Table 28: Types of Tracing........................................................................................................................117

Table 29: Log Levels.................................................................................................................................121

Table 30: Categories for Logs ...................................................................................................................121

Table 31: Software Components ...............................................................................................................142

Table 32: Overview of possible changes in different layers........................................................................168

Table 33: Overview of simple modifications related to the UI .....................................................................190

Table 34: User exits within the Basket.......................................................................................................193

Table 35: User exits within the Order.........................................................................................................194

Table 36: User exits within the OCI ...........................................................................................................194


August 2008 308

Table 37: User exits within the Extended Complaints ................................................................................195

Table 38: User exits within the Remanufacturer’s Inspection Application ...................................................195

Table 39: Methods of the BOBase class....................................................................................................198

Table 40: User exits for IPC for pricing......................................................................................................205

Table 41: User exits for IPC basket ...........................................................................................................205

Table 42: User exits for IPC basket ...........................................................................................................206

Table 43: User exits for Order and Order Status........................................................................................206

Table 44: User exits for Order and Order Status........................................................................................207

Table 45: User exits for Web Catalog........................................................................................................207

Table 46: User exits for for Pricing or Configuration...................................................................................207

Table 47: User exits for for Pricing or Configuration...................................................................................208

Table 48: ABAP Extension Structure (CRM)..............................................................................................212

Table 49: CRM - Supported Function Module / Business Object - Order....................................................212

Table 50: CRM - Supported Function Module / Business Object - User .....................................................212

Table 51: CRM - Supported Function Module / Business Object - Contract................................................213

Table 52: CRM - Supported Function Module / Business Object - Shop.....................................................213

Table 53: CRM - Supported Function Module / Business Object - Complaint .............................................213

Table 54: CRM - Supported Function Module / Business Object – ComplaintHeader.................................213

Table 55: CRM - Supported Function Module / Business Object – ComplaintItem......................................213

Table 56: ABAP Extension Structure (ERP) ..............................................................................................218

Table 57: ERP - Supported Function Module / Business Objects – Order ..................................................218

Table 58: Communication Structure in SAP ERP.......................................................................................220

Table 59: How to access the Request Context ..........................................................................................223

Table 60: Overview of the content of the web archive................................................................................264

Table 61: Overview of the content of the web archive................................................................................265

Table 62:Overview of configuration files ....................................................................................................265

Table 63:Overview of configuration files ....................................................................................................266

Table 64: Overview of the package structure of E-Commerce ...................................................................267

Table 65: Naming conventions for JSPs....................................................................................................268

Table 66: Naming conventions for Business Object Managers...................................................................270

Table 67: Naming conventions for packages .............................................................................................272

Table 68: Naming conventions for Java classes ........................................................................................272

Table 69: Naming conventions for Java classes ........................................................................................273

Table 70: : Naming conventions for resource files .....................................................................................273

Table 71: : Naming conventions for resource files .....................................................................................274

Table 72: Adding Meta data of XCM parameters .......................................................................................279

Table 73: Attributes of the param XML element.........................................................................................281

Table 74: Definition of a „allowedvalue“.....................................................................................................282

Table 75: Allowed Attributes for the tag <property> ...................................................................................284

Table 76: Allowed Attributes for the tag <allowedValue> ...........................................................................284


August 2008 309

Table 77: Main Components of the generic search framework...................................................................285

Table 78: BAdI Implementations in Component "CRM_ICSS_CR".............................................................286

Table 79: BAdI Implementations in Component “CRM_ISALES_SEARCH” ...............................................286

Table 80: Search definitions in E-Service Extended Complaints and Returns ............................................287

Table 81: Displaying text of keys...............................................................................................................290

Table 82: Displaying language dependent keys.........................................................................................291

Table 83: General Request Parameters ....................................................................................................294

Table 84: Request parameters for B2C .....................................................................................................295

Table 85: Attributes of Java Connector Pool..............................................................................................299

Table 86: Updating the application ............................................................................................................300


August 2008 310

Figure IndexFigure 1: SAP J2EE three-tier architecture..................................................................................................20

Figure 2: Components of the SAP J2EE Application Server.........................................................................21

Figure 3: SAP E-Commerce for mySAP CRM architecture ..........................................................................23

Figure 4: Architecture of SAP E-Commerce for mySAP ERP 2005 ..............................................................24

Figure 5: Layered Architecture ....................................................................................................................25

Figure 6: Internal processes within the interacton and presentation layer.....................................................26

Figure 7: BO Layer and the Business Object Manager ................................................................................27

Figure 8: Business Logic Service Layer (BLS Layer) ...................................................................................28

Figure 9: Component configuration within XCM...........................................................................................36

Figure 10: Actions within ECO Framework ..................................................................................................39

Figure 11: Error Message user_no_login.....................................................................................................46

Figure 12: Possible Attacks.........................................................................................................................51

Figure 13: Layout areas of frameless JSP pages.........................................................................................53

Figure 14: Bookmark Support......................................................................................................................72

Figure 15: XCM admin - defaultShopId........................................................................................................73

Figure 16: Prozess of re invoke of an invalid session...................................................................................74

Figure 17: BO Layer Structure.....................................................................................................................75

Figure 18: Design of BLS ............................................................................................................................77

Figure 19: Lifecycle of Backend Object .......................................................................................................78

Figure 20: Class Diagramm about use of JCo Connection...........................................................................81

Figure 21: Design of Logging / Tracing......................................................................................................115

Figure 22: Extend and Modify CRM Web Apps..........................................................................................143

Figure 23: Merged Web Files ....................................................................................................................144

Figure 24: Project specific application in CUSTCRMPRJ...........................................................................145

Figure 25: Creating a new Track ...............................................................................................................146

Figure 26: Adding Software Component....................................................................................................147

Figure 27: Required Software Components...............................................................................................148

Figure 28: Check-In of the Archives ..........................................................................................................149

Figure 29: Development System ...............................................................................................................150

Figure 30: Overview Developer Workplace................................................................................................157

Figure 31: Developer Workplace for SAP NetWeaver 2004s .....................................................................159

Figure 32: Directory Structure of Web AS Java 7.0....................................................................................160

Figure 33: SAP Management Console ......................................................................................................161

Figure 34: Visual Admin - Setting Up Debug Mode....................................................................................164

Figure 35: J2EE Engine - Enabling Debugging..........................................................................................164

Figure 36: Starting Remote Debugging .....................................................................................................165


August 2008 311

Figure 37: Flow of possible changes .........................................................................................................169

Figure 38: Overview of different categories of extensions ..........................................................................170

Figure 39: Statis extensions to the UI layer ...............................................................................................171

Figure 40: Extensions to the action flow ....................................................................................................172

Figure 41: Extensions to exchange additional data....................................................................................173

Figure 42: Extensions to exchange data with UI layer................................................................................174

Figure 43: Transfer additional input data to action class and business object layer ....................................175

Figure 44: Transfer additional output data from aciton class to JSP...........................................................177

Figure 45: Extensions to exchange data with the backend systems...........................................................179

Figure 46: Retrieve additional data from SAP CRM system to business object layer..................................180

Figure 47: Transfer additional data from business object layer to SAP CRM..............................................181

Figure 48: Call a SAP CRM system from the backend layer ......................................................................182

Figure 49: Retrieve additional data from SAP ERP system to business object layer...................................183

Figure 50: Transfer additional data from business object layer to SAP ERP system...................................185

Figure 51: Call a SAP ERP system from backend layer.............................................................................186

Figure 52: Exchange additional data between business object layer and an IPC system............................187

Figure 53: Exchange additional data with the web catalog.........................................................................188

Figure 54: Exchange additional data with the Java basket.........................................................................189

Figure 55: Action flow with CustomActions ...............................................................................................191

Figure 56: BOBase class ..........................................................................................................................198

Figure 57: Derive own class from existing Business Object .......................................................................199

Figure 58: Create own BOM......................................................................................................................199

Figure 59: Creating own Business Object..................................................................................................200

Figure 60: Creating own BOM...................................................................................................................201

Figure 61: Creating interface for Business Object......................................................................................202

Figure 62: Creating own Business Object Manager ...................................................................................202

Figure 63: Adding additional Function Modules .........................................................................................225

Figure 64: Java event listener for Standard Function Modules...................................................................226

Figure 65: Replacing calls to Standard Function Modules..........................................................................228

Figure 66 The IPC and its UI in the CRM Online Landscape......................................................................237

Figure 67 IPC Architecture more in detail ..................................................................................................238

Figure 68 General Action Flow..................................................................................................................239

Figure 69 Example for layout with UI components from both files (layout-config and ipclayout-config)........240

Figure 70 UI areas of the config UI............................................................................................................240

Figure 71 Example for tiles........................................................................................................................241

Figure 72 Combining low level layout and tiles ..........................................................................................242

Figure 73 JSP Key and Path.....................................................................................................................243

Figure 74 Interaction of UIBeans with the JSP pages and the Busines Object Layer..................................245

Figure 75 XCM settings for customer buttons ............................................................................................247

Figure 76 Customer buttons on screen......................................................................................................248


August 2008 312

Figure 77 Component configuration for customer tab ................................................................................249

Figure 78 Application configuration for customer tab .................................................................................250

Figure 79 Customer tab action mapping....................................................................................................250

Figure 80 Customer tab with characteristic details.....................................................................................251

Figure 81 Creating UIBeans via UIBeanFactory ........................................................................................252

Figure 82 Standard customer exit in actions..............................................................................................253

Figure 83 Handling extension data at client objects ...................................................................................255

Figure 84: Main objects of the UpdateDocumentView module ...................................................................257

Figure 85: Activities of the isaPerform() method of the UpdateDocumentViewAction..................................258

Figure 86: Creation of a new order. (ISA B2B)...........................................................................................259

Figure 87: Display a new Document type with the UpdateDocumentView Module......................................260

Figure 88: Original flow of actions .............................................................................................................268

Figure 89: Changed flow of actions ...........................................................................................................269

Figure 90: Adding and configuring new parameter (XCM)..........................................................................277

Figure 91: XCM - parameter shorttexts......................................................................................................280

Figure 92: Displaying name of JSP-Files in E-Commerce Applications ......................................................290

Figure 93: Calling the application with additional request parameters ........................................................296

Figure 94: Action flow of one request ........................................................................................................296

Figure 95: Original action flow...................................................................................................................297

Figure 96: Interrupted action flow..............................................................................................................297

70_DevAndExtGuide

Documents

owned trademarks of

sap logo

sap products

documentation example

registered trademarks

program names

service names

names of variables