Upload
others
View
6
Download
0
Embed Size (px)
Citation preview
Development and
Extension Guide
SAP E-Commerce
7.3 – Landscape,
Basics and
Concepts.
Document Version 1.0– October, 2012
SAP AG
Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com
© Copyright 2004 SAP AG. All rights reserved.
No part of this publication may be reproduced or transmitted in any form
or for any purpose without the express permission of SAP AG. The
information contained herein may be changed without prior notice.
Some software products marketed by SAP AG and its distributors contain
proprietary software components of other software vendors.
Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and
SQL 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 ServerTM
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 the
Open 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 names
referenced herein are trademarks of Citrix Systems, Inc.
HTML, DHTML, XML, XHTML are trademarks or registered
trademarks of W3C®, World Wide Web Consortium, Massachusetts
Institute 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 Sun
Microsystems, Inc., used under license for technology
invented and implemented by Netscape.
MarketSet and Enterprise Buyer are jointly owned
trademarks of SAP AG and Commerce One.
SAP, SAP Logo, R/2, ERP, mySAP, mySAP.com, xApps,
mySAP Business Suite, and other SAP products and
services mentioned herein as well as their respective logos
are trademarks or registered trademarks of SAP AG in
Germany and in several other countries all over the world.
All other product and service names mentioned are the
trademarks of their respective companies.
Disclaimer
Some components of this product are based on Java™.
Any code change in these components may cause
unpredictable and severe malfunctions and is therefore
expressively prohibited, as is any decompilation of these
components.
Any Java™ Source Code delivered with this product is
only to be used by SAP’s Support Services and may not
be modified or altered in any way.
Documentation in the SAP Service Marketplace
You can find this documentation at the following Internet
address:
service.sap.com/instguides
Typographic Conventions
Type Style Represents
Example Text Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths and options.
Cross-references to other documentation
Example text Emphasized words or phrases in body text, titles of graphics and tables
EXAMPLE TEXT Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example, SELECT and INCLUDE.
Example text Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, source code as well as names of installation, upgrade and database tools.
Example text Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation.
<Example text> Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.
EXAMPLE TEXT Keys on the keyboard, for example, function keys (such as
F2) or the ENTER key.
Icons
Icon Meaning
Caution
Example
Note
Recommendation
Syntax
Development and Extension Guide – SAP E-Commerce 7.3
June 2008 4
Contents
Contents ....................................................................................................... 4
Development and Extension Guide – SAP E-Commerce 7.3: Landscape, Basics and Concepts ................................................................................ 14
General Introduction 14
Where the Current Version of this Document is Located ...................................... 14
Naming Conventions ................................................................................................. 14 Terminology ........................................................................................................................................... 14 Variables ................................................................................................................................................ 15
Structure of this Document ...................................................................................... 16
Available Courses, Literature, Links, Notes ............................................................ 16 Courses ................................................................................................................................................. 16 CR800: CRM E-Commerce .................................................................................................................................. 16
Course Goals ..................................................................................................................................................... 16 Course Content ................................................................................................................................................. 16
CR870: CRM Channel Management .................................................................................................................... 17 Course Goals ..................................................................................................................................................... 17 Course Content ................................................................................................................................................. 17
CR850: Internet Sales ERP Edition ...................................................................................................................... 17 Course Goals ..................................................................................................................................................... 17 Course Content ................................................................................................................................................. 18
CR555: CRM Technology .................................................................................................................................... 18 Course Goals ..................................................................................................................................................... 18 Course Content ................................................................................................................................................. 18
Literature ............................................................................................................................................... 19 Links ...................................................................................................................................................... 19 Java in General ..................................................................................................................................................... 19 Java Tutorials ........................................................................................................................................................ 19 Java Newsgroups .................................................................................................................................................. 19
Introduction to SAP J2EE ......................................................................... 20
Web Container 21
E-Commerce Framework ........................................................................... 22
E-Commerce Architecture Overview 23
Layered Architecture ................................................................................................. 25 Interaction and Presentation Layer ....................................................................................................... 26 Business Object Layer (BO Layer) ........................................................................................................ 26 Business Logic Service Layer (BLS Layer) ........................................................................................... 27
Presentation Layer Details 28
JSPs ............................................................................................................................ 28 Custom ISA Tags .................................................................................................................................. 28 MimeURL ............................................................................................................................................................. 29 WebappsURL ....................................................................................................................................................... 30 translate ................................................................................................................................................................. 31 iterate .................................................................................................................................................................... 32 contentType .......................................................................................................................................................... 32 moduleName ......................................................................................................................................................... 33
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 5
message ................................................................................................................................................................. 33 imageAttribute ...................................................................................................................................................... 33
Dynamic Field Control .............................................................................................. 34 Definition ................................................................................................................................................ 34 The structure of the UI element object .................................................................................................................. 35 The structure of the UI element group object ....................................................................................................... 35 Configuration of fields via XCM admin .................................................................................................. 35 Add field to the xcmadmin-config.xml ................................................................................................................. 36 Add field to the conf-data.xml .............................................................................................................................. 37 Usage .................................................................................................................................................... 37 JSP ........................................................................................................................................................................ 37 Action ................................................................................................................................................................... 38
Interaction Layer Details 38
Overview .................................................................................................................... 38
UI Components .......................................................................................................... 38
Interaction Components ........................................................................................... 39 Actions ................................................................................................................................................... 39 Threads in Actions ................................................................................................................................................ 40 ActionForms .......................................................................................................................................... 41
Interaction Configuration .......................................................................................... 41 ActionServlet ......................................................................................................................................... 42 ActionFormBean .................................................................................................................................... 42 ActionMapping ....................................................................................................................................... 43 ActionForward ....................................................................................................................................... 43
ISA extension of Struts ............................................................................................. 44 ISA Actions ............................................................................................................................................ 44 com.sap.isa.core.InitAction................................................................................................................................... 44 com.sap.isa.core.BaseAction ................................................................................................................................ 45 com.sapmarkets.isa.isacore.action.EComBaseAction........................................................................................... 45 com.sapmarkets.isa.isacore.action.EComExtendedBaseAction............................................................................ 46 com.sap.isa.isacore.action.IsaCoreBaseAction ..................................................................................................... 47 com.sap.isa.core.UserSessionData ...................................................................................................... 47 Changing language dependand resource keys ..................................................................................... 47
Additional Information .............................................................................................. 48
Secure Programming 48
Input Validation .......................................................................................................... 48 Guideline ............................................................................................................................................... 48
HTTP Header Information ......................................................................................... 50 Guideline ............................................................................................................................................... 50 Persistent Cookies................................................................................................................................. 50 Guideline ............................................................................................................................................... 50
Cross Site Scripting .................................................................................................. 51 Guideline ............................................................................................................................................... 51 Error Handling ....................................................................................................................................... 52 Solution .................................................................................................................................................. 52
User Session/Authentication .................................................................................... 52 Guideline ............................................................................................................................................... 52 Logging/Tracing ..................................................................................................................................... 52 Guideline ............................................................................................................................................... 52
Comments in HTML Code ......................................................................................... 52 Guideline ............................................................................................................................................... 53
Support of Web Standards (only B2C) 53
Introduction................................................................................................................ 53
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 6
Frameless JSP pages ................................................................................................ 53 Introduction ............................................................................................................................................ 53 Structure of the layout-config.xml .......................................................................................................... 55 The structure of the UILayout tag ......................................................................................................................... 55 The structure of the Form tag................................................................................................................................ 56 The structure of the HTML attribute tag ............................................................................................................... 56 The structure of the UIArea tag ............................................................................................................................ 56 The structure of the UIAreaContainer tag ............................................................................................................. 57 The structure of the UIComponent tag ................................................................................................................. 57 The structure of the UIConfiguration tag .............................................................................................................. 58 Create your component actions ............................................................................................................ 58 Create your JSP includes ...................................................................................................................... 58 Control the layout .................................................................................................................................. 59 UILayout ............................................................................................................................................................... 59 Layout Processing ................................................................................................................................................. 60 UIArea .................................................................................................................................................................. 60 UIInclude .............................................................................................................................................................. 61 UIJSInclude .......................................................................................................................................................... 61 Dynamic change of HTML title .............................................................................................................. 62 Dynamic changes of the layout ............................................................................................................. 63 Support of navigation issues ................................................................................................................. 64 UIStoreLayout & UIStoreForward ....................................................................................................................... 64 UIStoreAction ....................................................................................................................................................... 65 UIAction ............................................................................................................................................................... 65 UIGetLayout & UIGetForward............................................................................................................................. 66 Summary of the UI Commands ............................................................................................................. 67 Global Commands ................................................................................................................................................ 67 Commands while Layout processing .................................................................................................................... 67
Browser Back Support .............................................................................................. 67 Usage of context values ........................................................................................................................ 68 Registration of context values ............................................................................................................................... 68 Getting and setting context values ........................................................................................................................ 69 Overruling context values in an url ....................................................................................................................... 70 Rules for UI components ...................................................................................................................................... 71 Redirect after form submit ..................................................................................................................... 71 General Guidelines ................................................................................................................................ 72
Bookmark Support .................................................................................................... 72
Business Object Layer Details 74 Design Considerations .......................................................................................................................... 74
Additional Information .............................................................................................. 76
Business Logic Service Layer Details 77
Design Considerations ............................................................................................. 77
Backend Objects ....................................................................................................... 77 Lifecycle of Backend Object .................................................................................................................. 78 Initialization of the Backend Object ..................................................................................................................... 78 Destruction of Backend Objects ........................................................................................................................... 79 Backend Context ................................................................................................................................... 79
BackendObjectManager ............................................................................................ 80
Connection Management .......................................................................................... 80 Design Considerations .......................................................................................................................... 80 Working with JCo Based Connectivity................................................................................................... 80 Connection Types ................................................................................................................................................. 81 Working with JCoConnections ............................................................................................................................. 83
Getting Default Connection Associated with a Backend Object ...................................................................... 83 Getting a Modified Connection ........................................................................................................................ 84 Getting a New Connection from a ConnectionFactory object .......................................................................... 85
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 7
Working with JCO.Functions ................................................................................................................. 85 Creating JCO.Functions .................................................................................................................................... 85
Executing JCo Functions ...................................................................................................................................... 86
Configuration of BLS Layer ...................................................................................... 87 Configuring Connection Management ................................................................................................... 87 JCo Function Cache .............................................................................................................................................. 87 Configuring Backend Objects ................................................................................................................ 89
Further Services 91
Message Framework ................................................................................................. 91 Message classes ................................................................................................................................... 92 Message, MessageList and MessageListHolder Class .......................................................................................... 92 Adding messages from a CRM backend ............................................................................................................... 92 MessageListDisplayer ........................................................................................................................................... 93 Message Tag ......................................................................................................................................... 94 Exception Handling................................................................................................................................ 94 Backend ................................................................................................................................................................ 95 Business Object Layer .......................................................................................................................................... 96 Action Layer ......................................................................................................................................................... 96 Error Pages ........................................................................................................................................... 96 appbase\backenderror.jsp ...................................................................................................................................... 96 appbase\runtimeerror.jsp ....................................................................................................................................... 96 appbase\panicexception.jsp ................................................................................................................................... 96 appbase\relogin\invalidsession.jsp ........................................................................................................................ 97 appbase\message.jsp ............................................................................................................................................. 97 appbase\jspruntimeerror.jsp .................................................................................................................................. 97 appbase\accessibilitymessages.inc.jsp .................................................................................................................. 97 Message handling in accessibility mode ............................................................................................... 97 How to integrate the global message pages in an application .............................................................. 98 Pre Condition check in the EComExtendedBaseAction ........................................................................ 99
Generic Search Framework .................................................................................... 101 Main Components of the Generic search framework .......................................................................... 103 Details of component “generic-searchbackend-config.xml” ................................................................ 103 Details of component “GenericSearchBaseAction” ............................................................................. 110 Details of component “CRM_ISALES_SEARCH” ............................................................................... 110 ESelling specific implementation of the Generic Search Framework ................................................. 113
Logging/Tracing ...................................................................................................... 115 Design Consideration .......................................................................................................................... 115 Difference between Logging/Tracing ................................................................................................... 115 Tracing ................................................................................................................................................................ 115 Logging ............................................................................................................................................................... 116 Summary Types of log messages ....................................................................................................... 117 Tracing ................................................................................................................................................. 117 APIs for Tracing: ISALocation ........................................................................................................................... 117
Initializing Location ........................................................................................................................................ 117 Entering/exiting non trivial method ................................................................................................................ 117 Throwing exception ........................................................................................................................................ 118 DEBUG........................................................................................................................................................... 118 ERROR ........................................................................................................................................................... 118 Coding Examples ............................................................................................................................................ 118
APIs for Tracing: SAP Logging API .................................................................................................................. 119 Initializing Location ........................................................................................................................................ 119 DEBUG........................................................................................................................................................... 119 ERROR ........................................................................................................................................................... 120 Entering/exiting non trivial method ................................................................................................................ 120 Throwing exception ........................................................................................................................................ 120
Logging ................................................................................................................................................ 121 Usage of Categories ............................................................................................................................................ 121 APIs for Logging: ISALocation.......................................................................................................................... 122
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 8
ERROR ........................................................................................................................................................... 122 FATAL ........................................................................................................................................................... 122 INFO ............................................................................................................................................................... 122 WARNING ..................................................................................................................................................... 122 Detailed Message Descriptions ....................................................................................................................... 123 Coding Examples ............................................................................................................................................ 123
APIs for Logging: SAP Logging API ................................................................................................................. 124 INFO ............................................................................................................................................................... 124 WARNING ..................................................................................................................................................... 124 ERROR ........................................................................................................................................................... 124 FATAL ........................................................................................................................................................... 124
How to Log/Trace: Usage patterns ...................................................................................................... 125
All purpose Cache ................................................................................................... 131 Working with the Cache ...................................................................................................................... 131
Initialization Handler ............................................................................................... 132
Extended Configuration Management (XCM) 134
Separation of Customer and SAP Configuration Files ......................................... 134
Separation of Configuration Data and Modification Data .................................... 135
XCM Extension Mechanism .................................................................................... 136
Web Application Configuration and Components ................................................ 137
SAP Java Remote Function Call (JRFC) ................................................ 138
Technology 138
Development Environment ..................................................................... 139
Development Tools and Concepts 140
External documentation .......................................................................................... 140
Additional information ............................................................................................ 140 Netweaver Developer Studio ............................................................................................................... 140 NWDS, SLD, and CMS track definition ............................................................................................... 141 Software component for own development ......................................................................................... 141
Overview of process ............................................................................................... 141 Software Component Architecture of the CRM or Extended Ecommerce Java Applications ............. 142 Modifications and Extensions of the Web User Interface .................................................................... 143 Extensions of the Java Code ............................................................................................................... 144 Merged Web Applications ................................................................................................................... 145 Handling of duplicate files .................................................................................................................................. 145 Restrictions ......................................................................................................................................................... 145
Initial Configuration of the NWDI 146
Pre-requisites........................................................................................................... 146
Creating a project specific Web Application with own context root 146
Basic concept .......................................................................................................... 147
Step by step process .............................................................................................. 147 Check SLD content and create a new Software Component .............................................................. 147 Create a new Track using the Landscape Configurator ...................................................................... 147 Add Software Components to track ..................................................................................................... 148 Configure Runtime Systems in the track ............................................................................................. 149 Import Software Components into this track ....................................................................................... 149 Download Archives ............................................................................................................................................ 149 Check-In archives ............................................................................................................................................... 150 Import the checked in archives into the Development system ............................................................................ 150
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 9
Import the checked in archives into the Consolidation system ........................................................................... 150 Create your own Enterprise Applications ........................................................................................................... 150 Test the CRM Java application on a local Web AS Java Engine ........................................................................ 152
Creation or Extensions of Java Classes ............................................................... 152
Importing Modifications and Extensions from older Releases ........................... 153
Developer Workplace 157
Required tools and versions .................................................................................. 158
Java Development Kit ............................................................................................. 158 Installation of JDK 1.6.0 ...................................................................................................................... 158
Developer Workplace for SAP NetWeaver 7.30..................................................... 160 Installing the Developer Workplace for SAP NetWeaver 7.30 ............................................................ 160 Directory Structure of the Web AS Java 7.30 ..................................................................................... 161 TCP-Ports ............................................................................................................................................ 162 Starting and Stopping the WebAS Java .............................................................................................. 163 Configuration of SAP WebAS Java 7.30 ............................................................................................. 163 Uninstalling the Developer Workplace for SAP NetWeaver 7.30 ........................................................ 163
Configuring and Working with Developer Studio ................................................. 164 Configuration of the web application ................................................................................................... 164
Remote Debugging 165
Setting up remote debugging for SAP WEB AS Java 7.3 .................................... 165 Enabling/Disabling Debug Mode Permanently .................................................................................... 165 Enabling/Disabling Debug Mode Temporarily ..................................................................................... 166 Starting Remote Debugging ................................................................................................................ 168
ABAP Debugging 169
Prerequesites ........................................................................................................... 169
Activating ABAP Debugging .................................................................................. 170
Java Debugging 170
Introduction to Extension Concepts ...................................................... 171
Extensions in the ISA Framework 171
Finding the Appropriate Extension Concept......................................................... 173 How to use these diagrams ................................................................................................................. 173 Overview .............................................................................................................................................. 173 Extensions to the UI Layer .................................................................................................................. 174 Extensions to the Action Flow ............................................................................................................. 175 Extensions to Exchange Additional Data ............................................................................................ 176 Extensions to Exchange Data with the UI-Layer ................................................................................................ 177 Extensions to Exchange Data with Backend-Systems ........................................................................................ 182
Extensions to the UI layer ....................................................................................... 192 Accessing the Session Context ........................................................................................................... 192 Accessing the Request Context .......................................................................................................... 192
Extensions in the Action Flow................................................................................ 192 Create a Customer Action ................................................................................................................... 193 Standard Actions providing User Exits ............................................................................................................... 195 Accessing the Session Context ........................................................................................................................... 197 Accessing Business Objects from Actions .......................................................................................................... 198 Accessing the Request Context .......................................................................................................... 199 Modifications in the Struts Configuration ............................................................................................. 199 Version ................................................................................................................................................................ 199 Example .............................................................................................................................................................. 199
Business Object Layer ............................................................................................ 199 Storing Additional Data - Extension Mechanism ................................................................................. 199
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 10
Version ................................................................................................................................................................ 200 Example .............................................................................................................................................................. 201 Extending existing Business Objects .................................................................................................. 201 Version ................................................................................................................................................................ 202 Create a Customer Business Object ................................................................................................... 202 Version ................................................................................................................................................................ 203 Example .............................................................................................................................................................. 203 Create a Customer Business Object Manager .................................................................................... 203 Version ................................................................................................................................................................ 205 Example .............................................................................................................................................................. 206
Business Logic Service Layer ................................................................................ 206 Create a Customer Backend Object .................................................................................................... 206 Standard Backend Objects providing User Exits ................................................................................................ 206 Creating new Customer Backend Objects .......................................................................................................... 210
Create an Interface of Backend Object ........................................................................................................... 210 Design Considerations when Creating Backend Object Interfaces ................................................................. 210 Create an Implementation of Backend Object ................................................................................................ 211 Register Backend Object in backendobject-config.xml .................................................................................. 211 Accessing Backend Objects from Business Objects ....................................................................................... 211
Version ................................................................................................................................................................ 212 Example .............................................................................................................................................................. 213 BADIs/SAP CRM Extensions .............................................................................................................. 213 Version ................................................................................................................................................................ 214 ABAP Extension Structure ................................................................................................................................. 214 Supported Function Modules and Business Objects ........................................................................................... 214
Order ............................................................................................................................................................... 214 User ................................................................................................................................................................. 214 Contract........................................................................................................................................................... 215 Shop ................................................................................................................................................................ 215 Complaint (E-Service) .................................................................................................................................... 215 ComplaintHeader (E-Service) ......................................................................................................................... 215 ComplaintItem (E-Service) ............................................................................................................................. 215
Reading data from the Backend .......................................................................................................................... 216 Writing data to the backend ................................................................................................................................ 217 Example .............................................................................................................................................................. 217 Enhancements for the Dynamic UI of ECO B2B ............................................................................................... 218 BAPIs/SAP ERP-Extensions ............................................................................................................... 219 Version ................................................................................................................................................................ 219 ABAP Extension Structure (BAPIPAREX) ....................................................................................................... 219 Supported Function Modules and Business Objects. .......................................................................................... 220
Order ............................................................................................................................................................... 220 Modification of Communication Structures in SAP ERP ................................................................................... 222 Configuration of the Web Application................................................................................................................ 222 Reading Data from the Backend ......................................................................................................................... 223 Writing Data to the Backend............................................................................................................................... 223 Example .............................................................................................................................................................. 224 Java Basket-Extensions ...................................................................................................................... 224 Version ................................................................................................................................................................ 224 Example .............................................................................................................................................................. 224
Request Context ...................................................................................................... 224 Version ................................................................................................................................................................ 225 Example .............................................................................................................................................................. 225
Adding additional Function Modules (Backend System) ..................................... 226 Version ................................................................................................................................................ 227
Interception of Calls to Standard Function Modules ............................................ 227 Thread Safety in Execution Listeners.................................................................................................. 229 Version ................................................................................................................................................ 229 What to Do ........................................................................................................................................... 229
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 11
Example ............................................................................................................................................... 229
Replacing Calls to Standard Function Modules (Backend System) ................... 229 Version ................................................................................................................................................ 230 What to Do ........................................................................................................................................... 230 Example ............................................................................................................................................... 231
Extension of the Web Catalog 231
New Fields in the Web Catalog (SAP CRM Backend) ........................................... 231 Preparation .......................................................................................................................................... 231 Show Additional Attribute in Product List ............................................................................................ 231 Show Additional Attribute in Product Details and in Compare Products ............................................. 232 Show Additional Keys for Extended Search in B2B ............................................................................ 233
New Fields in the Web Catalog (SAP ERP Backend and Memory Catalog) ....... 233 Loading additional Product Attributes from the SAP ERP Backend to the Memory Catalog .............. 233 Version ................................................................................................................................................ 233 Example ............................................................................................................................................... 233
New Fields in the Web Catalog (SAP ERP Backend and TREX) .......................... 234 Loading additional Product Attributes from the SAP ERP Backend to the TREX ............................... 235 Version ................................................................................................................................................ 235 Example ............................................................................................................................................... 235
Customer Specific Views in the Web Catalog (SAP ERP Backend and TREX) .. 237 Version ................................................................................................................................................ 238 Example ............................................................................................................................................... 238
Extensions of the IPC 239
Architecture of the IPC 5.0 UI in CRM Order Scenario ......................................... 239
Action Flow .............................................................................................................. 241
Use of the E-Commerce Layout Framework ......................................................... 241 UI Components .................................................................................................................................... 241 UI Layouts ........................................................................................................................................... 241 UI Areas ............................................................................................................................................... 242 Tiles ..................................................................................................................................................... 243 Low level layouts ................................................................................................................................. 243
Dynamic Includes .................................................................................................... 244 Extension To Transfer Data To JSP .................................................................................................... 246
UIBeans .................................................................................................................... 246
Client Object Layer .................................................................................................. 247
Finding The Appropriate Extension Concept For IPC .......................................... 247
Static extension to UI layer ..................................................................................... 248 Changing Stylesheets ......................................................................................................................... 248 Create New Layout Or Change Standard Layout ............................................................................... 249
Change UI Components .......................................................................................... 249 Example: Customer Buttons and Actions ............................................................................................ 249 Example: Adding Customer Tab To Multifunctional Area ................................................................... 250 Example: Display Characteristic Header And Values In One Line ..................................................... 253
Extensions To The UIBean Layer ........................................................................... 254
Extensions In The Action Layer ............................................................................. 254
Create Customer Backend Object .......................................................................... 256
SCE user functions ................................................................................................. 257
Exchange additional data with ECO ...................................................................... 257
Extensions of the Document Handling 258
Overview .................................................................................................................. 258
Implementation ........................................................................................................ 258
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 12
Example ............................................................................................................................................... 260
Integrating own documents .................................................................................... 262 PrepareNewDocAction ........................................................................................................................ 263 Creating a ManagedDocument ........................................................................................................................... 263 PrepareNewDocAction ....................................................................................................................................... 265
Structure of the Internet Sales application ........................................................... 266 Enterprise Application Archive (ear file) .............................................................................................. 266 Web Archive (war file) ......................................................................................................................... 266 Configuration files ................................................................................................................................ 267
Source Code ............................................................................................................ 269 General Package Structure of an E-Commerce application ............................................................... 269
Conventions when Enhancing the E-Commerce Application 270
Separation of SAP-Software / Customer Extensions ........................................... 270
Naming Conventions ............................................................................................... 270 Java Server Pages .............................................................................................................................. 270 Changes in config.xml (or other Struts configuration files) .................................................................. 270 Changes in bom-config.xml ................................................................................................................. 272 Java ..................................................................................................................................................... 273 Packages ............................................................................................................................................................. 274 Java Classes ........................................................................................................................................................ 274 Resource Files ..................................................................................................................................................... 275
Changes in Configuration 276
Application Configuration and Component Configuration .................................. 276
Common Configuration Changes .......................................................................... 276 Changes in init-config.xml ................................................................................................................... 276 Changes in backendobject-config.xml................................................................................................. 277 Changing existing Backend Object ..................................................................................................................... 277 Adding new Backend Object .............................................................................................................................. 278
Extending XCM with Customer Settings ............................................................... 279 What to Do ........................................................................................................................................... 279 Adding Parameter Name and default Value........................................................................................................ 280 Adding Meta data of XCM parameters ............................................................................................................... 281 API for reading XCM parameter Values ............................................................................................................ 284
Configuration of Dynamic fields in E-Service ....................................................... 284 Generic Search Framework ................................................................................................................ 287 E-Service Extended Complaints and Returns specific implementation of the Generic Search Framework ........................................................................................................................................... 288
Checking configuration during runtime ................................................................ 290
Best Practices .......................................................................................... 291
Getting Information about the Application 291
Getting Information about JSPs ............................................................................. 291 Displaying Names of JSPs while Running the Application ................................................................. 291 Example .............................................................................................................................................................. 291 Displaying Text Keys While Running the Application .......................................................................... 292 Example .............................................................................................................................................................. 293 Finding out Information about the Process Flow ................................................................................. 293 Analysing the config.xml File (or other Struts configuration files) .................................................................... 293
Session Tracing 294
Configuring session tracing ................................................................................... 294
Enabling session tracing ........................................................................................ 294 Tracing Function Modules ................................................................................................................... 295
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 13
Additional Request Parameters 296
General Request Parameters ................................................................................. 296 ECO Version ........................................................................................................................................ 297 Example ............................................................................................................................................... 297
Request parameters for B2C .................................................................................. 297 ECO Version ........................................................................................................................................ 297 Example ............................................................................................................................................... 297
Single Session Trace .............................................................................................. 298
Passing Data between Actions 298
Action Flow Remains on the Server ...................................................................... 298
Action Flow is Interrupted by a JSP ...................................................................... 299
Working with Request Parser 299
Writing Thread Safe Code 300
Administration Console 301 Java Connector Pools ......................................................................................................................... 301
Getting Application Version ................................................................................... 301
Logging .................................................................................................................... 301
Updating Application 302
Web Diagrams .......................................................................................... 303
Syntax of Web Diagrams 303
B2B - Start Page 304
B2B - Create Basket 305
B2B - Display Order Status 306
References ............................................................................................... 307
Update History ......................................................................................... 307
Table Index ............................................................................................... 308
Figure Index ............................................................................................. 311
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 14
Development and Extension Guide – SAP E-Commerce 7.3: Landscape, Basics and Concepts In SAP CRM 7.3, the Development and Extension Guide for SAP E-Commerce has been splitted into two documents.
The document Landscape, Basics and Concepts contains information about how the SAP E-Commerce applications are designed, how to setup the development environment and explains the extension concept of SAP 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 TODO: check if valid.
General Introduction
Where the Current Version of this Document is Located The 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 Operate can be downloaded from there.
Naming Conventions
Terminology
The 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 is connected to a CRM System (ECO CRM).
The term SAP E-Commerce for mySAP ERP is used, when the E-Commerce application is connected 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 15
Variables
The 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. 5.0 or 7.3).
<SP_NUMBER> Number of the service pack (two decimals), you want to upgrade 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.6.0).
<SAP_SID> System ID you entered during installation of the SAP Web Application Server Java with the SAPInst.
<INSTANCE_NUMBER> Instance number of your SAP Web AS, which you entered during installation with the SAPInst.
<INST_DIR> Installation directory for the SAP system. If you have installed the SAP Web AS with the SAPInst, the default installation path is:
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 or b2c).
<APPLICATION_HOME> Directory where the application is deployed.
(e.g. <J2EE_HOME>\cluster\server0\apps\sap.com\crm~b2b servlet_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 on the SAP J2EE Ports, please refer to the chapter Additional Information 'Figure
32: Directory Structure of Web AS Java 7.0
TCP-Ports' on page 161
Table 1: List of the variables used in this guide
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 16
Structure of this Document Before we start the general introduction to the various subjects covered in this document, we would like to explain 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-Commerce 7.3 J2EE solution and wish to set up their own local development environment. After you have read this extension guide, you should be able to make changes to both the local E-Commerce application and perform customer installations.
The first unit provides a short general introduction to SAP J2EE that is needed in order to understand the concepts 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-Commerce application when communicating with an SAP system.
Unit four provides an introduction to handling and installing the tools required for running the E-Commerce application and modifying it.
Best practices useful when extendion the application can be found in the last unit.
Available Courses, Literature, Links, Notes This unit provides an overview of important sources of Java knowledge. In particular, it introduces the standard courses available at SAP University, names important literature sources, and lists several interesting links about Java. It also contains introductory information on switching platforms in the frontend area.
Courses
CR800: CRM E-Commerce
Course Goals
This course will prepare you to
Apply CRM E-Commerce process knowledge
Perform the customizing settings for CRM E-Commerce
Course Content
E-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 Features
o Up/Down, Cross Selling
o Bestsellers
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 17
o Personalized Product Recommandations
E-Service
o Solution Search
o Service Request Management
o Complaints and Returns Management
Additional Features
o Ebay Integration
o ATP Check
o E-Analytics
o Contract Negotiation
o Live Web Collaboration
o Guided Selling
o Batches,
o Product determination,
o Request for Quotation
CR870: CRM Channel Management
Course Goals
This course will prepare you to:
Apply CRM Channel Management process knowledge
Perform the customizing settings for CRM Channel Management
Course Content
Channel 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 Segmentation
o Lead Management
o Opportunity Management
o Content Management
Channel Sales
o Order Management
o Business on behalf
Channel Commerce
o Collaborative Showroom
o Hosted Order Management
o Set up
Partner & Channel Analytics
CR850: Internet Sales ERP Edition
Course Goals
To enable the course participants to set up business processes with the ERP Internet Sales solution and to tailor them according to their needs.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 18
Course Content
Overview, positioning and benefits
How to set up Internet Sales in ERP
o User Concept
o Features of the ERP Product Catalog
o 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-Templates
o Configuration of Web XML- and Shop XML-File
Comparison to SAP Online Store and to mySAP CRM Internet Sales, upgrade path from one solution to the other and outlook.
CR555: CRM Technology
Course Goals
To provide the course participants with an understanding of the system architecture for the most
important SAP CRM Business Scenarios. The main focus is the technical system landscape and the connectivity between the systems and software components. The data flow will be analyzed with respect 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 Content
Introduction to the architecture of SAP CRM
Connectivity between the SAP back-end system and the CRM system:
o CRM Middleware/administration console
o Messaging BDoc
o Initial load / delta load
o 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 Database
o CRM Communication Station
o Mobile Clients
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 19
Literature
Title ISBN number Publisher Summary
Thinking in Java 0-13-659723-8 Book can be downloaded from
http://www.mindview.net/
Links
Java in General
Link Institution Content
http://www.oracle.com/t
echnetwork/java
Oracle Jave home
http://www.jguru.com jGuru.com Source for any kind of Java information
Java Tutorials
Link Institution Content
http://www.oracle.com/t
echnetwork/java
Oracle There are various tutorials for Java 2 Standard Edition as well as J2EE
Java Newsgroups
News-Link Group Content
de.comp.lang.java German Java Newsgroup
General Java topics.
comp.lang.java International Java Newsgroup
General Java topics.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 20
Introduction to SAP J2EE The SAP J2EE architecture consists of a multi-tiered distributed application model. This means that the application logic is divided into different components according to function. These various application components are installed on different machines depending on which tier in the multi-tiered SAP J2EE environment the application component belongs to. SAP J2EE multi-tiered applications are generally considered 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, database systems, 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 21
SAP Web Application Server Java
The SAP Web Application Server Java is part of the SAP Web Application Server platform and consists of the Web container, the EJB container, and services. The Web container is responsible for server-side presentation and for flow control. It contains Java Server Pages and Servlets. The EJB container is responsible for server-side business logic and therefore contains Enterprise Java Beans. The EJB container is not used by our Internet Sales application, because in our case the business logic is included in the SAP CRM (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 Container As mentioned before, the Web container consists of Servlets and JSPs. Servlets are Java programming language classes. A Servlet can be thought of as an applet that runs on the server side, without a user interface. 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 an HTTPServletRequest object and return a response in the form of an HTTPServletResponse. JSP pages are text-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 allowing Web developers to move programming logic into components. This means that Web application developers can concentrate on developing components while content developers build the HTML presentation. Furthermore, Java Server Pages simplify dynamic page development with tags. Java Server Pages technology 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 other functions that would be difficult to develop with programming code. Additionally, you can create a set of custom tags, for instance, that access database functions or some other business logic. Our Internet Sales application uses these custom tags for certain purposes, for example, translation, completion of a URL, iteration, and so on.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 22
E-Commerce Framework E-Commerce 7.3 is based, as the prior CRM releases 5.0 and so on, on the SAP J2EE platform designed to support the requirements of modern, extendable, e-business oriented, enterprise application systems. SAP J2EE provides component-based, scalable application architecture.
This chapter gives you a rough overview of the E-Commerce Framework to help you to understand the main framework concepts. This is a prerequisite for the following paragraphs, in which each layer is discussed in more detail. You need this information to understand the programming model of the ECO application, as well as possible customer-extensions to the standard application.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 23
E-Commerce Architecture Overview The 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
Web
Server
TREX
ERP
OLTP APO BW
Optional Backends
SAP E-Commerce for mySAP CRM
SAP EP
CRM Java
Components BW
XI
Firewall
Firewall
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 mySAP ERP might be different, since the IPC Engine has to be installed in an SAP Web Application Server ABAP 7.0, which has to be installed separately.
The ECO architecture pictures above contain some components that are only required for special processes or are optional. It might be possible that some components are not required in your system landscape.
Web Browser
Java Stack
Web AS Java
ABAP Stack
Web AS ABAP
IPC Engine
ERP System
Web
Server
TREX
APO BW
SAP E-Commerce for mySAP ERP
SAP EP
ERP Java
Components BW
XI
Firewall
Firewall
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 25
With SAP J2EE the presentation of data in E-Commerce is carried out exclusively on the client layer via the Web Browser. The HTML data is dynamically generated via Servlets and Java Server Pages (JSPs). A SAP J2EE Servlet Engine processes the dynamic generation of the HTML data as a server-side process. The Web 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 the respective 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 SAP Java Connector.
As mentioned above, Java technology is limited to the front-end area, that is, to layout design and the interaction logic of the Web shop. Business logic (such as order processing with partner determination, text determination, 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 Architecture The 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 object implementation classes, and so on.
UI / Interaction /
Custom Tags
BO-Layer
Lo
gg
ing
/ XC
M
Internet Sales Framework
CRM / R3 Catalog IPC DB
JSPs
Actions
Business Objects
Backend Objects
Internet Sales Application
JCo ...Socket JDBC
...
BLS-Layer
Backend ObjectsConnection Handling
Figure 5: Layered Architecture
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 26
Interaction and Presentation Layer
This layer is responsible for providing the user interface as well as the navigation within the application. This layer 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 framework providing the Model-View-Controller programming model in a JSP/Servlet environment. It acts as an interface 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
View
JavaServer
Pages
Actions
Business
Object Layer
"Model"
BO
BO
BO
BO
forw
ard
request
dispatch
response
config
update
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 layer when 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 acts
as a central dispatcher, routing all incoming requests to appropriate Actions. The dispatching mechanism
is configured externally. Actions represent a server-side processing unit and are accessed via a common interface. They act as a mediator between the HTTP world and the Business Objects. After calling the
appropriate Business Object(s) the process control returns to the ActionServlet. Depending on the return
value of the called Action and the external configuration, an appropriate JSP (or other Action) is called, in
order to present the result of the calculation to the user. After mixing the static HTML content with the dynamic 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 Presentation layer. Business Objects provide business functionality via well-defined interfaces in a backend-independent manner. Business functions are either completely provided by these objects or are located in an Enterprise Information System (EIS). An EIS is never accessed directly from the BO layer, because Business Objects are not aware of any backend-specific details. If they have to communicate with a backend they do so using a set of generic interfaces provided by corresponding Backend Objects. The implementation of these interfaces is backend-specific but the interfaces themselves are not.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 27
Business Objects are managed by Business Object Managers (BOM). A BOM is used as a central access point for accessing Business Objects. When Actions are accessing a Business Object they have to obtain a reference to it from the BOM.
BO Layer
BasketOrder
Item
Session
Context
Business
ObjectManager
<<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 Backend Object 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 (for
example, BasketCRM). A Business Object obtains a reference to a backend object from the Backend Object
Manager (BEM). The BEM takes care of the lifecycle of backend objects and returns their references to the BO layer.
The ISA Framework can handle communication to various backend systems simultaneously. Depending on the 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 28
Enterprise Application System
Business Logic Service Layer
Business Object Layer
BasketBO
Backend
Object 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 Details The Presentation layer is a relatively thin layer in the ISA framework. It consists basically of the SAP J2EE compliant JSP functionality and some ISA specific custom tags.
Struts tags are not used and are not supposed to be used in customer projects.
JSPs This chapter covers the server-side aspects of the ISA framework. Besides custom tags there are no ISA specific extensions which can be discussed here.
Custom ISA Tags Since the ISA tags are not supposed to generate HTML code (to facilitate UI adjustment), the ISA application will not use this group of tags. Non UI tags, however, are provided. These are described in the following section.
The functions of all the tags described are packaged as static functions in the class
com.sap.isa.core.util.WebUtil. This means that you can use the functions of the tag library from
any Scriplets.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 29
MimeURL
The mimeURL is used to completely resolve the location of a Web resource (such as a script, or image).The application context contains the ‘front’ part of the mime location (host: Port possibly directory structure). If no
explicit 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 the
application context is used. Mimes are searched using the following pattern:
Parameters
Attribute Description Required
name Resource name yes
theme Theme (default: session context / application context) no
language 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 SP06
or 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’ />
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 30
logo.gif is located in <APPLICATION_HOME>/b2b/mimes/images/logo.gif after deploying
application. No mimes server was specified. When calling the application using the following URL
http://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
WebappsURL
A Webapps URL is used to specify a URL for the current application, and, if cookies are not used, encode
the session ID using the additional jsessionid request parameter. Whenever you have to specify an
HREF in your JSP make sure to always use this tag. Only this tag will make sure that session handling still works if cookies are turned off.
Parameters
Attribute Description Required
Name Significant part of the URL yes
Secure 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 the appropriate ports in the XCM Administration UI (“General Application Settings” “Customer” “<APPLICATION NAME>” “<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 request
parameter refer to chapter General Request Parameters on page 296. This parameter is needed if you have the following infrastructure:
web browser => HTTPS => web server => HTTP J2EE engine
no
Anchor Appends an anchor to the URL no
completeUrl 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 values
of the used parameters are coded for HTTP.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 31
Example:
Never use the following (concatenating request parameters):
translate
This tag is used to represent a language-dependent text. The value of the key and attributes are determined with the actual language-dependent text at runtime.
Parameters
Attribute Description Required
key The key in the resource file yes
arg0 First argument no
arg1 Second argument no
arg2 Third argument no
arg3 Fourth argument no
arg4 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 the Application' on page 292.
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¶2&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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 32
iterate
Iteration via a collection. The object that contains the elements to iterate has to implement
com.sap.isa.core.Iterable, or has to be one of the standard Java collection classes (List, Set), a
standard 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 the
com.sap.isa.core.util.table package. Objects of type
com.sap.isa.core.util.table.ResultData can be used together with the iterate tag.
Parameters
Attribute Description Required
Name Name of object that contains data.
Implements com.sap.isa.core.Iterable
yes
Id Scripting variable to create. yes
Type Type of scripting variable. yes
resetCursor Used in scenarios where the iteration is based on ResultSets value: true|false
no
ignoreNull Determines the behavior if an entry in the iteration set is null
(default false; a null-entry will terminate the iteration without
any other notification).
value: true|false
no
Table 5: Parameters of the iterate Tag
Example:
contentType
Specifies the character encoding of the JSP based on the session locale. This tag is needed in order to display double-byte character encoding correctly.
This tag should always be entered on top of each main JSP. This is not necessary in JSPs included by the main JSP.
Parameters
Attribute Description Required
type 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 33
Example:
moduleName
This tag is useful in the development process. It displays the name of the current JSP if the application was
started 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' on page 291
Parameters
Attribute Description Required
Name 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
message
Please refer to chapter ‘Message Framework’ on page 91.
imageAttribute
This tag offers the option of either displaying an image associated with a product in the product catalog which 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 />
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 34
Parameters:
Attribute Description Required
name The name with which the current item may be retrieved from the session
yes
guids A list of comma separated attribute guids. At least one of these guids may be associated with an attribute which store a URL for an image
yes
defaultImg In case no guid can be identified as an attribute holding a value, the image specified as defaultImage is displayed as a mime
yes
language Taking account that the defaultImage is a mime component, it may 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 Control The dynamic field control offers a general functionality to hide, disable or generate fields or more generally page elements dynamically on JSP’s.
The functionality allows also customizing the UI with the help of the XCM admin application. The needed information will be stored static in XML or the XCM configuration or could be changed dynamic in actions or UI 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 UI objects 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. All information 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 direct way.
Additional the UI Field object could hold all information to generated fields or a group of fields on the JSP.
Definition
The UI element and fields will be defined in the uicontrol-config.xml file.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 35
Example
The structure of the UI element object
Field Description
name Name of UI element.
allowed With this flag you control, if a value is allowed. Only allowed field could be 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 object
Field Description
name 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 admin
The framework allows also that the UI elements could be controlled via the XCM admin tool. In the XCM admin we have only restricted possibilities to control the fields. The customer could change between the following 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 36
To allow the control via XCM admin you have to perform two steps
1. 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.xml
To 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 37
Add field to the conf-data.xml
To add a UI element to the conf-data.xml you have to add a parameter with the name ui.fields.<name of the element> in the ui component in the parameter list with the name ui-fields.
Example
Usage
JSP
The 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”) />
...
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 38
Action
In action you could access UI elements with the getUIElement method of the UI controller.
Example
Interaction Layer Details The ISA Interaction Layer consists mainly of the Apache Struts Framework. Some Internet-Sales-specific extensions have been added to this framework. This chapter describes how this layer works. For hands-on guidelines are covered in various other chapters of this guide.
Overview The Struts based ISA Interaction framework helps you to develop web applications based on Servlets and Java Server Pages. It enables the development of Web applications in which presentation is separate from the process flow.
In the MVC (Model View Control) paradigm, Struts represents the controller part through the
ActionServlet. The view is mapped via the JSP files. Whereas the model is mapped by one or more Java
Beans (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 is therefore 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, or visualization, through the provision of an ActionServlet.
Individual components and the interaction between them are described in an XML-based configuration files. Different (independent) parts of the application have on configuration files (new feature of Struts 1.1).
The following paragraphs introduce the main components of the Struts framework and ISA specific extensions to this framework.
UI Components UI components are realized using Java Server Pages and HTML files. Besides using ISA specific custom tags no additional Struts functions are used here. Since this chapter focuses on server-side capabilities there is nothing further to say than what is common knowledge in the area of JSP. Further details about extension of the ISA user interface can be found in chapter 'Introduction to Extension Concepts' on page 171.
UIController uiController = UIController.getController(userSessionData);
UIElement uiElement = uiController.getUIElement("catalog.general", userSessionData);
// disable the field for output:
uiElement.setAllowed(true, UIELEMENT.PR_AUTHORITHY);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 39
Interaction Components In addition to writing the JSP and HTML files for visualization, a web application developer is responsible for supplying the individual Actions as well as declaring the flow sequence between the Actions.
Actions
In 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 this case.
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 the
actual code sequence executed when an Action is called by the ActionServlet. Nevertheless, you will
never derive directly from an Action, but from ISA specific base actions
(com.sap.isa.core.BaseAction, or com.sap.isa.isacore.action.IsaCoreBaseAction),or
by extending a customer exit from an ISA application action (see chapter 'Accessing the Session Context' on page 192)
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 the
ActionServlet, 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 40
Threads in Actions
In the ActionServlet context a maximum of one instance of each Action type exists, but can be
processed simultaneously by multiple threads. This means that you have to pay special attention to thread safety when implementing an Action. You should not use instance variables or static variables in an Action if their 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-threaded
environment, 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, not
instance 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
}
}
public class myAction extends BaseAction
{
private ArrayList mArray;
public ActionForward doPerform( ActionMapping mapping, ActionForm form,
HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException
{
// doing something with mArray
// problem because mArray is an instance variable and shared among several threads
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 41
If there is no way to omit an instance variable you should synchronize the access to it:
ActionForms
The ActionForm is an optional component. It is used to accept user inputs and (optionally) save them. The ActionForm can be used to validate this data.
Each ActionForm specializes the abstract class org.apache.struts.action.ActionForm and defines
its own set of data. In the Struts framework, the request parameters of any existing ActionForm are set
automatically. To achieve this, the ActionForm must provide appropriate get and set methods. The
lifetime of an ActionForm usually corresponds to that of the request or, when declared accordingly, that of
the session. As is the case with the Action, the base class of every ActionForm contains a reference to
the ActionServlet. When validation of the data is requested, the respective ActionForm has to redefine
the 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 the
HttpServletRequest directly, or by using the RequestParser provided by
IsaCoreBaseAction (see chapter 'Working with Request Parser' on page 299).
Interaction Configuration The interaction flow in a Struts based application is configured in an XML based configuration file declaratively. This chapter discusses which framework components are controlled by this file.
public class myAction extends BaseAction
{
private ArrayList mArray;
public ActionForward doPerform( ActionMapping mapping, ActionForm form,
HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException
{
synchronized(mArray)
{
// do something with mArray
} // synchronized(mArray)
} // public ActionForward doPerform
} // class myAction
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 42
ActionServlet
The 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 the
ActionServlet. 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 request
whose URL ends with .do (and runs in the corresponding Web application).
ActionFormBean
The 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 is
addressed 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>
<!-- ActionServlet mapping -->
<servlet-mapping>
<servlet name>action</servlet name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
<!--ActionServlet declaration -->
<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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 43
ActionMapping
Every Action is embedded in an ActionMapping instance. The ActionMappings are described fully in
the configuration file and follow the pattern of the example below:
Each ActionMapping possesses, at least, the required attributes path and type, and thus assigns the
implementing class to a URL. An Action type can be assigned to different URLs, but only one instance of this Action is used in the context of the ActionServlet.
The optional attribute unknown with value true can only be declared once. This attribute emphasizes an
Action that is used when an Action is called that has not been implemented and/or declared. The default
value 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 attribute
tells the Struts environment to perform a validation. You can use the optional attribute input to declare a
form or the call of another Action that will be displayed or run if the validation fails. Finally, the optional
attribute scope declares the scope of the ActionForm. Possible values for the scope are request or
session.
You can use the optional attributes prefix and suffix to control the automatic mapping of the request
parameters to the ActionForm properties.
ActionForward
As 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 perform
routine, 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 local names 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 44
Example: Global declaration
The optional attribute redirect controls whether the server will perform the forwarding (value false) or
whether the client browser has to (value true). In the latter case, the client is given a URL and is transferred
to it via a request. The default setting is server-side forwarding.
ISA extension of Struts This chapter discusses some Internet Sales specific extensions to the struts framework. This will give you a better understanding about the application as well as possible extensions.
ISA Actions
The following Actions are used when developing or extending an ISA application.
com.sap.isa.core.InitAction
The InitAction should always be the first Action when starting an application. This action ensures that the ISA framework 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 and connections).
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. For
example: http://localhost/isa/b2c/init.do performs the initialization and branches to the success
forward defined in the InitAction. The URL http://localhost/isa/b2c/init.do?nextAction=logon performs the
initialization and branches to the logon forward (a corresponding forward must be defined in the configuration file).
<global-forwards>
<forward name=‘logon’ path=‘/logon.jsp’ redirect=‘true’ />
<forward name=‘failure’ path=‘/error.jsp’ />
</global-forwards>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 45
com.sap.isa.core.BaseAction
All application-specific ISA Actions specialize the abstract class BaseAction.
BaseAction itself specializes the Struts Action, and contains an abstract method doPerform from the
signature of the Action::perform(...) routine.
All ISA Actions implement the doPerform routine. BaseAction is responsible for checking whether or not
the current session is valid. If it is not, it is forwarded to session_not_valid. If the session is valid, then
doPerform (..) is called.
The perform routine is specified with final in the BaseAction to prevent it from being inadvertently
overwritten.
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 any
problems 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 are transparent for the A1Action.
If the state is OK, then doPerform() is called and the action-specific statements are executed.
com.sapmarkets.isa.isacore.action.EComBaseAction
This 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’);
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 46
com.sapmarkets.isa.isacore.action.EComExtendedBaseAction
The 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 47
com.sap.isa.isacore.action.IsaCoreBaseAction
This 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 this
Action as base action.
com.sap.isa.core.UserSessionData
All the ISA attributes created in the session scope have to be addressed via an object with type
UserSessionData. An instance of this type is created for each session the first time the InitAction is
run, and this instance is recorded in the session scope. The attributes are recorded under a modified key in the 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 keys
Using the struts message resource concept, it is very easy to change or add resource keys in a way which minimizes integration collision when applying patches or new service packs.
A separate project specific xlf file instead of modifying the standard file avoids integration conflicts completely.
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 a shared web component. Make sure, that you added the file to a source folder (e.g. src/packages or src). 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 attribute
E.g.
Open WEB-INF/config.xml in crm/isa/web/shopadmin and add projectfile to the filename list of the parameter 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());
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 Information For additional information about working with the Interaction Layer refer to chapter 'Introduction to Extension Concepts' on page 171.
Secure Programming This 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 tutorial how to prevent them. It merely shows the most common attacks and guidelines how to and make the life of a hacker harder. Most of the protection techniques mentioned in this chapter are not related to Internet Sales and well coverd in books and on the web.
Input Validation Web 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
Guideline
Validate 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 data shown/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 which are used to show this data. Take a look at this actions: If data is not passed directly to JCo but further processed 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 do further 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 49
Input Field Semantics
Incorrect Data / Boundary Data
Example Possible Expected Result
Number Field Alphabetical Entries qwert Error Message
Number Field Wrong Number Formats 123.123,123 Error Message
Number Field Numbers out of normal application range
4711 if range: 1 to 10
Error Message
Date / Time Alphabetical Entries 1234567 Error Message
Date / Time Wrong Date Formats 01/01/04 if date format 01.01.2004
Error Message
Date / Time Invalid Dates 31-Feb-2003 Error Message
Search Field Criterion
* All data
Search Field Criterion
empty string none or all
Search Field Criterion
Quotes "test" or 'test'
String of limited length
Very long string Message, either error or truncation warning
String of limited length
Empty String valid, possibly
Mandatory Field Blank String Error Message (Based on application)
Field represents an id
same as limited lenght
Field is not a text area, but input field
The character <Enter> (Based on application)
The basic handling of the <Enter> character, specially when encoded, it will tend to not show up at times.
Table 11: Input Validation
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 50
Input Field Semantics
Incorrect Data / Boundary Data
Example Possible Expected Result
General Input Fields Special characters ~!@#$%^&*()=+{}\|[],./?<>"':; <tab><enter>\u
Error Messages (Based on application)
Omit some characters if there are cases where some characters are allowed, for example a “,” or a “.” Or a “#” May be required under certain circumstances of address entry.
XSS attack The following string:
"><script>window.alert('Hello');</script>
No pop up after submiting the request
Table 12: Input Validation
HTTP Header Information Similar to Input Validation (because part of HTTP request). Header information (e.g. mime type, encoding etc.) is read and processed by application
Guideline
Please omit using HTTP header information
Persistent Cookies
Persistent Cookies are stored in an un-encrypted format on the client side. Content of cookies can be accessed or manipulated by unauthorized persons
Guideline
Please omit using persitent cookies. If you plan to use persistent cookies in your extension make sure that no action accepts cookie data without validating it. Cookies are not validated by the back-end. Introduce an additional 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 51
Cross Site Scripting Cross 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 take over 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
Web
Server
Triggers XSS attack
e.g. injects malicious script in guestbook
In case of
stored
attack injected
code is permanently
storedRequests
infected
page
Malicious code
is executed
e.g. session
cookies are
send to
attacker's
web server
1
2
3
4
5
attacker
victim
hijacks session6
Shop
Shop
Figure 12: Possible Attacks
Guideline
The fundamental issue is that XSS can happen when an unauthorized script is executed on the client side out 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 method JspUtil.encodeHtml(String input)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 52
Error Handling
If 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 useful while testing the application. Which information is show in case of error should be controlled in a central place by one code base.
Solution
Use the central error page. See chapter Message Framework on Page 91.
User Session/Authentication Functionality for authentication has to be centralized. This makes quality assurance and testing of this functionality 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 executing code. => If this is overlooked, potentially a user could type in the URL and look at data not intended for him/her.
Guideline
Your action should extend the class EComBaseAction which makes sure that a session is valid and the user is logged on.
Logging/Tracing
Sensitive data is traced in the application coding. An attacker can scan through log/trace files and get this information.
Guideline
Do 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 Code You do make HTML comments in JSP.
Any comments in the generated HTML can turn out to be meaningful to hackers.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 53
Guideline
Use JSP Comments or java comments.
Support of Web Standards (only B2C)
Introduction This chapter gives you a guideline how to write web standard compliant application which includes a frameless page structure, browser back and bookmark support.
Frameless JSP pages
Introduction
The following is the screen layout of the current B2C solution. It is obvious that we have to render one page with four screen areas. We call such an arrangement of screen areas a layout. Each layout area includes one 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.
workarea header
navig
ato
r
min
ibaske
t
work area
<%-- print user name --%>
<%
// print user name
out.println(name);
%>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 54
Example:
Beside the layout information also components will be defined. A component includes either directly a JSP or an action which provide all the data necessary on the JSP and defines then the used page include (see the UIInlude 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 the processing in new action.
The layout will be controlled in the struts configuration file with a set of commands, which can used in the forward 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” />
<UIArea name ="miniBasket" defaultComponent="miniBasket"
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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.xml
The 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 tag
Field Description
Name 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 are performed. The last action which is called must extend the com.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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 56
The structure of the Form tag
The form object includes a global HTML form which is using for the complete layout.
Field Description
name 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 tag
The html attribute object describes a HTML attribute.
Field Description
name Name of the HTML tag.
value Value of the HTML tag.
Table 15: Structure of the HTML Attribute Tag
The structure of the UIArea tag
The layout object includes a list with the existing layout area. And each layout area holds the information over the currently used component
Field Description
name 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 area controls 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 57
The structure of the UIAreaContainer tag
A UIAreaContainer allows grouping a sequence of areas into one „div” container. For this container an own style sheet can be defined, to control the appearance and the position.
Field Description
name 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 tag
Field Description
Name 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 the UIInclude 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 include file.
Could also be set with the UIJsInclude command in the struts configuration file.
jsOnload Name of a Java script function which should be call, while the onload event.
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 58
The structure of the UIConfiguration tag
The UIConfigurationobject includes a global configuration data which is valid for the complete layout.
Field Description
title 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 problems with other layout versions. Bookmarks could only be reactivated if the version 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 the JSP. 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 in frame application.
Create your JSP includes
If you create new JSP you should separate HTML and JavaScript coding in different includes. (Contact our JavaScript 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 the HTML 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 to add 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 59
Use the method getUiTarget of the BaseUI class to get the name of the current displayed layout area or the name 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 layout
The layout and the components will be controlled with commands in the struts configuration file:
UILayout
The 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 which should be used within the area. If an area is not listed the currently used or the default component will be used.
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 within the 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">
<forward name="success"
path="UILayout:[header=header,workarea=catalogentry]"/>
<forward name="error"
path="UILayout:[header=header,workarea=error]"/>
...
</action>
<action path="/base/start.do"
type="com.sapmarkets.isacore.action.StartApplicationAction">
<forward name="success"
path="UILayout:catalogLayout[header=header,workarea=catalogentry]"/>
<forward name="error"
path="UILayout:catalogLayout[header=header,workarea=error]"/>
...
</action>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 Processing
While the layout processing the current layout will be prepared for the display. Therefore the action assigned to the layout and all actions which are assigned to the current valid components will be performed. After this preparation the page assigned to the layout will be displayed.
UIArea
The UIArea command set the current layout area in the struts configuration file. The current layout area will be set automatically within the webappsURL tag. The value is set to the name of the current area or the name 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 61
Example:
The next example shows how the UIArea command looks like in struts configuration file:
Example:
The UIArea also starts the Layout processing.
UIInclude
If a component uses the action instead the page the used page must be delivered within in the struts configuration file using the UIInclude command.
Example:
It is not allowed to combine the UILayout, UIArea and the UIInclude commands.
UIJSInclude
If a component uses the action instead the page the used JavaScript include could be set within in the struts configuration 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="areaId" value="<%=aeraGuid%>"/>
<isa:param name="<%=Constants.CV_UITARGET%>"
value="<%=ui.getUiAreaKey(workarea)%>"
contextValue=”true”/>
</isa.webappsURL>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 62
Example:
After the UIJSInclude command must follow always a UIInclude command.
Dynamic change of HTML title
There is the possibility to change the title of the HTML page depending of the content of a defined layout
area. This can be done with the titleArea attribute of the UILayout object. If this attribute is set, the title is
taken 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.confirmation and 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 attributes titleArg0, 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" />
<UIArea name ="miniBasket" defaultComponent="miniBasket"
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 63
Example:
The attributes describes the name of request attributes. Therefore the attributes must be filled with reasonable values in actions.
Dynamic changes of the layout
Under some circumstances it is reasonable to change the layout dynamically. It these cases one can define a controller action for the layout. This action must extend the com.sap.isa.isacor.action.ControlLayoutAction class. (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" />
<UIArea name ="miniBasket" defaultComponent="miniBasket"
cssIdName="minibasket" />
</UILayout>
</UILayouts>
request.setAttribute(“order_Number”, order.getDocNumber());
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 64
Support of navigation issues
The 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 the display 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 current layout to the stack (e.g. the catalog layout) and then switch to the login layout to perform the layout. After that the developer pops the needed layout from the stack.
UIStoreLayout & UIStoreForward
With the UIStoreLayout command the current layout will be stored for later use. Beyond the UIStoreLayout command 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 of context 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 be displayed:
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 65
The UIStoreLayout and UIStoreForward can’t be the last command. There must always follow the UILayout, UIArea, UIInclude or the UIAction command.
UIStoreAction
With 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 is lost if you set a bookmark. Therefore you have to provide the fallback action “default” if the context is lost.
Following an example, which demonstrates how to handle the login before the marketing profile will be displayed:
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.
UIAction
With the UIAction command you could combine a normal path value with the UI commands. This is very useful 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 66
Example:
UIGetLayout & UIGetForward
The 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>
<!-- UIPopForward calls always the base/getCoreForward action -->
<action path="/base/getCoreForward"
type="com.sapmarkets.isa.isacore.action.EComGetForwardAction">
<forward name="profile" path="/b2c/gotoProfile.do">
</action>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 67
Summary of the UI Commands
Global Commands
Command Position in the Path Start Layout Output Redirect allowed
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 processing
Command 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 Support Typically problems with the browser back button occur because the context on the client differs from the context 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 forward button. But he expects that the catalog hold no information about his state (That means if the user presses the 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 recover the state of the page. Our Browser Back Support provides with the Context Values such a framework, which allows storing context information within the request context. The context values must provide all information which is necessary to recover the page entirely.
The framework allows putting and getting context values to/from the request context. You must not take care of 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 68
Usage of context values
It is possible to define a multi context value. In this case it is possible to store a list of values under the same name.
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 HTTP header.
There is no support of optional context values in the 7.0 release.
Registration of context values
The registration should be done in the static method initContextValues of some central action classes:
Usage Action
Used in all Ecommerce Applications
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 surrounding development component.
All classes which should be used in an application must be defined in int-config.xml. This allows to control which 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);
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 69
Example
Use always the constants instead of the value name directly. The constants should have always the prefix CV_.
Getting and setting context values
The BaseAction will have methods which allow the setting, changing and getting context values (see Java Doc for details).
Name Single Value
Multi Value
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 existing context.
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 the display 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 also automatically transfer to the new context to allow a redirect between processing and display. The method allows changing exiting values in one action (data processing) and use them while the data displaying.
<!-- Initialize Context values used by the application -->
<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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 url
It 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 to true. 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="areaId" value="<%=aeraGuid%>"/>
<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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 71
Rules for UI components
If 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 using MessageDisplayer object.)
Set context values only in component actions.
Redirect after form submit
To avoid strange effects if the user presses the F5 button to refresh the page, it is useful to introduce a redirect after some action. E.g. the user adds a product to the basket. He doesn’t expect to add the product again 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 in the redirected URL.
Example: Here some examples how to introduce redirects:
<action path="/b2c/savePersonalDetails"
type="com.sap.isa.isacore.action.b2c.SavePersonalDetailsAction">
<forward name="success"
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 Guidelines
Don’t offer “back buttons”. If you offer back buttons use browser back to enable the functionality.
Bookmark Support We offer additionally a support for bookmarks. The main problem is that we have to re invoke the application because normally the session is lost when the bookmark is chosen.
Process Action
Bookmark
Request
Store context and re invoke
application
Session is
invalid
Figure 14: Bookmark Support
We introduce the new ReInvoke command. With this command you could re invoke the session and define the action which should be called after the application is re invoked. The command store also the available context and request parameter and provide this information later on to the re invoked action.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 73
Example:
You can call the ReInvoke command also without defining an action. The action where the command is called 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 be started 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 74
Prerequisite: The application must define the re-entry point. This will be the done by calling a action which extends the StartApplicationBaseAction..This action will forward automatically to the action which is defined by the ReInvoke command.
In detail the re invoke of an invalid session looks like:
Init Application
e.g. /b2c/init.do
Store context request
parameter and the action
Start Application Action
e.g. /b2c/start.do
Restore Context and
parameter
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 StartApplicationBaseAction should 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 action redirect to the action which should be re invoked.
Business Object Layer Details
Design Considerations
The Internet Sales Framework is designed to be used with any backend system. This is achieved by dividing the business logic into a backend-independent (Business Objects) and a backend-dependent part (Backend Objects). The Business Objects (business logic objects or BOs) use a generic set of interfaces to communicate with the backend. Therefore, their purpose is to represent the backend-independent part of the business logic.
In order to be able to maintain the application, it is important that the procedure for saving objects that live longer than a request is as robust and transparent as possible.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 75
The standard concept for Servlets and JSPs entails storing this data in the session context. The disadvantage of this procedure is that the data is stored as name value pairs in a flat hierarchy (see also
javax.servlet.http.HttpSession). This can quickly lead to naming conflicts (data in the session is
overwritten by mistake) and confusion.
BO Layer
Item
Session
Context
Business
ObjectManager
<<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, called Business 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 extend
the 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 the
created objects types can be configured using the xml file bom-config.xml. Therefore, you are able to add
new Business Object Managers to the application, or to replace an existing one with a specialized sub-class written by you, without changing any source code.
As already mentioned, the BOM functions as a data capsule and an administration instance for the Business Objects, and is exclusively used from Actions.
The MetaBusinessObjectManager is the only object that exists directly in the session context. A
constant, SessionConst.MBOM_MANAGER, can be used to retrieve the object from the session, or a
convenience method, getMBOM(), of the UserSessionData object can also be used. To make the process
easier, you can call the getBOM() method of the MBOM directly on the UserSessionData object, which
passes the call through to the MBOM.
The BusinessObjectManager functions as a container and factory for BOs. Only the top level BOs are
stored 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 components contained within it.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 76
Additional Information For information on how to work with Business Objects and Business Object Managers, see chapter 'Introduction to Extension Concepts' on page 171.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 77
Business Logic Service Layer Details
Design Considerations The 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 connection handling to the Enterprise Application System.
«<<interface>>»
BasketBackend
+myOperation()
BasketCRM
+myOperation()
BackendBusinessObjectBaseSAP
+getDefaultJCoConnection()()
+initBackendObject()
+destroyBackendObject()
+getContext()
User defined
Interface to Backend
System
Base class providing
Backend Object with
access 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 not disclose any implementation details about the used backend.
There can be multiple implementations for a Backend Object interface, for example, BasketCRM and BasketR3. The BLS framework ensures that the correct Backend Objects are instantiated and that the correct 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 ERP system.
Backend Objects Each Backend Object implements the BackendBusinessObject interface. This interface defines some
generic methods for connection handling and Backend Object lifecycle. It is usually extended by a more
specialized backend specific interface (e.g. BackendBusinessObjectSAP). This interface provides type
safe access to backend-specific connections.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 SAP Java 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 Object
Backend is always instantiated by the framework, never by the application programmer. The Backend Object Manager (BEM) takes care of the lifecycle of the object.
Backend Object
Ready
Backend Object
destroyed
Backend Object
does not exist
initBackendObject() destroyBackendObject()
handle request from
Business Object
Figure 19: Lifecycle of Backend Object
When the Backend Object is created by the Backend Object Manager, the initBackendObject() method
is called. Before the Backend Object is destroyed, the destroyBackendObject() method is called and
gives the Backend Object the opportunity to perform some cleanup.
Initialization of the Backend Object
The initBackendObject method is used to perform one-time initialization. It has the following signature:
Each Backend Object must implement the initBackendObject() method. The
BackendObjectManager 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;
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 79
There are two types of properties passed to the Backend Object when the initBackendObject() method
is 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 has requested a new Backend Object by calling the BackendBusinessObject createBackendBusinessObject(String beBOType, BackendBusinessObjectParams params) method. When a Backend Object is created using the BackendBusinessObject createBackendBusinessObject(String beBOType) method, then the value of the BackendBusinessObjectParams is null The params object can be an arbitrary container passed by the Business Object when the Backend Object is created. The BackendBusinessObjectParams interface is just a tag interface without any methods.
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 277.
Destruction of Backend Objects
Before the Backend Object Manager becomes invalidated (for example: When a client session is removed
from memory), it notifies all of its Backend Objects by calling the destroyBackendObject() method. This
method can be used to clean up resources allocated by the Backend Object.
Backend Context
One 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 business functions. Nevertheless, sometimes there are cases where data should be made available to all backend objects. 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/>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 80
BackendObjectManager All Backend Objects are created and destroyed by a Backend Object Manager. A Backend Object Manager
is accessed using the BackendObjectManager interface. This interface provides methods for creating
Backend 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 of
the ISA framework. If your BOM implements the BackendAware interface, it automatically passes a
reference. Implementing the BackendAware interface indicates that a BOM manages Business Objects
which 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 171.
Connection Management
Design Considerations
Backend Objects communicate with the backend system using backend-specific connectors. The BLS layer makes 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 JCo connections are pooled or not
As you can see, there is not much you have to do for connection handling, apart from configuring the connection 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 you
work on connections of the typ com.sap.isa.core.eai.sp.jco.JCoConnection. Only
this ensures that the BLS layer can take care of connection handling/cleanup correctly.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 type
com.sap.isa.core.eai.sp.jco.BackendBusinessObjectSAP, which is the base class for all
Backend Objects using JCo connectivity.
Connection Types
There 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 is returned to the pool (pools can be monitored in the ISA administation; see chapter ‘Java Connector Pools' on page 301.)
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 duration of 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 169
Assigning connections to Backend Objects: chapter '
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 82
Configuring Backend Objects' on page 89.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 83
Working with JCoConnections
When a remote callable function module (RFC) in the SAP system has to be called, you always perform the following 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 method finally {}
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.xml
file. 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 {
// Step3: Close the connection
con.close();
}
JCoConnection con = getDefaultJCoConnection();
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 84
Configuring Backend Objects' on page 89.
Getting a Modified Connection
If you need a connection which is based on the configuration of the default connection but with different
connection parameters, you can call the getModDefaultJCoConnection(Properties) method. You
use a set of properties to overwrite/extend the connection definition properties used for the default connection.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 85
Example:
Constants which can be used to set JCo properties are located in class com.sap.isa.core.eai.sp.jco.JCoManagedConnectionFactory
The connection you get is not the default connection associated with the Backend Object. It is simply 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 a connection 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.Functions
After getting a JCoConnection you use it to get/execute JCO.Functions. How this is done is described in
this chapter.
Creating JCO.Functions
A JCO.Function is used to execute remote callable function modules in an SAP system. You obtain a
reference 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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 86
The BLS layer serves the JCO.Function from a centralized JCO repository. This ensures the best
performance, since each Backend Object does not have to create its own repository. Additionally, there is only one repository per backend system.
Never create an own JCO.Repository. Let the BLS layer do it for you
Example:
Executing JCo Functions
JCo 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 is as follows:
execute(JCO.Function func) throws BackendException;
Besides the BackendException, a JCO.AbapException runtime (!) exception can be thrown if
the calling function module throws an ABAP exception.
Therefore, please do not forget to catch the BackendException and JCO.AbapException if you call ABAP function modules and you expect that the Function Module throws an ABAP exceptions.
Example:
JCO.Function myFunc;
JCoConnection con = getDefaultJCoConnection();
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;
JCoConnection con = getDefaultJCoConnection();
myFunc = con.getJCoFunction(‘SAP_BASKET’);
JCoConnection.execute(JCO.Function);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 (for example, JCO.Function caching, connection lifecycle).
Configuration of BLS Layer The 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 in WEB-INF/xcm/customer/modification and use the XCM extension mechanism.
For information how to register backend objects in customer projects refer to chapter 'Changes in backendobject-config.xml' on page 277.
Configuring Connection Management
This guide assumes that you do not have to change the connection management configured in
eai-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 JCo
function cache. This one is explained in the next paragraph.
JCo Function Cache
When executing a JCO.Function (for further information about JCo see [4] SAP Java Connector: On the
SAP Service Marketplace: http://service.sap.com/connectors Java Connector) in the BLS layer, the result of the call can be either served from the SAP system or from a cache maintained by the BLS layer. The cache is useful for function modules returning static data and long execution times.
The cache is only implemented for function modues executed with connection type
com.sap.isa.core.eai.sp.jco.JCoConnectionStateless.
An unambiguous key recognizes each JCo function served from the cache. The key is represented by a String 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 88
Key Type B:
The JCo functions that have to be cached by the BLS layer are defined as name/value parameters of the
managedConnectionFactory 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 the customer version of eai-config.xml using the XCM extension mechanism. After the change the file looks as follows:
The cache functions are provided by the com.sap.isa.core.cache.Cache and configured
using the cache-config.xml file located in web-inf\cfg. If you want to change any cache
settings, 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 Connector Statistics => 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>
</managedConnectionFactories>
</config>
</configs>
</backend>
<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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 89
Configuring Backend Objects
SAP standard Backend Objects are registered in the file WEB-
INF/xcm/sap/modification/backendobject-config.xml. You can register new objects or extend
existing objects. If you do this in customer projects you have to register your objects in the customer version
of 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 277.
Backend Objects are registered using the businessObject XML element.
The businessObject element has the following attributes:
Attribute Description Required
type Specifies the type of the Backend Object, (for example, BASKET). The value of the type attribute must be
passed to the BackendObjectManager when a
Backend Object is created.
Yes
name Name of Backend Object. Currently not used by framework.
Yes
className Name of implementation class of Backend Object. Yes
connectionFactoryName Name of the connection factory that provides the default connection used by the Backend Object. Each BackendObject provides methods like getDefaultConnection() returning a connection of the specified type.
The possible values are:
JCO: for RFC based connectivity with the SAP
system using SAP Java Connector
IPC: for socket based connectivity to the IPC
Server
JDBC: for JDBC based connectivity to a
database
Connection parameters for all these types are defined in XCM.
If you omit this parameter, then null is returned when
calling getDefaultConnection().
No
Table 25: Attributes of BusinessObject elements
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 90
Attribute Description Required
defaultConnectionName Name of connection used as the default connection. There must be a connection with this name defined in the connection factory whose name has been specified
by the connectionFactoryName attribute.
The common values are:
JCO connection factory:
o ISAStateful for stateful connections
(type JCoConnectionStateful)
o ISAStateless for stateless
connections (type JCoConnectionStateless)
IPC connection
o IPC_SOCKET
JDBC connection
o JDBC_CON
no
Table 26: Attributes of BusinessObject elements
The body of the businessObject element can contain any number of name/value pairs. These properties
are 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 the
initBackendObject() method is called.
<businessObject
type=‘CatalogSite’
name=‘CatalogSite’
className=‘com.sap.isa.catalog.impl.CatalogSite’
connectionFactoryName=‘JCO’
defaultConnectionName=‘ISAStateless’>
<params>
<param name=‘distributable’ value=‘NO’/>
<param name=‘catalogSiteConfigFile’ value=‘WEB-INF//cfg//catalog-site-configR3.xml’/>
<param name=‘isClassPath’ value=‘false’/>
</params>
</businessObject>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 91
Further Services This chapter introduces generic services used in the SAP E-Commerce 7.0 solution.
Message Framework This document gives you a guideline, how to use the generic message framework in your application. The framework 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 Pages
Business 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 of
objects which already implement this interface:
MessageList,
MessageListDisplayer,
BusinessObjectBase
BusinessObjectException.
There are some steps necessary one-time to integrate the global message pages in your application. See chapter ’How to integrate the global message pages in an application’ (page 98) for details.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 92
Message classes
Message, MessageList and MessageListHolder Class
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 of
object 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 in log 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 backend
For 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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 file
The method splitMessagesToTarget take care of the field.
Example
MessageListDisplayer
The MessageListDisplayer class is a helper class to display a message or a list of messages with the
corresponding 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 the JavaDoc 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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 94
Example
Message Tag
The MessageTag can display messages of a MessageListHolder on JSP with the dependencies from type
and property.
Example
Exception Handling
Exceptions could be thrown in all level of the application. To prevent to mix up the exception in different level the 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 95
Backend
Encapsulate 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 ECommerce
Backend 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();
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 96
Business Object Layer
Use the method BusinessObjectHelper.splitException(ex) to convert a backend exception to an
ECommerce Front end Exception.
Example
Action Layer
Use the EComBaseAction class as a base class for your own actions. Because this action handles all
ECommerce action in appropriate way and forward to the correct error pages (see next chapter). If you want
to check also if the user is logged in use the class EComExtendedBaseAction (see chapter ‘Pre Condition
check in the EComExtendedBaseAction’ on page 99).
Error Pages
The framework provides a set of error and message pages which could easily use in other application. Best
you uses also the EComBaseAction as a base class for your own actions because this action handles the
common exceptions and forward to appropriate pages (see global forwards in chapter ’How to integrate the global message pages in an application’ on page 98).
appbase\backenderror.jsp
This page should be displayed after a CommunicationException is thrown. The exception should be stored in
the request under the name ContextConst.EXCEPTION.
appbase\runtimeerror.jsp
This page should be displayed after a RuntimeException is thrown. The exception should be stored in the
request under the name ContextConst.EXCEPTION.
appbase\panicexception.jsp
This 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;
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 97
appbase\relogin\invalidsession.jsp
This page should be displayed after the session is invalid. The /base/relogin/getcookie.do action (see global
forwards in chapter ’How to integrate the global message pages in an application’ on page 98) should be called before the page is displayed.
appbase\message.jsp
This page can be used to display all kind of messages. The information about the page and the message will
be handled by the MessageListDisplayer class.
appbase\jspruntimeerror.jsp
This page displays runtime error on a JSP’s. Without this page the J2EE engine displays only a white screen with no information that an error occurs. Insert the following line in your JSP to get a message page instead of a white screen.
appbase\accessibilitymessages.inc.jsp
This 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 mode
There 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 a
resource 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 the
page. 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" %>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 of
the 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 application
There 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" %>
<% } %>
<!-- base actions start -->
<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>
<!-- base actions end -->
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 your
application:
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 EComExtendedBaseAction
The 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:
<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>
<!-- Initialize UI -->
<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 Forward Definitions ========================= -->
<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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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;
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 101
Generic Search Framework The Generic Selection Framework provides a mechanism to build a Selection screen out of an XML description. In CRM 7.0 the document selection and the customer selection (B2R scenario) are created using the Generic Search Framework.
B2B Document Selection Screen:
Search screen
Result list
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 102
Architecture of the Generic Search Framework
JSP
Selection Criteria
JSP
Result list
UI Class
Request Context
Maintenance Object
(and helper classes)
XCM
Action & Businessobjects Search / GenericSearchCommand
CRM
Or
JDBC …
UI Class
Class handling the dynamic content
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 103
Following describes the structure of the xml and the relations of the attributes. See section “Examples of Extensions -> Extension of the Document Search Screen“ on how to use the generic search framework to manipulate the document search screen.
Main Components of the Generic search framework Component Application layer
\appbase\genericsearch.jsp Web server
\xcm\sap\modification\generic-searchbackend-config.xml Web server
com.sap.isa.ui.uiclass.genericsearch.GenericSearchBaseUI.java Web server
com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory.java Web server
com.sap.isa.isacore.action.GenericSearchBaseAction.java Web server
com.sap.isa.isacore.action.GenericSearchSortAction.java Web server
CRM_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"> <!-- THIS IS THE BACKENDTYPE LEVEL (e.g CRM, R/3, ...) <config id="crmbasket_crmtemplate"> <!-- THIS IS THE BASKETTYPE LEVEL (e.g crmbasket,
First entry for each backend is the declaration of the available search screens and the result lists. The search screen describes which fields should be offered to the web-user and how do they depend from each other. Once the web-user starts a search request the result list defines the fields which should be returned for each found object (e.g. for orders this could be the order no., the creation date, …)
Next part describes all search screens and result lists which are defined for a backend- / baskettype combination.
<screen-group name="search_criteria"
description="search.criteria" uiClassName="com.sap.isa.ui.uiclass.genericsearch.GenericSearchISAUI"
type="search"> <property-group>SearchCriteria_B2B_Sales</property-group>
<property-group>SearchCriteria_B2B_Contracts</property-group>
… </screen-group>
<screen-group name="result_list"
description="result.list" type="result">
<property-group>salesdoc_resultlist_B2B_itemlist</property-group>
<property-group>order_resultlist_B2B</property-group> </screen-group>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 104
Next part defines a search screen. A search screen is packed within a <property-group> tag.
<!-- ***************************************************************************** * START of the search criteria definition for B2B Sales Documents
******************************************************************************* --> <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 order number 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 which should 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."/>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 105
Allowed attributes for tag <screen-group>
Attribute Default Remark
uiClassName - Defines the UI class which should be used to build up the search and result list screen. The class must implement Interface GenericSearchUIData or more easily extend class GenericSearchBaseUI.
Allowed attributes for tag <property-group> describing a search screen.
Attribute Default Remark
useSearchRequestMemory false If set to true, the last search request parameters (drop down boxes, input fields) will be stored and after a performed search represented to the web user.
If set to false, the search screen will always be displayed according to default settings.
bodyInclTop - Defines the path/name of an include which will be placed right after the <body> tag of the <html> page.
bodyInclBottom - Defines the path/name of an include which will be placed right before the </body> tag of the <html> page.
maxScreenAreas 1 Number of screen areas for this search screen. This allows splitting the search criteria into several areas. The areas are <div> blocks and can be controlled by the Cascading Style 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 into another frame as the search screen.
msgKeyObjectFound gs.result.msg. Resource key prefix for message of how many objects have been found
The 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 occurred
See also <propert-group> describing a result list.
Allowed attributes for tag <property> describing a search screen.
Attribute Default Remark
name - Name of the property which will be used for searching in a backend.
The name MUST be unique within one search screen definition where the property appears on the screen. To separate properties with the same name add an index in form of (1), (2) to the 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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 add the word “token” to your subtype (e.g. type=”box(datetoken)”. The information “datetoken” will be passed on to the backend in attribute “param_function” (see details of component “CRM_ISA_GEN_DOCUMENT_SEL”)
By appending “UI” to the type, this property will only be used on the screen, but not send to the backend.
helpValuesMethod - Identifies a help value method defined in file sap\modification\helpvalues-config.xml. Adding the name of an <helpValuesSearch> will bring up an binocular beside of an input field.
implemenationFilter - If set to true the value send with the request will be used to first identify an backend object (see file sap\modification\backendobject-config.xml) and second to select the ABAP class performing the search.
resultlistName - Default name of the result list which will be used, if not otherwise specified (see <allowedValue> tag. Only meaningful if flag “implemenationFilter” is set to “true”.
entityType - Database entity where the search will performed. (e.g. to identify where the entity in the CRM 1order reporting framework will search for this property)
tokenType - To identify an token on how to be search (e.g. an token from the CRM 1order reporting framework like “RAN”)
parameterType - Additionally describing attribute for the property which will be passed on to the backend in attribute “param_func_type” (e.g. to identify 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 web server. Since there is no further processing on this attribute, the name could be freely chosen (to be unique).
UIJScriptToCall - Defines a JScript function and event for this property (e.g onBlur=’dosomething();’)
UIJScriptOnChange - Defines a JScript function which should be called on the “onchange” event. The function will be called BEFORE the standard 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 be interpreted 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 the
selection takes place. The Framework will only return this amount of result list entries. Setting the value to “-1” will return ALL result list entries.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 107
Special Values for the Attributes
Some values of the attributes are having a special meaning.
Attribute Value Remark
entityType 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 has to 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. (BAdI CRM_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 to perform a document type specific search. The implementation is selected by a filter value, that is controlled with the attribute implementationFilter. Possible values are e.g. ORDER, CONTRACT, QUOTATION and others. 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 select options 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 additional select option is generated.
The implementation CRM_ISA_FLT_DOCFLOW_CAMPAIGN is an example for a filter before and after the selection. First the given campaign is read and additional select options are generated so that only orders in the time range of the campaign are selected by the reporting framework. After the selection the document flow 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 Remark
propertyName - 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 this dependency 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 Remark
value - Static value which will be added as select option to a <html> select box (e.g.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 list is assigned. (e.g. an order document has other fields within its result 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 to instantiate and perform the defined method. Within this method the entries of the drop down box can be generated, and by that reflecting user settings, shop settings or other customizing.
contentCreateClass - Full qualified class name
contentCreateMethod - 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, this property will not appear on the final <html> page.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 109
Allowed attributes for tag <property-group> describing a result list.
Attribute Default Remark
bodyInclBeforeResult - 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 found
The 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 occurred
If not set on the result list level, value from search screen will take place.
See also <property-group> describing a search screen.
expandedResultlist false If set to true, the web application will be instructed to expanded the search area.
Allowed attributes for tag <property> describing a result list.
Attribute Default Remark
name - 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 for internal purposes and not intended to be visible to the web user.
“date” and “number” mark properties which are not meant to be sorted as String!
“nosort” marks properties which should not have the possibility to be sorted be the web user.
“text” in conjunction with attribute “readOnly” (=false) will render a <input> tag allowing the web user to enter some data (a surrounding <form> tag to process the data, must be rendered by using the custom includes (see attributes “bodyInclBeforeResult” and “bodyInclAfterResult”)
readOnly false Render the field as input field is set to “false”. This is possible for 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 on the <html> page
cssClassName - Assigns a special CSS class to this property. By that it is
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 name
linkParamMethod - 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 to issue 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 the GenericSearchISAAction is derivated from this base action to deliver ISales specific objects like BOM or UserSessionData.
While this action is processed it will be decided where the search request should be processed. This could either be the CRM Application server or the JavaBasket. Determined for the backend is the value of the property where attribute “implemenationFilter” is set to “true”. The object with this type will be picked up from the 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 options are linked together with a handle. From the <html> page generated by the genericsearch.jsp only ONE search request at the time will be send.
The function module itself is not responsible to handle the search request. It only determines the right BAdI implementation and hands over the control to it. To determine this BAdI implementation, one of the search
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 111
request entries (import table IT_SEL_OP) with key SELECT_PARAM = ‘LIST_FUNCTION’ is picked up and its value used to instantiate the BAdI.
Known standard implementations for CRM Internet Sales are:
Filter Value ABAP class Remark
ORDER 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 the documents (R/3 or CRM) and also what type of documents (invoice, credit memo or down payment).
BACKORDER CL_IM_CRM_ISA_GDS_BACKORD This implementation is exclusively used to select backorder documents
1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for items within one sales document (1Order documents). It returns items instead of header objects.
BILLINGITM CL_IM_CRM_ISA_GDS_BILLDOCI This implementation is used to search for items within CRM billing documents. It returns items instead of header objects.
ORDERITM CL_IM_CRM_ISA_GDS_ORDERITM This implementation is used to search for items in 1Order order documents. It returns items instead of header objects.
ORDTMPITM CL_IM_CRM_ISA_GDS_ORTMPITM This implementation is used to search for items in 1Order order template documents. It returns items instead of header objects.
QUOTITM CL_IM_CRM_ISA_GDS_QUOTITM This implementation is used to search for items in 1Order quotation documents. It returns items instead of header objects.
RETURNITM CL_IM_CRM_ESRV_RET_ITEMS This implementation is used to search for items within CRM return transactions. It returns items instead of header objects.
COMPLITM CL_IM_CRM_ESRV_COMPL_ITEMS This implementation is used to search for items within CRM complaint transactions. It returns items instead 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. To select documents from the CRM 1order the application provides the CRM 1order reporting framework. To communicate with the reporting framework the helper class provides various methods to format the incoming search request and convert it into a reporting framework query. The reporting framework only return the main key (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_.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 112
Same applies to the billing documents except the prefix of the methods is BILLING_ and the selection is covert by the function module “/1BEA/CRMB_BD_O_GETLIST” or “CRM_ISA_INVOICE_LIST_GET” for R3 billing documents.
If none of the prefixes is used the method has common character and can be used for reporting framework and billing.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 113
ESelling specific implementation 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 section now 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 Remarks
SearchCriteria_B2B_Sales B2B To search for sales documents.
- orders
- quotations
- order templates
Even billing documents are defined, once one of those is selected, via JScript search definition “SearchCriteria_B2B_Billing” is called. Forwarding to “SearchCriteria_B2B_Items” if items should 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 JScript search definition while for Billing documents “SearchCriteria_B2B_Billing” is called
SearchCriteria_B2B_Contracts B2B To search for contract documents
SearchCriteria_B2B_Sales_OrderStatus_Items B2B To search for sales document items (used to find items in case of large document handling is enabled in the shop)
SearchCriteria_B2B_Billing B2B To search for billing documents
- invoices
- credit memos
- down payments
Even sales documents are defined, once one of those is selected, via JScript search definition “SearchCriteria_B2B_Sales” is called.
SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items (used to find items in case of large document handling is enabled in the shop)
SearchCriteria_B2B_Auction B2B Only describes the search criteria, but the actually search is not done by the Generic Search Framework
SearchCriteria_BOB_Sales Business on Behalf
To search for sales documents
SearchCriteria_BOB_Customers Business on Behalf
To search for customers in a BOB scenario
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 114
SearchCriteria_HOM_Sales Hosted Order Management
To search for order document in a HOM scenario
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 document types 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 allowed by 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");
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 115
Logging/Tracing Logging/Tracing provides a means for the user to write structured data into a file, a console, or some other output destination.
This chapter gives background information on how to use and configure logging/tracing within the Internet Sales application.
Design Consideration
When the first Java version of E-Commerce was released there was neither a logging API within the Java Development Kit, nor an SAP logging API. Instead, an open source LOG4J logging API was well accepted within the Java community.
When designing the E-Commerce architecture it was clear that there would be a time when a new logging API (either from SUN or SAP) would be released. In order to be able to switch to this logging API without changing the application coding it was decided to introduce an own logging facade (API) over the existing log4j 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 new applications 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 projects migration 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
Tracing
Trace 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 on existing customer coding already using ISALocation
New Customer Project
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 116
A trace message can have the following content:
Information about execution steps
Value of important variables
Important return codes
Information about thrown Exceptions
Logging Log 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 enough information in order to enable the administrator to understand the message or to solve a potential problem. In order to have a uniform log output there are some helper methods in the
class com.sap.isa.core.logging.LogUtil for constructing log messages.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 117
Summary Types of log messages
Message Type Interested Party What to use
message customer or admin log record
message developer, support trace record
exception customer, admin log record
exception developer, support trace record
entering/exiting method
developer, support trace record
Table 27: Types of Log Messages
Tracing
Use the following severities to write trace messages:
Severity Description
DEBUG Developer trace. Any information useful for a developer in order to understand program execution 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. If you don’t have enhancements, or if you do enhancements for new applications, please use the SAP 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()
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 exception
Use the following methods to write trace messages with the severity level “ERROR”:
DEBUG
Use the following methods to write trace messages with the severity level “DEBUG”:
ERROR
Use the following methods to write trace messages with the severity level “ERROR”:
Coding Examples
Strings 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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 119
APIs for Tracing: SAP Logging API
Initializing Location
Contrary to the IsaLocation you pass the class object instead of a string
DEBUG
Use 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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 120
ERROR
Use the following methods to write trace messages with the severity level “ERROR”:
Entering/exiting non trivial method
Use the following methods to write trace messages with the severity level “PATH”:
Throwing exception
Use the following methods to write trace messages when an exception is thrown, that is only relevant for developers 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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 121
Logging
Use the log levels according to the following table:
Severity Description
Info 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 provide further information for later reviews, audits or investigations.
Warning The application processing can and will proceed, but later follow-up activity by people responsible for the specific category is necessary to avoid error situations in the future. Information of how to solve the problem in the future should be available.
Error The application processing terminates without completing the desired tasks. The application is still usable, but corrective actions need to be performed to avoid the erroneous termination in the future. Information of how to solve the problem should be available. If not, customers will need to open problem messages to solve the problem.
Fatal The application processing terminates without completing the desired tasks. The application is not usable anymore and cannot be started without corrective actions by experts. Customers will normally need to open problem messages to solve the problem.
Table 29: Log Levels
Usage of Categories
Application 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 to security
com.sap.isa.core.logging.LogUtil
/Applications/Common/Infrastructure everything related to infrastructure i.e. generic services (JCo, cache, database, etc.)
com.sap.isa.core.logging.LogUtil
/Applications/UserInterface User Interface Layer (e.g. JSPs)
com.sap.isa.core.logging.LogUtil
/Applications/BusinessLogic functionality dealing with business logic (e.g. E-Commerce Business Objects)
com.sap.isa.core.logging.LogUtil
/Applications/Interaction classes controlling the interaction with the user (e.g. Struts actions)
com.sap.isa.core.logging.LogUtil
Table 30: Categories for Logs
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 122
APIs for Logging: ISALocation
ERROR
Use the following methods to write log messages with the severity level “ERROR”:
FATAL
Use the following methods to write log messages with the severity level “FATAL”:
INFO
Use the following methods to write log messages with the severity level “INFO”:
WARNING
Use 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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 123
Detailed Message Descriptions
It is recommended to use detailed message descriptions. These messages can be created using the
following 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 Examples
When 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"));
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 124
APIs for Logging: SAP Logging API
INFO
Use the following methods to write log messages with the severity level “INFO”:
WARNING
Use the following methods to write log messages with the severity level “WARNING”:
ERROR
Use the following methods to write log messages with the severity level “ERROR”:
FATAL
Use 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,
java.lang.Object[] args, java.lang.String msgClear, java.lang.Throwable exc)
logThrowable(Severity.ERROR, Location loc, java.lang.Object msgCode,
java.lang.String msgClear, java.lang.Throwable exc)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 125
How to Log/Trace: Usage patterns
As a general rule, trace messages are meant for developers to understand the execution flow of the program. Log messages are used by system administrators to monitor the health of an application. The following 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 might throw an exception causing the execution flow to exit the method, you have to trace the exit in a finally 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,
java.lang.Object[] args, java.lang.String msgClear, java.lang.Throwable exc)
logThrowable(Severity.FATAL, Location loc, java.lang.Object msgCode,
java.lang.String msgClear, java.lang.Throwable exc)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 the exception.
In general, there is no need to log the throwing of an exception. It is up to the calling layer to interpret 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
private static final Location loc = Location.getLocation(ClassName.class);
// …
public void methodX() {
final String METHOD_NAME = " methodX()";
loc.entering(METHOD_NAME);
//do some proecssing …
loc.exiting();
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 127
4. Catching Exceptions. When catching an exception, following are some common cases which should be 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 caught exception.
In case of recovering from the exception, i.e. the exception is handled in the catch clause and 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
private static final Location loc = Location.getLocation(ClassName.class);
// …
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;
}
//…
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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
private static final ISALocation log = ISALocation.getInstance(ClassName.class.getName());
// If Trace recover from caught exception using SAP logging API
private static final Location loc = Location.getLocation(ClassName.class);
// …
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
}
//…
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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. Use severity INFO for events that need to provide information about the progress of an operation. For detailed context information including state variables use severity DEBUG. It is especially important that sufficient context information is logged and traced for an error condition.
// If Trace the throwing a wrapper exception using ISALocation
private static final ISALocation log = ISALocation.getInstance(ClassName.class.getName());
// If Trace the throwing a wrapper exception using SAP logging API
private static final Location loc = Location.getLocation(ClassName.class);
// …
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;
}
//…
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 130
Example
// If Trace the throwing a wrapper exception using ISALocation
private static final ISALocation log = ISALocation.getInstance(ClassName.class.getName());
// If Trace the throwing a wrapper exception using SAP logging API
private static final Location loc = Location.getLocation(ClassName.class);
// …
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;
}
//…
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 131
All purpose Cache Internet Sales comes with an all purpose cache, which can be used to store any arbitrary data. This chapter describes how to use and configure the cache.
Working with the Cache
The cache is divided in so called regions. Each region represents an individual cache and the region name is used to distinguish between caches. If you need your own cache you have to add a new region together with attributes. These attributes define how the cache handles objects cached in the region. The most common 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.xml file:
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>
<!-- includes SAP cache configuration -->
<xi:include href=‘${sap}/modification/cache-config.xml#xpointer(cache/regions/*)’/>
<!-- defines customer project cache -->
<region name=‘Z_AcmeCache’ idleTime=‘60’ timeToLive=‘300’ descr=‘Project ACME cache’/>
</regions>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 132
Example
Initialization Handler When 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 opportunity
to perform some initialisation tasks.
The terminate() method is called when the application is stopped or the SAP J2EE engine is shutting
down. 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 defined
in the body of the initalization XML element. These parameters are passed as Properties to the
initialize() 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);
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 XCM
Extension mechanism. An example is given in chapter 'Changes in init-config.xml' on page 276.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 the customer.
The XCM Administrator tool has been developed for general configuration activities (for example, connection parameters to the SAP system). The tool enables you to maintain the configuration for each deployed web application 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 SAP Service 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 configuration changes must be done manually.
Separation of Customer and SAP Configuration Files XCM 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 the
customer template. In most cases customer changes, done by customers, take place in init-config.xml
or backendobject-config.xml
You should never change the files config-data.xml or scenario-config.xml. This is done using XCM Administrator
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 change
settings you must use the XCM extension mechanism. The following chapter explains how the extension mechanism works.
Separation of Configuration Data and Modification Data Besides the separation of SAP and customer data there is another separation of data. That is, data used for configuration of the application (for example, connection data to the SAP System; this is often changed), and modification data (this data is rarely changed).
The location of the customer configuration data is located in the folder specified using the context parameter
customer.config.path.xcm.config.isa.sap.com. There are two files used for this kind of
configuration:
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 customer
modification data is located in <APPLICATION_HOME>\WEB-INF\xcm\customer\modification. Here
you can:
Reassign backend classes to standard business objects, or assign backend classes to customer
specific 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 capture
handler 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 function
module 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 in
this 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’>
<!-- customer changes in init-config should be done here by
extending/overwriting the base configuration-->
<xi:include href=‘${sap}/modification/init-config.xml#xpointer(initializations/*)’/>
</initializations>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 136
XCM Extension Mechanism The XCM extension mechanism enables you to manipulate XML nodes using inheritance. If you want to change 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’]”>
<params id=“logoncrm“>
<param name=“password“ value=“topsecret“/>
<param name=”language” value=”de”/>
</params>
</config>
</configs>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 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 to topsecret.
<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 those parameters 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 releases within the XCM Administrator.
The XCM Administration tool is used for creating a web application configuration. Each application provides one or more pre-defined configurations. You have to create your own configuration based on one of the delivered 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 component configures connection parameters to the SAP system)
Refer to chapter ‘
<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’]”>
<params id=“logoncrm“>
<param name=“password“ value=“topsecret“/>
<param name=”language” value=”de”/>
<param name=”user” value=”john”/>
</params>
</config>
</configs>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 138
Extending XCM with Customer Settings’ (page 279) to get information how to do custom extensions in the XCM.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 139
SAP Java Remote Function Call (JRFC) The SAP Java Remote Funciton Call (JRFC) is a middleware product that enables communication between Java 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.
Technology JRFC communicates with the SAP system via Remote Function Call (RFC). The RFC is SAP’s own representation of the Remote Procedure Call (RPC). Since the RFC is an ABAP component, it is frequently used 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 (function module) 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 middleware layer 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 140
Development Environment This unit introduces the development tools that are required for both installing and developing all of the required frontend components and the CRM java applications.
It describes how to use the Netweaver Development Infrastructure (NWDI) to modify or extend CRM and ERP Java Web Applications.
The Netweaver Development Infrastructure supports integration of patches, Service Packs and upgrades to new releases without loosing modifications or enhancements and it supports team development.
We will discuss the following components:
Java Development Kit (JDK)
NetWeaver 7.30 Java Development Infrastructure (NWDI)
NetWeave 7.30s Java Integrated Development Environment (IDE)
NetWeaver 7.30 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
Ch
an
ge M
an
ag
em
en
t S
erv
ice
(CM
S)
Run
Time
J2EE
Systems
Run
Time
J2EE
Systems
Deploy
Local File
System
Component
Model
Local J2EE
Engine
Component
Build Service
(CBS)
Design Time
Repository
(DTR)
Name Server
System Landscape
Directory (SLD)
The first of this unit deals with installing and configuring the SAP NetWeaver Development Infrastructure which is a precondition for the development.
The second part handles the installation and configuration of a developer workplace.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 141
Development Tools and Concepts
The SAP NetWeaver Developer Studio provides access to the SAP NetWeaver Java Development Infrastructure. It enhances the concept of an IDE by server-side services, centrally provides the development teams with a consistent development environment and supports the software development during the entire life cycle of a product.
Development Infrastructure (NWDI) Comprising of DTR, CBS, CMS, and using SLD.
Design Time Repository (DTR): Versioning source code management. Distributed development of software 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 and the transports covering the entire software life cycle.
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. See the documentation in the NWDS: ‘SAP NetWeaver Developer Studio Documentation > Developer's Guide > Developing Java EE 5 Applications > Tasks > Developing Persistence’
SAP Java Test Tools: Predefined static tests and runtime tests for the Java development. E.g. ‘SAP NetWeaver Developer Studio Documentation > Developer's Guide > SAP NetWeaver Developer Studio Basics > Working with the Developer Studio > Testing Java Applications with JLin’
You use the development configuration to configure the development environment. The access paths for the used services are automatically set by importing a development configuration, for example, the URI of the used DTR (-> ‘SAP NetWeaver Developer Studio Documentation > Developer's Guide > Development Infrastructure > Concepts’.
You can develop in the development infrastructure according to the component model (‘SAP NetWeaver Developer Studio Documentation > Developer's Guide > Development Infrastructure > Concepts > SAP's Component Model’).
External documentation This document refers to the following official documents delivered by SAP in the help portal ( http://help.sap.com ) :
Administration manual of NWDI :
o https://help.sap.com/saphelp_nw73/helpdata/en/48/bc0992ec1b5295e10000000a42189b/frameset.htm
Additional information If you did development for CRM 7 on NW 7.0 before you should be aware of the following points
Netweaver Developer Studio
Before using the NWDS with existing projects please read note 1659387. In some constellations a popup might come up asking you to perform a migration of the project. This migration attempt must be cancelled, as it will break the projects
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 142
NWDS, SLD, and CMS track definition
Please make sure to
Use the dependencies to the NW 7.3 libraries
Use JDK 1.6 instead of 1.4 on all relevant places
Exclude all irrelevant SC’s from deployment, see chapter “Create a new Track using the Landscape Configuraton”
Software component for own development
Although for convenience there is a Software Component (SC) CUSTCRMPRJ it should only be used for test purposes and not for own development, as it belongs to the SAP name space. Please create your own SC according to the documentation e.g. in
https://help.sap.com/saphelp_nwce711/helpdata/en/d4/8d784289b4de54e10000000a155106/frameset.htm
Overview of process CRM Software Components delivered by SAP are imported in a track. Some of the components are designed to be modified. Others are required for compiling and building the application.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 143
Software Component Architecture of the CRM or Extended Ecommerce Java Applications
The 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-Commerce Applications, 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 the applications.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 144
The following table shows all components at a glance:
Software Component Software Component for Developement
Used in ERP
Used in CRM
Usage
SAP-SHRWEB.sca Yes Yes Yes Contains Web Modules for E-Selling, IPC Web Applications and Workforce Management
SAP-SHRAPP.sca Yes Yes Yes Contains J2EE Applications and deployable Libraries.
SAP-CRMWEB.sca Yes No Yes Contains Web Modules for other E-Commerce Applications
SAP-CRMAPP.sca Yes No Yes Contains J2EE Applications and deployable Libraries.
SAP-CRMDIC.sca Yes Yes Yes Contains Data Dictionary Development Components
sap.com~STRUTS.sca No Yes Yes Contains required jar Files for compiling and building
TEALEAF.sca No Yes Yes Contains required jar Files for compiling and building
SAP-IPCMSA.sca No Yes Yes Contains required jar Files for compiling and building
Table 31: Software Components
Thus, you must add the components SAP-SHRWEB.sca and SAP-SHRAPP.sca into the list of the Software Components for Development. The required Software Components will be selected automatically.
Modifications and Extensions of the Web User Interface
The web user interface of the CRM Applications is contained in the Software Components SHRWEB or CRMWEB.
For each web application there is one Development Component. The naming convention for the Web Module Development 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 the list of Components to be synched.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 145
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 when applying new patches
Extensions of the Java Code
The Software Component SHRWEB contains the Development Component crm/home/shr/ext. It’s designed to 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 context menu (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 the classes are required by a web application, the Used Relationship to the public part “assembly” must be added for the Web Module Development Component of the application. Search for “Changing Used DC” in the 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 in crm/isa/web/b2b. It must refer to crm/home/shr/ext.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 146
Merged Web Applications
All CRM Java applications have the same structure. There are some files which need to be available in all applications.
For this reason, there is a shared web component DC introduced. This development component type is based on a regular Java Development Component with a public part of purpose "compilation". Despite normal java development components the shared web components contain web files to be shared in the src/packages directory. These files can be merged into other web archive Development Components by defining 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 a special meaning!
Files in src/packages directory of the shared component will be merged into the web archive at build time
Shared files can be overwritten by files in the web archive if they have the same name and directory
Handling of duplicate files
If a file with the same name and directory exists in two different shared web components, it's not predictable 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 from the web module will be in the generated web application.
Restrictions
Due 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 147
Initial Configuration of the NWDI This 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 steps needed to handle a Support Package upgrade).
Pre-requisites This 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 information about this.
NWDI has been installed
The NWDI online configuration has been executed
The System Landscape Directory (SLD) has the new content (of the Software Components delivered with this release).
Creating a project specific Web Application with own context root In order to be able to compare the SAP standard web applications with the extended applications, it makes sense to have two deployments. The first one is the one delivered by SAP, the second one contains project specific 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 (Please keep in mind this is only valid for testing purposes. For real life projects please create you own Software Component, check chapter “Software component for own development”).
• Change Context Root
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 148
• Exclude SAP-SHRAPP from deployment
Basic concept Create 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 (except application.xml).
Add the used relationship to the public part of the Web Module Development Component to the new Development Component.
Check in the files.
Only the new Software Component will get the extended version of the application. These versions will be deployed on the Web AS Java System by NWDI.
The SAP standard component SAP-CRMDIC, SAP-SHRAPP and/or SAP-CRMAPP can be deployed directly to the Web AS Java Server.
Step by step process
Check SLD content and create a new Software Component
If you installed the NWDI Infrastructure by installing usage type DI, the SLD content was imported automatically. This content may not be up-to-date.
Check whether the Software Component CRM JAVA CUSTOMER PROJECT 5.0 exists in the SLD:
If this component is missing, you import an update of the CIM Model from the service market place. Refer to Note 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 Configurator
On the “Track Data” tab of the Landscape Configurator, enter the general data as shown below:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 149
Figure 25: Creating a new Track
Substitute the URLs with the appropriate ones from your landscape.
Add Software Components to track
On 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 150
After this step, the bottom half of this tab will look as shown below:
Figure 27: Required Software Components
Save your changes by clicking on the “Save” button on this tab.
Configure Runtime Systems in the track
Configure 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
Import Software Components into this track
Download Archives
The 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 be found under the following path: “<CMS Transport Directory>\CMS\inbox”, where the <CMS Transport Directory> 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.sca o SAP_BUILDT.sca o SAP-JEE.sca o SAP-SHRJAV.sca o SAP-SHRWEB.sca o SAP-SHRAPP.sca o SAP-CRMJAV.sca o SAP-CRMWEB.sca o SAP-CRMAPP.sca o SAP-CRMDIC.sca o SAP-IPCMSA.sca o STRUTS.sca o TEALEAF.sca
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 151
The names of .sca files could be different – they may include version numbers, vendor name, etc.
Check-In archives
In the “Check-In” tab of the CMS Transport Studio CMS perform a “Check-In” : select each of the above archives and click on the “Check-In” button.
Figure 28: Check-In of the Archives
Import the checked in archives into the Development system
In 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 system
Repeat the above step in the “Consolidation” tab.
Create your own Enterprise Applications
The following steps need to be done:
Import the Development Configuration into your Netweaver IDE.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 152
Create a new Enterprise Application Development Component in Software Component CRMCUSTPRJ.
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 Enterprise Archive 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 project for 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/b2b component 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 153
Test the CRM Java application on a local Web AS Java Engine
In order to be able to run CRM Java applications you need to deploy the SAP-CRMDIC software component on 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 Development configuation perspective of the Netweaver IDE:
Look at the online help of the Netweaver IDE for more details.
Creation or Extensions of Java Classes This 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 to be extended in the NWDI. For SAP-CRMWEB the java DC is crm/home/crm/ext, for SAP-SHRWEB it’s crm/home/shr/ext. These components are empty when shipped.
A used relationship in the web module development components of the applications to the java development components 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 java development components are already defined. If a new java class needs further references to other java development 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, a
new used relationship in crm/home/shr/ext to the public part default in crm/isa/isacorer3 needs to
be added.
More details of Used Relationships can be found in the online help to the SAP Netweaver IDE.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 154
Importing Modifications and Extensions from older Releases Please check this chapter in the Development and Extension Guide SAP E-Commerce 7.0: “SAP_ECO70_DevAndExtGuide_Concepts.doc”
Here only the import of releases of CRM
This chapter describes how to import modifications and extensions from former Releases (CRM 3.0, 3.1 and 4.0) to a NWDI track (>= CRM 5.0). It assumes that the buildtool was used to build the modified application and that there is a new NWDI track available to import the extensions and modifications. It further assumes that basic knowledge about NWDI is available.
The “SAP Customer Relationship Management 5.0 Java on <Operating System> : <Database>” guide describes 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 Development Configurations.
Importing buildtool to NWDI for releases lower CRM 5.0 to a higher release
In 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 structure which can be imported to the NWDI track. You can call this target in the same way as you execute the other targets like build “extract.ears”.
To install the buildtool do the following steps:
Step Description
1 Update the build tool Note 594370 contains a description of the upgrade procedure.
2 Execute target “nwdi” with the buildtool The documentation of the buildtool contains a description how to execute an ant target (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 java extensions:
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 Software Component SHRJAV. Crm/home/crm/ext ist designed to hold extensions of the java classes in Software Component CRMJAV.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 155
Hint: It’s possible to create an own Software Component, an own Development or both to hold the java source. In this case the required used relationships of the Software Components have to be setup on the nameserver and the used 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 during initialization.
Copy the content of this directory to the <NWDI Configuration root>/<Configuration Number>/DCs/sap.com/crm/home/shr/ext/_comp or to <NWDI Configuration root>/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 Development Configuration(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 already established. However it might be necessary to add further Used Relationships to make the extensions compilable.
6 Create a java project for the Web Module Development Component to be modified or extended.
The Web Module Development Components are located either in CRMWEB or in SHRWEB 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/<Development Component name>/_comp
Hint: If the IDE will not automatically check that the new files have been added. After executing a refresh on the java project the files will be displayed and you will be asked 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/<application name>_<project name>.
This directory has the same structure as the same directory structure as the Web Module Development Components.
Some of the files shipped in the new release might differ from the older versions of the files, so it’s not possible to copy the modified files into the _comp directory but the changes need to be merged into the new version.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 156
Step Description
10 If you added java classes and you want to use them in the modified web application, you need to add the java Development Component to the list of Used DC’s of the Web Module. Look at the 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 of crm/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 release
Following you will see the steps which are necessary to do the import for sources. 1. Update CIM Model Download 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 inform NWDI 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 157
Synchronize SC Dependencies in CMS
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 158
After clicking on the synchronisation button the following popup may appear if inconsistencies in the Dependency Definition exist. Since the current Dependency Definition is located in the SLD, therefore use the 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 red lights. 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 on http://xads.wdf.sap.corp:8000/sap(bD1lbiZjPTgwMA==)/bc/bsp/sap/zidesinfobase/detailareaframe.htm?theme=STANDARD&aview=1&scenario=010000005762&inframe=
Developer Workplace When we look at the architecture of SAP E-Commerce 7.3 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 159
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.
Figure 30: Overview Developer Workplace
Required tools and versions SAP CRM 7.3 is based on SAP NetWeaver 7.30. There the following software component versions are contained or required:
Component Version
SAP Web AS Java 7.30
JDK 1.6.0
IDE SAP NetWeaver 7.30 Developer Studio
Java Development Kit The Java Development Kit represents the Java Virtual Machine (JVM), which is a prerequisite for the SAP Web AS Java (Servlet Engine). In addition, JDK offers options for compiling, executing and debugging Java applications.
Installation of JDK 1.6.0
Download the JDK from the oracle homepage http://www.oracle.com/technetwork/java/javasebusiness/downloads -> Previous
Releases.
Select the version you require from the list ‘Java 2 Platform, Standard Edition (J2SE)’.
Make sure that you download the ‘SDK’ and not the ‘JRE’!
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 160
Once j2sdk-1_6_0_XX-windows.exe (where XX is the number of the patch) has been downloaded, you have
to execute it. A destination location <JAVA_HOME> must be chosen and you have to select the following
components for installation:
Program files
Native interface header files
Old native interface header files
Demos
Java sources
Once JDK 1.6.0 has been successfully installed, the JAVA_HOME environment variable must still be set in
such a way that the Java compiler can be found (SET JAVA_HOME=<JAVA_HOME>). You also have to
append the ‘<JAVA_HOME>\bin‘ directory to your environment variable ‘path’. These settings can be
configured, for example, in the Windows environment in the system properties, which can be accessed via the control panel (System Settings Control Panel) and by double clicking on the Systems icon. Please make sure that the PATH environment variable is expanded to the binary directory underneath the jdk1.6.0 directory. If this was not done automatically, for example, during the manual installation of JDK, you can do this 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 161
Developer Workplace for SAP NetWeaver 7.30 The SAP Developer Workpace consists of the following Components:
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 7.30
Installing the Developer Workplace for SAP NetWeaver 7.30
The installation of the SAP Developer Workplace is described in the “Installation Guide - Developer Workplace for NW7.30”, that is available on the SAP Service Marketplace quick link instguides (http://service.sap.com/instguides) SAP NetWeaver Release 7.3 Installation (in the list 2 - Installation - SAP NetWeaver Systems and 4 - Installation - Clients).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 162
Directory Structure of the Web AS Java 7.30
Once it has been installed, the directory of the Web Application Server is structured as follows:
Root DI Transfer folder SAP SID J<INSTANCE_NUMBER> Contains deployed web applications Server directory Logfile directory (also contains the ECO log entries) SAP Web AS Configuration Tool JSPM directory
Figure 32: Directory Structure of Web AS Java 7.0
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 163
TCP-Ports
The ports used by the Central J2EE Instance are determined by the instance number, which is entered within the installation and can be calculated with the following formula:
<Base port> = 50000 + 100 * <INSTANCE_NUMBER>
Name Formula Description
HTTP <Base port> + 0 Used to access the Central J2EE Instance using a browser
P4 <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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 164
Example
The SAP WebAS Java has been installed on the server with instance number 00. The used HTTP port is then 50000.
The actual used ports can be checked using the configuration tool under Cluster/Dispatcher -> services -> http, p4, telnet.
Starting and Stopping the WebAS Java
Since NetWeaver’04, the SAP Management Console is used to start and stop the Web AS Java. Each Web AS 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 and press the start/stop button in the button bar.
Figure 33: SAP Management Console
Configuration of SAP WebAS Java 7.30
The SAP WebAS Java 7.30 can be configured using the configuration tool.
Uninstalling the Developer Workplace for SAP NetWeaver 7.30
How to uninstall the Developer Workplace for SAP NetWeaver 7.30 is described in Appendix of the “Installation Guide - Developer Workplace for NW7.30”, that is available on the SAP Service Marketplace
Central J2EE Instance
Database Instance
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 165
quick link instguides (http://service.sap.com/instguides) SAP NetWeaver Release 7.30 Installation (in the list 2 - Installation - SAP NetWeaver Systems).
Configuring and Working with Developer Studio This section describes manual deployment of an SAP E-Commerce web application. The focus of this guide is to enable consultants to quickly get started using the new concepts used by SAP and set up a local development landscape that enables them to implement customer requirements. This local development landscape can differ from the production environment. Consultants can install variants on their laptops.
Configuration of the web application
This section describes the configuration of the Internet Sales application. In Internet Sales 7.3 the Extended Configuration Management (XCM) is used to configure the web applications. The tool, used to configure them, is the XCM Admin. This tool is contained in every web application. You have to configure each application with it’s own XCM Admin. For more details how to configure the web applications please see the corresponding documentation.
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 SAP configuration default templates.
2. Restart the web application through the SAP J2EE NetWeaver Administrator, http://localhost:50000/nwa -> Operations -> Start & Stop -> Java Applications, filter for ‘b2b’ and click Restart.
3. Create shop definitions refering the corresponding backend system using the Shoadmin web application.
4. You can call the application via the URL, for example, http://localhost:50000/b2b/b2b/init.do. Please
note that links that end in ‘.do’ are forwarded as events to the ActionServlet that is defined and
configured in the web.xml file. The following entry is required in the web.xml file to ensure correct
forwarding:
5. The servlet mappings are configured in the config.xml in the directory WEB-INF of your web application.
We recommend you perform all customer enhancements on a copy of the original EAR file. You can create a copy with the ISA Buildtool.
<!-- ActionServlet Mapping -->
<servlet-mapping>
<servlet name>action</servlet name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 166
Remote Debugging This unit gives you some information about remote debugging on the SAP J2EE server. This information is useful if you extend the ISA application by writing your own Java code, and want to debug this code while it is being executed on the server.
Setting up remote debugging for SAP WEB AS Java 7.3 This section describes the necessary configuration of Eclipse for remote debugging of a web application running 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 Permanently
To enable/disable the debug mode of the SAP Web Application Server Java 7.3 permanently, perform the following steps:
1. Start the oflline configtool by executing <DRIVE>:\usr\sap\<SID>\J<INSTANCE-NUMBER>\j2ee\configtool\configtool.bat
2. Navigate to cluster-data -> template -
3. On VM Environment tab set DebugMode and Debuggable to true.
4. Save the new settings by clicking on the floppy disk icon.
5. Restart the server.
Figure 34: Offline Config Tool - Setting Up Debug Mode
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 167
Enabling/Disabling Debug Mode Temporarily
To enable/disable the debug mode of the SAP Web Application Server Java 7.3 temporarily, perform the following steps:
1. Start the Net Weaver Developer Studio.
2. Switch to the Servers View (menu Window Show View Other… Server Servers)
3. Select the Server Node.
4. Open the context menu (by clicking the right mouse button) and select Enable Debugging of Processes.
Figure 35: J2EE Engine - Enabling Debugging
As an alternative way to switch the debug mode temporarily you can use the SAP MMC:
1. In the AS Java Process Table right click on the server
2. From the drop down menu select “All Tasks” -> “Enable Debugging”
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 168
Figure 36: J2EE Engine - Enabling Debugging
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 169
Starting Remote Debugging
Perform the following steps in your SAP NetWeaver Developer Studio:
In the Java or Debug perspective open the menu Run Debug Configurations…
Select Remote Java Application and press the button New
Host name. The host, where the process being debugged runs.
Address: the port. This has to correspond with the -Xrunjdwp:address setting.
Figure 37: 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 170
ABAP Debugging Since SAP Netweaver 2004 it’s no longer possible to debug ABAP code from Java side. This chapter describes 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 the Java side. The following procedure is necessary to start a debug session:
Prerequesites To 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 are performed, e.g. the host, where the SAP Web AS is running on.
- Since load balancing is not supported, you have to configure your web application to connect to a single 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 Navigate 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 parameters ashost 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 clicking on 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 select the 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 171
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 HTTP Debugging.
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 setting appropriate 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 these authorizations 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 pressing
the button Set/Delete External Breakpoint .
6. Start your web application. When within the web application, with the specified user the ABAP coding will be called, the set breakpoint will be executed.
For detailed information and further questions please refer to the notes 668256, 668252 and 751872.
Java Debugging
If you want to debug the Java coding delivered by SAP, but the coding has not been attached to the .jar files, refer to note 932457. There you’ll find instructions how to attach the SAP Java coding to the jar files.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 172
Introduction to Extension Concepts
Extensions in the ISA Framework The first part of this unit gives an overview of possible extensions and extension concepts. It should help you to find an appropriate extension concept for specific requirements. The subsequent parts of the unit give theoretical introduction to the various extension concepts of the Internet Sales framework. The concepts in this 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 307).
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 backend functions
Calls to function modules are interfered (before and after function call)
Custom function modules are called instead of the standard modules
Backend (e.g. CRM) New/enhanced functions (for example, extension of existing function modules, new function modules).
These extensions are not covered by this document.
Table 32: Overview of possible changes in different layers
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 173
CustomAction
Custom
BusinessObject
Custom
BackendObject
Custom
Function Module
customer data
has to be entered
or displayed
Possible
extensions in
all layers
Figure 38: Flow of possible changes
The E-Service Extended Complaints and Returns application and the Remanufacturer’s Inspection uses the ISA Framework and, as a consequence, supports the extensions to the ISA Framework.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 174
Finding the Appropriate Extension Concept
How to use these diagrams
The following diagrams should help you to find, step by step, the appropriate extension concept depending on your individual requirements. Each diagram has one starting point referring to different branches. The branches describe different requirements (i.e. what you want do), where you have to check according to your requirements which branch is the right one for you. The result of each branch could be a reference to another lower level diagram, or a description of what to do, together with a reference to the detailed description of the available extension concept, with examples.
Overview
Start here to find the appropriate extension concepts or just to get an overview of different categories of extensions.
Static extensions to the
UI-Layer (colors,
images, texts)
Additional data should
be exchanged between
different layers (UI, BO,
BE)
End
Extensions to
exchange additional
data
Start
Extension to ISA
Terminator
Reference to sub
diagram with
more details
What to do -
Reference to detailed
description
Decision
Requirement -
What you want
to do
Legend:
Action flow should be
modified or extended
Extensions to the
action flow
Static extensions to
the UI layer
Figure 39: Overview of different categories of extensions
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 175
Extensions to the UI Layer
This diagram gives an overview of how to realize static extensions which only affect the UI layer.
Texts on the UI should
be changed/added/
removed
Colors of the UI should
be changed
End
Start
Static extensions to the
UI layer
Change/add text in the
text property file (language
dependent!)
Rearrange UI elements
within JSP and/or to other
JSP
Images on the UI should
be changed/added/
removed
Arrangement of UI
elements should be
changed (e.g. frames,
texts, buttons, images)
Change colors in style
definition (CSS)
Replace (standard) image
or add new image
Add/remove text from JSP
Change colors of static
images (e.g. buttons,
frames)
Add/remove image from
JSP
(If required) Adjust frame
targets in JSP’s and in
action flow configuration.
Figure 40: Statis extensions to the UI layer
For details see:
Chapter Extensions to the UI layer on page 192
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 307) with examples for extension
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 176
Extensions to the Action Flow
This diagram gives an overview of how to realize extensions to the action flow, like adding or replacing actions, and writing new actions.
The action flow should
be modified by adding/
removing other
(standard or customer
specific) actions
The action flow should
be modified by changing
the action forward of a
specific (standard)
action
End
Start
Extensions to the
action flow
Modification of the action
flow in configuration3)
Derive new action from
standard action and
implement user exit2)
Appropriate user exit
available in standard action1)
Create new action from
standard action2)
no
yes
Register new action flow in
configuration3)
Figure 41: Extensions to the action flow
For details see:
1) Standard Actions providing User Exits on page 195
2) Create a Customer Action on page 193
3) Modifications in the Struts Configuration
on page 199
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 177
Extensions to Exchange Additional Data
This diagram is the entry point to all extensions related to the exchange of additional data, which are the most common types of extensions. Typically, the additional data has to be displayed on the UI and has to be retrieved from a backend system, or should be entered on the UI and have to be transferred to a backend system. These kind of extensions always affect all ISA layers.
Should the additional data
be exchanged with a
backend system?
Additional data should
be displayed or should
be entered on the UI
Additional data should
be transfered between
the web applicatiion and
a backend system
no
End End
yesExtensions to
exchange data with
the UI-layer
Extensions to
exchange data with a
backend system
Start
Extensions to exchange
additional data
Figure 42: Extensions to exchange additional data
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 178
Extensions to Exchange Data with the UI-Layer
This diagram shows the necessary steps to display or enter additional data on the UI and to transfer this additional data with the underlying action classes.
Input data Output data
End
Start
Extensions to exchange data
with the UI-layer
Extensions to
retrieve input data
from http request
Extension of JSP with
additional input fields1)
End
Extensions to
transfer data to JSP
Extension of JSP with
additional output fields1)
Figure 43: Extensions to exchange data with UI layer
For details see:
1) ‘Extensions to the UI layer’ on page 192 and 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 307).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 179
This diagram shows how to transfer additional input data from the http request (from submitting the HTML form) to the action class and, from there, to the busines object layer.
yes
Start
Extensions to retrieve input
data from http request
Derive new action from
existing action class and
overwrite the empty user-
exit.2)
Appropriate user exit in
corresponding action class
available1)
no
Create new action class.2)
no
Create own BO and write
additional data to BO5)
The additional data can be
handled together with an
standard BO (e.g. order
or order item)
Write additional data as
extension data to standard
BO7)
yes
Write additional data to
request context6)
End
no
The additional
data can be stored as
extension data4)
yes
Register new action class
in configuration3)
Figure 44: Transfer additional input data to action class and business object layer
For details see:
1) Standard Actions providing User Exits on page 195
2) Create a Customer Action on page 193
3) Create a Customer Action on page 193
4) Depends on the question if the additional data should be transferred to a backend system and how this can be performed. See also: Storing Additional Data - Extension Mechanism on page 199
5) Create a Customer Business Object on page 202
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 180
6) Request Context on page 224
7) ’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 307).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 181
This diagram shows how to transfer additional output data in the action class to the JSP.
yes
Start
Extensions to transfer data to
JSP
yes
Derive new action class
from existing action class
and overwrite the empty
user-exit.
Register new action class
in configuration.2)
The additional data is
stored as extension data at
standard BO (e.g. order
or order item)
Appropriate user exit in
corresponding action class
available1)
no
Create new action class.
Register new action class
in configuration.2)
no
Transfer BO data to
session context3)
Extension data is
transferred to session
context together with
standard BO data
- no action required
Additional data to be
retrieved from request
context
Additional data to be
retrieved from business
object
Retrieve data in JSP from
request context 5)
End
Retrieve data in JSP from
session context.4)
Figure 45: Transfer additional output data from aciton class to JSP
For details see:
1) Standard Actions providing User Exits on page 195
2) Create a Customer Action on page 193 and Modifications in the Struts Configuration on page 199
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 182
Table 38: User exits within the Remanufacturer’s Inspection Application
Accessing the Session Context on page 197
4) Accessing the Session Context on page 192
5) Request Context on page 224
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 183
Extensions to Exchange Data with Backend-Systems
This diagram is the entry point to extensions related to exchange of additional data between the business object layer and any backend system.
Retrieve data from a
backend system
Transfer data to a
backend system
End
Start
Extensions to exchange data
with a backend system
Extensions to
exchange data with
the Web Catalog
Extensions to
exchange data with
an IPC system
Extensions to retrieve
data from a R/3
system
Extensions to retrieve
data from a CRM
system
End
Extensions to
exchange data with
Web Catalog
Extensions to
exchange data with
an IPC system
Extensions to
transfer data to a
R/3 system
Extensions to
transfer data to a
CRM system
Extensions to
exchange data with
the Java Basket
Extensions to
exchange data with
the Java Basket
Figure 46: Extensions to exchange data with the backend systems
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 184
This diagram shows how to retrieve additional data from a SAP CRM system to the business object layer.
Data is retrieved within
a standard call from the
backend system
(e.g. at order save, at
ship to read)1)
Start
Extensions to retrieve data
from a CRM system
No action required
Create new backend
class. Implement
method(s) to call function
module.5)
Data is retrieved by a
new (customer specific)
call from the backend
system
End
Derive new backend class
from standard backend
class. Overwrite method(s)
to call function module
and/or to process data.5)
Processing
with other data or
postprocessing after transfer
required
yes
no
Extension data of CRM
function module can be
used3)
Implement JCO event
listener class.6)
Write additional data to
request context.7)
no
yes
Create new business
object and new BOM.2)
Create new backend
interface.4)
Figure 47: 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 standard process flow. The function module itself does not have to be a standard function call (see Replacing Calls to Standard Function Modules (Backend System) on page 229)
2) Create a Customer Business Object on page 202 and Create a Customer Business Object Manager on page 202
3) Supported Function Modules and Business Objects on page 214 Table 47: User exits for for Pricing or Configuration
Creating new Customer Backend Object on page 210
5) Create a Customer Backend Object on page 206
6) Interception of Calls to Standard Function Modules on page 227
7) Request Context on page 224
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 185
This diagram shows how to transfer additional data from the business object layer to a SAP CRM system.
Data stored in the
request context
Data stored in a
(customer) business
object
Start
Extensions to transfer data to
a CRM system
Implement JCO event
listener class.2)
Read data from request
context3)
Create new backend
cIass. Implement method
to call CRM function
module4)
Data stored within a
standard business
object as extension data
yes
End
Call function module
in CRM system
No action required
Processing
with other data or
preprocessing before
transfer required
Extension data of CRM
function module can be
used1)
no
yes
no
Figure 48: Transfer additional data from business object layer to SAP CRM
For details see:
1) Supported Function Modules and Business Objects on page 214
2) Interception of Calls to Standard Function Modules on page 227
3) Request Context on page 224
4) Create a Customer Backend Object on page 206
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 186
This diagram shows how to call a SAP CRM system from the backend layer.
No extension of
interface or of the logic
of the standard function
module required
Extension of interface
and of the logic of the
standard function
module required
Start
Call function module in CRM
system
No extension of
interface but extension
of the logic of the
standard function
module required
Create customer function
module with extended
interface of standard
function module
Create customer
implementation of BADI1)
recomm.
concept
recomm.
concept
Create customer function
module
End
Use standard backend
object and implement JCO
event listener class3)
Use standard backend
object -
no action required
Create customer backend
object.
Register new backend
object in configuration4)
Configure BADI in CRM
Assign customer function
module and event listener
class to standard function
module in configuration3)
Create customer function
module with interface of
standard function module2)
Use standard backend
object -
no action required
Assign customer function
module to standard
function module in
configuration2)
No action required
Figure 49: Call a SAP CRM system from the backend layer
For details see:
1) Supported Function Modules and Business Objects on page 214
2) Replacing Calls to Standard Function Modules (Backend System) on page 229
3) Interception of Calls to Standard Function Modules on page 227
4) Create a Customer Backend Object on page 206; it is assumed at this point, that a customer business object and a customer BOM are already available.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 187
This diagram shows how to retrieve additional data from a SAP ERP system to the business object layer.
Data is retrieved within
a standard call from the
backend system
(e.g. at order save, at
ship to read)1)
Start
Extensions to retrieve data
from a R/3 system
Configure extension data6)
Create new backend
class. Implement
method(s) to call function
module.5)
Data is retrieved by a
new (customer specific)
call from the backend
system
End
Derive new backend class
from standard backend
class. Overwrite method(s)
to call function module
and/or to process data.5)
Processing
with other data or
postprocessing after transfer
required
yes
no
Extension data of R/3
function module can be
used3)
Implement JCO event
listener class.7)
Write additional data to
request context.8)
no
yes
Create new backend
interface.4)
Create new business
object and new BOM.2)
Figure 50: 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 standard process flow. The function module itself does not have to be a standard function call (see Replacing Calls to Standard Function Modules (Backend System) on page 229)
2) Create a Customer Business Object on page 202 and Create a Customer Business Object Manager on page 203Table 56: ABAP Extension Structure (ERP)
Supported Function Modules and Business Objects. on page 214Table 47: User exits for for Pricing or Configuration
Creating new Customer Backend Object on page 210
5) Create a Customer Backend Object on page 206
6) Modification of Communication Structures in SAP and Configuration of the Web Application on page 222
7) Interception of Calls to Standard Function Modules on page 227
8) Request Context on page 224
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 188
This diagram shows how to transfer additional data from the business object layer to a SAP ERP system.
Data stored in a request
container
Data stored in a
(customer) business
object
Start
Extensions to transfer data to
a R/3 system
Implement JCO event
listener class.2)
Read data from request
container.3)
Create new backend
class. Implement method
to call R/3 function
module5)
Data stored within a
standard business
object as extension data
yes
End
Call function module
in R/3 system
Configure extension data4)
Processing
with other data or
preprocessing before
transfer required
Extension data of R/3
function module can be
used1)
no
yes
no
Figure 51: 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 214.
2) Interception of Calls to Standard Function Modules on page 227
3) Request Context on page 224
4) Modification of Communication Structures in SAP and Configuration of the Web Application on page 222
5) Create a Customer Backend Object on page 206
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 189
This diagram shows how to call a SAP ERP system from the backend layer.
No extension of
interface or of the logic
of the standard function
module required
Extension of interface
and of the logic of the
standard function
module required
Start
Call function module in R/3
system
No extension of
interface but extension
of the logic of the
standard function
module required
Create customer function
module with extended
interface of standard
function module
Create customer function
module with interface of
standard function module1)
recomm.
concept
Create customer function
module
End
Use standard backend
object and implement JCO
event listener class2)
Use standard backend
object -
no action required
Create customer backend
object.
Register new backend
object in configuration3)
Assign customer function
module to standard
function module in
configuration1)
Assign customer function
module and event listener
class to standard function
module in configuration2)
No action required
Figure 52: Call a SAP ERP system from backend layer
For details see:
1) Replacing Calls to Standard Function Modules (Backend System) on page 229
2) Interception of Calls to Standard Function Modules on page 227
3) Create a Customer Backend Object on page 206; it is assumed at this point, that a customer business object and a customer BOM are already available.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 190
This diagram shows how to exchange additional data between the business object layer and an IPC system.
Additional data should
be transferred to the
IPC for Pricing
Additional data should
be transferred to the
IPC for configuration
Start
Extensions to exchange data
with an IPC system
End
Derive new backend
object from standard
(CRM/R/3) backend
object. Implement user
exit.1)
Derive new backend
object from standard
(CRM/R/3) backend
object. Implement user
exit.1)
Figure 53: Exchange additional data between business object layer and an IPC system
For details see:
1) Standard Backend Objects providing User Exits on page 206
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 307).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 191
This diagram shows how to exchange additional data with the web catalog.
Additional product/
hierarchy attributes
should be transferred
from R/3 system at
initial catalog load
Additional product
attributes should be
retrieved from the web
catalog
Start
Extensions to exchange data
with the Web Catalog
Additional product
attributes should be
transferred for catalog
search
End
Copy standard function
module for catalogue data
read and implement
extensions1)
Create new backend
object from BasketJDBC
to transfer additional data
to extension data3)
Add additional search
attributes in configuration2)
Additional product/
hierarchy attributes
should be transferred
from CRM system at
initial catalog load
No action required
Figure 54: 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 233 and New Fields in the Web Catalog (SAP ERP Backend and TREX) on page 234
2) Show Additional Keys for Extended Search in B2B on page 233
3) See note 684119 (for ISA ERP) and ‘Extensions to Exchange Additional Data’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 307).
For displaying additional data in web catalog, see Show Additional Attribute in Product List on page 231 and Show Additional Attribute in Product Details and in Compare Products on page 232
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 192
This diagram shows how to exchange additional data with the Java basket.
Additional data is
attached as extension
data to the basket
header or to the basket
item
Additional data is
attached as extension
data to other business
objects
Start
Extensions to exchange data
with the Java Basket
End
Extension data is
automatically transferred
with the header or with the
item of the Java Basket -
no action required.1)
Derive new backend
object from standard
(JDBC or DB) backend
object.2)
Overwrite method to
exchange extension data.
Figure 55: Exchange additional data with the Java basket
For details see:
1) Java Basket-Extensions on page 224
2) Create a Customer Backend Object on page 206
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 193
Extensions to the UI layer The 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 to web application
Replacing existing Mimes
No
Changing text displayed on the screen
On JSP
In language dependent resource files
No
Changing colors On JSP
In cascading style sheets
No
Replacing existing JSP Register new JSP in Struts configuration file
(config.xml)
Depending on the functions of the new JSP, changes in other layers 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 enter additional data. Such changes are in most cases not limited to just the UI layer.
Accessing the Session Context
In order to access the UserSessionData object from the JSP you have to do the following:
Accessing the Request Context
For information about how to access the RequestContext within a JSP refer to chapter 'Request Context' on page 224.
Extensions in the Action Flow The action flow is realized using the STRUTS framework. In order to get/display additional data on the UI it is often 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());
%>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 194
Figure 56: Action flow with CustomActions
Create a Customer Action
You would like to modify a specific interaction within the application. A reason for doing this could be that you want to perform some additional checks that are not part of the original Actions before you continue with the process flow. Or you are modifying a dispatcher Action (for example
MaintainBasketDispatcherAction) and extending its functions.
When you extend existing Actions you usually overwrite one of the methods provided by the base Action and provide 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 ISA functions (for example, you extend the functions of Internet Sales without using current
functions). 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 Sales
application 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 the com.sapmarkets.isa.isacore.action.EComBaseAction, either directly or indirectly (through other class inheritance).
Depending on the type of modification, you can use different possible base classes for your Action in the Extended Complaints and Returns application:
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 business
object manager which handles several business objects such as user, business partner manager, delivery, recall, generic search, etc.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 195
com.sap.eservice.common.action.CommonControlAccessBaseAction
o Inherit from CommonBaseAction; checks whether the user is properly logged in before
proceeding to the execution of the action
com.sap.eservice.crb2b.action.EserviceBaseAction
o Inherit from CommonBaseAction; gives access to the Eservice business object manager
which 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 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 manager
which handles several business objects: complaint, complaint dynamic fields, complaint items list.
com.sap.eservice.crb2b.action.ComplaintControlAccessBaseAction
o Inherit from ComplaintBaseAction; checks whether the user is properly logged in before
proceeding 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 business
object manager which handles several business objects such as user, business partner manager, delivery, recall, generic search, etc.
com.sap.eservice.common.action.CommonControlAccessBaseAction
o Inherit from CommonBaseAction; checks whether the user is properly logged in before
proceeding 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 properly
logged 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 manager
which handles several business objects: complaint, complaint dynamic fields, complaint items list.
com.sap.eservice.crb2b.action.ComplaintControlAccessBaseAction
o Inherit from ComplaintBaseAction; checks whether the user is properly logged in before
proceeding to the execution of the action
com.sap.eservice.srvconfirmations.action.ConfirmationBaseAction
o Inherit from CommonBaseAction; gives access to the Confirmation business object
manager.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 196
com.sap.eservice.srvconfirmations.action.ConfirmationControlAccessBaseActi
on
o Inherit from CommonControlAccessBaseAction; gives access to the Confirmation
business object manager and checks whether the user is properly logged in before proceeding to the execution of the action
Standard Actions providing User Exits
Some action classes already provide user exits in the form of predefined, but empty, methods. For extensions only the existing empty methods have to be implemented in a new action class derived from the standard action class. The advantage of predefined user exits is that extensions or changes in the standard action 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 the shopping basket and sales documents similar to the basket.
customerExitParseRequestHeader Modify the header data; called after the header data is parsed from the request.
customerExitParseRequestItem Modify the item data; called after the item data is parsed from the request.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainBasketDeleteItemAction Action to delete an item from the current document.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainBasketReplaceItemAction Action to replace an item of the basket with another one during the cross- and upselling process.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainBasketNewShiptoAction Action to add a new ship to to a document.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainBasketDispatcherAction Action to dispatch all requests coming from the order.jsp to different (specialized) actions.
customerExitDispatcher Set forward; called after standard forward is determined.
customerExitParseRequestHeader Modify the header data; called after the header data is parsed from the request.
customerExitParseRequestItem Modify the item data; called after the item data is parsed from the request.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
Table 34: User exits within the Basket
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 197
Order
Class / Methode Description
MaintainOrderBaseAction Base action for all actions providing functions to manage the shopping basket and sales documents similar to the basket.
customerExitParseRequestHeader Modify the header data; called after the header data is parsed from the request.
customerExitParseRequestItem Modify the item data; called after the item data is parsed from the request.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainOrderReplaceItemAction Action to replace an item of the order with another one during the cross- and upselling process.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainOrderNewShiptoAction Action to add a new ship to to a document.
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainOrderSendAction Action to perform the final step in the processing of a document (i.e. to save it in the backend).
customerExitParseRequest Modify the document; called after the header and item data are parsed from the request.
MaintainOrderDispatcherAction Action to dispatch all requests coming from the order_change.jsp to different (specialized) actions.
customerExitDispatcher Set forward; called after standard forward is determined.
Table 35: User exits within the Order
OCI (Open Catalog Interface) (interface to external catalogs)
Class / Methode Description
OciGetCatalogURLAction Action which retrieves the URL from the external catalog.
customerExitDispatcher Set forward; called after standard forward is determined.
customerExitGetOCIURL Modify URL to external catalog (e.g. add user data).
OciReceiveAction Action for receiving items via the OCI.
customerExitDispatcher Set forward; called after standard forward is determined.
userExitCheckRequest The result of the standard method „checkRequest’ can be modified.
userExitModifyItemListBefore ConvertRequest
Read additional data from OCI message.
userExitModifyItemListBeforeAddToBasket
Read additional data from OCI message.
Table 36: User exits within the OCI
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 198
As in the Internet Sales application, some action classes provide user exits in the form of predefined, but empty, methods.
Extended Complaints and Returns Application
Class / Method Description
ComplaintEntryBaseAction Base action for all actions providing functions to manage the entry of complaints and returns.
customerExitParseRequest This method is called when the update of a whole document is invoked, either when the user presses the “update” or “send” button on the complaint entry or return entry. It is called before the 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 the complaint entry or return entry. It is called before the header is actually updated in the CRM system.
customerExitParseRequestItem This method is called when the update of an item is invoked when the user presses “update” or “send” on the complaint/return main entry page, the complaint/return item entry or complaint/return item resubmission. It is called before the item is actually updated in 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 to create an inspection confirmation.
customerExitParseRequest This method is called when the user submits an inspection, before the inspection is actually created in the CRM system.
Table 38: User exits within the Remanufacturer’s Inspection Application
Accessing the Session Context
In most cases you need to access the session context from Actions. The base class of your Actions
com.sap.isa.core.BaseAction provides methods enabling you to communicate with the session
context.
Within the ISA framework you are only allowed to communicate with the session using the
com.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(String
name) and setAttribute(String name, Object object).
// get user session data object
UserSessionData userSessionData =
UserSessionData.getUserSessionData(request.getSession());
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 199
Accessing Business Objects from Actions
Actions act as a mediator between the HTTP world and the BO Layer. Business Objects do not know anything about HTTP. Actions are responsible for retrieving data from the HTTP-based environment and passing 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 the following 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 can get a reference to the Business Object Manager, which manages the Business Object you are interested in:
o The next step is to get a reference to the Business Object Manager. The easiest, and
recommended, way is to use the convenience method getBOM() of the
UserSessionData class:
If your base class is com.sap.isa.isacore.action.IsaCoreBaseAction you get passed the
reference to the Business Object Manager in the isaPerform() as a parameter (please see
JavaDoc).
Now you can use the reference to the BOM to get a reference to a Business Object or to create a Business Object:
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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 200
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 be
reused within the Action as often as required. These references should never be passed onto other Actions via the session context, since this would undermine the purpose of the Object Manager. This rule forces every Action to retrieve the Business Objects using the technique described above.
Accessing the Request Context
For information about how to access the RequestContext within an JSP refer to chapter 'Request Context' on page 224.
Modifications in the Struts Configuration
Modifications 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 is
located in <esrv>\web-inf\struts-config.xml.
Version
This feature is available in all versions of E-Commerce.
Example
See ‚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 chapter References on page 307).
Business Object Layer
Storing Additional Data - Extension Mechanism
This modification concept uses the previously mentioned extension mechanism that enables you to store any data in a Business Object. The base class of each Business Object provides this mechanism.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 201
Additionally, this data can be passed transparently to the backend system. This is the preferred extension concept when you have to pass data between the Business Object and the SAP CRM or the SAP ERP system. For further information on this concept please refer to chapters BADIs/SAP CRM Extensions on page 213 or BAPIs/SAP ERP-Extensions on page 219.
Use only string objects with the extension data, if you want to automatically transport this data to the backend using the Extension mechanism (see BADIs/SAP CRM Extensions).
Figure 57: BOBase class
Each Business Object extends the com.sap.isa.core.businessobject.BOBase class. This base
class provides the following methods to store any data:
Method Name Function
addExtensionData(Object key, Object name) Stores any data within the Business Object.
Object getExtensionData(Object key) Retrieves extension data associated with the Business Object.
getExtensionDataValues() Retrieves all extension data associated with the Business Object.
removeExtensionData(Object key) Removes extension data from the Business Object.
Table 39: Methods of the BOBase class
Version
This feature is available in all versions of Internet Sales.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 202
Example
Storing additional data in the basket Business Object:
Retrieving extended data:
Extending existing Business Objects
You use this extension concept when you want to add functions to an existing Business Object, or if you want to replace the functions of an existing method with your own implementation. In either case, you have to derive from the existing Business Object and extend/replace its functions.
Figure 58: Derive own class from existing Business Object
Since every Business Object is accessed via a Business Object Manager, you have to extend the BOM that manages the Business Object you have extended. In order to make the new version of the Business Object available for use, you have to overwrite the get/create method of the BOM that creates this Business Object.
Figure 59: 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);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 203
The new modified version of the BOM creates an instance of the new Business Object. The return value must 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:
Version
Own 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 and Remanufacturer’s Inspection.
Create a Customer Business Object
There 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 customer extensions. Function modules are called within Backend Objects and there is always need of a corresponding Business Object
BOBase
+addExtensionData()
+getExtensionData()
+removeExtensionData()
Z_CustomFunc
+getInfo()
Figure 60: 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();
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 204
Z_CustomFunc
+getInfo()
Z_CustomBusinessObjectManager
+ getCustomFunc()creates
DefaultBusinessObjectManager
Figure 61: 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 is
identified 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 implement com.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 the
businessobject package. If you have a lot of custom Business Objects, create a deeper
package structure that reflects the business functions provided by your custom business objects.
Version
This feature is available in all versions of Internet Sales.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
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 307) provides you a template you can use for your own projects when writing own Business Objects, Business Object Managers and Backend Objects.
Create a Customer Business Object Manager
A Business Object Manager usually has a method to generate a BO (createXX), a method to interrogate
existing 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 not
already 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 been
generated with createXX.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 205
The createXX, getXX, and releaseXX methods must be re-implemented for new BOs, whereby XX is
replaced by the exact name of the BO class in question. If the class is called User, for example, one method
is created with the signature User getUser(), one with the signature User createUser(), and one
with 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 also
implement 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 to be 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 62: Creating interface for Business Object
To make it easier to develop Business Object Managers, you can use the
GenericBusinessObjectManager as a base class for your own Business Object Manager. This class
can 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 generic methods 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 63: Creating own Business Object Manager
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 206
After implementing a BOM, you have to register it in the customer version of the bom-config.xml file and
add an entry to it for the new manager.
The file is located in WEB-INF\xcm\customer\modification\bom-config.xml:
Version
This feature is available in all versions of Internet Sales.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
<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;
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 207
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 307) provides you a template you can use for your own projects when writing own Business Objects, Business Object Managers and Backend Objects.
Business Logic Service Layer Many Business Objects (e.g. basket) in the Business Object layer have a corresponding Backend Object 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 (for example:
BasketCRM).
Customizing of the Java part is often related to changes in the SAP CRM system. Additional functions can be provided 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 Object
You would like to enhance a specific processing step within the application. A reason for doing this could be that you want to perform some additional checks that are not part of the original processing, before you continue with processing. Or, you want to add additional data before you continue with processing. Or, you want 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 add additional Methods.
Overwrite customer exits
The Backend Object is needed for a customer Business Object and can not be derived from a standard Backend Object:
Standard Backend Objects providing User Exits
Some 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 backend object class derived from the standard backend object class. The advantage of predefined user exits is that extensions or changes in the standard backend object classes by SAP within support packages or future releases are aware of these user exits:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 208
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.xml
configuration file. For further information refer to 'Changes in backendobject-config.xml' on page 277
Call IPC for Pricing (ISA CRM)
Class / Methode Description
PriceCalculatorInitDataCRMIPC Price calculator for the SAP CRM backend. It determines list/scale prices from catalog attributes, as well as dynamic prices through IPC, based on the settings in the web shop.
customerExitBeforeIpcDocument Create
Called after preparing the IPCDocumentProperties, but before creating the document in IPC. Overwrite this method if you want to add or modify document properties, for example to pass additional attributes to the document.
customerExitAfterIpcDocument Create
This exit is called after creating the IPCDocument. Overwrite this method if you want to change the IPC document in some way.
customerExitBeforeIpcItemsCreate This exit is called after preparing the IPCItemProperties, but before creating the items in IPC. Overwrite this method if you want to add or modify item properties, for example to pass additional attributes to the item.
customerExitAfterIpcItemsCreate This exit is called after creating the IPCItems. Overwrite this method 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 Prices object which is then returned. Overwrite this method if you want to subclass PriceInfoIPC, and use your subclass.
customerExitGetPriceType This exit is called for PriceType determination. When the PriceCalculator is initialized, the price types used are read from eai-config.xml. For each String in that list, this method is called and it returns a PriceType object.
Table 40: User exits for IPC for pricing
IPC-Basket (ISA CRM)
Class / Methode Description
BasketIPC Basket implementation for IPC
customerExitAfterAddBusiness PartnerInBackend
This method provides the possibility to extend or modifiy the IPC document. The exit is called within the method
addBusinessPartnerInBackend when a user has
already logged on, and after the basket has been created.
customerExitSetDocumentProperties This method provides the possibilty, to easily extend the document properties of a sales document according to special customer requirements. The exit is called within the
method createInBackend when a basket is created, but
before the IPC-document is created.
Table 41: User exits for IPC basket
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 209
Class / Methode Description
customerExitSetItemProperties This method provides the possibilty, to easily extend the item properties of a sales document according to special customer requirements. The exit is called within the method
update(BasketData) when a new item is created, but
before an IPC item is created.
Table 42: User exits for IPC basket
Order and Order Status (ISA ERP)
Class / Methode Description
CreateStrategyR3 Algorithms for creating and simulating an order. Both tasks are done with the function module SD_SALESDOCUMENT_CREATE.
performCustExitBeforeR3Call This method can be used to set additional tables or table fields before the function module SD_SALESDOCUMENT_CREATE is called.
performCustExitAfterR3SimulateCall This method can be used to set additional tables or table fields after the function module SD_SALESDOCUMENT_CREATE is called. It is called after the ISA sales document has been filled with the function module data.
ChangeStrategyR3 Algorithms used for sales document change.
performCustExitBeforeR3Call This method can be used to set additional tables or table fields before the function module SD_SALESDOCUMENT_CHANGE is called
performCustExitAfterR3Call This method can be used to modify the ISA sales document after the function module SD_SALESDOCUMENT_CHANGE is called. It is called only if no error messages from have been returned and after re-reading the ISA sales document from ERP.
DetailStrategyR3 Contains the algorithms for reading an entire sales document from ERP.
performCustExitBeforeR3Call This method can be used to set additional tables or table fields before the function module BAPI_ISAORDER_GETDETAILEDLIST is called.
performCustExitAfterR3Call This method can be used to set additional tables or table fields after the function module BAPI_ISAORDER_GETDETAILEDLIST is called. It is called after the ISA sales document has been filled with the function module data.
Table 43: User exits for Order and Order Status
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 210
Class / Methode Description
ReadStrategyR3 Contains base functionality for transferring data from function module tables to the ISA sales document that is used from all other algorithm groups. For example reading the item and schedule line info is used from all strategies that deal with order change simulation, order change, order read and order create simulation.
setUpMessageMap List of ERP messages which are raised by function modules when simulating or saving orders and which should be displayed on the UI or should be ignored (in case of error messages). See notes 640735 and 641132.
Table 44: User exits for Order and Order Status
Web Catalog (Memory Catalog) (ISA ERP)
Class / Methode Description
R3CatalogServerEngine Memory Catalog.
performCustomerExitAfter CatalogRead
Called after the catalog has been set up. Can be used to e.g. attach additional attributes to the catalog. This customer exit is only called for the standard main memory implementation.
Table 45: User exits for Web Catalog
See also: Extension of the Web Catalog on page 231.
Call IPC for Pricing or Configuration (ISA ERP)
Class / Methode Description
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 been created. This customer exit can be used to set the context if reference characteristics are involved.
customerExitBeforeItemCreation Customer exit that is called before an array of IPC items are created.
customerExitAfterItemCreation Customer exit that is called after an array of IPC items has been created. This customer exit can be used to set the context if reference characteristics are involved.
customerExitBeforeHeaderAttributeCall Customer exit that is called directly before ISA_PRICING_HDRDATA_GET is called. Can be used to set additional parameters in table EXTENSION_IN.
Table 46: User exits for for Pricing or Configuration
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 211
Class / Methode Description
customerExitBeforeItemAttributeCall Customer exit that is called directly before ISA_PRICING_ITEM_ATTRIBUTE is called.
Can be used to set additional parameters in table EXTENSION_IN.
Note that the backend context is available here with e.g. the shop customizing.
Only relevant for the non-TREX case.
Table 47: User exits for for Pricing or Configuration
Creating new Customer Backend Objects
When 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 your
implementation from the com.sap.isa.core.eai.sp.jco.
BackendBusinessObjectBaseSAP class.
Stateless classes should use IsaBackendBusinessObjectBaseSAP as in this case the
correct logon language is used in the connection.
Within the Backend Object implementation, communicate with the backend system using the connection management provided by the BLS layer
Add configuration information to the customer version of the backendobject-config.xml
configuration 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 backend system.
Design Considerations when Creating Backend Object Interfaces
If you need to access data located in the Business Object layer you should not pass the reference of the business object to the backend object, but instead use a data access interface instead. This interface should provide all necessary access methods. Place the data interface in the same package as the Backend Object interface.
public interface Z_CustomFuncBackend extends BackendBusinessObject {
public String getInfo();
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 212
Create an Implementation of Backend Object
Write an implementation for the interface of the Backend Object. Use the
BackendBusinessObjectBaseSAP class as the base class for backend objects communicating with an
SAP system using the SAP Java Connector.
Register Backend Object in backendobject-config.xml
The backend object has to be registered in the customer version of backendobject-config.xml using
XCM extension mechanism:
Accessing Backend Objects from Business Objects
If Backend Objects need access to the BLS layer they have to implement the
com.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’
connectionFactoryName=‘JCO’
defaultConnectionName=‘CRMStateless’>
<params>
<param name=‘myinit’ value=‘myvalue’/>
</params>
<businessObject/>
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’);
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 213
The Backend Object Manager is assigned to the Business Object within the
assignBackendObjectManager().
Having a reference to the Backend Object Manager enables the Business Object to create a instance of a
backend object using the createBackendBusinessObject(String backendObjectType) method.
The value of backendObjectType corresponds to the value of the type XML element within the backendobject-config.xml
Version
This feature is available in all versions of Internet Sales.
<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;
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 214
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
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 307) provides you a template you can use for your own projects when writing own Business Objects, Business Object Managers and Backend Objects.
BADIs/SAP CRM Extensions
This section describes a solution for modifying Business Objects without modifying the standard backend implementation, with SAP CRM as the backend system. This means that you can extend the standard Business Objects with your own data without changing anything in the Business Object and BLS layer. You only 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 the BADIs 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 the
backend.
To extend a Business Object with your own fields, you need to implement a BADI in SAP CRM, where the fields are filled in extension structures as name value pairs. After that you can access the field using the key from the extension in the Java layer. The extensions in the Java layer are also key value pairs that are assigned 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 the extension structure in SAP CRM as a modification of your function modules in this ‘pre BADI’ period. After the 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 the JDBC backend objects and DB basket.
As in the Internet Sales application, the E-Service Extended Complaints and Returns application provides some 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 (type CRMT_ISALES_EXTENSION_INT). For those function modules, this data extension structure can be processed in the CRM system by implementing the BADI definition. Note that some function modules do not use 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 the java application. It also lists the BADIs method where your processing can be inserted. If there are no business objects, it means that the data structure extension is not used as parameter for the function module.
Note that the Complaint business object handles both complaints and returns. The separation of complaints and returns is merely done on the user interface only: the process, and as a consequence, the business objects, backend objects and ABAP function modules are basically the same.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 215
Version
This 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 Structure
Field 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 business
objects 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 the
guids are normally generated from the backend, the guids are empty when new entries are created. In this case, the handle is filled and, with it, you can associate the extension with the related item.
Supported Function Modules and Business Objects
Order
Function 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
User
Function 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 216
Contract
Function module Business object
CRM_ISA_CNT_GETCONTRACTS ContractHead ContractItem
Table 51: CRM - Supported Function Module / Business Object - Contract
Shop
Function 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 217
Reading data from the Backend
If you are reading additional fields from the backend you have to fill the extension tables properly. Here are some 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 218
Writing data to the backend
This case is little bit more complex, since we have a problem with the table-like structure at creation point. In this 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 219
Enhancements for the Dynamic UI of ECO B2B
The dynamic UI of ECO B2B enables the customer to hide or disable fields on the order screens of the ECO B2B application dynamically. It is based on the CRM Sales Order Override concept and the Dynamic Field Control 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 order processing 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 and assign fields to them (IMG: CRM -> Basic Functions -> Authoritizations). These authorization groups can be incorporated to the user’s authorization within the authorization object CRM_FLDCHK. Calling the CRM function module CRM_ORDER_FIELDCHECK the changeability of the order fields are determined depending 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 or change attributes of the fields must be determined separately.
The field attributes of order data are determined in the CRM via the function module CRM_ORDER_FIELDCHECK and transferred to the table parameter HEADER_STATUS_CHANGEABLE of the function module CRM_ISA_BASKET_GETHEAD and the parameter ITEM_STATUS_CHANGEABLE of the function module CRM_ISA_BASKET_GETITEMS.
Thus for the customer fields it is necessary to implement the corresponding methods GET_HEAD_FROM_IL of BADI CRM_ISA_BASKET_HEAD for the order header and GET_ITEMS_FROM_IL of BADI CRM_ISA_BASKET_ITEMS for the order items. The BADI implementations should perform the CRM_ORDER_FIELDCHECK for these fields and the results need to be transferred to the table parameter CT_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, a corresponding message will notice the user, that additional field(s) are available. In order to be able to determine, if a visible field was hidden before the last update, it is necessary to store the hidden fields in a temporary 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 used transation type. If this feature should be supported for the additional item fields as well the following enhancements are necessary in the above mentionded BADI for the order items.The relevant item categories can be determined by calling the function module CRM_ORDER_IT_ASS_SEL_PROC_CB. For every item type and object the function module CRM_FIELDCHECK_TOOL identifies the field attribute regarding the user’s authorizations. Finally the table parameter CT_FIELD_CHANGEABLE needs to be assigned to a new entry for each item field with an initial value for the component ITEM_GUID and PARENT_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 mapping of the CRM field name to the UI Element of the additional fields needs to be entered in the UI element definition in the XCM file uicontrol-config.xml. Thus the display attribute of the UI element will be adopted generically from the table parameter HEADER_STATUS_CHANGEABLE respectively ITEM_STATUS_CHANGEABLE. For the item fields the label of the items needs to be assigned to the description fields of the UI element in order to enable the display the field labels of the additional fields.
Example
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 220
BAPIs/SAP ERP-Extensions
This section describes a solution for modifying Business Objects without modifying the standard backend implementation, with SAP ERP as the backend system. This means that you can extend the standard Business Objects with your own data without changing anything in the Business Object and BLS layer. You only 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 the ABAP extension structure in the SAP ERP BLS layer.
Use String objects when storing extension data, if you want to access this data from the
backend.
To extend a Business Object with your own fields, you need to implement the corresponding append structures 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 the web application. After that you can access the field using the key from the extension in the Java layer. The extensions in the Java layer are also key value pairs that are assigned to the corresponding Business Objects.
Version
This feature is available in all versions of ISA 5.0.
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 221
VALUEPART1 VALUEPART Extension data (240 characters).
VALUEPART2 VALUEPART Extension data (240 characters).
VALUEPART3 VALUEPART Extension data (240 characters).
VALUEPART4 VALUEPART Extension data (240 characters).
Table 56: ABAP Extension Structure (ERP)
Supported Function Modules and Business Objects.
Order
Function 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 ‘
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 222
Generic Search Framework’ (page 101).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 223
Modification of Communication Structures in SAP ERP
In contrast to the BADI/SAP CRM extension concept, where additional data are transferred by name/ value pairs, in the BAPI/SAP ERP extension concept only values of additional data are transferred. The sequence of data, as well as the data length of the individual data fields within the extension structure BAPIPAREX, is defined 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 be transferred between the extension structure and the data structures in SAP ERP. By default, data is transferred 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 to
the ERP data structure VBKD also parameter structure and/or structureitem has to be changed in the
configuration backendobject-config.xml (see bellow).
If the data should be transferred to other data structures in SAP ERP you have to implement an additional form routine for data transfer (see below).
Configuration of the Web Application
Corresponding to the SAP ERP system, you have to define the data definition of the communication
structure in ISA, in configuration backendobject-config.xml (see Changes in backendobject-config.xml
on page 277), 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 224
Reading Data from the Backend
If the additional data should be read from the default data structure (see above), no further activities are necessary.
Only character type data can be transferred through this mechanism, binary data has to be converted before transfer.
If the additional data should be read from a different data structure, an additional form routine for data transfer has to be implemented, as shown in the following example:
Writing Data to the Backend
If the additional data should be transferred to the default data structure (see above), no further activities are necessary.
The extension structure can only used for character type data, binary data in the data structure has to be converted before transfer.
If the additional data should be transferred to a different data structure, an additional form routine for data transfer 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.
CATCH SYSTEM-EXCEPTIONS CONVERSION_ERRORS = 1.
MOVE WA_BAPE_VBAK TO EXTENSION_OUT+30.
ENDCATCH.
MODIFY EXTENSION_OUT INDEX TABLE_TABIX.
ENDIF.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 225
Example
Chapter ‘Extensions Demo 5 – Maintain Delivery Block Indicator in ECO ERP’ of the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 307).
Java Basket-Extensions
This section describes a solution for modifying Business Objects without modifying the standard backend implementation, with the Java basket as the backend system. This means that you can extend the standard Business 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 only possible for extension data attached to the basket header or to the basket items. Extension data attached to other business objects, for example the ship to have to transfered manually by extending the corresponding standard backend objects.
Version
This feature is available in all versions of ISA 5.0.
Example
(no example available)
Request Context The request context is a container enabling you to easily exchange data between layers in an Internet Sales application. The context is accessible from nearly everywhere within the ISA framework, making it a very powerful way to exchange data. Using the request context violates some rules defined for standard ISA development. 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.
CATCH SYSTEM-EXCEPTIONS CONVERSION_ERRORS = 1.
MOVE EXTENSION_IN+30 TO WA_BAPE_VBAK.
ENDCATCH.
ENDIF.
MOVE _BAPE_VBAK-ZZPMNTTRMS TO ORDER_BUSINESS_IN-PMNTTRMS.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 226
JSP RequestContext.getRequestContext(request)
Action getRequestContext()
Business Object getRequestContext()
Backend Object getBackendObjectSupport().getRequestContext()
Function Module execution listener
Within the connectionEvent(JCoConnectionEvent event)method of a
function module execution listener (com.sap.isa.core.eai.sp.jco. JCoConnectionEventListener)
event.getRequestContext()
For further information about execution listeners refer to chapter 'Interception of Calls to Standard Function Modules' on page 227.
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 Request Context
For more information about the Request Context refer to the Java Doc of com.sap.isa.core.RequestContext
The scope of the request context is one request (usually one HTTP request). After the request is finished the context is cleared. If you want to store data between requests use the Business Object layer or use the session context instead.
Version
This feature is available in CRM ISA 5.0.
Example
This 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 the JSP:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 227
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 when
the function module is executed.
For information how to work with function module execution listeners refer to chapter 'Interception of Calls to Standard Function Modules' on page 227.
Adding additional Function Modules (Backend System) Function modules are accessed by Backend Objects. If you have to access your own custom function modules you usually do it by writing a Backend Object. Backend Objects are accessed by Business Objects via 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);
}
}
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 228
Figure 64: 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 new functions.
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 202
'Create a Customer Backend Object' on page 206
Version
This feature is available in all versions of ISA 4.0.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
Interception of Calls to Standard Function Modules This concept allows you to intercept calls to remote callable function modules in a SAP CRM or SAP ERP system, 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 Standard Function Modules (Backend System)' on page 229.
The basic idea behind this concept is to register a Java event listener, which is notified before/after a function module is called. The listener can be used to manipulate the function call, and has access to the RequestContext, meaning that it can communicate with other parts of the application (Action, JSP, Business Object, Backend Object).
The following diagramm shows the how this concepts works at runtime:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 229
BLS Connection
Management
Standard ISA
class
Customer execution
listener
execute
JCO.Function
notify before
execution
Retrieve data from Request
Context if needed
Pass additional data to
function module if needed.
CRM
or R/3
execute
JCO.Function
notify after
execution
Retrieve data from function
module if needed. Pass data
to Request Context if
neededreturn
JCO.Function
Figure 65: Java event listener for Standard Function Modules
This concept can also be used to extend the interface of an existing function module with optional parameters and pass/retrieve additional data. Nevertheless, this extension concept should only be used when the function module, which you would like to extend, has no extension table (see 'chapter BADIs/SAP CRM Extensions' on page 213).
Please keep in mind, when you extend these interfaces, that the interfaces of existing function modules can change with subsequent releases of ISA. It is also possible that the function module will be replaced in subsequent releases.
A common modification is the addition of optional parameters to the interface of the function module. In this case 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. You
can 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 to
provide/retrieve additional data from other layers of the application (Action, JSP, Business Object, Backend Object).
Within the event you have access to the JCO.Function, which is called. This gives you the opportunity to
provide/retrieve additional data in your optional parameters.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 230
Thread Safety in Execution Listeners
Please note that every listener has configuration scope! That means that you shouldn’t define instance variables 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.
Version
This feature is available in all versions of ISA 5.0.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
What to Do
The following steps describe the tasks you have to perform:
1. Write an execution event listener by implementing the
com.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 a
function module is executed. Within this method you have the follwing possibilites:
o You can find out which function module has been called by calling event.getJCoFunction().getName()
o You can find out if this is an event before, or after, the function call by retrieving the event id
event.getId(), and comparing with event.AFTER_JCO_FUNCTION_CALL or event.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 data after the module has been called. Within the event handler method you have full access to
the JCO.Function object.
Example
For 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 chapter References on page 307).
Replacing Calls to Standard Function Modules
<function-module-listener>
<param
name=‘fmevent:NAME_OF_FUNCTION_MODULE’
value=‘ClassNameEventListener’/>
</function-module-listener>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 231
(Backend System) This concept allows you to replace calls to remote callable function modules in a SAP CRM or SAP ERP system without changing the Java coding provided.
You can use this extension concept to let the application call your function modules, instead of the standard function modules.
Prerequisite is that the interface of your function module is compatible with the interface of the standard function module called by ISA, that means your function module can only provide additional parameters but you 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 Connection
Management
Standard ISA
class
getJCoFunction
Z_Function in
CRM
or R/3
return Z_Function having
same or compatible
interface as standard function
Check if
replacement function
was registered in
backendobject-config.xml
fill import parameters
and tables execute Z_function
perform
operations
Standard
Function
call standard
perform
operations
return function
Figure 66: Replacing calls to Standard Function Modules
Version
This feature is available in all versions of ISA 5.0.
It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection.
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)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 232
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
Example
See Customer Specific Views in the Web Catalog (SAP ERP Backend and TREX) on page 237
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 add the attribute in product catalog maintenance in SAP CRM and adapt the JSPs accordingly.
Preparation
Create a catalog, variants, shop, and so on in SAP CRM. Go to catalog maintenance and add a list of characteristics to the catalog that contains the attribute you want to add. For this example, please add an
attribute Z_COLOR, for the color of the product. Ensure that this attribute is maintained for the products in
your 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 in
your language resource file ISARessources.
Show Additional Attribute in Product List
Only 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> is responsible for the table headings. For the new attribute, we need an additional heading in the area between these.
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 233
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 the description, so we also need to put the content after the content of the description. The content of the description 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 for each contract. Our attribute is valid for the product in general and therefore the table cell should span over these contract lines too.
Show Additional Attribute in Product Details and in Compare Products
There 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 that
have a non empty description and their names conatin a “_“ (item.getAttributeDescription() !=
null && item.getAttributeName().indexOf("_") != 0) are shown, or all catalog-specific
attributes that have a resource key corresponding to the pattern
catalog.isa.attribute.<attribute_name> are shown. This means, if an additional catalog specific
attribute Z_MyAttribute should be displayed, an appropriate resource key has to be added to the
ISAResource 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 234
Show Additional Keys for Extended Search in B2B
The extended search is done with respect to catalog-specific attributes. By default, only the OBJECT_ID and
OBJECT_DESCRIPTION attributes are taken into consideration. However, it is very easy for
bigSearch.jsp to display new search keys. Each attribute that has a resource key corresponding to the
pattern 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 and Memory Catalog) This unit describes how additional attributes can be transfered from the SAP ERP system to the ISA product catalog, using the memory catalog. In addition to the extensions described in this unit, the ISARessource file has 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, the appropriate JSP has to be extended as for ISA CRM.
Loading additional Product Attributes from the SAP ERP Backend to the Memory Catalog
Additional product attributes can be transferred from the SAP ERP Backend to ISA using a predefined
customer exit performCustomerExitAfterCatalogRead in the class
com.sap.isa.backend.r3.catalog.R3CatalogServerEngine. The method is shipped empty and
called after reading the catalog. The parameters of the method are the catalog and a JCO connection to the SAP ERP system. In the method additional data can be read from the SAP ERP system and added to the catalog.
The following steps have to be performed:
1. Create a new class extending
com.sap.isa.backend.r3.catalog.R3CatalogServerEngine.
2. Implement the method performCustomerExitAfterCatalogRead. Use the JCO connection
provided as call parameter to read additional information from SAP ERP, if necessary, and add the results to the catalog object.
3. Register your individual class instead of
com.sap.isa.backend.r3.catalog.R3CatalogServerEngine in with the ISA extension
concept as described in ‘ Changing existing Backend Object’ on page 277.
Version
This feature is available in all versions of ISA 5.0.
Example
See note 610393.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 235
New Fields in the Web Catalog (SAP ERP Backend and TREX) This unit describes how additional attributes can be transferred from the SAP ERP system to the ISA product catalog, using the TREX. In addition to the extensions described in this unit, the ISARessource file has be extended as for ISA CRM for display the additional attributes in the product detail of the web catalog, and for searching in the catalog. If the attributes should be displayed in the product list of the web catalog, the appropriate JSP has to be extended as for ISA CRM.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 236
Loading additional Product Attributes from the SAP ERP Backend to the TREX
Additional products attributes can be transferred from the SAP ERP Backend to TREX by using the methods
ATTRIBUTE_NAMES_GET and NODE_GET_ATTRIBUTE_VALUES of class
CL_ISA_REPLICATION_CATALOG. The first method is used to define the names and types of the attributes
on TREX, the second method is called for every catalog area and item to add values for the additional attributes. The methods are delivered empty in the standard class and have to be redefined in a customer
class inheriting from CL_ISA_REPLICATION_CATALOG. The usage of the new class is controlled by the
BAdI BADI_ISA_REPL_CAT.
The following steps have to be performed:
1. Use the class builder (transaction SE24), to create a new class named ZCL_ISA_REPLICATION_CATALOG
inheriting from CL_ISA_REPLICATION_CATALOG (use the button “Define inheritance” next to the file name
in the creation dialog).
2. Redefine the methods IF_ISA_REPLICATION_CATALOG~ATTRIBUTE_NAMES_GET and
IF_ISA_REPLICATION_CATALOG~NODE_GET_ATTRIBUTE_VALUES. See the example below for
further details.
3. Create a new implementation for BAdI BADI_ISA_REPL_CAT. The BAdI implementation is used to return an
instance of your catalog class instead of the standard class. The standard implementation
ISA_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.
Version
This feature is available in all versions of ISA 5.0.
Example
This example shows how to define the view attribute (see also chapter “Customer Specific Views in the Web
Catalog (SAP ERP Backend and TREX)” on page 237) and an additional attribute MAT_GROUP that will
contain 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_ATTRIBUTES
and AREA_ATTRIBUTES. This example only deals with item attributes:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 237
The second method is called once for each catalog node (i.e. for each area and each item). Therefore its
interface contains only one parameter ATTRIBUTES with attribute assignments. The method checks if the
caller passed an area or an item. For each item, it assigns the content of field MARA-MATKL from material
master 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 more
view assignments shall be made, it’s important to increase the multi-value counter per view id. See the coding 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 238
Customer Specific Views in the Web Catalog (SAP ERP Backend and TREX) This unit describes how to get customer specific views of the product catalog with an SAP ERP backend system 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 239
Customer specific views of the product catalog are created by matching ‘catalog view’ attributes, attached to the (ECO) product catalog area/item, with the (ECO) customer. These attributes have to be transferred from
the SAP ERP Backend to ECO via the SAP ERP function modules ISA_READ_CATALOG_COMPLETE and
ISA_CUSTOMER_READ_CAT_VIEWS. Neither function module retrieves any ‘catalog view’ attributes in
standard, but both have to be extended due to individual requirements.
The following steps have to be performed:
1. Create a new SAP ERP function module Z_READ_CATALOG_COMPLETE by copying the standard
function 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 table
ATTRIBUTES.
o attributes-layout - catalog layout o attributes-area - internal area number o 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 module
ISA_READ_CATALOG_COMPLETE with the E-Commerce extension concept as described in Changes
in Configuration on page 276.
4. Create a new SAP ERP function module Z_CUSTOMER_READ_CAT_VIEWS with an interface as
described 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 table
CATALOG_VIEWS.
o catalog-views-string – value of ‘catalog view’ attribute
6. 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 in
Changes in Configuration on page 276.
7. Activate catalog views in the web shop definition.
Version
This feature is available in E-Commerce 5.0
Example
See note 677319 and the example in chapter “New Fields in the Web Catalog (SAP ERP Backend and TREX)” on page 234.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 240
Extensions of the IPC The 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 configuration user interface. SCE and SPE are components of the SAP application server. The interactive configuration user 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 as described 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 SAP scenarios (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 modification concepts 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 Scenario This unit gives an introduction to the IPC UI concepts.
SAP R/3
Backoffice
Systems
(SD, PLM,
MM,PP...)
R/3
Plug-In
Optional:
No SAP R/3 backend
(data maintainance
including pricing and
configuration data in
SAP CRM)
SAP CRM
System
HTML control
Customer Data
Order Data
Product Catalog
Product Master
...maintain
configuration
models
IPC
SAP J2EE Engine
Java Server Pages
UI Beans
Struts Actions
IPC Client Objects
API
HTTP Server
Get and Modify
configuration
state
Display
configuration
UI
Master Data
(products,
knowledge bases,
pricing
Transaction
Data (order..)
Figure 67 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 order scenario). You can find detailed descriptions in the installation documents on the SAP Service Marketplace under alias /crm-inst.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 241
In summary:
There is a clear separation between the IPC engines as part of the CRM or ERP system and the IPC Web Application, which is the JSP UI used for interactive product configuration and runs on the SAP J2EE Engine.
As of release 5.0 the IPC is not a separate server anymore. The IPC comes with the CRM or ERP and exchanges data with its client applications via RFC.
In all scenarios (including ISA CRM, ISA ERP), the IPC reads master data directly from the SAP CRM or ERP server; The former dataloader is not required anymore.
Instead of directly calling RFC function modules, the interactive configuration (JSP) UI uses an abstraction layer (Client Object API) very similar to the ISA Business Object/Backend Object APIs with 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 68 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 all scenarios.
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 UI communicates 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 IPC over 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 242
Action Flow
Action:
setCharacteristicValues
Action(s):
displayLayout
Po
st
Fo
rward
to
dis
pla
yL
ayo
ut
redirectGet
Data Processing Data Display
Figure 69 General Action Flow
The slide shows the general action flow in the 5.0 UI (same as in E-Commerce applications). We can divide the action flow into two blocks:
1. Data processing actions: Receives user input via http post request and changes the state of the configuration
2. Data display actions: Reads the current state of the configuration, creates the html according to the layout and sends the response
Use of the E-Commerce Layout Framework The 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 source not found. for more details.
UI Components
The XCM file /sap/modification/ipclayout-config.xml defines the UI Components that are
common for SAP’s standard applications that include the interactive configuration ui (b2b; b2c; ipc).
UI Layouts
The XCM file /sap/modification/layout-config.xml defines the layouts of the application. The
common UI components of the interactive configuration ui together with the UI components of the standard application form these layouts.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 243
Figure 70 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 components from ipclayout-config can be reused.
UI Areas
The picture below shows the partitioning of the interactive configuration UI in different UI Areas. Theses UI areas are filled with UI components at runtime.
Figure 71 UI areas of the config UI
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 244
Tiles
The layout of the interactive configuration is highly dynamic. The work area for example lists a variable number 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 UI introduces the concept of “tiles”.
Tiles are low level UI parts included by UI Components.
Figure 72 Example for tiles
The interactive configuration UI uses tiles mainly for rendering of characteristic values. You’ll find tiles in
software component SAP-SHRWEB in development component crm/ipc/web/ipcshared in folder ipc/tiles.
Low level layouts
In order to reuse tiles, the UI combines tiles with low level layouts. This low level layout technique is different from 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 and
holds only a table in which the tiles are included. You’ll find layouts in software component SAP-SHRWEB in
development component crm/ipc/web/ipcshared in folder ipc/layouts.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 245
Figure 73 Combining low level layout and tiles
Dynamic Includes The application calculates at runtime which layouts to combine with which tiles. Layouts and tiles carry keys that the application replaces at runtime by the physical file path of the JSP page for the layout or tile. The
application does this with a XCM customizing table lookup in file jspinclude-config.xml for each
request before sending the response back to the users browser.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 246
Figure 74 JSP Key and Path
The indirection -> key -> XCM table lookup -> physical path gives application programmers the possibility to easily replace SAP’s standard JSP pages by their own pages in
xcm/customer/modification/jspinclude-config.xml. You will find an example for this technique
in 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 in
folder com/sap/isa/ipc/ui/jsp/uiclass. The include methods offer a typesafe api to the page. They
make sure that the parameters passed to the included page do not interfere with parameters used by other included pages.
public static void include(
PageContext pageContext,
String characteristicController,
UIContext uiContext,
InstanceUIBean instance,
GroupUIBean charGroup,
CharacteristicUIBean cstic,
UIArea uiArea,
Hashtable customerParams) {
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 247
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 interactive configuration UI consists of recursively nested JSP pages. Include parameter are supposed to be valid only for the current include method and not visible for all the included pages. The parameter stack ensures that getIncludeParams retrieves those parameter that are passed with the last include method. That means on
the top of each included page you need to call getIncludeParams(pageContext).
Extension To Transfer Data To JSP
In addition to the standard ways to transfer data to JSP pages described in this document, the dynamic includes with UIClasses used in the interactive product configuration offer a possibility to pass extension data to JSP pages. All include methods of UIClasses offer a customerParams parameter. All IncludeParams
objects have a method getCustomerParams() that returns a Hashtable.
UIBeans UIBeans form an intermediate layer between the JSP pages and the Business objects (IPC client object layer). Methods of UI Beans are optimized for use within the JSP pages and reduce the complexity of the JSP pages.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 248
Figure 75 Interaction of UIBeans with the JSP pages and the Busines Object Layer
Client Object Layer The IPC client object layer is the business object layer and the backend layer of the IPC. It performs caching and provides convenient Java API’s to its calling applications. It performs communication with the IPC in the backend via RFC function calls or Socket commands (Mobile Sales). Please see Figure 68 IPC Architecture more in detail.
Finding The Appropriate Extension Concept For IPC The chapter Error! Reference source not found. applies also to the Interactive Configuration User Interface. Specific concepts are described in this chapter.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 249
Start
extension To
IPC
Static extension to
UI layer
Call your own
actions or change
the interaction flow
of the application
Additional data
should exchanged
between different
layers
Static
extension to
UI layer
Extensions to
the action
flow
Extensions to
exchange
additional
data
End
Make additional
calculations for UI
layer based on
the existing
business data
Extension to
the UIBean
layer
Static extension to UI layer
Changing Stylesheets
In 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 JSP pages.
IPC shared styles are located in software component SAP-SHRWEB development component
crm/ipc/web/ipcshared/ folder ipc/mimes/style/stylesheet.css. Shared styles means those
styles are common to b2b, b2c, and ipc web applications.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 250
Create New Layout Or Change Standard Layout
The only thing that differs here from the E-Commerce framework is the location of UIComponents for the
interactive configuration UI. UIComponents are located in /sap/modification/ipclayout-
config.xml.
Change UI Components
Example: Customer Buttons and Actions
The interactive configuration UI gives you the possibility to add three customer buttons to the header area without modification to the UI component header.
In order to do this you need to define those customer buttons in the xcm customizing under components customerbutton1 to customerbutton3.
Figure 76 XCM settings for customer buttons
The parameter forward is not supported in SAP’s standard UI. The parameter target allows the three values for html hyperlink targets: _self, _parent, top. By default the result will be displayed in the same frame as the interactive configuration UI.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 251
Figure 77 Customer buttons on screen
In order to display language dependend labels for the customer buttons you need to provide the appropriate
label for the session language in the language dependent resource files. SAP provides three placeholder for
customer button labels: ipc.customer_button1_label, … (see: Change/add text in the text
property file (language dependent!))
The customer buttons call the actions that you have defined in the parameter customerbutton1.action. SAP
provides three placeholders for action mappings /ipc/customerButtonXAction in the ipc-config.xml.
Example: Adding Customer Tab To Multifunctional Area
The interactive configuration UI gives you the possibility to add a customer specific tab to the multifunctional area (area on the right side of the standard interactive configuration UI).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 252
Figure 78 Component configuration for customer tab
You activate this area when setting the parameter “customertab.show” of the XCM component
multifunctional area to “T”.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 253
Figure 79 Application configuration for customer tab
Figure 80 Customer tab action mapping
When you click on the customer tab, by default the system will execute the action
com.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 be
active. 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 action
mapping to use your own action and forward to your own JSP page.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 254
Figure 81 Customer tab with characteristic details
Example: Display Characteristic Header And Values In One Line
Depending on the space on screen and your configuration model (length of characteristic names and values), you may want to display the name of the characteristic and its values in one line to save vertical
space. Software component SAP-SHRWEB, development component crm/ipc/web/ipcshared, folder
ipc/customer/tiles/characteristic.jsp shows the modified JSP page.
/xcm/customer/modification/jspinclude-config.xml shows an example how to include this
modified page instead of the SAP standard page.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 255
Extensions To The UIBean Layer The interactive configuration creates UIBeans using a generic factory that you may subclass and replace SAP’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 82 Creating UIBeans via UIBeanFactory
The customer UIBean factory in the example creates an object of type
com.customer.isa.ipc.ui.jsp.beans.ValueUIBean which in turn is a subclass of
com.sap.isa.ipc.ui.jsp.beans.ValueUIBean and overwrites the getLanguageDependentName
method.
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 the
business data itself. A good example is the method determineLayout() in
com.sap.isa.ipc.ui.jsp.beans.CharacteristicUIBean. This method calculates the
characteristic layout to be used from a number of characteristic attributes (multi value, interval domain, …). This calculation is neither business logic nor should the calculation been done on the jsp page.
2. You extended the business object layer (IPC client object layer) and want to display additional data from the business object layer in the JSP pages. The UIBean passes the data through.
Extensions In The Action Layer Since struts 2.1 allows the definition of multiple config-files, SAP introduced a new /customer/ipc-config.xml file.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 256
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 requests
Z_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 flow
delivered from SAP, those changes in /Web-inf/ipc-config.xml will be supported by the Netweaver
Development Infrastructure. The NWDI will support merges of SAP’s corrections and your changes of those files.
You will find an example for an extension in the action layer in
com.customer.isa.ipc.ui.jsp.action.GetInstancesAction. This action implements a
customerExit that shows all instance nodes of the instance tree expanded. The example how to change the
action flow is in ipc-config.xml.
Figure 83 Standard customer exit in actions
The shown standard customer exit is called at the end of every IPC action. It allows customers to read request parameter from request or requestParser and add, modify or remove the data in the http request attributes, the userSessionData or mbom.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 257
Create Customer Backend Object To get additional data from a backend system and to use these data in the interactive configuration UI or in conjunction with IPC pricing functions you would need to either use the E-Commerce extension framework techniques like function call interception, calling additional function modules or you need to extend the client object layer.
The IPC Client object layer is not only used by the interactive configuration UI, but also by the E-Commerce catalog 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 to backend systems. Using these connections you may call virtually all remote function modules in the backend system. You are not limited to IPC function modules. Defining your own connections in XCM, you may call other RFC enabled systems as well.
As with UI Beans, a factory creates the client objects. Analog to the UIBeans you may register your own
IPCClientObjectFactory in /xcm/customer/modification/factory-config.xml. The customer
IPCClientObjectFactory should be a subclass of SAP’s standard IPCClientObjectFactory so that you need to overwrite 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. The
client object class com.customer.client.object.CustomerDefaultConfiguration introduces a
new method “checkAvailibility()”. This method is then used by
com.customer.isa.ipc.ui.jsp.beans.CustomerConfigUIBean in method
“getAvailabilityImage()” which in turn is used by
ipc/customer/tiles/statusbarWithAvailibilityCheck.jsp. The private method
callATPCheck 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 example
newConfiguration)
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 example CustomerDefaultConfiguration.checkAvailability
6. Use the method of your customer object in the corresponding UIBean or any action (in the example
CustomerConfigUIBean)
You may also use IPC client objects as container for extension data. Client objects inherit from BOBase and
provide the methods addExtensionData(…), getExtensionData() and removeExtensionData().
You would typically use these methods in actions in order to transport your data to JSP pages. You may
acess these data on JSP pages with UIBean.getBusinessObject().getExtensionData().
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 258
Figure 84 Handling extension data at client objects
SCE user functions Please refer to note 870201 for information on SCE user functions. Those user functions are independent of the interactive configuration UI and therefore not subject of this guide.
Exchange additional data with ECO Standard E-Commerce backend objects used by ECO CRM or ECO ERP provide different customer exits to exchange additional data between E-Commerce and the IPC for pricing, configuration or creating the IPC basket (only ECO CRM).
For details see Standard Backend Objects providing User Exits on page 206. Examples see ’Extending Existing Backend Objects’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 307).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 259
Extensions of the Document Handling This unit describes the UpdateDocumentView Module used to manage the behavior of the user interface with respect to the display of documents.
Overview In the B2B application you can have up to two active documents (documents having a tab strip in the documents frame, and technically with corresponding objects in the business layer); an document you can edit, and a document you cannot edit. Additionally, a catalog page can be displayed. This complex constellation 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 user interface (GUI), the DocumentHandler. Together with some other objects and actions they form the
UpdateDocumentView module.
The UpdateDocumentView module is responsible for representing the following frames:
form_input
This is the working area. The documents and the catalog are displayed here.
documents
Displays the tab strips of the documents.
_history
Displays 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 in
the form_input frame. A corresponding tab strip is displayed in the documents frame, and the document
must be set at the beginning of the history.
Implementation The diagram shows the main objects of the UpdateDocumentView module:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 260
Figure 85: Main objects of the UpdateDocumentView module
The DocumentHandler stores the status of the GUI for the documents and the catalog. It knows if the
catalog, a document, or a default page must be displayed. There is only one DocumentHandler object for
every 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 history need additional information, for example the text which is displayed on the tab strip and in the history. This
information is stored in a ManagedDocument object. Additionally, a ManagedDocument holds a reference
to 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 of
documents 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 the
isaPerform() method of the UpdateDocumentViewAction.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 261
Figure 86: Activities of the isaPerform() method of the UpdateDocumentViewAction
The forward strings of the UpdateDocumentViewAction are mapped to special JSPs (Refresher JSPs) in
the file config.xml (see <action path=‘/b2b/updatedocumentview’ ...>). The file name of a
Refresher JSP always has the prefix refresher_. A Refresher JSP loads with JavaScript functions the
documents, _history, and form_input frame. The necessary Actions and JSPs are coded in the
refresher JSP. Because of this, each document type needs its own refresher JSP.
Example
This example shows the creation of a new order. (ISA B2B).
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 262
Figure 87: 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, and
creates a new ManagedDocument for the basket.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 263
UpdateDocumentViewAction is called. It asks the DocumentHandler what should be displayed and
gets the ManagedDocument for the basket. It reads from the ManagedDocument that
refresh_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 refresher
JSP. 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 frame
displays header information and all positions of the basket. The ShowBasketAction reads all necessary
information from the Basket object and puts it in the request context. The order.jsp will display it. The
frameset_order.jsp also loads the details and the closer_details frame.
Integrating own documents There are two phases which must be considered when integrating new documents; prepare and display. The prepare phase is passed if a new document is created or opened. The display phase is passed if the document is displayed. For a specific document, normally the prepare phase is passed only once, while the display phase is passed more than once, for example if the user selects the browser refresh-button.
Figure 88: Display a new Document type with the UpdateDocumentView Module
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 264
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 the
other actions are not relevant for the UpdateDocumentView module.
PrepareNewDocAction
The action for the prepare phase (PrepareNewDocAction):
Must create a new, or use an available business object, for example, by asking the BOM for it. This object must implement the interface DocumentState.
Must create a new ManagedDocument object.
Must hand over this object to the DocumentHandler.
Creating a ManagedDocument
A ManagedDocument is created by calling its constructor with the following parameters:
DocumentState doc Reference to the corresponding business object.
String docType Type of the document, for example, order, quotation, contract. The document type is displayed on the 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, and
twodocnav.jsp). You have to add an entry in your project specific XLF file (see chapter “Changing
language dependand resource keys” for more details).
String docNumber docNumber is a unique string, automatically assigned by the backend for every document. It is displayed 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 “Changing
language dependand resource keys” for more details) is displayed instead. docNumber may be null.
String refNumber, refName refNumber and refName are the number and name which can be assigned by the customer for the document. 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. refNumber and refName may be null.
String docDate docDate is a date, often the date when the document is created. It is displayed on the tab strip for the document and in the history list. It is not translated and it may be null.
String forward
This string is used by UpdateDocumentViewAction for the forward mapping. In the file
config.xml a path must be assigned for this string. The corresponding tag is <action path=‘/b2b/updatedocumentview’ ...>.
If forward is null then the DocumentHandler will directly hand over the ManagedDocument to the
history list. It is not managed by the DocumentHandler and so it will not be displayed. This means
you have a way of adding entries to the history without displaying it.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 265
String href, hrefParameter
These strings are used by history.jsp. Every entry in the history is a link to a document. With
href and hrefParameter the anchor of the link is built, href+’?’+hrefParameter. The result must
be 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 documents without 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 or
DocumentState.TARGET_DOCUMENT. If the state is not set to one of these, then the document cannot be
added 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 business
object to the new ManagedDocument) should be on top of th other document. But this does not remove the
catalog 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(‘&’);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 266
PrepareNewDocAction
The 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 the
document. 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. It
loads the action, which is mapped to the path /b2b/displaynewdoc in the file config.xml. In this
example it should be the action DisplayNewDocAction. If your document consists of a frameset with
several JSPs, the frameset must be loaded. We recommend you copy an existing refresh JSP, for example, 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 flow
is different). They load the WorkareaNavAction and the UpdateHistoryAction, which are configured
in 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 267
Structure of the Internet Sales application Before an Internet Sales application can be extended it is necessary to know how it is structured. This unit gives an overview of the structure of the application. After reading this unit you should be able to identify the location 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 the Internet 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 following table gives an overview of the content of the archive.
Directory within the war file Description
auction
b2b
catalog
ecall
ipc
Meta-inf
mimes
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 XCM Administrator 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 SAP Internet Sales application.
WEB-INF\classes Internet Sales resource files contain language dependent texts used within 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
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 268
Directory within the war file Description
WEB-INF\xcm Configuration files managed by the Extended Configuration Management (XCM).
WEB-INF\xcm\sap These configuration files contain default application configuration and must 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\conf
iguration
This folder contains configuration files used for common configuration settings. These settings are done using the XCM Administrator.
Files in this folder should never be changed manually, only using XCM Administrator.
The files in this folder usually do not contain the actual settings. The files in this folder are copied to a folder placed outside the SAP J2EE Engine installation directory during initial deployment.
WEB-
IND\xcm\customer\modi
fication
This folder contains files used to change less common settings. These files are usually touched when extending functions of the web application. SAP delivered default settings are changed manually using XCM extension mechanism.
Table 61: Overview of the content of the web archive
Configuration files
The following table gives an overview of the most important configuration files and their location within the web 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, there are only a few application related parameters in this file. Most of the application specific parameters are managed by XCM.
WEB-INF\config.xml Configuration of the Struts Interaction Layer.
This file should be modified if you perform changes in the process flow of the application.
WEB-
INF\xcm\customer\modi
fication\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 custom Business Object Manager.
Table 62:Overview of configuration files
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 269
Folder Description
WEB-
INF\xcm\customer\modi
fication\eai-
config.xml
Central file for configuration of the BLS layer. You usually do not change this file. You only need to change it if you are using JCo function execution cache.
See chapter 'JCo Function Cache' on page 87
WEB-
INF\xcm\customer\modi
fication\init-
config.xml
This file defines a set of handlers called during the initialization of the application. You make settings in this file if you want to add your own initialization handler or to change settings in the available initialization handlers.
See chapter 'Initialization Handler' on page 132
WEB-
INF\xcm\customer\modi
fication\cache-
config.xml
Configuration for application caches. You can change settings of existing caches or register your own caches.
See chapter 'All purpose Cache' on page 131
WEB-
INF\xcm\customer\modi
fication\
modification-
config.xml
File used to register function module execution listeners, turning on ABAP debugging, enabling JCo function tracing and register custom function modules
See chapter 'Interception of Calls to Standard Function Modules' on page 227
See chapter 'ABAP Debugging' on page 169
See chapter 'Tracing Function Modules' on page 295
See chapter 'Replacing Calls to Standard Function Modules (Backend System)' on page 229
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 capabilities of the ISA application. You make changes in this file if you want to change the logging/tracing settings.
TODO: See chapter ‘Generic Search Framework’ on page 101.
Table 63:Overview of configuration files
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 270
Source Code
General Package Structure of an E-Commerce application
The following table shows the general ideas behind the package structure of E-Commerce.
Package structure Comment com.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-specific implementation of the business objects.
.core Core ISA functionality (no application logic).
.isacore Core application logic functionality.
Table 64: Overview of the package structure of E-Commerce
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 271
Conventions when Enhancing the E-Commerce Application The following chapter gives recommended conventions for enhancing the E-Commerce application.
Separation of SAP-Software / Customer Extensions It is necessary to strictly distinguish between the components delivered by SAP and extensions made by the customer.
Changes can only be made by integrating new Java code into the existing application framework. Application logic extensions should be placed in customer-specific Java packages. For example, Java-side business
logic of Internet Sales is located in the com.sap.isa.businesobject package. If the name of the
customer is ACME, the customer should place his business objects in the
com.acme.isa.businessobject package.
The following unit gives you information on recommended conventions for customer extensions.
Naming Conventions All extensions made by the customer should follow naming conventions that are described in the following units.
Java Server Pages
The following table gives you information about some naming conventions recommended when working with JSPs.
Type of Modification Naming convention
All additional elements in JSP (for example: input field)
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 89: Original flow of actions
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 272
The config.xml for this process flow is as follows:
Example:
This process flow is interfered by introducing a customer written CustomAction.
Figure 90: Changed flow of actions
<action path=‘/firstaction’
type=‘com.sap.isa.action.FirstAction’>
<forward name=‘success’ path=‘/secondaction.do’/>
</action>
<!-- original path modified -->
<action path=‘/Z_secondaction’
type=‘com.sap.isa.action.SecondAction’>
<forward name=‘success’ path=‘/thirdaction.do’/>
</action>
<!-- custom 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 273
The original path /secondaction.do is used to route the flow to Z_CustomAction. When
Z_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 JSPs in order to call custom Actions. For interfering the process it is recommended to limit changes to
the config.xml file only.
Changes in bom-config.xml
When 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 Object
Manager in bom-config.xml
Z_<name>-BOM
example:
Z_CUSTOM-BOM
Accessing name of new Business Object Manager from an Action
Place a constant containing the above name in the class of the new BOM.
example:
public class Z_CustomBusinessObjectManager
extends BusinessObjectManagerBase
implements BOManager, BackendAware
{
public static final
String CUSTOM_BOM = ‘Z_CUSTOM-BOM’;
Table 66: Naming conventions for Business Object Managers
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 274
Example
The following example shows how these naming conventions work together:
Entry in bom-config.xml:
Definition of constant:
Accessing Custom BOM from Action:
Java
All 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 in the delivered E-Commerce source code are not allowed.
...
// get user session data object
UserSessionData userSessionData =
UserSessionData.getUserSessionData(request.getSession());
// gettting custom BOM
Z_CustomBusinessObjectManager myBOM =
(Z_CustomBusinessObjectManager)userSessionData.
getBOM(Z_CustomBusinessObjectManager.CUSTOM_BOM);
public class Z_CustomBusinessObjectManager
extends BusinessObjectManagerBase
implements BOManager, BackendAware {
public static final String CUSTOM_BOM = ‘Z_CUSTOM-BOM’;
...
}
<BusinessObjectManager
name=‘Z_CUSTOM-BOM’
className=‘com.acme.isa.businessobject.Z_CustomBusinessObjectManager’/>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 275
Packages
When 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 your
company>.isa.businessobject
Example: com.acme.isa.businessobject
Backend Object Interfaces com.<name of your
company>.isa.backend.boi
Example: com.acme.isa.backend.boi
Implementation of Backend Objects com.<name of your
company>.isa.backend.<type of
backend>
current backend-types are: <crm>,
<ipc>
Example: com.acme.isa.backend.crm
Table 67: Naming conventions for packages
Java Classes
The following naming conventions should be used when developing custom classes:
Type of Java Code Naming conventions
Action Z_<Arbitrary name>Action for self
written classes
Z_<Original Action name>Action
when deriving from existing ECO actions
Business Objects Z_<Name of BO e.g. Basket> for
self-written classes
Z_<Original Business Object
name> when deriving from existing ECO
business objects
The name of a business object should be a noun.
Do not use BO or BusinessObject in the name
of the business object.
Example: com.acme.isa.businessobject.Z_Basket
Table 68: Naming conventions for Java classes
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 276
Type of Java Code Naming conventions
Business Object Manager Z_<Name of BOM e.g.
CustomBusinessObjectManager> for
self-written classes
Z_<Original BOM name> when
deriving from a existing ECO Business Object Manager
Example: com.acme.isa.businessobject.Z_Busines
sObjectManager
Backend Object Interfaces Z_<Name of Business
Object>Backend for self written classes
Z_<Original Backend Object
interface name> when deriving from
existing ECO business objects
Example: com.acme.isa.backend.crm.Z_OrderCRM
Implementation of Backend Objects Z_<name of Business
Object><type of backend in
upper case>
Z_<Original Backend Object
impementation name>
Example:
com.acme.isa.backend.crm.Z_CustomBask
etCRM, this class provides additional basket
functionality but does not derive from the CRM specific ECO basket.
Table 69: Naming conventions for Java classes
Resource Files
If 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 following naming convention:
<name of your company>z_<key name>
Example:
original key:
b2b.header.settings=My Settings
after changing:
acme.b2b.header.z_settings=My
personal Settings
Table 70: : Naming conventions for resource files
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 277
Changes Naming convention
Added custom key <name of your company>z_<key name>
The key name should correspond to the component within the application (e.g. b2b, cic).
Example: acme.b2b.order.display.z_extheaderdat
a_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 the application.
Changes in Configuration The following chapter explains changes to the configuration using Extended Configuration Management (XCM).
Application Configuration and Component Configuration Application configuration and component configuration can be created and maintained using the XCM Administrator tool. A detailed description can be found in the XCM Administrator tutorial which is part of the mySAP CRM Java Installation Guide (see [1])
Common Configuration Changes This section details how you make common configuration changes to the settings in init-config.xml or
backendobject-config.xml. These changes cannot be made using the XCM Administration tool. You
can, of course, use the same extension mechanism in other configuration files, but changes to these two files are the most common.
Changes in init-config.xml
The 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’/>
<!-- time in hours -->
<param name=‘removal’ value=‘48’/>
</initialization>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 278
You want to change the value of the removal attribute from 48 to 4711. You make the changes in the
customer 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 the
parameter you wish to change (removal), all others are inherited (for example, expiration).
Changes in backendobject-config.xml
You use this file to register backend objects in the Business Logic Service Layer (BLS). In previous releases
the file eai-config.xml was used for registering Backend Objects.
Changing existing Backend Object
If you need to change configuration for existing backend objects, and there is no appropriate switch in the XCM Administrator, you need to carry out the changes manually, using XCM extension mechanism. All customer 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 is
taken 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’
connectionFactoryName=‘JCO’
defaultConnectionName=‘ISAStateless’>
<params>
<param name=‘priceTypes’ value=‘totalGrossValue’/>
<!-- for allowed values see defined constants in
com.sap.isa.backend.boi.webcatalog.pricing.PriceType -->
</params>
</businessObject>
</config>
<initialization isa:extends=‘../initialization
[@className='com.sap.isa.catalog.cache.CatalogCacheInitHandler']’>
<param name=‘removal’ value=‘4711’/>
</initialization>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 279
To change the value of priceTypes from totalGrossValue to netValueWithoutFreight, carry out
the 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 you
derive 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 those
you 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. You need it to tell XCM which backend object you are extending.
The following coding in the customer version of backendobject-config.xml is placed after the
xi:include:
4. Check the result of this extension in the XCM cache.
Adding new Backend Object
If you have written a backend object you have to register it in backendobject-config.xml. Perform the
following step. (Example taken from ISA B2C)
You can always extend the base configuration crmdefault when registering your object. (even if you use
ECO ERP).The reasons is that this is the base configuration for all other configurations.
<!-- the crmdefault configuration can be always be extended for self written backend objects
-->
<config isa:extends=‘../config[@id='crmdefault'‘>
<!-- register your backend objects here -->
<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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 280
Extending XCM with Customer Settings If you extend the application and would like to make your extensions configurable, you can extend the XCM configuration 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 Do
The first step consists of adding the name (myParam) and the default value (defaultValue) of the new parameter and the name of the component (project) the parameter is assigned to. In addition to that you have 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 the following figure:
Figure 91: Adding and configuring new parameter (XCM)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 281
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 the paramter.
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 type
o 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>
<!-- add additional scenariometadata here -->
</scenariometadata>
</xcmadmin>
<component id="project">
<configs>
<config id="projectconfig">
<params id="default">
<param name="myParam" value="defaultValue"/>
</params>
</config>
</configs>
</component>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 282
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 XML file is valid and well formed before uploading it to DB. Uploading invalid files can cause the application 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 parameters
This paragraph gives some information on how adding component meta data.
The component XML element has the following attributes:
Attribute Description Required
id The id of the component. Used to identify the component. yes
shorttext One sentence describing what this component is good for. This will be used in a summary table giving the customer an overview on the available components.
yes
testclass This class is used to test the component configuration. This can be done in the XCM Admin by the user during configuration (e.g. testing connection to SAP system using JCO). The test class has to implement the interface com.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 this
attribute 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 is
obsolete and should not be used any longer. An obsolete component is marked with an icon in the tree. You should update the short/long text and describe the consequences of the deprecation
See [5] Chapter Changing XCM Parameters for rules when changing configuration parameters
no
Table 72: Adding Meta data of XCM parameters
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 283
A component is configured using parameters. Each parameter should have a one sentence long shorttext giving information what the parameter is good for. It can also have a longtext with detailed information about the 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 92: XCM - parameter shorttexts
Example:
Example of text type:
<param type="text" name="myParam" shorttext="myValue" />
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 284
Example:
Example of singleselect type:
The param XML element has the following attributes.
Attribute Description Required
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 user an idea what the parameter is used for as well in a printable summary of component parameters.
If one sentence is enough to describe the meaning of the parameter then this is sufficient
yes
conversionclass A class used to convert the value. This can be used to convert the value before it is stored. The class has to implement com.sapmarkets.isa.core.xcm.admin.conv.
ParamConverter
no
longtext If the parameter is of type text you can provide additional information here helping the customer to maintain this parameter correctly
no
type Either text or singleselect. In case of single select you have to define the allowed values
yes
Status New in 5.0: Allowed value 'obsolete’. This attribute indicates
that 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 the consequences of the deprecation
See [5] Chapter Changing XCM Parameters for rules when changing 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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 285
Definition of a allowedvalue located in the body of the param XML tag.
Attribute Description Required
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 give the user an idea what the value is used for as well in a printable summary of component parameters.
If one sentence is enough to describe the meaning of the parameter then this is sufficient
yes
longtext More details about the value. no
Table 74: Definition of a „allowedvalue“
API for reading XCM parameter Values
The 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.It
provides access methods for XCM parameters: getParamConfig("default").getProperty("myParam");
Configuration of Dynamic fields in E-Service Dynamic fields are fields that a customer can add to be included in the complaints and returns. They can be defined on the following one-order structure: CUSTOMER_I, PRICING, SHIPPING and PRODUCT_I. These dynamic fields can be defined in customizing: Customer Relationship Management Basic Functions Authorizations 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 web application, 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 be
modified. (The delivered standard file is placed under …\WEB-INF\xcm\sap\modification\dynamic-
fields-config.xml and should not be changed.)
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 286
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 named ComplaintItemDynFieldsPG and define underneath it all the properties that you want to appear in the web application.
<maintenance-object xmlns:isa="com.sap.isa.core.config"
xmlns:xi="http://www.w3.org/2001/XInclude" >
<!-- customer changes in dynamic-fields-config should be done here by extending/overwriting
the base configuration -->
<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"
objectType="CUSTOMER_I"
fieldName="CARRIER_CLAIM">
</property>
<property name="HS_OF_PRIME_QTY" type="input"
description="esrv.crb2b.cl.dyn.hsq"
objectType="CUSTOMER_I"
fieldName="HS_OF_PRIME_QTY"
size="10">
</property>
<property name="HS_OF_PRIME_UNIT" type="input"
description="esrv.crb2b.cl.dyn.hsu"
objectType="CUSTOMER_I"
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 287
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 the web application UI. This key must exist in crm~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 an binocular 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 option to a <html> select box (e.g.
<select id…>
<option value=”value” …)
Description - The resource file key containing the value that will be displayed on the web application UI. This key must exist in crm~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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 288
Generic Search Framework
Main Components of the Generic search framework for E-Service Extended Complaints and Returns:
Component Application layer Specific or Shared component ?
\appbase\genericsearch.jsp Web server Re-use from Internet Sales
\xcm\sap\modification\generic-searchbackend-config.xml Web server E-Service specific
com.sap.isa.ui.uiclass.genericsearch.GenericSearchBaseUI.java Web server Re-use from Internet Sales
com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory.java Web server Re-use from Internet Sales
com.sap.isa.isacore.action.GenericSearchBaseAction.java Web server Re-use from Internet Sales
com.sap.isa.isacore.action.GenericSearchSortAction.java Web server Re-use from Internet Sales
CRM_ISALES_SEARCH Application server (Dev.class)
Re-use from Internet Sales
CRM_ICSS_CR Application server
(Dev. class)
E-Service specific
CRM_ISA_GEN_DOCUMENT_SEL Application server (func. Mod)
Re-use from Internet Sales
CL_ISA_GEN_DOC_SEARCH_HELP Application server (class)
Re-use from Internet Sales
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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 289
BAdI Implementations in component “CRM_ICSS_CR”
Filter Value ABAP class Remark
CAMPAIGN 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 of header objects.
DELIVERY CL_IM_CRM_ESRV_DELIVERY This implementation is exclusively used to select deliveries.
DELIVERY_I CL_IM_CRM_ESRV_DELIVERY_I This implementation is exclusively used to select deliveries. It returns items instead of header objects.
PSL CL_IM_CRM_ESRV_PSL This implementation is exclusively used to select product service letters (PSL).
REJECTED_I CL_IM_CRM_ESRV_REJECTED_I This implementation is exclusively used to select rejected complaints and returns items.
RETURN CL_IM_CRM_ESRV_RETURN This implementation is exclusively used to select returns.
RETURN_I CL_IM_CRM_ESRV_RETURN_I This implementation is exclusively used to select returns. It returns items instead of header objects.
Table 78: BAdI Implementations in Component "CRM_ICSS_CR"
BAdI Implementations in component “CRM_ISALES_SEARCH” (Those BAdI implementations are re-used from Internet Sales application).
Filter Value ABAP class Remark
BILLINGDOC 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 items instead of header objects.
ORDER CL_IM_CRM_ISA_GDS_ORDER This implementation is exclusively used to select order documents.
1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for items within 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 specific implementation 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 section now focuses on the integration of the Generic Search Framework into the CRM E-Service Extended Complaints and Returns.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 290
1. Known search definitions in E-Service Extended Complaints and Returns
Search Screen Definition Scenario Remarks
SearchCriteria_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 returns documents.
SearchCriteria_B2B_Sales_OrderStatus_Items B2B To search for sales document items (used to find items in case large document handling is enabled)
SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items (used to find items in case large document handling is enabled)
SearchCriteria_Delivery_Items B2B To search for delivery document items (used to find items in case large document handling is enabled)
SearchCriteria_B2B_Claim_Items B2B To search for claim document items (used to find items in case large document handling is enabled)
SearchCriteria_B2B_Return_Items B2B To search for return document items (used to find items in case large document handling is enabled)
SearchCriteria_RejectedItems B2B To search for complaints and returns items 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 the complaints 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 class
com.sap.eservice.crb2b.uiclass.GenericSearchCrUI. This class makes sure that the user has
sufficient authority to view each document types for either his company or a company in his hierarchy before displaying the search criteria.
If you wish to override these conditions, it is possible to define your own UI class, extending the base one
and specifying it in the <screen-group> of the generic-searchbackend-config.xml.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 291
Checking configuration during runtime After changing configuration in customer files you need to check your extension mechanism is working properly. The XCM processed configuration files only exist in the memory. You must therefore check the XCM 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 in from 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.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 292
Best Practices
Getting Information about the Application The 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 the corresponding page in the browser by placing the mouse pointer on a particular page, and
selecting Refresh from the context menu.
Displaying Names of JSPs while Running the Application
Use 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
Example
By 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:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 293
Figure 93: Displaying name of JSP-Files in E-Commerce Applications
Displaying Text Keys While Running the Application
Use this feature if you would like to find out which text displayed in the application corresponds to which key in 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 is displayed instead of the corresponding text.
translate.show.key.concat Value: <any value> The language independent resource key as well as text is displayed in the form:
<resource key>:<text>
Table 81: Displaying text of keys
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 294
Example
By 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 Flow
You need this information if you have to interfere the process flow of the application in order to provide your custom 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 you
should be familiar with the Struts framework.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 295
Session Tracing Session tracing enables you to write all trace entries of a user session to a separate file, in addition to the standard log files. The log level used for this is always DEBUG, regardless of how the other logging settings
are. Session logging offers the following:
Tracing a client session
Debug log level (highest level of detail) independent of further logging settings. This function allows a detailed 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 the
directory <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 files
defaultTrace.<COUNTER>.trc, where counter is a number between 1 and 20.
Configuring session tracing
Before you can make use of the session tracing, you have to configure it. To do this, perform the following steps:
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 of
the host, your SAP Web AS Java is running on, and <PORT> is the http port of your SAP Web AS
Java.
Open the application specific component in the XCM admin tree view: "General and Application
Settings/Customer/<APPLICATION>/<APPLICATION>config", where <APPLICATION> is the
context 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 tracing To 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 provides a "Single Session Trace" link for each of them. The application will start a web session based on the selected XCM application configuration. A second browser window will open where the session id will be displayed.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 296
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 Modules
You can enable tracing for any function module executed in the ECO application. This feature traces import/export and table parameters. It is useful if you need to know which parameters were used when the function module was called. Additionally, you can decide whether you want to trace the function module before 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 to omit tracing some of the parameters. For information on how to do this, please see the
comments in the file modification-config.xml
Example:
For examples see comments in file modification-config.xml
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 297
Additional Request Parameters
General Request Parameters The following table gives you an overview of HTTP request parameters which can be passed to the application, when it is started.
Request Parameter Description
Autoentry Value: Rel3.1 = X, Rel4.0 = yes (X) | no; Comes with 3.1: Until SP03, parameter allowed to automatically pass shoplist and sold-to party selection without any user action. First entry of the shoplist or sold-to party list had been selected. For SP04 and higher, an error page will be presented if autoentry is used, but no shop is passed via URL parameter, and a sold-to selection 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 in the 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 normale
search path /b2b_dev/b2b/mimes/images/shopHeader.gif
to /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 J2EE Engine is HTTP, the application is never accessed using HTTPS. In order to let the application know that HTTPS is used it should be started using the additional request parameter secure=on
Table 83: General Request Parameters
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 298
ECO Version
This feature is available in all versions of E-Commerce.
Example
http://localhost:50000/b2b/b2b/init.do?shop=muster&language=en
Request parameters for B2C To directly display the product details of a certain product, you can start the application with some extra parameters in the URL.
There are three parameters that should be in the request to display the details for a certain product. The parameters are:
Request Parameter Description
areaID This parameter specifies the GUID for the area that contains the product. This parameter can be obtained for a certain item (WebCatItem object) by calling item.getAreaID().
productID This parameter specifies the product Id that is associated with every product from the catalog by the ISA B2C application. It can be obtained by calling item.getItemID().
Shop This parameter is used to specify the shop that contains the desired product.
Table 84: Request parameters for B2C
ECO Version
This feature is available in all versions of E-Commerce.
Example
The 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 selected shop area:
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 299
Figure 94: Calling the application with additional request parameters
Single Session Trace
Passing Data between Actions When you have a chain of Actions you often need to pass data from one Action to another. There are two different strategies, depending on the Action flow.
Action Flow Remains on the Server In this scenario all the Actions operate on the same request:
Figure 95: 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’);
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 300
Action Flow is Interrupted by a JSP In 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 you have to retrieve the data from the Business Object layer and set it as a request attribute as described above.
Before
Figure 96: Original action flow
After
Figure 97: Interrupted action flow
Working with Request Parser This unit describes the Request Parser which can be used if your Actions derive from com.sap.isa.isacore.action.IsaCoreBaseAction.
The Servlet concept for managing request parameters is based on strings and causes a lot of work when converting the data into other data types. This class is a wrapper around the request object and allows you to 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();
}
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 301
The data of this form contains two associative arrays ‘personal’ and ‘beer’. You can retrieve the data using this wrapper class in the following way:
Writing Thread Safe Code Internet Sales is used by many concurrent users, at the same time, during runtime. You therefore have to be careful 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 by many concurrent threads from different sessions. For further information, please see chapter 'Interception of Calls to Standard Function Modules' on page 227.
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>
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 302
Administration Console There are some administration pages which help you to administer the following technical aspects of the application:
Aplication Cache statistics
Catalog cache statistics
Application System Cache Statistics
Java Connector Pools
Java Connector Pools
pool name Name of the connection pool
max pool size The maximum number of connections to the SAP System that are required per pool up to that point in time
max cons used The maximum number of connections to the SAP System that are required per pool up to that point in time
num current used cons The number of connections that are currently available 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 application server, and not just the pools of the Web application in which the administration page is.
Getting Application Version Since the SAP Web Application Server Java provides a central web page, were the versions of all deployed components are shown, the E-Commerce page has been removed. The version information was moved to http://<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
Logging In SAP E-Commerce 5.0, the E-Commerce logging was replaced with the standard logging of the SAP Web AS. For more information please refer to chapter Logging/Tracing on page 115.
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 303
Updating Application This table gives you information about after which changes to the application you have to restart the SAP J2EE Server.
Changes What to do
JSPs Refresh corresponding page in browser.
Configuration files Restart application through SAP J2EE administration console.
Java files Restart application through SAP J2EE administration console.
Table 86: Updating the application
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 304
Web Diagrams
Syntax of Web Diagrams
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 305
B2B - Start Page
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 306
B2B - Create Basket
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 307
B2B - Display Order Status
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 308
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 Standalone Components.
[2] SAP CRM 5.0 Java. InstallationGuide on SAP Service Marketplace: http://service.sap.com/crm-inst mySAP 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 Java Connector
Update History
Version Date Remarks
1.0 October 2012 First Version for SAP CRM Release 7.3
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 309
Table Index Table 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 ................................................................................................................... 143
Table 32: Overview of possible changes in different layers .......................................................................... 171
Table 33: Overview of simple modifications related to the UI ....................................................................... 192
Table 34: User exits within the Basket .......................................................................................................... 195
Table 35: User exits within the Order ............................................................................................................ 196
Table 36: User exits within the OCI ............................................................................................................... 196
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 310
Table 37: User exits within the Extended Complaints ................................................................................... 197
Table 38: User exits within the Remanufacturer’s Inspection Application ..................................................... 197
Table 39: Methods of the BOBase class ....................................................................................................... 200
Table 40: User exits for IPC for pricing .......................................................................................................... 207
Table 41: User exits for IPC basket ............................................................................................................... 207
Table 42: User exits for IPC basket ............................................................................................................... 208
Table 43: User exits for Order and Order Status ........................................................................................... 208
Table 44: User exits for Order and Order Status ........................................................................................... 209
Table 45: User exits for Web Catalog ............................................................................................................ 209
Table 46: User exits for for Pricing or Configuration ..................................................................................... 209
Table 47: User exits for for Pricing or Configuration ..................................................................................... 210
Table 48: ABAP Extension Structure (CRM) ................................................................................................. 214
Table 49: CRM - Supported Function Module / Business Object - Order ..................................................... 214
Table 50: CRM - Supported Function Module / Business Object - User ....................................................... 214
Table 51: CRM - Supported Function Module / Business Object - Contract ................................................. 215
Table 52: CRM - Supported Function Module / Business Object - Shop ...................................................... 215
Table 53: CRM - Supported Function Module / Business Object - Complaint .............................................. 215
Table 54: CRM - Supported Function Module / Business Object – ComplaintHeader ................................. 215
Table 55: CRM - Supported Function Module / Business Object – ComplaintItem ...................................... 215
Table 56: ABAP Extension Structure (ERP) .................................................................................................. 220
Table 57: ERP - Supported Function Module / Business Objects – Order ................................................... 220
Table 58: Communication Structure in SAP ERP ......................................................................................... 222
Table 59: How to access the Request Context ............................................................................................. 225
Table 60: Overview of the content of the web archive .................................................................................. 266
Table 61: Overview of the content of the web archive .................................................................................. 267
Table 62:Overview of configuration files........................................................................................................ 267
Table 63:Overview of configuration files........................................................................................................ 268
Table 64: Overview of the package structure of E-Commerce...................................................................... 269
Table 65: Naming conventions for JSPs ....................................................................................................... 270
Table 66: Naming conventions for Business Object Managers..................................................................... 272
Table 67: Naming conventions for packages ................................................................................................ 274
Table 68: Naming conventions for Java classes ........................................................................................... 274
Table 69: Naming conventions for Java classes ........................................................................................... 275
Table 70: : Naming conventions for resource files ........................................................................................ 275
Table 71: : Naming conventions for resource files ........................................................................................ 276
Table 72: Adding Meta data of XCM parameters .......................................................................................... 281
Table 73: Attributes of the param XML element ............................................................................................ 283
Table 74: Definition of a „allowedvalue“ ........................................................................................................ 284
Table 75: Allowed Attributes for the tag <property> ...................................................................................... 286
Table 76: Allowed Attributes for the tag <allowedValue> .............................................................................. 286
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 311
Table 77: Main Components of the generic search framework ..................................................................... 287
Table 78: BAdI Implementations in Component "CRM_ICSS_CR" .............................................................. 288
Table 79: BAdI Implementations in Component “CRM_ISALES_SEARCH” ................................................ 288
Table 80: Search definitions in E-Service Extended Complaints and Returns ............................................. 289
Table 81: Displaying text of keys ................................................................................................................... 292
Table 82: Displaying language dependent keys ............................................................................................ 293
Table 83: General Request Parameters ........................................................................................................ 296
Table 84: Request parameters for B2C ......................................................................................................... 297
Table 85: Attributes of Java Connector Pool ................................................................................................. 301
Table 86: Updating the application ................................................................................................................ 302
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 312
Figure Index Figure 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 ............................................................................................. 144
Figure 23: Merged Web Files ........................................................................................................................ 145
Figure 24: Project specific application in CUSTCRMPRJ ............................................................................. 146
Figure 25: Creating a new Track ................................................................................................................... 148
Figure 26: Adding Software Component ....................................................................................................... 148
Figure 27: Required Software Components .................................................................................................. 149
Figure 28: Check-In of the Archives .............................................................................................................. 150
Figure 29: Development System ................................................................................................................... 150
Figure 30: Overview Developer Workplace ................................................................................................... 158
Figure 31: Developer Workplace for SAP NetWeaver 7.30 .......................................................................... 160
Figure 32: Directory Structure of Web AS Java 7.0 ...................................................................................... 161
Figure 33: SAP Management Console .......................................................................................................... 163
Figure 34: Offline Config Tool - Setting Up Debug Mode ............................................................................. 165
Figure 35: J2EE Engine - Enabling Debugging ............................................................................................. 166
Figure 36: J2EE Engine - Enabling Debugging ............................................................................................. 167
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 313
Figure 37: Starting Remote Debugging ......................................................................................................... 168
Figure 37: Flow of possible changes ............................................................................................................. 172
Figure 38: Overview of different categories of extensions ............................................................................ 173
Figure 39: Statis extensions to the UI layer ................................................................................................... 174
Figure 40: Extensions to the action flow ........................................................................................................ 175
Figure 41: Extensions to exchange additional data ....................................................................................... 176
Figure 42: Extensions to exchange data with UI layer .................................................................................. 177
Figure 43: Transfer additional input data to action class and business object layer ..................................... 178
Figure 44: Transfer additional output data from aciton class to JSP ............................................................. 180
Figure 45: Extensions to exchange data with the backend systems ............................................................. 182
Figure 46: Retrieve additional data from SAP CRM system to business object layer .................................. 183
Figure 47: Transfer additional data from business object layer to SAP CRM ............................................... 184
Figure 48: Call a SAP CRM system from the backend layer ......................................................................... 185
Figure 49: Retrieve additional data from SAP ERP system to business object layer ................................... 186
Figure 50: Transfer additional data from business object layer to SAP ERP system ................................... 187
Figure 51: Call a SAP ERP system from backend layer ............................................................................... 188
Figure 52: Exchange additional data between business object layer and an IPC system ............................ 189
Figure 53: Exchange additional data with the web catalog ........................................................................... 190
Figure 54: Exchange additional data with the Java basket ........................................................................... 191
Figure 55: Action flow with CustomActions .................................................................................................. 193
Figure 56: BOBase class ............................................................................................................................... 200
Figure 57: Derive own class from existing Business Object.......................................................................... 201
Figure 58: Create own BOM .......................................................................................................................... 201
Figure 59: Creating own Business Object ..................................................................................................... 202
Figure 60: Creating own BOM ....................................................................................................................... 203
Figure 61: Creating interface for Business Object ......................................................................................... 204
Figure 62: Creating own Business Object Manager ...................................................................................... 204
Figure 63: Adding additional Function Modules ............................................................................................ 227
Figure 64: Java event listener for Standard Function Modules ..................................................................... 228
Figure 65: Replacing calls to Standard Function Modules ............................................................................ 230
Figure 66 The IPC and its UI in the CRM Online Landscape ........................................................................ 239
Figure 67 IPC Architecture more in detail ...................................................................................................... 240
Figure 68 General Action Flow ...................................................................................................................... 241
Figure 69 Example for layout with UI components from both files (layout-config and ipclayout-config) ....... 242
Figure 70 UI areas of the config UI ................................................................................................................ 242
Figure 71 Example for tiles ............................................................................................................................ 243
Figure 72 Combining low level layout and tiles ............................................................................................. 244
Figure 73 JSP Key and Path ......................................................................................................................... 245
Figure 74 Interaction of UIBeans with the JSP pages and the Busines Object Layer .................................. 247
Figure 75 XCM settings for customer buttons ............................................................................................... 249
Development and Extension Guide – SAP E-Commerce 7.3
October 2012 314
Figure 76 Customer buttons on screen ......................................................................................................... 250
Figure 77 Component configuration for customer tab ................................................................................... 251
Figure 78 Application configuration for customer tab .................................................................................... 252
Figure 79 Customer tab action mapping ....................................................................................................... 252
Figure 80 Customer tab with characteristic details ........................................................................................ 253
Figure 81 Creating UIBeans via UIBeanFactory ........................................................................................... 254
Figure 82 Standard customer exit in actions ................................................................................................. 255
Figure 83 Handling extension data at client objects ...................................................................................... 257
Figure 84: Main objects of the UpdateDocumentView module ..................................................................... 259
Figure 85: Activities of the isaPerform() method of the UpdateDocumentViewAction .................................. 260
Figure 86: Creation of a new order. (ISA B2B) .............................................................................................. 261
Figure 87: Display a new Document type with the UpdateDocumentView Module ...................................... 262
Figure 88: Original flow of actions ................................................................................................................. 270
Figure 89: Changed flow of actions ............................................................................................................... 271
Figure 90: Adding and configuring new parameter (XCM) ............................................................................ 279
Figure 91: XCM - parameter shorttexts ......................................................................................................... 282
Figure 92: Displaying name of JSP-Files in E-Commerce Applications ........................................................ 292
Figure 93: Calling the application with additional request parameters .......................................................... 298
Figure 94: Action flow of one request ............................................................................................................ 298
Figure 95: Original action flow ....................................................................................................................... 299
Figure 96: Interrupted action flow .................................................................................................................. 299