document version 1.0 january, 2016 - help.sap.com

Development and

Extension Guide

SAP E-Commerce

7.54 – Landscape,

Basics and

Concepts.

Document Version 1.0– January, 2016

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, SAP, SAP.com, xApps, SAP

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

June 2008 4

Contents

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

Development and Extension Guide – SAP E-Commerce 7.54: 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


January 2015 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.sap.isa.isacore.action.EComBaseAction ...................................................................................... 45 com.sap.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


January 2015 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................................................................................................... 82 Connection Types ................................................................................................................................. 82 Working with JCoConnections .............................................................................................................. 84

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


January 2015 7

Working with JCoFunctions ................................................................................................................... 86 Creating JCoFunctions ...................................................................................................................... 86

Executing JCo Functions ...................................................................................................................... 87

Configuration of BLS Layer ...................................................................................... 88

Configuring Connection Management ................................................................................................... 88 JCo Function Cache ............................................................................................................................. 88 Configuring Backend Objects ............................................................................................................... 91

Further Services 93

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

Generic Search Framework .................................................................................... 103

Main Components of the Generic search framework .......................................................................... 105 Details of component “generic-searchbackend-config.xml” ................................................................ 105 Details of component “GenericSearchBaseAction” ............................................................................. 112 Details of component “CRM_ISALES_SEARCH” ............................................................................... 112 ESelling specific implementation of the Generic Search Framework ................................................. 115

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

Initializing Location .......................................................................................................................... 119 Entering/exiting non trivial method .................................................................................................. 120 Throwing exception ......................................................................................................................... 120 DEBUG ............................................................................................................................................ 120 INFO/WARNING/ERROR/FATAL ................................................................................................... 120 Coding Examples ............................................................................................................................ 121

APIs for Tracing: SAP Logging API .................................................................................................... 121 Logging ................................................................................................................................................ 122 Usage of Categories ........................................................................................................................... 122 APIs for Logging: ISALocation ............................................................................................................ 123

INFO/WARNING/ERROR/FATAL ................................................................................................... 123 Detailed Message Descriptions ....................................................................................................... 123 Coding Examples ............................................................................................................................ 123

How to Log/Trace: Usage patterns ...................................................................................................... 124

All purpose Cache ................................................................................................... 130


January 2015 8

Working with the Cache ...................................................................................................................... 130

Initialization Handler ............................................................................................... 131

Extended Configuration Management (XCM) 133

Separation of Customer and SAP Configuration Files ......................................... 133

Separation of Configuration Data and Modification Data .................................... 134

XCM Extension Mechanism .................................................................................... 134

Web Application Configuration and Components ................................................ 136

SAP Java Remote Function Call (JRFC) ................................................ 137

Technology 137

Development Environment ..................................................................... 138

Development Tools and Concepts 139

External documentation .......................................................................................... 139

Additional information ............................................................................................ 139 Netweaver Developer Studio ............................................................................................................... 140 NWDS, SLD, and CMS track definition ............................................................................................... 140 Software component for own development ......................................................................................... 140

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

Initial Configuration of the NWDI 145

Pre-requisites........................................................................................................... 145

Creating a project specific Web Application with own context root 145

Basic concept .......................................................................................................... 146

Step by step process .............................................................................................. 146

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

Creation or Extensions of Java Classes ............................................................... 151

Importing Modifications and Extensions from older Releases ........................... 152

Developer Workplace 156

Required tools and versions .................................................................................. 157

Java Development Kit ............................................................................................. 157

Installation of JDK 1.8.0 ...................................................................................................................... 157

Developer Workplace for SAP NetWeaver 7.5....................................................... 158 Installing the Developer Workplace for SAP NetWeaver 7.5 .............................................................. 158


January 2015 9

Directory Structure of the NetWeaver AS Java 7.5 ............................................................................. 159 TCP-Ports ............................................................................................................................................ 160 Starting and Stopping the NW AS Java .............................................................................................. 161 Configuration of SAP NetWeaver AS Java 7.5 ................................................................................... 161 Uninstalling the Developer Workplace for SAP NetWeaver 7.5 .......................................................... 161

Configuring and Working with Developer Studio ................................................. 162

Configuration of the web application ................................................................................................... 162

Remote Debugging 163

Setting up remote debugging for SAP NW AS Java 7.5 ....................................... 163 Enabling/Disabling Debug Mode Permanently .................................................................................... 163 Enabling/Disabling Debug Mode Temporarily ..................................................................................... 164 Starting Remote Debugging ................................................................................................................ 166

ABAP Debugging 167

Activating ABAP Debugging .................................................................................. 168

Java Debugging 168

Introduction to Extension Concepts ...................................................... 169

Extensions in the ISA Framework 169

Finding the Appropriate Extension Concept......................................................... 171

How to use these diagrams ................................................................................................................. 171 Overview .............................................................................................................................................. 171 Extensions to the UI Layer .................................................................................................................. 172 Extensions to the Action Flow ............................................................................................................. 173 Extensions to Exchange Additional Data ............................................................................................ 174 Extensions to Exchange Data with the UI-Layer ................................................................................ 175 Extensions to Exchange Data with Backend-Systems ....................................................................... 180

Extensions to the UI layer ....................................................................................... 190

Accessing the Session Context ........................................................................................................... 190 Accessing the Request Context .......................................................................................................... 190

Extensions in the Action Flow................................................................................ 190

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

Business Object Layer ............................................................................................ 197

Storing Additional Data - Extension Mechanism ................................................................................. 197 Version ................................................................................................................................................ 198 Example .............................................................................................................................................. 199 Extending existing Business Objects .................................................................................................. 199 Version ................................................................................................................................................ 200 Create a Customer Business Object ................................................................................................... 200 Version ................................................................................................................................................ 201 Example .............................................................................................................................................. 201 Create a Customer Business Object Manager .................................................................................... 201 Version ................................................................................................................................................ 203 Example .............................................................................................................................................. 204

Business Logic Service Layer ................................................................................ 204

Create a Customer Backend Object .................................................................................................... 204 Standard Backend Objects providing User Exits ................................................................................ 204 Creating new Customer Backend Objects .......................................................................................... 208


January 2015 10

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

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

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

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

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

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

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

Version ................................................................................................................................................ 225

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

Replacing Calls to Standard Function Modules (Backend System) ................... 227 Version ................................................................................................................................................ 228 What to Do ........................................................................................................................................... 228 Example ............................................................................................................................................... 229

Extension of the Web Catalog 229

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

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

New Fields in the Web Catalog (SAP ERP Backend and Memory Catalog) ....... 231

Loading additional Product Attributes from the SAP ERP Backend to the Memory Catalog .............. 231


January 2015 11

Version ................................................................................................................................................ 231 Example ............................................................................................................................................... 231

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

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

Extensions of the IPC 237

Architecture of the IPC 5.0 UI in CRM Order Scenario ......................................... 237

Action Flow .............................................................................................................. 239

Use of the E-Commerce Layout Framework ......................................................... 239 UI Components .................................................................................................................................... 239 UI Layouts ........................................................................................................................................... 239 UI Areas ............................................................................................................................................... 240 Tiles ..................................................................................................................................................... 241 Low level layouts ................................................................................................................................. 241

Dynamic Includes .................................................................................................... 242

Extension To Transfer Data To JSP .................................................................................................... 244

UIBeans .................................................................................................................... 244

Client Object Layer .................................................................................................. 245

Finding The Appropriate Extension Concept For IPC .......................................... 245

Static extension to UI layer ..................................................................................... 246 Changing Stylesheets ......................................................................................................................... 246 Create New Layout Or Change Standard Layout ............................................................................... 247

Change UI Components .......................................................................................... 247

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

Extensions To The UIBean Layer ........................................................................... 250

Extensions In The Action Layer ............................................................................. 251

Create Customer Backend Object .......................................................................... 253

SCE user functions ................................................................................................. 254

Exchange additional data with ECO ...................................................................... 254

Extensions of the Document Handling 255

Overview .................................................................................................................. 255

Implementation ........................................................................................................ 255

Example ............................................................................................................................................... 257

Integrating own documents .................................................................................... 259

PrepareNewDocAction ........................................................................................................................ 260 Creating a ManagedDocument ........................................................................................................... 260 PrepareNewDocAction ....................................................................................................................... 262

Structure of the Internet Sales application ........................................................... 263

Enterprise Application Archive (ear file) .............................................................................................. 263 Web Archive (war file) ......................................................................................................................... 263 Configuration files ................................................................................................................................ 264

Source Code ............................................................................................................ 266

General Package Structure of an E-Commerce application ............................................................... 266

Conventions when Enhancing the E-Commerce Application 267


January 2015 12

Separation of SAP-Software / Customer Extensions ........................................... 267

Naming Conventions ............................................................................................... 267

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

Changes in Configuration 273

Application Configuration and Component Configuration .................................. 273

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

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

Configuration of Dynamic fields in E-Service ....................................................... 281

Generic Search Framework ................................................................................................................ 284 E-Service Extended Complaints and Returns specific implementation of the Generic Search Framework ........................................................................................................................................... 285

Checking configuration during runtime ................................................................ 287

Best Practices .......................................................................................... 288

Getting Information about the Application 288

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

Session Tracing 291

Configuring session tracing ................................................................................... 291

Enabling session tracing ........................................................................................ 291

Tracing Function Modules ................................................................................................................... 292

Additional Request Parameters 293

General Request Parameters ................................................................................. 293

ECO Version ........................................................................................................................................ 294 Example ............................................................................................................................................... 294

Request parameters for B2C .................................................................................. 294

ECO Version ........................................................................................................................................ 294 Example ............................................................................................................................................... 294

Single Session Trace .............................................................................................. 295

Passing Data between Actions 295

Action Flow Remains on the Server ...................................................................... 295

Action Flow is Interrupted by a JSP ...................................................................... 296


January 2015 13

Working with Request Parser 296

Writing Thread Safe Code 297

Administration Console 298

Getting Application Version ................................................................................... 298

Logging .................................................................................................................... 298

Updating Application 299

Web Diagrams .......................................................................................... 300

Syntax of Web Diagrams 300

B2B - Start Page 301

B2B - Create Basket 302

B2B - Display Order Status 303

References ............................................................................................... 304

Update History ......................................................................................... 304

Table Index ............................................................................................... 305

Figure Index ............................................................................................. 308


January 2015 14

Development and Extension Guide – SAP E-Commerce 7.54: Landscape, Basics and Concepts In SAP CRM 7.0, the Development and Extension Guide for SAP E-Commerce has been split 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 current document covers information valid for E-Commerce 7.54.

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 and higher releases.

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 Enhancement Package 4 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 SAP CRM is used, when the E-Commerce application is connected to a CRM System (ECO CRM).

The term SAP E-Commerce for SAP 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.

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


January 2015 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 higher).

<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. NW 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 NetWeaver Application Server Java with the SAPInst.

<INSTANCE_NUMBER> Instance number of your SAP NW AS, which you entered during installation with the SAPInst.

<INST_DIR> Installation directory for the SAP system. If you have installed the SAP NW 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 TCP-Ports

Table 1: List of the variables used in this guide


January 2015 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.54 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


January 2015 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.


January 2015 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 SAP 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


January 2015 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.

http://www.mindview.net/

http://www.oracle.com/technetwork/java


http://www.jguru.com/



news:de.comp.lang.java

news:comp.lang.java


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


January 2015 21

SAP NetWeaver Application Server Java

The SAP NetWeaver Application Server Java is part of the SAP NetWeaver 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.


January 2015 22

E-Commerce Framework E-Commerce 7.54 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.


January 2015 23

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

.

Figure 3: SAP E-Commerce for SAP CRM architecture

Web Browser

Java Stack

NW AS Java

ABAP Stack

NW 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


January 2015 24

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

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

In case you use an older ERP or R/3 release, the architecture of SAP E-Commerce for SAP ERP might be different, since the IPC Engine has to be installed in an SAP NetWeaver 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

NW AS Java

ABAP Stack

NW 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


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


January 2015 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 in the source archive at http://archive.apache.org/dist/struts/struts-1.1/).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.


January 2015 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.


January 2015 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.


January 2015 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’ />


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


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


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


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

Example:

Key in your XLF file (see chapter “Changing language dependand resource keys” for more details):

system.initFailed=Initalization of {0} failed

The result at runtime is as follows:

Initalization of logging configuration failed

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

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

</isa:webappsURL>

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

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

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

</isa: webappsURL>


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


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


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>


January 2015 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 288

Parameters


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

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


January 2015 34

Parameters:


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.


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


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


January 2015 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”) />

...


January 2015 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 169.

UIController uiController = UIController.getController(userSessionData);

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

// disable the field for output:

uiElement.setAllowed(true, UIELEMENT.PR_AUTHORITHY);


January 2015 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 190)

Figure 10: Actions within ECO Framework

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

The base class of each org.apache.struts.action.Action contains a reference to 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


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

}

}


{

private ArrayList mArray;




{

// doing something with mArray

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

}

}


January 2015 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 296).

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.


{

private ArrayList mArray;




{

synchronized(mArray)

{

// do something with mArray

} // synchronized(mArray)

} // public ActionForward doPerform

} // class myAction

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



<servlet-mapping>

<servlet name>action</servlet name>

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

</servlet-mapping>



<servlet>

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

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

<init-param>

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

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

/WEB-INF/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>


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


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

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


January 2015 45


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.sap.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’);

}

}


January 2015 46

com.sap.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>


January 2015 47


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


January 2015 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 169.

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.


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


empty string none or all


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


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


January 2015 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)


January 2015 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 93.

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.


January 2015 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);

%>


January 2015 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” />


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>


January 2015 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.sap.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>


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


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


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


January 2015 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:


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


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


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

...

</action>


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


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


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

...

</action>


January 2015 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.sap.isa.isacore.action.EComGetForwardAction">

<forward name="catalog"

path="UILayout:catalogLayout"/>

<forward name="basket"

path="UILayout:basketLayout"/>

...

</action>

<action path="/base/updateBasket"

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

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

</action>


January 2015 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.sap.isa.isacore.action.marketing.ShowCatalogEntryAction">

<forward name="showcatalogentry"

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

</action>

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

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

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

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

...

</action>

<% String workarea = " workarea "; %>

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


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

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

contextValue=”true”/>

</isa.webappsURL>


January 2015 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" />


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.sap.isa.isacore.action.marketing.ShowCatalogEntryAction">

<forward name="showcatalogentry"

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

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

</action>


January 2015 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" />


cssIdName="minibasket" />

</UILayout>

</UILayouts>

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


January 2015 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.sap.isa.isacore.action.b2c.CheckLoginAction">

<forward name="login"

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

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

</action>


January 2015 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.sap.isa.isacore.action.b2c.DisplayLoginAction">

<forward name="succes"

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

</action>

January 2015 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.sap.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.sap.isa.isacore.action.b2c.LoginAction">

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

</action>



<action path="/base/getCoreForward"

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

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

</action>


January 2015 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.


January 2015 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);

}

January 2015 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.



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


January 2015 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="<%=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);


January 2015 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">


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>


January 2015 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.


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


January 2015 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.


January 2015 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.


January 2015 76

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


January 2015 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.


January 2015 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.


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;


January 2015 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 88 and chapter 'Changes in backendobject-config.xml' on page 274.

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.

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=‘ISAStateless’>

<params>

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

</params>

<businessObject/>


January 2015 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()

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

Connection Management

Design Considerations

With regards to security and product standards, E-Commerce 7.54 uses the SAP Java Connector 3.0 API for backend communication. However, the JCo API is not called directly, but the SAP NetWeaver Destination Service is used.

Each destination represents one connectivity end-point at a target system. The destination service provides a secure storage for the connection properties. The properties of the destinations can be changed programmatically via the destination service API, but also manually via the destination service UI that is integrated in the NetWeaver Administrator (short: NWA).

More detailed information on the new way of defining connection definitions can be found in the Guide “JCo 3.0 in Web Channel 7.54”. It provides not onlydetails on configuration, but also covers the migration steps required in oder to adapt RFC calls implemented based on a prior version of the JCo API towards JCo 3.0.

The correct connection respectively destination will be provided by the Destination Service. In

JCoManagedConnectionFactory the correct destination will be determined.


January 2015 81

Figure 20: Destination Determination with JCo 3.0

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.

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 is done via destination service

o Destination assignment 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 to do for connection handling. Three main steps are nececessary: configuring the connection parameters in NWA, configuring the destination in XCM and assigning the connections within backend objects.

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

RFC based connectivity using SAP Java Connector (JCo)

JDBC based connectivity to a database


January 2015 82

Working with JCo Based Connectivity

Within the BLS layer you never work directly on JCo Destinatons (JCoDestination).

Instead, you work on connections of type

com.sap.isa.core.eai.sp.jco.JCoConnection, which is part of the ISA Framework.

Only this ensures that the BLS layer can take care of connection handling/cleanup correctly.

JCoConnection

+getJCoFunction(funcName : String)

+execute(function : JCO.Function)

+isValid() : boolean


+getDefaultJCoConnection()

+getModDefaultJCoConnection(conProps : Properties)

+getConnectionFactory() : ConnectionFactory

0..n

ConnectionFactory

+getConnection()

1..1

0..n

MyBackendObject

Figure 21: 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 within the SAP NetWeaver Administrator via:

https://<host>:<port>/nwa Availability and Performance Resource Monitoring JCo Monitoring)

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 167


January 2015 83

Assigning connections to Backend Objects: chapter 'Configuring Backend Objects' on page 91.


January 2015 84

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. Handle Exceptions in order to react to errors that occurred during backend communication.

Explicitely closing the JCoConnection is no longer required as of JCo API 3.0. The connection lifecycle is completely handled and controlled by the NW now.

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 'Configuring Backend Objects' on page 91.

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.

JCoConnection con = null;

try {

// Step1: Obtain a connection

con = getDefaultJCoConnection();

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

JCoFunction func = con.getJCoFunction(‘RFC_PING’);

con.execute(func);

} catch (BackendException ex) {

//... error handling of BLS layer

} catch (AbapException) {

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

} finally {

// Step3: Close the connection

con.close();

}

JCoConnection con = getDefaultJCoConnection();


January 2015 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 JCoFunctions

After getting a JCoConnection, this instance is used to get/execute JCoFunctions. The appropriate

steps are described in this chapter.

Creating JCoFunctions

A JCoFunction is used to execute remote callable function modules in an SAP system. You obtain a

reference to a JCoFunction object by calling the following method:

Properties conProps = new Properties();

conProps.setProperty(‘user’, webUser);

conProps.setProperty(‘passwd’, webUserPassword);

JCoConnection mJCoCon =

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

JCoConnection mJCoCon = (JCoConnection)getConnectionFactory()

// get connection from JCO connection factory

getConnection(‘JCO’, ‘ISAStateless’);

Properties props = new Properties();

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

JCoConnection = getModDefaultJCoConnection(props);

JCoFunction JCoConnection .getJCoFunction(String)


January 2015 86

The BLS layer serves the JCoFunction 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 JCoRepository. Let the BLS layer do it for you

Example:

Executing JCo Functions

JCo functions are executed using the following method:

Take care of execptions when executing JCo functions: The signature of the execute method is as follows:

execute(JCoFunction func) throws BackendException;

The basic JCoException (encapsulating all types of errors that might occur during an RFC

call) does no longer inherit from RuntimeException. As a result, they can only be catched in

cases they were thrown explicitly before.

ABAP exceptions that are explicitely thrown by function modules get encapsulated within

BackendFMExceptions

Therefore, please do not forget to catch the BackendException and BackendFMException if you call ABAP function modules and you expect that the Function Module throws an ABAP exceptions.

Example:

JCoFunction myFunc;


myFunc = con.getJCoFunction(‘SAP_BASKET’);

JCoConnection.execute(JCoFunction);


January 2015 87

Always use JCoConnection for executing the JCoFunction instead of calling JCo API directly. Only this ensures that the application can fully utilize services provided by the BLS layer (for example, JCoFunction 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 274.

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 JCoFunction (for further information about JCo see [4] SAP Java Connector: On the

SAP Service Marketplace: https://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.

JCoFunction myFunc;


myFunc = con.getJCoFunction(‘SAP_BASKET’);

try {

con.execute(myFunc);

} catch (BackendException bex) {

// system error

} catch (BackendFMException abapEx) {

// application error in SAP system

}


January 2015 88

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:

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:

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

<logon client to SAP system e.g. 805> + <logon language to SAP system> + <string

representation of import parameters> + <JCO function name>


January 2015 89

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


January 2015 90

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

Backend Objects are registered using the businessObject XML element.

The businessObject element has the following attributes:


type Specifies the type of the Backend Object, (for example, BASKET). The value of the type attribute must 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

JDBC: for JDBC based connectivity to a

database

Connection parameters for all these types are defined in XCM respectively its assigned destination (in case of JCO)

If you omit this parameter, then null is returned when

calling getDefaultConnection().

No

Table 25: Attributes of BusinessObject elements


January 2015 91


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)

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’



<params>

<param name=‘distributable’ value=‘NO’/>

<param name=‘catalogSiteConfigFile’ value=‘WEB-INF//cfg//catalog-site-configR3.xml’/>

<param name=‘isClassPath’ value=‘false’/>

</params>

</businessObject>


January 2015 92

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 100) for details.


January 2015 93

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");

JCoTable 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);


January 2015 94

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");

JCoTable messages =

profTemplCharGet.getTableParameterList().getTable("MESSAGES");

attributeSet.clearMessages();

MessageCRM.splitMessagesToTarget(attributeSet,messages);


January 2015 95

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>


January 2015 96

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

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 {

JCoFunction function = connection.getJCoFunction(moduleName);

...

return new JCoHelper.ReturnValue(null, "");

}

catch (JCoException ex) {

JCoHelper.splitException(ex);

}

finally {

log.exiting();

}


January 2015 97


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 101).

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 100).

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;


January 2015 98

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 100) 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 99) 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" %>

January 2015 99

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

<% } %>



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

January 2015 100

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



<initialization className="com.sap.isa.ui.UIInitHandler">

<param name="simple-header" value="/shopadmin/simpleheader.inc.jsp"/>

</initialization>

<!— support of the global init action -->

<action path="/init.do" forward "/b2b/init.do"/>



<global-forwards>

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

<forward name="message" path="/appbase/message.jsp"/>

<forward name="backenderror" path="/appbase/backenderror.jsp"/>

<forward name="session_not_valid" path="/base/relogin/getcookie.do"/>

<forward name="runtimeexception" path="/appbase/runtimeexception.jsp"/>

<forward name="panicexception" path="/appbase/panicexception.jsp"/>

</global-forwards>


January 2015 101

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;

}

}


January 2015 102

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


January 2015 103

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

January 2015 104

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>

January 2015 105

Next part defines a search screen. A search screen is packed within a <property-group> tag.

 <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."/>


January 2015 106

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.


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.


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)


January 2015 107

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


January 2015 108

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.


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.


value - Static value which will be added as select option to a <html> select box (e.g.


January 2015 109

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


January 2015 110

Allowed attributes for tag <property-group> describing a result list.


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.


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


January 2015 111

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


January 2015 112

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


January 2015 113

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.


January 2015 114

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


January 2015 115

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");


January 2015 116

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 22: 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, 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 an older ECO release).

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


January 2015 117

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.


January 2015 118

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 can use the ISALocation or SAP Logging API. What ever you prefer more.

Initializing Location

or

private static final IsaLocation log = IsaLocation.getInstance(ClassName.class.getName());

private static final IsaLocation log = IsaLocation.getInstance(ClassName.class);


January 2015 119

Entering/exiting non trivial method

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

INFO/WARNING/ERROR/FATAL

Use the following methods to write trace messages with the severity level “ERROR”:

The same methods are available for all the other severity levels.

public void entering(String method)

public void exiting()

public void throwing(String message, Throwable th)

public void throwing(Throwable th)

public void debug(Supplier<String>)

public void debug(Object, Object...)

public void debug(Object, Throwable)

public void debug(Throwable, Object, Object...)

public void error(Supplier<String>)

public void error(Object, Object...)

public void error(Object, Throwable)

public void error(Throwable, Object, Object...)

public void error(Object, Object[], Throwable)

public void error(Throwable)


January 2015 120

Coding Examples

Strings are traced as passed to the methods (resource keys can be used as well).

APIs for Tracing: SAP Logging API

The latest documentation about the SAP Logging API can be found at help.sap.com.

protected static IsaLocation log =

IsaLocation.getInstance(ClassName.class.getName());

// simple developer trace

log.debug("This is a trace message");

// extensive developer trace using a supplier (Java 8). The method inside

// will only be called if the logging level is set to debug.

log.debug(() -> generateComplicatedTraceMessage());

// 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); // the resource key will be translated via I18N

// Using String formatter and varargs for your messages

log.debug(ex, "This is a trace message with value 1: %s and value 2: %s", myval1, myval2);

http://help.sap.com/saphelp_nw74/helpdata/en/48/47e2c0ccaf31c3e10000000a42189d/content.htm


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


/Applications/Common/Infrastructure everything related to infrastructure i.e. generic services (JCo, cache, database, etc.)


/Applications/UserInterface User Interface Layer (e.g. JSPs)


/Applications/BusinessLogic functionality dealing with business logic (e.g. E-Commerce Business Objects)


/Applications/Interaction classes controlling the interaction with the user (e.g. Struts actions)


Table 30: Categories for Logs


January 2015 122

APIs for Logging: ISALocation

INFO/WARNING/ERROR/FATAL

Use the following methods to write log messages with the severity level “ERROR”:

The same methods are available for all the other severity levels.

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 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 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"));


January 2015 123

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.

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.

// 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();

}


January 2015 124

Example

4.

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

// If Trace throwing exception using ISALocation

private static final ISALocation loc = ISALocation.getInstance(ClassName.class.getName());

// If Trace throwing exception using SAP logging API


// …

public void methodX() throws MyException {

//…

final String msg = “information about the exception”;

MyException err = new MyException(…);

loc.throwing(msg, err);

}


January 2015 125

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


// …

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;

}

//…

}


January 2015 126

Example

Throwing a wrapper exception.

In case of throwing a wrapper exception, you should:

User severity level ERROR or FATAL

Trace the throwing exception

// If Trace recover from caught exception using ISALocation


// If Trace recover from caught exception using SAP logging API


// …

public void methodX() {

//…

try {

// do something …

} catch (InternalException ex) {

// If using ISALocation

log.warning(Category.Applications, "messageKey", args,ex);

log.info(“Do something to recover from exception”);

// perform recover/alternate operation

}

//…

}


January 2015 127

Example

6. Never hide exceptions you cannot handle.

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


// If Trace the throwing a wrapper exception using SAP logging API


// …

public void methodX() throws WrapperException {

//…

try {

// do something …

} catch (SQLException ex) { // If using ISALocation

log.error(Category.APP_COMMON_SECURITY,"messageKey", args, ex);

// log context information to help in error support

WrapperException wrapperEx = new WrapperException(ex);

log.throwing(wrapperEx, “messageKey”, args);

throw wrapperEx;

}

//…

}


January 2015 128

Example

// If Trace the throwing a wrapper exception using ISALocation


// If Trace the throwing a wrapper exception using SAP logging API


// …

public void save() throws DBException {

//…

try {

// start transaction

log.info(“started transaction for user”, new Object[]{user});

// perform some sql operation …

// commit transaction

log.info(“commited transaction”);

log.info(Category.Applications,”saved business object {0}”, new Object[]{obj});

} catch (SQLException ex) { // If using ISALocation

log.error(Category.APP_COMMON_SECURITY,”Error saving business object {0}”,

new Object[]{obj});

log.error(Category. APP_COMMON_SECURITY,”error.sqlerror”, ex);

// rollback transaction

log.info(“rollbacked transaction”);

DBException wrapperEx = new DBException(ex);

log.throwing(“messageKey”,args,wrapperEx);

throw wrapperEx;

}

//…

}

January 2015 129

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>



<xi:include href=‘${sap}/modification/cache-config.xml#xpointer(cache/regions/*)’/>



<region name=‘Z_AcmeCache’ idleTime=‘60’ timeToLive=‘300’ descr=‘Project ACME cache’/>

</regions>


January 2015 130

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

}


January 2015 131

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

January 2015 132

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

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

Example

This is the customer version of the file init-config.xml:

<initializations xmlns:isa=‘com.sap.isa.core.config’

xmlns:xi=‘http://www.w3.org/2001/XInclude’

xmlns:xml=‘http://www.w3.org/XML/1998/namespace’>



<xi:include href=‘${sap}/modification/init-config.xml#xpointer(initializations/*)’/>

</initializations>

http://localhost:50000/%3cweb%20application%3e/admin/xcm/init.do


January 2015 133

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.

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’


January 2015 134

The following example illustrates how the extension mechanism works:

The node with the id TestConfigData extends the node with id configdata.

You read the path to the base node as follows:

'..' means go back one node. After performing this you are in the configs node.

/config[@id='configdata'] means go to node named 'config' with attribute 'id' having value 'configdata'.

<configs>

<config id=“configdata“>

<params id=“logoncrm“>

<param name=“user“ value=“john“/>

<param name=”password” value=”secret”/>

</params>

</config>

<config id=“TestConfigData“ isa:extends=”../config[@id=’configdata’]”>


<param name=“password“ value=“topsecret“/>

<param name=”language” value=”de”/>

</params>

</config>

</configs>


January 2015 135

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 refers to the destination that stores the connection parameters to the SAP system)

Refer to chapter ‘

<configs>

<config id=“configdata“>


<param name=“user“ value=“john“/>

<param name=”password” value=”secret”/>

</params>

</config>

<config id=“TestConfigData“ isa:extends=”../config[@id=’configdata’]”>


<param name=“password“ value=“topsecret“/>

<param name=”language” value=”de”/>

<param name=”user” value=”john”/>

</params>

</config>

</configs>


January 2015 136

Extending XCM with Customer Settings’ to get information how to do custom extensions in the XCM.


January 2015 137

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

As of E-Commerce 7.54 (based on NW 7.5) the SAP JCo API of version 3.0 is used for backend communication.

The API is not directly called, instead the destination service is leveraged. See Chapter

The destination service is integrated into SAP NetWeaver and offers a single central service for managing client side information required to connect to (backend) services. It provides a secure storage for the connection properties. Each destination represents one connectivity end-point at a target system.


January 2015 138

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.5 Java Development Infrastructure (NWDI)

NetWeave 7.5 Java Integrated Development Environment (IDE)

NetWeaver 7.5 Java Application Server

CRM 7.54 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.


January 2015 139

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

Application Help Function-Oriented View Application Server Application Server Java Administering Application Server Java

Additional information If you did development for CRM 7 on NW 7.0 before you should be aware of the following points

http://help.sap.com/saphelp_nw75/helpdata/en/82/c701ea566e4f8ab1f279f5c1b20f71/content.htm

http://help.sap.com/saphelp_nw75/helpdata/en/b8/a2a1484cf843adb126f0628652eef0/frameset.htm

http://help.sap.com/saphelp_nw75/helpdata/en/49/1ce7ae096d16b8e10000000a42189d/content.htm?

http://help.sap.com/saphelp_nw75/helpdata/en/4c/20a62a213c5793e10000000a15822b/content.htm

http://help.sap.com/saphelp_nw75/helpdata/en/49/1006013d9d132ee10000000a421937/content.htm

http://help.sap.com/saphelp_nw75/helpdata/en/48/c46505095735b6e10000000a42189d/frameset.htm

http://help.sap.com/saphelp_nw75/helpdata/en/48/c46583095735b6e10000000a42189d/content.htm?

http://help.sap.com/

https://help.sap.com/nw75


January 2015 140

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. The pop ups will be gone as soon you have performed a proper conflict resolution.

NWDS, SLD, and CMS track definition

Please make sure to

Use the dependencies to the NW 7.5 libraries

Use JDK 1.8 instead of 1.4 or 1.6 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 Creating a Software Component in the SLD

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.

http://help.sap.com/saphelp_nw74/helpdata/en/49/1966e569cd3896e10000000a421937/content.htm


January 2015 141

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 SAP 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-CRMJAV.sca

sap.com~SAP-SHRJAV.sca

are designed not to be modified in the NWDI. They are required for compiling and building the applications or implementing patches from SAP.


January 2015 142

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.

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

SAP-CRMJAV.sca No No Yes Contains the Java classes required for compiling and building.

SAP-SHRJAV.sca No Yes Yes Contains the Java classes required 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.

The software components SAP-CRMJAV and SAP-SHRJAV must be imported as development component if you want to use the Java Patch functionality (JNote).

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), 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.

Open the Software Component SAP-SHRWEB or SAP-CRMWEB


January 2015 143

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.

Figure 23: 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 (or create your own DC/SC)

• 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 is 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.

Open the Software Component 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.

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.


January 2015 144

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 24: 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 must not contain java source files.


January 2015 145

Initial Configuration of the NWDI This section describes how to configure the NWDI 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 25: 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


January 2015 146

• 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 NW AS Java System by NWDI.

The SAP standard component SAP-CRMDIC, SAP-SHRAPP and/or SAP-CRMAPP can be deployed directly to the NW 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 for your release 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 will find more information about SLD and maintenance of Software Dependencies at http://help.sap.com



January 2015 147

Create a new Track using the Landscape Configurator

On the “Track Data” tab of the Landscape Configurator, enter the general data as shown below:

Figure 26: 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)

If you want to use Java Patching functionality:

SAP-CRMJAV (Package Type: Source + Archive)

SAP-SHRJAV (Package Type: Source + Archive)

An example is shown below:


January 2015 148

Figure 27: Adding Software Component

After this step, the bottom half of this tab will look as shown below:

Figure 28: 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 with the title Configuring Runtime Systems.

Import Software Components into this track

Download Archives

The Software Component archives ( .sca files ) must be downloaded from the Service Marketplace ( http://support.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 available in the CMS inbox folder:

o SAP-SHRJAV.sca o SAP-SHRWEB.sca o SAP-SHRAPP.sca o SAP-CRMJAV.sca o SAP-CRMWEB.sca

http://help.sap.com/saphelp_nw74/helpdata/en/4d/a75bd31fb4548de10000000a15822b/content.htm

http://help.sap.com/saphelp_nw74/helpdata/en/4d/a75bd31fb4548de10000000a15822b/content.htm

http://support.sap.com/patches


January 2015 149

o SAP-CRMAPP.sca o SAP-CRMDIC.sca o ENGFACADE.sca o ENGINEAPI.sca o FRAMEWORK.sca o FRAMEWORK-EXT.sca o SAP_BUILDT.sca o STRUTS.sca

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 29: 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 30: 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”


January 2015 150

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.

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.


January 2015 151

Test the CRM Java application on a local NW 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 NW 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.


January 2015 152

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.pdf”

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.


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


January 2015 153

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.


January 2015 154

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


January 2015 155

Synchronize SC Dependencies in CMS

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 Resolving Inconsistencies or in SAP note 1693378.

http://help.sap.com/saphelp_nw74/helpdata/de/49/1d57ac50b23896e10000000a421937/content.htm

http://help.sap.com/saphelp_nw74/helpdata/de/49/1d57ac50b23896e10000000a421937/content.htm


January 2015 156

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

Developer Workplace When we look at the architecture of SAP E-Commerce 7.54 we will discuss the following components:

Java Development Kit (JDK)

SAP NW AS Java

o SAP J2EE Application Server

o SAP Java Connector (JCo)

o SAP Java Basis

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 31: Overview Developer Workplace


January 2015 157

Required tools and versions SAP CRM 7.0 EHP 4 is based on SAP NetWeaver 7.5. There the following software component versions are contained or required:

Component Version

SAP NetWeaver AS Java 7.5

JDK 1.8.0

IDE SAP NetWeaver 7.5 Developer Studio

Java Development Kit The Java Development Kit represents the Java Virtual Machine (JVM), which is a prerequisite for the SAP NW AS Java (Servlet Engine). In addition, JDK offers options for compiling, executing and debugging Java applications.

Installation of JDK 1.8.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’!

Once j2sdk-1_8_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.8.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.

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-javase6-419409.html


January 2015 158

Developer Workplace for SAP NetWeaver 7.5 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 32: Developer Workplace for SAP NetWeaver

Installing the Developer Workplace for SAP NetWeaver 7.5

As of SAP NetWeaver 7.3, Composition Environment (and by that the Developer Workplace) has become part of the overall NetWeaver platform. You can find more information in the according Master Guide for NetWeaver 7.5.

Note 226948 provides information on how to install or update the SAP NetWeaver Developer Studio 7.5.

https://support.wdf.sap.corp/sap/support/notes/2226948


January 2015 159

Directory Structure of the NetWeaver AS Java 7.5

Once it has been installed, the directory of the NetWeaver 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 NW Configuration Tool

Figure 33: Directory Structure of NW AS Java 7.5


January 2015 160

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)


January 2015 161

Example

The SAP NW AS 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 NW AS Java

Since NetWeaver’04, the SAP Management Console is used to start and stop the NW AS Java. Each NW AS Java consists of two nodes:

The Central J2EE Instance and

The database instance.

To start/stop the NW AS Java, open the SAP Management Console, select the NW AS Java Instance and press the start/stop button in the button bar.

Figure 34: SAP Management Console

Configuration of SAP NetWeaver AS Java 7.5

The SAP NW AS Java 7.5 can be configured using the configuration tool or the NetWeaver Administrator under the alias /nwa.

Uninstalling the Developer Workplace for SAP NetWeaver 7.5

How to uninstall the Developer Workplace for SAP NetWeaver 7.5 is described in Appendix of the “Installation Guide - Developer Workplace for NW7.5”, that is available on the SAP Service Marketplace

Central J2EE Instance

Database Instance

January 2015 162

quick link instguides (http://service.sap.com/instguides) SAP NetWeaver Release 7.5 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 E-Commerce 7.54 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.



<servlet-mapping>

<servlet name>action</servlet name>

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

</servlet-mapping>

http://service.sap.com/instguides

http://localhost:50000/%3cAPPLICATION_NAME%3e/admin/xcm/init.do

http://localhost:50000/b2b/admin/xcm/init.do

http://localhost:50000/nwa

http://localhost:50000/b2b/b2b/init.do


January 2015 163

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 NW AS Java 7.5 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 NW AS (either temporarily or permanently)

- Start Remote Debugging

Enabling/Disabling Debug Mode Permanently

To enable/disable the debug mode of the SAP NetWeaver Application Server Java 7.5 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 35: Offline Config Tool - Setting Up Debug Mode


January 2015 164

Enabling/Disabling Debug Mode Temporarily

To enable/disable the debug mode of the SAP NetWeaver Application Server Java 7.5 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 36: 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”


January 2015 165

Figure 37: J2EE Engine - Enabling Debugging


January 2015 166

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 38: 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.


January 2015 167

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:


January 2015 168

Activating ABAP Debugging

1. Start the SAPGui

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

4. Open your ABAP coding and set an External Breackpoint by pressing CTRL+Shift+F9 or by pressing

the button Set/Delete External Breakpoint .

5. Start Transaction SRDEBUG and click on “Activate Debugging” in order to enable debugging across application servers.

6. Enter the same user ID like above and choose “External breakpoints already set”. Alternatively, you can also define new breakpoints for classes or function modules.

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


January 2015 169

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 304).

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


January 2015 170

CustomAction

Custom

BusinessObject

Custom

BackendObject

Custom

Function Module

customer data

has to be entered

or displayed

Possible

extensions in

all layers

Figure 39: 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.


January 2015 171

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 40: Overview of different categories of extensions


January 2015 172

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 41: Statis extensions to the UI layer

For details see:

Chapter Extensions to the UI layer on page 190

Chapter ‘Extensions Limited to the UI Layer’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 304) with examples for extension


January 2015 173

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 42: Extensions to the action flow

For details see:

1) Standard Actions providing User Exits on page 193

2) Create a Customer Action on page 191

3) Modifications in the Struts Configuration

on page 197


January 2015 174

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?


be displayed or should

be entered on the UI


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 43: Extensions to exchange additional data


January 2015 175

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 44: Extensions to exchange data with UI layer

For details see:

1) ‘Extensions to the UI layer’ on page 190 and chapter ‘Extensions Limited to the UI Layer’ in the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 304).


January 2015 176

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 45: Transfer additional input data to action class and business object layer

For details see:




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 197

5) Create a Customer Business Object on page 200


January 2015 177

6) Request Context on page 222

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 304).


January 2015 178

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.


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.


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 46: Transfer additional output data from aciton class to JSP

For details see:


2) Create a Customer Action on page 191 and Modifications in the Struts Configuration on page 197


January 2015 179

Table 38: User exits within the Remanufacturer’s Inspection Application

Accessing the Session Context on page 195

4) Accessing the Session Context on page 190



January 2015 180

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


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 47: Extensions to exchange data with the backend systems


January 2015 181

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)


request context.7)

no

yes

Create new business

object and new BOM.2)

Create new backend

interface.4)

Figure 48: 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 227)

2) Create a Customer Business Object on page 200 and Create a Customer Business Object Manager on page 200

3) Supported Function Modules and Business Objects on page 212 Table 47: User exits for for Pricing or Configuration

Creating new Customer Backend Object on page 208

5) Create a Customer Backend Object on page 204

6) Interception of Calls to Standard Function Modules on page 225



January 2015 182

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


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


used1)

no

yes

no

Figure 49: Transfer additional data from business object layer to SAP CRM

For details see:

1) Supported Function Modules and Business Objects on page 212





January 2015 183

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


module

End

Use standard backend

object and implement JCO

event listener class3)


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)


module with interface of

standard function module2)


object -

no action required


module to standard

function module in

configuration2)

No action required

Figure 50: Call a SAP CRM system from the backend layer

For details see:

1) Supported Function Modules and Business Objects on page 212

2) Replacing Calls to Standard Function Modules (Backend System) on page 227


4) Create a Customer Backend Object on page 204; it is assumed at this point, that a customer business object and a customer BOM are already available.


January 2015 184

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


used3)

Implement JCO event

listener class.7)


request context.8)

no

yes

Create new backend

interface.4)

Create new business

object and new BOM.2)

Figure 51: 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 227)

2) Create a Customer Business Object on page 200 and Create a Customer Business Object Manager on page 201Table 56: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects. on page 212Table 47: User exits for for Pricing or Configuration

Creating new Customer Backend Object on page 208


6) Modification of Communication Structures in SAP and Configuration of the Web Application on page 220




January 2015 185

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


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


used1)

no

yes

no

Figure 52: Transfer additional data from business object layer to SAP ERP system

For details see:Table 56: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects. on page 212.



4) Modification of Communication Structures in SAP and Configuration of the Web Application on page 220



January 2015 186

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


module with extended

interface of standard

function module


module with interface of

standard function module1)

recomm.

concept


module

End


object and implement JCO

event listener class2)


object -

no action required

Create customer backend

object.

Register new backend

object in configuration3)


module to standard

function module in

configuration1)


module and event listener

class to standard function

module in configuration2)

No action required

Figure 53: Call a SAP ERP system from backend layer

For details see:

1) Replacing Calls to Standard Function Modules (Backend System) on page 227


3) Create a Customer Backend Object on page 204; it is assumed at this point, that a customer business object and a customer BOM are already available.


January 2015 187

This diagram shows how to exchange additional data between the business object layer and an IPC system.


be transferred to the

IPC for Pricing


be transferred to the

IPC for configuration

Start


with an IPC system

End

Derive new backend

object from standard

(CRM/R/3) backend

object. Implement user

exit.1)

Derive new backend


(CRM/R/3) backend

object. Implement user

exit.1)

Figure 54: Exchange additional data between business object layer and an IPC system

For details see:

1) Standard Backend Objects providing User Exits on page 204

Example, see ’Extension within Data Processing’ of the ‘Development and Extension Guide: E-Comemrce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 304).


January 2015 188

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


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 55: Exchange additional data with the web catalog

For details see:

1) New Fields in the Web Catalog (SAP ERP Backend and Memory Catalog) on page 231 and New Fields in the Web Catalog (SAP ERP Backend and TREX) on page 232

2) Show Additional Keys for Extended Search in B2B on page 231

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 304).

For displaying additional data in web catalog, see Show Additional Attribute in Product List on page 229 and Show Additional Attribute in Product Details and in Compare Products on page 230


January 2015 189

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


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


(JDBC or DB) backend

object.2)

Overwrite method to

exchange extension data.

Figure 56: Exchange additional data with the Java basket

For details see:

1) Java Basket-Extensions on page 222



January 2015 190

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

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

%>


January 2015 191

Figure 57: 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.


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


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.


o Base class providing MetaBOM.

All the action classes of the E-Service Extended Complaints and Returns application extend the com.sap.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:


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.


January 2015 192

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


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


In the Remanufacturer’s Inspection Application, you can use the following actions as base actions:


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


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


com.sap.eservice.srvconfirmations.action.ConfirmationBaseAction

o Inherit from CommonBaseAction; gives access to the Confirmation business object

manager.


January 2015 193

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.


MaintainBasketReplaceItemAction Action to replace an item of the basket with another one during the cross- and upselling process.


MaintainBasketNewShiptoAction Action to add a new ship to to a document.


MaintainBasketDispatcherAction Action to dispatch all requests coming from the order.jsp to different (specialized) actions.

customerExitDispatcher Set forward; called after standard forward is determined.




Table 34: User exits within the Basket


January 2015 194

Order


MaintainOrderBaseAction Base action for all actions providing functions to manage the shopping basket and sales documents similar to the basket.




MaintainOrderReplaceItemAction Action to replace an item of the order with another one during the cross- and upselling process.


MaintainOrderNewShiptoAction Action to add a new ship to to a document.


MaintainOrderSendAction Action to perform the final step in the processing of a document (i.e. to save it in the backend).


MaintainOrderDispatcherAction Action to dispatch all requests coming from the order_change.jsp to different (specialized) actions.


Table 35: User exits within the Order

OCI (Open Catalog Interface) (interface to external catalogs)


OciGetCatalogURLAction Action which retrieves the URL from the external catalog.


customerExitGetOCIURL Modify URL to external catalog (e.g. add user data).

OciReceiveAction Action for receiving items via the OCI.


userExitCheckRequest The result of the standard method „checkRequest’ can be modified.

userExitModifyItemListBefore ConvertRequest

Read additional data from OCI message.

userExitModifyItemListBeforeAddToBasket

Read additional data from OCI message.

Table 36: User exits within the OCI


January 2015 195

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





January 2015 196

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.getUserSessionData(session);


January 2015 197

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

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 304).


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.


January 2015 198

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 211 or BAPIs/SAP ERP-Extensions on page 217.

Use only string objects with the extension data, if you want to automatically transport this data to the backend using the Extension mechanism (see BADIs/SAP CRM Extensions).

Figure 58: 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.


January 2015 199

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 59: 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 60: 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);


January 2015 200

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 61: 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();


January 2015 201

Z_CustomFunc

+getInfo()

Z_CustomBusinessObjectManager

+ getCustomFunc()creates

DefaultBusinessObjectManager

Figure 62: 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



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 304) 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.


January 2015 202

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 63: 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 64: Creating own Business Object Manager


January 2015 203

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



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

}

}


January 2015 204

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 304) 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:


January 2015 205

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 274

Call IPC for Pricing (ISA CRM)


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)


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


January 2015 206


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)


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


January 2015 207


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)


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

Call IPC for Pricing or Configuration (ISA ERP)


ServiceR3IPC Provides IPC functionality for the Internet Sales ERP. Contains creation of documents and items.

customerExitAfterDocumentCreation Customer exit that is called after an IPC document is created.

customerExitBeforeItemCreation Customer exit that is called before an IPC item is created.

customerExitAfterItemCreation Customer exit that is called after an IPC item has 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


January 2015 208


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

}


January 2015 209

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’



<params>

<param name=‘myinit’ value=‘myvalue’/>

</params>

<businessObject/>

public class Z_CustomFuncCRM

extends BackendBusinessObjectBaseSAP

implements BasketBackend, Z_CustomFuncBackend {

public String getInfo() {

JCoFunction func = getDefaultJCoConnection().getJCoFunction(‘Z_GETINFO’);

getDefaultJCoConnection().execute(func);

return func.getExportParameterList().getString(‘info’);

}

}


January 2015 210

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


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

}


January 2015 211


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 304) 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.


January 2015 212

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


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


January 2015 213

Contract


CRM_ISA_CNT_GETCONTRACTS ContractHead ContractItem

Table 51: CRM - Supported Function Module / Business Object - Contract

Shop


CRM_ISA_SHOP_DATA_GET Shop

CRM_ISA_SHOP_GETLIST Shop

Table 52: CRM - Supported Function Module / Business Object - Shop

Complaint (E-Service)


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)


CRM_ESRV_COMPL_CHANGE_HEADER ComplaintHeader

CRM_ESRV_COMPL_GET_HEADER ComplaintHeader

Table 54: CRM - Supported Function Module / Business Object – ComplaintHeader

ComplaintItem (E-Service)


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


January 2015 214

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.


January 2015 215

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.


January 2015 216

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


January 2015 217

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


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>


January 2015 218

VALUEPART1 VALUEPART Extension data (240 characters).




Table 56: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects.

Order


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 ‘


January 2015 219

Generic Search Framework’ (page 103).


January 2015 220

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 274), 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>


January 2015 221

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.


MOVE WA_BAPE_VBAK TO EXTENSION_OUT+30.

ENDCATCH.

MODIFY EXTENSION_OUT INDEX TABLE_TABIX.

ENDIF.


January 2015 222

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 304).

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


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.


MOVE EXTENSION_IN+30 TO WA_BAPE_VBAK.

ENDCATCH.

ENDIF.

MOVE _BAPE_VBAK-ZZPMNTTRMS TO ORDER_BUSINESS_IN-PMNTTRMS.


January 2015 223

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

Table 59: How to access the Request Context

The request context can store any type of data. The most important methods are:

addData(Object name, Object value)

o Stores any kind of data

Object getData(Object name)

o Returnes the stored data or null if not data with the given name is available in the 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 and higher.

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:


January 2015 224

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

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

JCoFunction 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);

}

}

}


January 2015 225

Figure 65: 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 200

'Create a Customer Backend Object' on page 204

Version



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

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:


January 2015 226

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 66: 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 211).

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 JCoFunction, which is called. This gives you the opportunity to

provide/retrieve additional data in your optional parameters.


January 2015 227

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 and higher.


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 JCoFunction 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-Commerce 7.0 – Examples and Tutorials’ (see [1] in chapter References on page 304).

Replacing Calls to Standard Function Modules

<function-module-listener>

<param

name=‘fmevent:NAME_OF_FUNCTION_MODULE’

value=‘ClassNameEventListener’/>

</function-module-listener>


January 2015 228

(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 67: Replacing calls to Standard Function Modules

Version

This feature is available in all versions of ISA 5.0 and higher.


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)


January 2015 229

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 235

Extension of the Web Catalog

New Fields in the Web Catalog (SAP CRM Backend) Showing more attributes in the web catalog is very easy, since no java class needs to be touched. Just 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>


January 2015 230

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>


January 2015 231

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

Version


Example

See note 610393.


January 2015 232

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.


January 2015 233

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.


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


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 235) 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:


January 2015 234

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.


January 2015 235

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.


January 2015 236

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.


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

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

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


January 2015 237

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


January 2015 238

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

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


January 2015 239

Action Flow

Action:

setCharacteristicValues

Action(s):

displayLayout

Po

st

Fo

rward

to

dis

pla

yL

ayo

ut

redirectGet

Data Processing Data Display

Figure 70 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.


January 2015 240

Figure 71 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 72 UI areas of the config UI


January 2015 241

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


January 2015 242

Figure 74 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.


January 2015 243

Figure 75 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) {


January 2015 244

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.


January 2015 245

Figure 76 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. Please see Figure 69 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.


January 2015 246

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.


January 2015 247

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


January 2015 248

Figure 78 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).

Figure 79 Component configuration for customer tab

You activate this area when setting the parameter “customertab.show” of the XCM component

multifunctional area to “T”.


January 2015 249

Figure 80 Application configuration for customer tab

Figure 81 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.


January 2015 250

Figure 82 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.

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.


January 2015 251

You may register your own UIBeanFactory in /xcm/customer/modification/factory-config.xml.

The file contains an example for registering a customer UIBeanFactory.

Figure 83 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.


January 2015 252

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


January 2015 253

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


January 2015 254

Figure 85 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 204. 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 304).


January 2015 255

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:

http://deigb01s56:1080/public/Doku/UI/B2B/Framestructure/framestruktur_frame.htm


January 2015 256

Figure 86: 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.


January 2015 257

Figure 87: 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).


January 2015 258

Figure 88: 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.


January 2015 259

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 89: Display a new Document type with the UpdateDocumentView Module


January 2015 260

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.


January 2015 261

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(‘&’);


January 2015 262

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>


January 2015 263

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


January 2015 264

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


January 2015 265

Folder Description

WEB-


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 88

WEB-


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 131

WEB-


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 130

WEB-


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 225

See chapter 'ABAP Debugging' on page 167

See chapter 'Tracing Function Modules' on page 292

See chapter 'Replacing Calls to Standard Function Modules (Backend System)' on page 227

WEB-INF\cfg\log-

config.properties

Starting from ISA SP07 this file replaces the previously used log-

config.xml configuration file.

The settings in this file configure the logging and tracing 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 103.

Table 63:Overview of configuration files


January 2015 266

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


January 2015 267

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 90: Original flow of actions

January 2015 268

The config.xml for this process flow is as follows:

Example:

This process flow is interfered by introducing a customer written CustomAction.

Figure 91: Changed flow of actions

<action path=‘/firstaction’

type=‘com.sap.isa.action.FirstAction’>

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

</action>



<action path=‘/Z_secondaction’

type=‘com.sap.isa.action.SecondAction’>

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

</action>



<action path=‘/secondaction’

type=‘com.acme.isa.action.Z_CustomAction’>

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

</action>

<action path=‘/firstaction’

type=‘com.sap.isa.action.FirstAction’>

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

</action>

<action path=‘/secondaction’

type=‘com.sap.isa.action.SecondAction’>

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

</action>


January 2015 269

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:


extends BusinessObjectManagerBase

implements BOManager, BackendAware

{

public static final

String CUSTOM_BOM = ‘Z_CUSTOM-BOM’;

Table 66: Naming conventions for Business Object Managers


January 2015 270

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.

...




// gettting custom BOM

Z_CustomBusinessObjectManager myBOM =

(Z_CustomBusinessObjectManager)userSessionData.

getBOM(Z_CustomBusinessObjectManager.CUSTOM_BOM);


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


January 2015 271

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


January 2015 272

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

January 2015 273

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 SAP 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’/>



<param name=‘removal’ value=‘48’/>

</initialization>

January 2015 274

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

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:

To change the value of priceTypes from totalGrossValue to netValueWithoutFreight, carry out

the following steps:

<config id=‘crmdefault’>

<businessObject type=‘PriceCalc’ name=‘CatPriceCalc’

className=‘com.sap.isa.backend.crm.webcatalog.pricing.PriceCalculatorCRMIPC’



<params>

<param name=‘priceTypes’ value=‘totalGrossValue’/>



</params>

</businessObject>

</config>

<initialization isa:extends=‘../initialization

[@className='com.sap.isa.catalog.cache.CatalogCacheInitHandler']’>

<param name=‘removal’ value=‘4711’/>

</initialization>

January 2015 275

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.



<config isa:extends=‘../config[@id='crmdefault'‘>



<businessObject type=‘Z_Custom’ name=‘z_custom’

className=‘com.acme.isa.backend.crm.Z_Custom’

connectionFactoryName=‘JCO’ defaultConnectionName=‘ISAStateless’>

<params>

<param name=‘myParam’ value=‘myValue’/>

</params>

</businessObject>

</config>

<config isa:extends=‘../config[@id='crmdefault'‘>

<businessObject type=‘PriceCalc’>

<params>

<param name=‘priceTypes’ value=‘netValueWithoutFreight’/>

</params>

</businessObject>

</config>


January 2015 276

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 92: Adding and configuring new parameter (XCM)

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

January 2015 277

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>



</scenariometadata>

</xcmadmin>

<component id="project">

<configs>

<config id="projectconfig">

<params id="default">

<param name="myParam" value="defaultValue"/>

</params>

</config>

</configs>

</component>


January 2015 278

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:


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


January 2015 279

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 93: XCM - parameter shorttexts

Example:

Example of text type:

<param type="text" name="myParam" shorttext="myValue" />


January 2015 280

Example:

Example of singleselect type:

The param XML element has the following attributes.


name Name of a parameter. yes

shorttext One sentence describing what this parameter is good for.

This description is shown in the XCM Admin tool to give the 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.sap.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>


January 2015 281

Definition of a allowedvalue located in the body of the param XML tag.


value The value of the parameter yes

shorttext One sentence describing what this parameter is good for.

This description is shown in the XCM Admin tool to 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.)

January 2015 282

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



<xi:include href="${sap}/modification/dynamic-fields-

config.xml#xpointer(backendobject/configs/config[@id='${backendtype}']/*)"/>

<property-group name="ComplaintItemDynFieldsPG">

<property name="DANG_TO_RETURN" type="selectbox"

description="esrv.crb2b.cl.dyn.dang"

objectType="CUSTOMER_I"

fieldName="DANG_TO_RETURN">

<allowedValue value="A" description="esrv.crb2b.cl.opt.scr" />

<allowedValue value="B" description="esrv.crb2b.cl.opt.mov" />

</property>

<property name="CARRIER_CLAIM" type="checkbox"

description="esrv.crb2b.cl.dyn.car"


fieldName="CARRIER_CLAIM">

</property>

<property name="HS_OF_PRIME_QTY" type="input"

description="esrv.crb2b.cl.dyn.hsq"


fieldName="HS_OF_PRIME_QTY"

size="10">

</property>

<property name="HS_OF_PRIME_UNIT" type="input"

description="esrv.crb2b.cl.dyn.hsu"


fieldName="HS_OF_PRIME_UNIT"

helpValuesSearchName="UnitOfMeasure"

size="10">

</property>

<property name="SCRAP_VALUE" type="input"

description="ScrapValue"

objectType="PRICING"

fieldName="SCRAP_VALUE"

size="12">

</property>

</property-group>

</maintenance-object>

http://www.w3.org/2001/XInclude


January 2015 283

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.


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>


January 2015 284

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)


CL_ISA_GEN_DOC_SEARCH_HELP Application server (class)


Table 77: Main Components of the generic search framework

Details of component “generic-searchbackend-config.xml”

Location: xcm \ sap \ modification \ generic-searchbackend-config.xml.

Known standard implementations for CRM E-Service extended Complaints and Returns.


January 2015 285

BAdI Implementations in component “CRM_ICSS_CR”


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


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.


January 2015 286

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.


January 2015 287

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.


January 2015 288

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:


January 2015 289

Figure 94: 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


January 2015 290

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.

http://localhost:50000/b2b/b2b/init.do?translate.show.key.concat=99


January 2015 291

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 NW 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 NW AS Java is running on, and <PORT> is the http port of your SAP NW 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 NW 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.


January 2015 292

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


January 2015 293

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.


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


January 2015 294

ECO Version


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:


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


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:

http://localhost:50000/b2b/b2b/init.do?shop=muster&language=en


January 2015 295

Figure 95: 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 96: 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’);


January 2015 296

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 97: Original action flow

After

Figure 98: 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();

}


January 2015 297

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

RequestParser parser = new RequestParser(request);

RequestParser.Parameter param = parser.getParameter(‘personal[]’);

if (param.isSet()) {

// gives you the value of personal[email]

String email = param.getValue(‘email’).getString();

String name = param.getValue(‘name’).getString();

}

param = parser.getParameter(‘beer[]’);

for (int i = 0; i < parm.getNumValues(); i++) { %>

param.getValue(i).getInt();

}

<form action=‘array.php’ method=‘post’>

Name: <input type=‘text’ name=‘personal[name]’><br>

Email: <input type=‘text’ name=‘personal[email]’><br>

Beer: <br>

<select multiple name=‘beer[]’>

<option value=‘122’>Warthog

<option value=‘33’>Guinness

<option value=‘7373’>Stuttgarter Schwabenbräu

</select>

<input type=‘submit’>

</form>


January 2015 298

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

Getting Application Version Since the SAP NetWeaver 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 NW AS, but you can use additional logging features in E-Commerce applications. See SAP note 2207842.

https://service.sap.com/sap/support/notes/2207842


January 2015 299

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 85: Updating the application


January 2015 300

Web Diagrams

Syntax of Web Diagrams


January 2015 301

B2B - Start Page


January 2015 302

B2B - Create Basket


January 2015 303

B2B - Display Order Status


January 2015 304

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 7.0 Enhnancement Package 4J. InstallationGuide on SAP Service Marketplace: http://service.sap.com/crm-inst SAP CRM 7.0 Enhancement Package 4 Installation follow the link “Installation Guides for SAP EHP 4 CRM 7.0”. Follow the “Java” link that is applicable for the database and operating system you want to use.

[3] Struts documentation in the source archive at http://archive.apache.org/dist/struts/struts-1.1/

[4] SAP Java Connector: On the SAP Service Marketplace: https://service.sap.com/connectors Java Connector

Update History

Version Date Remarks

1.0 January 2016 First Version for E-Commerce Release 7.54



http://archive.apache.org/dist/struts/struts-1.1/


January 2015 305

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

Table 26: Attributes of BusinessObject elements ............................................................................................ 92

Table 27: Types of Log Messages ................................................................................................................ 119

Table 28: Types of Tracing ............................................................................................................................ 119

Table 29: Log Levels ..................................................................................................................................... 122

Table 30: Categories for Logs ....................................................................................................................... 122

Table 31: Software Components ................................................................................................................... 142

Table 32: Overview of possible changes in different layers .......................................................................... 169

Table 33: Overview of simple modifications related to the UI ....................................................................... 190

Table 34: User exits within the Basket .......................................................................................................... 193

Table 35: User exits within the Order ............................................................................................................ 194

Table 36: User exits within the OCI ............................................................................................................... 194


January 2015 306

Table 37: User exits within the Extended Complaints ................................................................................... 195

Table 38: User exits within the Remanufacturer’s Inspection Application ..................................................... 195

Table 39: Methods of the BOBase class ....................................................................................................... 198

Table 40: User exits for IPC for pricing .......................................................................................................... 205

Table 41: User exits for IPC basket ............................................................................................................... 205

Table 42: User exits for IPC basket ............................................................................................................... 206

Table 43: User exits for Order and Order Status ........................................................................................... 206

Table 44: User exits for Order and Order Status ........................................................................................... 207

Table 45: User exits for Web Catalog ............................................................................................................ 207

Table 46: User exits for for Pricing or Configuration ..................................................................................... 207

Table 47: User exits for for Pricing or Configuration ..................................................................................... 208

Table 48: ABAP Extension Structure (CRM) ................................................................................................. 212

Table 49: CRM - Supported Function Module / Business Object - Order ..................................................... 212

Table 50: CRM - Supported Function Module / Business Object - User ....................................................... 212

Table 51: CRM - Supported Function Module / Business Object - Contract ................................................. 213

Table 52: CRM - Supported Function Module / Business Object - Shop ...................................................... 213

Table 53: CRM - Supported Function Module / Business Object - Complaint .............................................. 213

Table 54: CRM - Supported Function Module / Business Object – ComplaintHeader ................................. 213

Table 55: CRM - Supported Function Module / Business Object – ComplaintItem ...................................... 213

Table 56: ABAP Extension Structure (ERP) .................................................................................................. 218

Table 57: ERP - Supported Function Module / Business Objects – Order ................................................... 218

Table 58: Communication Structure in SAP ERP ......................................................................................... 220

Table 59: How to access the Request Context ............................................................................................. 223

Table 60: Overview of the content of the web archive .................................................................................. 263

Table 61: Overview of the content of the web archive .................................................................................. 264

Table 62:Overview of configuration files........................................................................................................ 264

Table 63:Overview of configuration files........................................................................................................ 265

Table 64: Overview of the package structure of E-Commerce...................................................................... 266

Table 65: Naming conventions for JSPs ....................................................................................................... 267

Table 66: Naming conventions for Business Object Managers..................................................................... 269

Table 67: Naming conventions for packages ................................................................................................ 271

Table 68: Naming conventions for Java classes ........................................................................................... 271

Table 69: Naming conventions for Java classes ........................................................................................... 272

Table 70: : Naming conventions for resource files ........................................................................................ 272

Table 71: : Naming conventions for resource files ........................................................................................ 273

Table 72: Adding Meta data of XCM parameters .......................................................................................... 278

Table 73: Attributes of the param XML element ............................................................................................ 280

Table 74: Definition of a „allowedvalue“ ........................................................................................................ 281

Table 75: Allowed Attributes for the tag <property> ...................................................................................... 283

Table 76: Allowed Attributes for the tag <allowedValue> .............................................................................. 283


January 2015 307

Table 77: Main Components of the generic search framework ..................................................................... 284

Table 78: BAdI Implementations in Component "CRM_ICSS_CR" .............................................................. 285

Table 79: BAdI Implementations in Component “CRM_ISALES_SEARCH” ................................................ 285

Table 80: Search definitions in E-Service Extended Complaints and Returns ............................................. 286

Table 81: Displaying text of keys ................................................................................................................... 289

Table 82: Displaying language dependent keys ............................................................................................ 290

Table 83: General Request Parameters ........................................................................................................ 293

Table 84: Request parameters for B2C ......................................................................................................... 294

Table 85: Attributes of Java Connector Pool ..................................................... Error! Bookmark not defined.

Table 86: Updating the application ................................................................................................................ 299


January 2015 308

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 SAP CRM architecture ................................................................................. 23

Figure 4: Architecture of SAP E-Commerce for SAP 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: Destination Determination with JCo 3.0 ......................................................................................... 81

Figure 21: Class Diagramm about use of JCo Connection ............................................................................. 82

Figure 22: Design of Logging / Tracing ......................................................................................................... 117

Figure 23: Extend and Modify CRM Web Apps ............................................................................................. 143

Figure 24: Merged Web Files ........................................................................................................................ 144

Figure 25: Project specific application in CUSTCRMPRJ ............................................................................. 145

Figure 26: Creating a new Track ................................................................................................................... 147

Figure 27: Adding Software Component ....................................................................................................... 148

Figure 28: Required Software Components .................................................................................................. 148

Figure 29: Check-In of the Archives .............................................................................................................. 149

Figure 30: Development System ................................................................................................................... 149

Figure 31: Overview Developer Workplace ................................................................................................... 156

Figure 32: Developer Workplace for SAP NetWeaver .................................................................................. 158

Figure 33: Directory Structure of NW AS Java 7.5 ........................................................................................ 159

Figure 34: SAP Management Console .......................................................................................................... 161

Figure 35: Offline Config Tool - Setting Up Debug Mode ............................................................................. 163

Figure 36: J2EE Engine - Enabling Debugging ............................................................................................. 164


January 2015 309

Figure 37: J2EE Engine - Enabling Debugging ............................................................................................. 165

Figure 38: Starting Remote Debugging ......................................................................................................... 166

Figure 39: Flow of possible changes ............................................................................................................. 170

Figure 40: Overview of different categories of extensions ............................................................................ 171

Figure 41: Statis extensions to the UI layer ................................................................................................... 172

Figure 42: Extensions to the action flow ........................................................................................................ 173

Figure 43: Extensions to exchange additional data ....................................................................................... 174

Figure 44: Extensions to exchange data with UI layer .................................................................................. 175

Figure 45: Transfer additional input data to action class and business object layer ..................................... 176

Figure 46: Transfer additional output data from aciton class to JSP ............................................................. 178

Figure 47: Extensions to exchange data with the backend systems ............................................................. 180

Figure 48: Retrieve additional data from SAP CRM system to business object layer .................................. 181

Figure 49: Transfer additional data from business object layer to SAP CRM ............................................... 182

Figure 50: Call a SAP CRM system from the backend layer ......................................................................... 183

Figure 51: Retrieve additional data from SAP ERP system to business object layer ................................... 184

Figure 52: Transfer additional data from business object layer to SAP ERP system ................................... 185

Figure 53: Call a SAP ERP system from backend layer ............................................................................... 186

Figure 54: Exchange additional data between business object layer and an IPC system ............................ 187

Figure 55: Exchange additional data with the web catalog ........................................................................... 188

Figure 56: Exchange additional data with the Java basket ........................................................................... 189

Figure 57: Action flow with CustomActions .................................................................................................. 191

Figure 58: BOBase class ............................................................................................................................... 198

Figure 59: Derive own class from existing Business Object.......................................................................... 199

Figure 60: Create own BOM .......................................................................................................................... 199

Figure 61: Creating own Business Object ..................................................................................................... 200

Figure 62: Creating own BOM ....................................................................................................................... 201

Figure 63: Creating interface for Business Object ......................................................................................... 202

Figure 64: Creating own Business Object Manager ...................................................................................... 202

Figure 65: Adding additional Function Modules ............................................................................................ 225

Figure 66: Java event listener for Standard Function Modules ..................................................................... 226

Figure 67: Replacing calls to Standard Function Modules ............................................................................ 228

Figure 68 The IPC and its UI in the CRM Online Landscape ........................................................................ 237

Figure 69 IPC Architecture more in detail ...................................................................................................... 238

Figure 70 General Action Flow ...................................................................................................................... 239

Figure 71 Example for layout with UI components from both files (layout-config and ipclayout-config) ....... 240

Figure 72 UI areas of the config UI ................................................................................................................ 240

Figure 73 Example for tiles ............................................................................................................................ 241

Figure 74 Combining low level layout and tiles ............................................................................................. 242

Figure 75 JSP Key and Path ......................................................................................................................... 243

Figure 76 Interaction of UIBeans with the JSP pages and the Busines Object Layer .................................. 245


January 2015 310

Figure 77 XCM settings for customer buttons ............................................................................................... 247

Figure 78 Customer buttons on screen ......................................................................................................... 248

Figure 79 Component configuration for customer tab ................................................................................... 248

Figure 80 Application configuration for customer tab .................................................................................... 249

Figure 81 Customer tab action mapping ....................................................................................................... 249

Figure 82 Customer tab with characteristic details ........................................................................................ 250

Figure 83 Creating UIBeans via UIBeanFactory ........................................................................................... 251

Figure 84 Standard customer exit in actions ................................................................................................. 252

Figure 85 Handling extension data at client objects ...................................................................................... 254

Figure 86: Main objects of the UpdateDocumentView module ..................................................................... 256

Figure 87: Activities of the isaPerform() method of the UpdateDocumentViewAction .................................. 257

Figure 88: Creation of a new order. (ISA B2B) .............................................................................................. 258

Figure 89: Display a new Document type with the UpdateDocumentView Module ...................................... 259

Figure 90: Original flow of actions ................................................................................................................. 267

Figure 91: Changed flow of actions ............................................................................................................... 268

Figure 92: Adding and configuring new parameter (XCM) ............................................................................ 276

Figure 93: XCM - parameter shorttexts ......................................................................................................... 279

Figure 94: Displaying name of JSP-Files in E-Commerce Applications ........................................................ 289

Figure 95: Calling the application with additional request parameters .......................................................... 295

Figure 96: Action flow of one request ............................................................................................................ 295

Figure 97: Original action flow ....................................................................................................................... 296

Figure 98: Interrupted action flow .................................................................................................................. 296