sap isa50 devandextguide

8/21/2019 SAP ISA50 DevAndExtGuide

http://slidepdf.com/reader/full/sap-isa50-devandextguide 1/303

Development and

Extension Guide

SAP E-Commerce

5.0 – Landscape

Basics and

Concepts.

Document Version 2.0– October, 2006



© 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 Server TM

are trademarks of

IBM Corp. in USA and/or other countries.

ORACLE® is a registered trademark of ORACLE Corporation.

UNIX®, X/Open®, OSF/1®, and Motif ® are registered trademarks of the

Open Group.

LINUX is a registered trademark of Linus Torvalds and others.

Citrix®, the Citrix logo, ICA®, Program Neighborhood ®, MetaFrame®,

WinFrame®, VideoFrame®, MultiWin® and other Citrix product names

referenced herein are trademarks of Citrix Systems, Inc.

HTML, DHTML, XML, XHTML are trademarks or registered

trademarks of W3C®, World Wide Web Consortium, Massachusetts

Institute of Technology.

JAVA® is a registered trademark of Sun Microsystems,

Inc.

J2EE™ is a registered trademark of Sun Microsystems,

Inc.

JAVASCRIPT® is a registered trademark of Sun

Microsystems, Inc., used under license for technology

invented and implemented by Netscape.

MarketSet and Enterprise Buyer are jointly owned

trademarks of SAP AG and Commerce One.

SAP, SAP Logo, R/2, ERP, mySAP, mySAP.com, xApps,

mySAP Business Suite, and other SAP products and

services mentioned herein as well as their respective logos

are trademarks or registered trademarks of SAP AG in

Germany and in several other countries all over the world.

All other product and service names mentioned are the

trademarks of their respective companies.

Disclaimer

Some components of this product are based on Java™.

Any code change in these components may cause

unpredictable and severe malfunctions and is therefore

expressively prohibited, as is any decompilation of these

components.

Any Java™ Source Code delivered with this product is

only to be used by SAP’s Support Services and may not

be modified or altered in any way.

Documentation in the SAP Service Marketplace

You can find this documentation at the following Internet

address:service.sap.com/instguides

SAP AGNeurottstraße 1669190 Walldorf GermanyT +49/18 05/34 34 24F +49/18 05/34 34 20www.sap.com

http://www.sap.com/

http://www.sap.com/

http://www.sap.com/

Typographic Conventions

Type Style Represents

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

Cross-references to other

documentation

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

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

Example text Screen output. This includes fileand directory names and their paths, messages, names of variables and parameters,source code as well as names of installation, upgrade anddatabase tools.

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

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

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

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax



Development and Extension Guide – SAP E-Commerce 5.0

September 2006 4

Contents

Development and Extension Guide – SAP E-Commerce 5.0: Landscape,

Basics and Concepts ......................................................................................3General Introduction 3

Where the Current Version of th is Document is Located ........................................3

Naming Conventions...................................................................................................3Terminology....................................................................................................................................... 3Variables............................................................................................................................................ 3

Structure of this Document ........................................................................................3

Available Courses, Literature, Links, Notes..............................................................3Courses ............................................................................................................................................. 3CR800: CRM E-Commerce ............................................................................................................................. 3

Course Goals ............................................................................................................................................... 3

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

Course Content ............................................................................................................................................ 3CR850: Internet Sales ERP Edition .................................................................................................................. 3

Course Goals ............................................................................................................................................... 3Course Content ............................................................................................................................................ 3

CR550: CRM Technology................................................................................................................................ 3Course Goals ............................................................................................................................................... 3Course Content ............................................................................................................................................ 3

Literature ........................................................................................................................................... 3Links.................................................................................................................................................. 3Java in General................................................................................................................................................ 3

Java Tutorials .................................................................................................................................................. 3Java Newsgroups ............................................................................................................................................. 3

Introduction to SAP J2EE...............................................................................3SAP Web Application Server Java 3

Web Container 3

E-Commerce Framework ................................................................................3E-Commerce Architecture Overview 3

Layered Architecture...................................................................................................3Interaction and Presentation Layer..................................................................................................... 3Business Object Layer (BO Layer) ..................................................................................................... 3Business Logic Service Layer (BLS Layer)......................................................................................... 3

Presentation Layer Details 3

JSPs..............................................................................................................................3Custom ISA Tags............................................................................................................................... 3MimeURL ....................................................................................................................................................... 3WebappsURL.................................................................................................................................................. 3translate........................................................................................................................................................... 3iterate.............................................................................................................................................................. 3

contentType..................................................................................................................................................... 3moduleName ................................................................................................................................................... 3message........................................................................................................................................................... 3

imageAttribute................................................................................................................................................. 3




September 2006 5

Dynamic Field Control ................................................................................................3Definition............................................................................................................................................ 3The structure of the UI element object.............................................................................................................. 3The structure of the UI element group object .................................................................................................... 3

Configuration of fields via XCM admin................................................................................................ 3Add field to the xcmadmin-config.xml ............................................................................................................. 3Add field to the conf-data.xml.......................................................................................................................... 3

Usage................................................................................................................................................ 3JSP.................................................................................................................................................................. 3Action ............................................................................................................................................................. 3

Interaction Layer Details 3

Overview ......................................................................................................................3

UI Components ............................................................................................................3

Interaction Components .............................................................................................3Actions............................................................................................................................................... 3Threads in Actions........................................................................................................................................... 3

ActionForms....................................................................................................................................... 3

Interaction Configuration............................................................................................3ActionServlet...................................................................................................................................... 3ActionFormBean................................................................................................................................ 3ActionMapping................................................................................................................................... 3ActionForward.................................................................................................................................... 3

ISA extension of Struts ...............................................................................................3ISA Actions ........................................................................................................................................ 3com.sap.isa.core.InitAction .............................................................................................................................. 3

com.sap.isa.core.BaseAction............................................................................................................................ 3com.sapmarkets.isa.isacore.action.EComBaseAction........................................................................................ 3com.sapmarkets.isa.isacore.action.EComExtendedBaseAction.......................................................................... 3

com.sap.isa.isacore.action.IsaCoreBaseAction.................................................................................................. 3

com.sap.isa.core.UserSessionData.................................................................................................... 3Changing language dependand resource keys................................................................................... 3

Addi tional Information ................................................................................................3

Secure Programming 3

Input Validation............................................................................................................3Guideline ........................................................................................................................................... 3

HTTP Header Information ...........................................................................................3Guideline ........................................................................................................................................... 3Persistent Cookies............................................................................................................................. 3Guideline ........................................................................................................................................... 3

Cross Site Script ing ....................................................................................................3

Guideline ........................................................................................................................................... 3Error Handling.................................................................................................................................... 3Solution ............................................................................................................................................. 3

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

Comments in HTML Code...........................................................................................3Guideline ........................................................................................................................................... 3

Support of Web Standards (only B2C) 3

Introduction .................................................................................................................3

Frameless JSP pages..................................................................................................3Introduction........................................................................................................................................ 3




September 2006 6

Structure of the layout-config.xml ....................................................................................................... 3The structure of the UILayout tag..................................................................................................................... 3

The structure of the Form tag........................................................................................................................... 3The structure of the HTML attribute tag ........................................................................................................... 3The structure of the UIArea tag ........................................................................................................................ 3

The structure of the UIAreaContainer tag......................................................................................................... 3

The structure of the UIComponent tag.............................................................................................................. 3The structure of the UIConfiguration tag .......................................................................................................... 3

Create your component actions.......................................................................................................... 3Create your JSP includes................................................................................................................... 3Control the layout............................................................................................................................... 3UILayout......................................................................................................................................................... 3

Layout Processing............................................................................................................................................ 3UIArea ............................................................................................................................................................ 3UIInclude ........................................................................................................................................................ 3

UIJSInclude..................................................................................................................................................... 3

Dynamic change of HTML title............................................................................................................ 3Dynamic changes of the layout........................................................................................................... 3Support of navigation issues .............................................................................................................. 3

UIStoreLayout & UIStoreForward ................................................................................................................... 3UIStoreAction ................................................................................................................................................. 3UIAction ......................................................................................................................................................... 3

UIGetLayout & UIGetForward ........................................................................................................................ 3

Summary of the UI Commands .......................................................................................................... 3Global Commands........................................................................................................................................... 3

Commands while Layout processing ................................................................................................................ 3

Browser Back Support................................................................................................3Usage of context values..................................................................................................................... 3Registration of context values .......................................................................................................................... 3

Getting and setting context values .................................................................................................................... 3Overruling context values in an url................................................................................................................... 3

Rules for UI components.................................................................................................................................. 3Redirect after form submit .................................................................................................................. 3General Guidelines ............................................................................................................................ 3

Bookmark Support ......................................................................................................3

Business Object Layer Details 3Design Considerations....................................................................................................................... 3

Addi tional Information ................................................................................................3

Business Logic Service Layer Details 3

Design Considerations ...............................................................................................3

Backend Objects .........................................................................................................3Lifecycle of Backend Object ............................................................................................................... 3

Initialization of the Backend Object ................................................................................................................. 3Destruction of Backend Objects ....................................................................................................................... 3

Backend Context................................................................................................................................ 3

BackendObjectManager..............................................................................................3

Connect ion Management ............................................................................................3Design Considerations....................................................................................................................... 3Working with JCo Based Connectivity ................................................................................................ 3Connection Types ............................................................................................................................................ 3Working with JCoConnections......................................................................................................................... 3

Getting Default Connection Associated with a Backend Object..................................................................... 3Getting a Modified Connection .................................................................................................................... 3Getting a New Connection from a ConnectioFactory object .......................................................................... 3

Working with JCO.Functions .............................................................................................................. 3Creating JCO.Functions ............................................................................................................................... 3




September 2006 7

Executing JCo Functions.................................................................................................................................. 3

Configuration of BLS Layer ........................................................................................3Configuring Connection Management................................................................................................. 3JCo Function Cache......................................................................................................................................... 3

Configuring Backend Objects ............................................................................................................. 3

Further Services 3Message Framework ...................................................................................................3

Message classes ............................................................................................................................... 3Message, MessageList and MessageListHolder Class....................................................................................... 3Adding messages from a CRM backend ........................................................................................................... 3MessageListDisplayer ...................................................................................................................................... 3

Message Tag ..................................................................................................................................... 3Exception Handling ............................................................................................................................ 3Backend .......................................................................................................................................................... 3Business Object Layer ..................................................................................................................................... 3Action Layer.................................................................................................................................................... 3

Error Pages........................................................................................................................................ 3appbase\backenderror.jsp ................................................................................................................................. 3appbase\runtimeerror.jsp.................................................................................................................................. 3appbase\panicexception.jsp .............................................................................................................................. 3appbase\relogin\invalidsession.jsp.................................................................................................................... 3

appbase\message.jsp ........................................................................................................................................ 3appbase\jspruntimeerror.jsp.............................................................................................................................. 3appbase\accessibilitymessages.inc.jsp............................................................................................................... 3

Message handling in accessibility mode............................................................................................. 3How to integrate the global message pages in an application............................................................. 3Pre Condition check in the EComExtendedBaseAction....................................................................... 3

Generic Search Framework ........................................................................................3Architecture of the Generic Search Framework .................................................................................. 3Main Components of the Generic search framework........................................................................... 3

Details of component “generic-searchbackend-config.xml” .............................................................................. 3Details of component “GenericSearchBaseAction”........................................................................................... 3Details of component “CRM_ISALES_SEARCH”........................................................................................... 3

Internet Sales specific implementation of the Generic Search Framework........................................... 3

Logging/Tracing ..........................................................................................................3Design Consideration......................................................................................................................... 3Difference between Logging/Tracing .................................................................................................. 3Tracing............................................................................................................................................................ 3

Logging........................................................................................................................................................... 3

Summary Types of log messages....................................................................................................... 3Tracing .............................................................................................................................................. 3APIs for Tracing: ISALocation......................................................................................................................... 3

Initializing Location..................................................................................................................................... 3

Entering/exiting non trivial method .............................................................................................................. 3Throwing exception ..................................................................................................................................... 3DEBUG....................................................................................................................................................... 3ERROR ....................................................................................................................................................... 3Coding Examples......................................................................................................................................... 3

APIs for Tracing: SAP Logging API ................................................................................................................ 3Initializing Location..................................................................................................................................... 3DEBUG....................................................................................................................................................... 3ERROR ....................................................................................................................................................... 3

Entering/exiting non trivial method .............................................................................................................. 3Throwing exception ..................................................................................................................................... 3

Logging.............................................................................................................................................. 3Usage of Categories......................................................................................................................................... 3APIs for Logging: ISALocation ....................................................................................................................... 3

ERROR ....................................................................................................................................................... 3




September 2006 8

FATAL........................................................................................................................................................ 3INFO ........................................................................................................................................................... 3

WARNING.................................................................................................................................................. 3Detailed Message Descriptions..................................................................................................................... 3Coding Examples......................................................................................................................................... 3

APIs for Logging: SAP Logging API ............................................................................................................... 3

INFO ........................................................................................................................................................... 3WARNING.................................................................................................................................................. 3

ERROR ....................................................................................................................................................... 3FATAL........................................................................................................................................................ 3

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

All purpose Cache.......................................................................................................3Working with the Cache ..................................................................................................................... 3

Init ial ization Handler ...................................................................................................3

Extended Configuration Management (XCM) 3

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

Separation of Conf iguration Data and Modification Data ........................................3

XCM Extension Mechanism ........................................................................................3

Web Appl ication Conf iguration and Components ....................................................3

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

Development Environment.............................................................................3Development Tools and Concepts 3

External documentation..............................................................................................3

Overview of process ...................................................................................................3Software Component Architecture of the CRM or Extended Ecommerce Java Applications ................ 3Modifications and Extensions of the Web User Interface..................................................................... 3Extensions of the Java Code.............................................................................................................. 3Merged Web Applications .................................................................................................................. 3Handling of duplicate files............................................................................................................................... 3

Restrictions...................................................................................................................................................... 3

Initial Configuration of the NWDI 3

Pre-requisi tes...............................................................................................................3

Creating a project specific Web Application with own context root 3

Basic concept ..............................................................................................................3

Step by step process ..................................................................................................3Check SLD content and create a new Software Component ............................................................... 3Create a new Track using the Landscape Configurator....................................................................... 3Add Software Components to track .................................................................................................... 3Configure Runtime Systems in the track............................................................................................. 3Import Software Components into this track ....................................................................................... 3Download Archives ......................................................................................................................................... 3Check-In archives ............................................................................................................................................ 3

Import the checked in archives into the Development system............................................................................ 3Import the checked in archives into the Consolidation system........................................................................... 3Create your own Enterprise Applications.......................................................................................................... 3Test the CRM Java application on a local Web AS Java Engine........................................................................ 3

Creation or Extensions of Java Classes ...................................................................3Import ing Modif ications and Extensions from older Releases ...............................3




September 2006 9

Developer Workplace 3

Required tools and vers ions ......................................................................................3

Java Development Kit .................................................................................................3Installation of JDK 1.4.2 ..................................................................................................................... 3

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

Configuring and Working wi th Developer Studio .....................................................3Configuration of the web application................................................................................................... 3

Remote Debugging 3

Setting up remote debugging for SAP WEB AS Java 7.0 ........................................3Enabling/Disabling Debug Mode Permanently.................................................................................... 3

Enabling/Disabling Debug Mode Temporarily ..................................................................................... 3Starting Remote Debugging............................................................................................................... 3

ABAP Debugging 3

Prerequesites...............................................................................................................3

Activat ing ABAP Debugging ......................................................................................3

Java Debugging 3

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

Finding the Appropr iate Extension Concept ............................................................3How to use these diagrams................................................................................................................ 3Overview............................................................................................................................................ 3Extensions to the UI Layer ................................................................................................................. 3Extensions to the Action Flow............................................................................................................. 3Extensions to Exchange Additional Data ............................................................................................ 3Extensions to Exchange Data with the UI-Layer ............................................................................................... 3

Extensions to Exchange Data with Backend-Systems ....................................................................................... 3

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

Extensions in the Action Flow....................................................................................3Create a Customer Action.................................................................................................................. 3Standard Actions providing User Exits ............................................................................................................. 3Accessing the Session Context......................................................................................................................... 3Accessing Business Objects from Actions ........................................................................................................ 3

Accessing the Request Context.......................................................................................................... 3Modifications in the Struts Configuration............................................................................................. 3Version............................................................................................................................................................ 3

Example .......................................................................................................................................................... 3

Business Object Layer................................................................................................3Storing Additional Data - Extension Mechanism ................................................................................. 3Version............................................................................................................................................................ 3Example .......................................................................................................................................................... 3

Extending existing Business Objects.................................................................................................. 3

Version............................................................................................................................................................ 3Create a Customer Business Object................................................................................................... 3Version............................................................................................................................................................ 3




September 2006 10

Example .......................................................................................................................................................... 3

Create a Customer Business Object Manager.................................................................................... 3Version............................................................................................................................................................ 3Example .......................................................................................................................................................... 3

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

Create an Interface of Backend Object.......................................................................................................... 3

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

Version............................................................................................................................................................ 3Example .......................................................................................................................................................... 3

BADIs/SAP CRM Extensions ............................................................................................................. 3Version............................................................................................................................................................ 3ABAP Extension Structure............................................................................................................................... 3Supported Function Modules and Business Objects .......................................................................................... 3

Order ........................................................................................................................................................... 3User............................................................................................................................................................. 3Contract....................................................................................................................................................... 3Shop............................................................................................................................................................ 3

Complaint (E-Service).................................................................................................................................. 3ComplaintHeader (E-Service)....................................................................................................................... 3ComplaintItem (E-Service)........................................................................................................................... 3

Reading data from the Backend........................................................................................................................ 3Writing data to the backend.............................................................................................................................. 3Example .......................................................................................................................................................... 3

BAPIs/SAP ERP-Extensions .............................................................................................................. 3Version............................................................................................................................................................ 3

ABAP Extension Structure (BAPIPAREX) ...................................................................................................... 3Supported Function Modules and Business Objects. ......................................................................................... 3Order ........................................................................................................................................................... 3

Modification of Communication Structures in SAP ERP................................................................................... 3Configuration of the Web Application.............................................................................................................. 3

Reading Data from the Backend....................................................................................................................... 3Writing Data to the Backend............................................................................................................................ 3Example .......................................................................................................................................................... 3

Java Basket-Extensions..................................................................................................................... 3Version............................................................................................................................................................ 3Example .......................................................................................................................................................... 3

Request Context ..........................................................................................................3Version............................................................................................................................................................ 3

Example .......................................................................................................................................................... 3 Adding addi tional Funct ion Modules (Backend System).........................................3

Version .............................................................................................................................................. 3

Intercept ion of Calls to Standard Function Modules................................................3Thread Safety in Execution Listeners ................................................................................................. 3Version .............................................................................................................................................. 3What to Do......................................................................................................................................... 3Example............................................................................................................................................. 3

Replacing Calls to Standard Funct ion Modules (Backend System) .......................3Version .............................................................................................................................................. 3What to Do......................................................................................................................................... 3Example............................................................................................................................................. 3

Extension of the Web Catalog 3




September 2006 11

New Fields in the Web Catalog (SAP CRM Backend)...............................................3Preparation ........................................................................................................................................ 3Show Additional Attribute in Product List ............................................................................................ 3Show Additional Attribute in Product Details and in Compare Products............................................... 3Show Additional Keys for Extended Search in B2B............................................................................. 3

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

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

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

Extensions of the IPC 3

Architecture of the IPC 5.0 UI in CRM Order Scenario .............................................3 Action Flow ..................................................................................................................3

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

Dynamic Includes ........................................................................................................3Extension To Transfer Data To JSP ................................................................................................... 3

UIBeans ........................................................................................................................3

Client Object Layer......................................................................................................3Finding The Appropriate Extension Concept For IPC..............................................3

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

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

Extensions To The UIBean Layer...............................................................................3

Extensions In The Action Layer .................................................................................3

Create Customer Backend Object..............................................................................3

SCE user funct ions .....................................................................................................3

Exchange addit ional data with ECO ..........................................................................3

Extensions of the Document Handling 3

Overview ......................................................................................................................3

Implementation ............................................................................................................3Example............................................................................................................................................. 3

Integrating own documents........................................................................................3PrepareNewDocAction....................................................................................................................... 3Creating a ManagedDocument ......................................................................................................................... 3

PrepareNewDocAction .................................................................................................................................... 3

Structure of the Internet Sales application ...............................................................3




September 2006 12

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

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

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

Naming Conventions...................................................................................................3Java Server Pages............................................................................................................................. 3Changes in config.xml (or other Struts configuration files)................................................................... 3Changes in bom-config.xml ................................................................................................................ 3Java................................................................................................................................................... 3Packages.......................................................................................................................................................... 3Java Classes..................................................................................................................................................... 3

Resource Files ................................................................................................................................................. 3

Changes in Configuration 3

Appl ication Configuration and Component Conf iguration ......................................3

Common Conf iguration Changes ..............................................................................3Changes in init-config.xml .................................................................................................................. 3Changes in backendobject-config.xml ................................................................................................ 3Changing existing Backend Object ................................................................................................................... 3Adding new Backend Object ............................................................................................................................ 3

Extending XCM wi th Customer Sett ings ...................................................................3What to Do......................................................................................................................................... 3Adding Parameter Name and default Value ...................................................................................................... 3Adding Meta data of XCM parameters ............................................................................................................. 3API for reading XCM parameter Values........................................................................................................... 3

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

Generic Search Framework................................................................................................................ 3E-Service Extended Complaints and Returns specific implementation of the Generic SearchFramework......................................................................................................................................... 3

Checking configuration during runtime ....................................................................3

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

Getting Information about JSPs.................................................................................3Displaying Names of JSPs while Running the Application................................................................... 3Example .......................................................................................................................................................... 3

Displaying Text Keys While Running the Application .......................................................................... 3

Example .......................................................................................................................................................... 3Finding out Information about the Process Flow ................................................................................. 3Analysing the config.xml File (or other Struts configuration files) .................................................................... 3

Session Tracing 3

Configuring session tracing .......................................................................................3

Enabling session tracing ............................................................................................3Tracing Function Modules .................................................................................................................. 3

Addi tional Request Parameters 3

General Request Parameters .....................................................................................3ECO Version...................................................................................................................................... 3Example............................................................................................................................................. 3

Request parameters for B2C......................................................................................3ECO Version...................................................................................................................................... 3




September 2006 13

Example............................................................................................................................................. 3

Single Session Trace ..................................................................................................3

Passing Data between Actions 3

Action Flow Remains on the Server ..........................................................................3

Action Flow i s Interrupted by a JSP ..........................................................................3Working with Request Parser 3

Writing Thread Safe Code 3

Administ rat ion Console 3Java Connector Pools........................................................................................................................ 3

Getting Appl ication Version .......................................................................................3

Logging ........................................................................................................................3

Updating Application 3

Web Diagrams .................................................................................................3Syntax of Web Diagrams 3

B2B - Start Page 3

B2B - Create Basket 3

B2B - Display Order Status 3

References .......................................................................................................3

Update History .................................................................................................3

Table Index.......................................................................................................3

Figure Index .....................................................................................................3




September 2006 14

Development and Extension Guide –

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

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

The document Examples and Tutorials contains examples and extension tutorials for SAP E-Commerce 5.0.

General Introduction

Where the Current Version of this Document is LocatedThe current version of this document is located on the SAP Service Marketplace quick link CRM-INST(https://service.sap.com/crm-inst) mySAP CRM 2005 CRM Core and 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 SAP E-Commerce for mySAP CRM is used, when the E-Commerce application isconnected to a CRM System (ECO CRM).

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

The term command shell is the same as command prompt.

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

The term SP is an abbreviation for support pack.

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

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

September 2006 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. 4.0 or 5.0).

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

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

<J 2EE_REL> SAP J2EE Engine release (e.g. Web AS 7.0).

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

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

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

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

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

<J 2EE_HOME> <INSTDIR>\j2ee

<SDM_HOME> <INSTDIR>\SDM

<APPLI CATI ON> Name of the deployed Internet Sales application (e.g. b2b or b2c).

<APPLI CATI ON_HOME> Directory where the application is deployed.

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

<BUI LDTOOL_HOME> Directory where the ISA build tool is located.

(e.g. C:\isa_build_tool)

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

<PORT> Port on which the deployed application can be reached. For more details onthe SAP J2EE Ports, please refer to the chapter Additional Information 'Figure34: Directory Structure of Web AS Java 7.0

TCP-Ports' on page 3

Table 1: List of the variables used in this guide




September 2006 16

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

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

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

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

Unit four provides an introduction to handling and installing the tools required for running the E-Commerce

application and modifying it.The second part of this document begins with unit 5. This unit introduces various extension concepts neededin order to understand the Example of Extensions and the extension tutorials, that are provided in a specialdocument (see [1] – “Development & Extension Guide: E-Commerce 5.0 - Examples and Tutorials”).

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

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

Courses

CR800: CRM E-Commerce

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




September 2006 17

Marketing Featureso Up/Down, Cross Sellingo Bestsellerso Personalized Product Recommandations

E-Service

o Solution Searcho Service Request Managemento Complaints and Returns Management

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

o Request for Quotation

CR870: CRM Channel Management

Course 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 Segmentationo Lead Managemento Opportunity Management

o Content Management Channel Sales

o Order Managemento Business on behalf

Channel Commerceo Collaborative Showroomo Hosted Order Managemento Set up

Partner & Channel Analytics




September 2006 18

CR850: Internet Sales ERP Edit ion

Course Goals

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

Course Content

Overview, positioning and benefits How to set up Internet Sales in ERP

o User Concepto Features of the ERP Product Catalogo Shop maintenance

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

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

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

CR550: 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 theconnectivity between the systems and software components. The data flow will be analyzed withrespect to the different business scenarios by addressing the following questions:

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

Course 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 BDoco Initial load / delta loado Data flow, configuration and monitoring

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

o WebClient/WinClient

Architecture and technical configuration for Field Saleso CRM Middleware: Synchronization BDoc and Consolidated Databaseo CRM Communication Stationo Mobile Clients




September 2006 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://java.sun.com/ SUN J ave home

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

Java Tutor ials

Link Institution Content

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

Java Newsgroups

News-Link Group Content

de.comp.lang.java German JavaNewsgroup

General Java topics.

comp.lang.java International JavaNewsgroup

General Java topics.


http://java.sun.com/

http://www.jguru.com/



http://www.jguru.com/






September 2006 20

Introduction to SAP J2EEThe 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 applicationcomponents are installed on different machines depending on which tier in the multi-tiered SAP J2EEenvironment the application component belongs to. SAP J2EE multi-tiered applications are generallyconsidered to be three-tiered applications because they are distributed over three different locations:

Client machines

SAP J2EE application server

Database or legacy systems at the backend

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

First tier

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

Middle tier

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

Third tier

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

Figure 1: SAP J2EE three-tier architecture

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

Components can be reused

Availability of a unified security modelFlexible transaction control




September 2006 21

SAP Web Application Server JavaThe SAP Web Application Server Java is part of the SAP Web Application Server platform and consists of the Web container, the EJB container, and services. The Web container is responsible for server-sidepresentation 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 SAPCRM (ERP) system. SAP J2EE based services, for instance resource pooling, security, naming, and so on,are offered by the service component of the SAP J2EE application server.

Figure 2: Components of the SAP J2EE Application Server

Web Container As mentioned before, the Web container consists of Servlets and JSPs. Servlets are Java programminglanguage classes. A Servlet can be thought of as an applet that runs on the server side, without a 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 anHTTPServletRequest object and return a response in the form of an HTTPServletResponse. JSP pages aretext-based documents that execute as Servlets, but allow a more natural approach to creating static content.Java Server Pages cleanly separate Web content (HTML and XML) from programming code by allowingWeb developers to move programming logic into components. This means that Web application developerscan concentrate on developing components while content developers build the HTML presentation.Furthermore, Java Server Pages simplify dynamic page development with tags. Java Server 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 Salesapplication uses these custom tags for certain purposes, for example, translation, completion of a URL,iteration, and so on.




September 2006 22

E-Commerce FrameworkE-Commerce 5.0 is based 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 mainframework concepts. This is a prerequisite for the following paragraphs, in which each layer is discussed inmore detail. You need this information to understand the programming model of the ECO application, as wellas possible customer-extensions to the standard application.




September 2006 23

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

.

Figure 3: Architecture of SAP E-Commerce for mySAP CRM 2005.

Web Browser

Java Stack

Web AS Java

ABAP Stack

Web AS ABAP

IPC Engine

CRM System

Web

Server

TREX

ERPOLTP

APO BW

Optional Backends

SAP E-Commerce fo r mySAP CRM

SAP EP

CRM Java

ComponentsBW

XI

Firewall

Firewall




September 2006 24

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

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

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

The ECO architecture pictures above containe some components that are only required for special processes or are optional. It might be possible that some components are not required in

your system landscape.

Web Browser

Java Stack

Web AS Java

ABAP Stack

Web AS ABAP

IPC Engine

ERP System

WebServer

TREX

APO BW

SAP E-Commerce fo r mySAP ERP

SAP EP

ERP JavaComponentsBW

XI

Firewall

Firewall




September 2006 25

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

The server-side interaction layer processes user requests and calls the server-side business logic and 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 SAPJava Connector.

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

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

Layered ArchitectureThe ISA application architecture consists of the following layers:

Server-side interaction and presentation layer

Business Object layer

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

Business Logic Service layer (BLS)

Manages the backend depended part of the application.

Additional generic services are used throughout all layers:

Loggon/Tracing Extended Configuration Management

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

UI / Interaction /Custom Tags

BO-Layer

L o g gi n g / X C M

Internet Sales Framework

CRM / R3 Catalog IPC DB

JSPs

Actions

Business Objects

Backend Objects

Internet Sales Application

JCo ...Socket JDBC

...

BLS-Layer Backend Objects

Connection Handling

Figure 5: Layered Architecture




September 2006 26

Interaction and Presentation Layer

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

The user interface is realized using Java Server Page technology.

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

JSPs "View"

Interaction Layer

"Controller"

Controller

(Servlet)

Browser

Act ionServ let

View

JavaServer

Pages

Act ions

Business

Object Layer

"Model"

BO

BO

BO

BO

f o r w a r d

r e q u e

s t

dispatch

r e s p o n s e

config

u p d a t e

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 Act i onSevl et . This Servlet actsas a central dispatcher, routing all incoming requests to appropriate Act i ons. The dispatching mechanismis configured externally. Actions represent a server-side processing unit and are accessed via a commoninterface. They act as a mediator between the HTTP world and the Business Objects. After calling theappropriate Business Object(s) the process control returns to the Act i onSer vl et . Depending on the returnvalue of the called Acti on and the external configuration, an appropriate JSP (or other Action) is called, inorder to present the result of the calculation to the user. After mixing the static HTML content with 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 Presentationlayer. Business Objects provide business functionality via well-defined interfaces in a backend-independentmanner. Business functions are either completely provided by these objects or are located in an EnterpriseInformation System (EIS). An EIS is never accessed directly from the BO layer, because Business Objectsare not aware of any backend-specific details. If they have to communicate with a backend they do so usinga set of generic interfaces provided by corresponding Backend Objects. The implementation of theseinterfaces is backend-specific but the interfaces themselves are not.

http://jakarta.apache.org/struts/userGuide/index.html).Struts

http://jakarta.apache.org/struts/userGuide/index.html).Struts

September 2006 27

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

BO Layer

BasketOrder

Item

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 BackendObject in the BLS layer. The functionality of a Backend Object is accessed via a well-defined Java interface(for example, Basket Backend). The implementation of such an interface is backend-dependent (for example, Basket CRM). A Business Object obtains a reference to a backend object from the Backend ObjectManager (BEM). The BEM takes care of the lifecycle of backend objects and returns their references to theBO layer.

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

September 2006 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 DetailsThe Presentation layer is a relatively thin layer in the ISA framework. It consists basically of the SAP J2EEcompliant JSP functionality and some ISA specific custom tags.

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

JSPs

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

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

The functions of all the tags described are packaged as static functions in the classcom. sap. i sa. cor e. ut i l . WebUt i l . This means that you can use the functions of the tag library from

any Scriplets.

September 2006 29

MimeURL

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

application context is used.Mimes are searched using the following pattern:

Parameters

Attr ibute Descript ion Required

name Resource name yes

t heme Theme (default: session context / application context) no

l anguage Language no

Table 2: Parameters of the MimeURL

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

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

There are two additional possibilities to specify the theme parameter:

As context parameter in web. xml file:

As request parameter:

ht t p: / / l ocal host : 50000/ b2b/ b2b/ i ni t . do?theme=<name of theme e.g. summer>

Example:

<context - param>

<paramname>t heme. cor e. i sa. sap. com</ paramname>

<par am- val ue>summer <par am- val ue/ >

</ cont ext - par am>

%mi meSer ver %/ %t eme%/ % anguage%/ %name

%mi meSer ver %/ %t heme%/ %l anguage%/ %name

<cont ext - param>

<paramname>mi mes. i sa. cor e. sap. com</ paramname>

<par am- val ue>htt p: / / p54909: 1080/ i sa/ mi mes</ par am- val ue></ cont ext - par am>

September 2006 30

l ogo. gi f is located in <APPLI CATI ON_HOME>/ b2b/ mi mes/ i mages/ l ogo. gi f after deployingapplication. No mimes server was specified. When calling the application using the following URL

ht t p: / / host : 50000/ b2b/ b2b/ i ni t . do&theme=summer

The mime is searched in the following location

ht t p: / / host : 50000/ b2b/ summer / b2b/ mi mes/ i mages/ l ogo. gi f

WebappsURL

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

Parameters


Name Significant part of the URL yes

Secure Triggers the de-/activation of https protocol in an SSLenvironment. Values: ON | OFF

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

http.port.core.isa.sap.com

Needed when switching from HTTPS to HTTP

https.port.core.isa.sap.com

Needed when switching from HTTP to HTTPS

For information about the secur e requestparameter refer to chapter General RequestParameters on page 3. This parameter is neededif you have the following infrastructure:

web browser => HTTPS => web server => HTTPJ2EE engine

no

AnchorAppends an anchor to the URL nocompl eteUr l 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 tags. The valuesof the used parameters are coded for HTTP.

September 2006 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 determinedwith the actual language-dependent text at runtime.

Parameters


key The key in the resource file yes

arg0 First argument no

arg1 Second argument noarg2 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- I NF\ cl asses\ .

Placeholders within the keys of type {0...4} are replaced by the content of the arg attributes.

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

Example:

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

system. i ni t Fai l ed=I ni t al i zat i on of {0} f ai l ed

The result at runtime is as follows:

I ni tal i zat i on of l oggi ng conf i gurat i on f ai l ed

September 2006 32

iterate

Iteration via a collection. The object that contains the elements to iterate has to implementcom. sap. i sa. cor e. I t er abl e, or has to be one of the standard Java collection classes (Li st , Set ), astandard Java collection iterator, a JDBC Resul t Set , or any one dimensional Java language array.

When working with tables in Internet Sales you can use the classes located in thecom. sap. i sa. cor e. ut i l . t abl e package. Objects of typecom. sap. i sa. cor e. ut i l . t abl e. Resul t Dat a can be used together with the i terate tag.

Parameters


Name Name of object that contains data.Implements com. sap. i sa. cor e. I t er abl e

yes

I d Scripting variable to create. yes

Type Type of scripting variable. yesr esetCur sor Used in scenarios where the iteration is based on

Resul t Set s val ue: t r ue| f al seno

i gnor eNul l Determines the behavior if an entry in the iteration set is null(default f al se; a null-entry will terminate the iteration withoutany other notification).

val ue: t r ue| f al se

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 todisplay double-byte character encoding correctly.

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

Parameters


t ype Specifies the content type (default text/html) no

Table 6: Parameters of th contentType Tag



<TR><TD> <%= cur sor . get Name( ) %> </ TD></ TR>

September 2006 33

Example:

moduleName

This tag is useful in the development process. It displays the name of the current JSP if the application wasstarted with the additional showmodul ename=t r ue request attribute.

This tag should always be entered on top of each main JSP.

For usage of this custom tag refer to chapter 'Displaying Names of JSPs while Running the Application' onpage 3

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/ l ogon. j sp) is shown:

ht t p: / / host : 50000/ b2b/ b2b/ i ni t . do?showmodul ename=t r ue

message

Please refer to chapter ‘Message Framework’ on page 3.

imageAttribute

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

<i sa: modul eName name=‘ / b2b/ l ogon. j sp’ /

<i sa: cont ent Type /




September 2006 34

Parameters:


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

yes

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

yes

def aul t I mg In case no guid can be identified as an attribute holding avalue, the image specified as defaultImage is displayed as amime

yes

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

no

Table 8: Parameters of the imageAttribute Tag

Example:

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

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

The functionality allows also customizing the UI with the help of the XCM admin application. The 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 UIobjects in actions and the UI classes.

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

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

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

Definition

The UI element and fields will be defined in the ui cont rol - conf i g. xml file.

September 2006 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 couldbe set visible. (Default: true)

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

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

Table 9: The structure of the UI element object

The structure of the UI element group 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 XCMadmin we have only restricted possibilities to control the fields. The customer could change between thefollowing values:

Hidden: the screen element is not visible

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

Editable: the screen element is visible and could be changed

<Ui El ement name = "Shi pTo"

al l owed = “f al se”

di sabl ed = "f al se" / >

<Ui El emet name = "Bi l l To"

al l owed = “t r ue”

hi dden = “f al se”

di sabl ed = "f al se" / >

<Ui El ement Gr oup name=”Header”>

<el ememt name=”Shi pTo”/ >

<el ememt name=”Bi l l To”/ >

</ Ui El ementGr oup>

September 2006 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 f ield 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

<par am name="ui.fields. order . del i veryPr i or i ty"

t ype="si ngl esel ect"

short t ext="Vi s i bi l i ty and avai l abl i t i t y of t he f i el d del i very pr i or i ty">

<l ongt ext >

Vi s i bi l i ty and avai l abl i t i ty of the f i el d del i very pr i or i ty .

Not e: Thi s f i el d i s not avai l abl e i n t he Col l abrati ve Showroom at al l !

</ l ongt ext >

<const r ai nt >

<al l owedval ue val ue="hi dden" shor t t ext ="The scr een el ement i s not vi si bl e"/ >

<al l owedval ue val ue="vi si bl e"

shor t t ext ="The scr een el ement i s vi si bl e but coul d not be changed"/ >

<al l owedval ue val ue="edi t abl e" shor t t ext ="The scr een el ement i s vi si bl e and

coul d be changed"/ >

</ const r ai nt >

</ par am

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

<conf i gs>

<conf i g i d="def aul t ">

<params i d="ui - set t i ngs" >

<param name="l anguage" val ue="en" / >

. . .

</ par ams>

<par ams i d="ui-fields">

<paramname="ui . f i el ds. order. del i ver yPr i ori t y" val ue="edi t abl e"/ >

<param name="ui . f i el ds. order . shi ppi ngCondi t i on" val ue="hi dden"/ >

<param name="ui . f i el ds. order . bomExpl osi on" val ue="vi si bl e"/ > <param name="ui . f i el ds. order . subi t emDetai l Vi ew" val ue="hi dden"/ >

<paramname="ui . f i el ds. order. l at est Del i ver yDat e" val ue="edi t abl e"/ >

</ par ams>

</ conf i g>

</ conf i gs>

</ component>

<%- - ask UI cl ass - - %>

<% / * f i rs t exampl e, how to cal cul ate “col span” */

i nt numCol = ui . getNumberOfVisibleElements ( “Gr oup1”) ;

/ * out put of t he f i el ds */

i f ( ui . isElementVisible( ”i t emKey”) { %>

”

<%=ui . getElementDisable( ”i t emKey”) / >

<% i f ( ui . i sVi si bl e( ”i t emName”) { %>

”

<%=ui . getElementDisable( ”i t emName”) / >

. . .




September 2006 38

Action

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

Example

Interaction Layer DetailsThe ISA Interaction Layer consists mainly of the Apache Struts Framework. Some Internet-Sales-specificextensions have been added to this framework. This chapter describes how this layer works. For hands-on

guidelines are covered in various other chapters of this guide.

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

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

E-Commerce 5.0 uses Struts version 1.1 (in older releases Struts 1.0 has been used).ECO uses only a limited set of Struts functionality (for example, no Struts custom tags are used). It istherefore not planned to upgrade to a current version of the Struts framework.

The Struts framework supports the following:

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

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

( ActionForm; rarely used in ISA)

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

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

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

UI ComponentsUI components are realized using Java Server Pages and HTML files. Besides using ISA specific customtags no additional Struts functions are used here. Since this chapter focuses on server-side capabilities thereis nothing further to say than what is common knowledge in the area of JSP. Further details about extension

of the ISA user interface can be found in chapter 'Introduction to Extension Concepts' on page 3.

UI Cont r ol l er ui Cont r ol l er = UI Cont r ol l er. get Cont r ol l er( user Sessi onDat a) ; UI El ement ui El ement = ui Cont r ol l er. getUI El ement ( "cat al og. general ", userSessi onData) ;

/ / di sabl e t he f i el d f or out put :

ui El ement . set Al l owed( t r ue, UI ELEMENT. PR_AUTHORI THY) ;




September 2006 39

Interaction ComponentsIn 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 Acti on is the smallest possible unit that is run in response to a request.Several Actions can also be combined to process a request; the current Action initiates the forwarding in thiscase.

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

Each Action that is to be created is a specialization of class or g. apache. st r ut s. acti on. Acti on.

Each Action has to overwrite the Act i onFor war d per f or m( . . . ) method. This method contains theactual code sequence executed when an Action is called by the Act i onSer vl et . Nevertheless, you willnever derive directly from an Action, but from ISA specific base actions

(com. sap. i sa. cor e. BaseAct i on, or com. sap. i sa. i sacor e. act i on. I saCor eBaseAct i on) , or by extending a customer exit from an ISA application action (see chapter 'Accessing the Session Context' onpage 3)

Figure 10: Actions within ECO Framework

Each Action ends by returning an Act i onFor ward instance, and therefore defines what is done next.

The base class of each or g. apache. st r ut s. acti on. Acti on contains a reference to theAct i onSer vl et , which makes it possible to access Web application resources from within any Action.

The declaration of an Action is explained under Act i onMappi ng 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




September 2006 40

Threads in Actions

In the Act i onSer vl et context a maximum of one instance of each Act ion type exists, but can beprocessed simultaneously by multiple threads. This means that you have to pay special attention to threadsafety when implementing an Action. You should not use instance variables or static variables in an Action if their content is session dependent.

Design issues to remember when coding Acti on 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 Acti on class so that it operates correctly in a multi-threadedenvironment, just as you must code a servlet's ser vi ce( ) method safely.

The most important principle that aids in thread-safe coding is to use only local variables, notinstance variables, in your Acti on 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!

publ i c cl ass myAct i on ext ends BaseAct i on

{

publ i c Act i onForward doPerf orm( Act i onMappi ng mappi ng, Act i onFor m f orm,

Ht t pSer vl etRequest r equest , Ht t pSer vl etResponse r esponse)

t hr ows I OExcept i on, Servl etExcept i on

{ Ar rayLi st arr ay;

/ / doi ng somethi ng wi t h arr ay

/ / no pr obl em because ar r ay i s a l ocal vari abl e and onl y vi si bl e f or a si ngl e t hr ead

}

}


{

pr i vat e Ar r ayLi st mAr r ay;




{

/ / doi ng somet hi ng wi t h mAr r ay

/ / pr obl em because mAr r ay i s an i nst ance var i abl e and shared among several t hreads

}

}




September 2006 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. TheActionForm can be used to validate this data.

Each ActionForm specializes the abstract class or g. apache. st r ut s. act i on. Act i onFor mand definesits own set of data. In the Struts framework, the request parameters of any existing Act i onFor mare set

automatically. To achieve this, the Act i onFor mmust provide appropriate get and set methods. Thelifetime of an Act i onFor musually corresponds to that of the request or, when declared accordingly, that of the session. As is the case with the Acti on, the base class of every Act i onFor mcontains a reference tothe Act i onSer vl et . When validation of the data is requested, the respective Act i onFor mhas to redefinethe Acti onErr or val i dat e( . . . ) method.

The declaration of an Act i onFor mis described in more detail under Act i onFormBean below.

ActionsForms are rarely used in ISA. In most cases data is retrieved from theHttpServletRequest directly, or by using the Request Par ser provided byI saCoreBaseAct i on (see chapter 'Working with Request Parser' on page 3).

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


{

pr i vat e Ar r ayLi st mAr r ay;




{

synchr oni zed(mAr r ay)

{

/ / do somethi ng wi t h mAr r ay

} / / synchroni zed( mAr r ay)

} / / publ i c Act i onFor ward doPer f or m

} / / cl ass myAct i on

September 2006 42

ActionServlet

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

The Act i onSer vl et is defined using the usual Servlet declaration:

The config attribute informs the Servlet about the name of the configuration file. You can use the 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 theAct i onSer vl et . This is achieved using the usual web. xml declaration:

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

ActionFormBean

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

The Act i onFormBean forms the assignment between the name, under which an Act i onFor misaddressed in the configuration file, and the implementation class.

<f or m- beans>

<f orm- bean name=‘ l ogonForm’ t ype=‘ com. sap. i sa. st r uts. LogonForm’ / >

<f orm- bean name=‘ catal ogForm’ t ype=‘ com. sap. i sa. st r ut s. Catal ogForm’ / >

</ f or m- beans>

<! - - Act i onServl et mappi ng - - >

<ser vl et - mappi ng>

<ser vl et name>act i on</ ser vl et name>

<ur l - pat t er n>*.do</ url - pat t ern>

</ servl et - mappi ng>

<! - - Acti onSer vl et decl ar at i on - - >

<servl et>

<ser vl et - name>act i on</ ser vl et - name>

<ser vl et- cl ass>or g. apache. st r ut s. act i on. Act i onServl et </ ser vl et- cl ass>



<par amname>conf i g</ par amname>

<par am- val ue>/ WEB- I NF/ conf i g. xml , / WEB- I NF/ xcmadmi n-conf i g. xml ,

/ WEB- I NF/ ccmsi ms- conf i g. xml , / WEB- I NF/ i pc- conf i g. xml ,

/ i pc/ cust omer/ conf i g. xml , / WEB- I NF/ conf i g_l wc_b2b. xml ,

/ WEB- I NF/ schedul er - conf i g. xml , / WEB- I NF/ i pcpr i ci ng- conf i g. xml

</ paramval ue>



</ ser vl et>

September 2006 43

ActionMapping

Every Acti on is embedded in an Act i onMappi ng instance. The Act i onMappi ngs are described fully inthe configuration file and follow the pattern of the example below:

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

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

The optional attribute name assigns an Act i onFor mto the current Act i onMappi ng.

It only makes sense to use the optional attribute val i dat e when an Act i onFor mis used. This attributetells the Struts environment to perform a validation. You can use the optional attribute i nput to declare aform or the call of another Action that will be displayed or run if the validation fails. Finally, the optionalattribute scope declares the scope of the ActionForm. Possible values for the scope are r equest or sessi on.

You can use the optional attributes pref i x and su f f i x to control the automatic mapping of the requestparameters to the ActionForm properties.

ActionForwardAs explained under ‘Action’ above, every Acti on tells the Struts environment which successive step to call.To do this, the Action tells the Act i onSer vl et how to ‘logically’ continue when it exits the per f or mroutine, a reference to the surrounding Act i onMappi ng instance through a call like:

Act i onFor ward act i onFor war d = ( mappi ng. f i ndFor war d( ‘ l ogon’ ) ) ;

The f or ward tag in the configuration file declares the actual direction for the execution flow.

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

<act i onmappi ngs>

<act i on path = ‘/logon’

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

unknown = ‘ f al se’

name = ‘ l ogonFor m’

pref i x = ‘ i sa_’

suf f i x = ‘ _ i sa’

i nput = ‘ / Logon. j sp’

scope = ‘ r equest ’

val i dat e = ‘ t rue’ >

<f orward name = ‘ success’ pat h = ‘ / showShops. do’ / >

<f orward name = ‘ r egi st er’ path = ‘ / r egi st er. do’ / >. . .

</ acti on>

</ act i onmappi ngs>

September 2006 44

Example: Global declaration

The optional attribute r edi r ect controls whether the server will perform the forwarding (value f al se) or whether the client browser has to (value true). In the latter case, the client is given a URL and is transferredto it via a request. The default setting is server-side forwarding.

ISA extension of Struts

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

ISA 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.I ni t Act i on is a special Action with the following tasks:

Checks if the given XCM configuration is already loaded

o If not, then XCM configuration is loaded.

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

If a session already exists:

o Cleans up the session.

o Notifies the Business Object layer about clean up.

If no session exists yet:

o Initializes the session.

o Sets up/initializes specific objects.

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

You can use the request parameter next Act i on to pass the logical forward on to the I ni t Act i on. For example: htt p: / / l ocal host / i sa/ b2c/ i ni t . do performs the initialization and branches to the successforward defined in the I ni t Act i on. The URL http://localhost/isa/b2c/init.do?nextAction=logon performs theinitialization and branches to the logon forward (a corresponding forward must be defined in the configurationfile).

<gl obal - f orwards>

<f orward name=‘ l ogon’ path=‘ / l ogon. j sp’ r edi r ect =‘ t r ue’ / >

<f or ward name=‘ f ai l ur e’ pat h=‘ / err or. j sp’ / >

</ gl obal - f orwards>




September 2006 45

com.sap.isa.core.BaseAction

All application-specific ISA Actions specialize the abstract class BaseAct i on.

BaseAct i on itself specializes the Struts Action, and contains an abstract method doPer f or mfrom thesignature of the Acti on: : perf or m( . . . ) routine.

All ISA Actions implement the doPer f or mroutine. BaseAct i on is responsible for checking whether or notthe current session is valid. If it is not, it is forwarded to sessi on_not _val i d. If the session is valid, thendoPer f orm(..) is called.

The per f or mroutine is specified with f i nal in the BaseAct i on to prevent it from being inadvertentlyoverwritten.

In addition, BaseAct i on has an auxiliary method:

protected ActionForward isStateValid(ActionMapping mapping, HttpServletRequest request)

This method checks the state of the application and returns a forward to st at e_not _val i d should anyproblems arise.

Example:

General example for using BaseAction.

Process flow:

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

This method is implemented in BaseAction.

A1Action::perform()

Checks the session state.

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

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

com.sapmarkets.isa.isacore.action.EComBaseAction

This Base class provides easy access to Meta Business Object Managers.

publ i c cl ass A1Act i on ext ends BaseAct i on {

publ i c Act i onFor ward doPerf orm(

Act i onMappi ng mappi ng,

Act i onFor m f orm,

Ht t pServl etRequest r equest ,

Ht t pServl etResponse r esponse) t hr ows . . . {

/ / some l ogi c

r eturn mappi ng. f i ndFor ward(‘ success’ ) ;

}

}

September 2006 46

com.sapmarkets.isa.isacore.action.EComExtendedBaseAction

The EComExtendedBaseAction extends the EComBaseAction with a check if the user is logged in.

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

object manager must implement the UserBaseAware interface.

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

(user_no_login)

Example:

This leads to the following error message:

Figure 11: Error Message user_no_login

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

depending from the application in the initialize method.

/ **

* I ni t i al i ze the act i on.

* I n B2C t hi s act i on coul d be used by anonymous user .

*

* @see com. sap. i sa. i sacor e. act i on. I saCoreBaseAct i on#i ni t i al i ze( )

*/

publ i c voi d i ni t i al i ze( ) {

i f ( getAppl i cati on( ) . equal s( CONSTANTS. B2C) ) {

t hi s. checkUserI sLoggedI n = f al se;

}

<gl obal - f orwards t ype="or g. apache. st r ut s. acti on. Act i onFor ward">

<f orward name="l ogi n" path="/ b2b/ l ogi n/ l ogi n. j sp"/ >

<f orward name="user_no_l ogi n" path="/ appbase/ err or. do" / >

September 2006 47

com.sap.isa.isacore.action.IsaCoreBaseAction

This Base class provides easy access to Business Object Managers of the ISA core functionality, the IPC,and the catalog. This action is usually used when developing new functions related to the existing functions,

or when extending existing functions. You have to overwrite the i saPer f or m( ) method when using thisAction 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 typeUser Sessi onData. An instance of this type is created for each session the first time the I ni tAct i on isrun, and this instance is recorded in the session scope. The attributes are recorded under a modified key inthe session scope through this object, and can therefore only be read again via this specific object.

The following code sequence within an Action retrieves a reference to a User Sessi onData 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 whichminimizes integration collision when applying patches or new service packs.

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

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

1. Create a new xlf file for the customer project in the web applications development component or in ashared web component. Make sure, that you added the file to a source folder (e.g. src/packages 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 thefilename 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 theparameter attribute

4. Check in the config file.

<message- r esour ces

par amet er =" projectfile,cr m~i sa~xcmadmi n~r esour ces, cr m~i sa~shopadmi n~r esour ces,

cr m~t c~user~r esour ces, cr m~t c~appbase~r esour ces, cr m~i sa~accessi bi l i t y~r esour ces,

cr m~t c~cor e~r esources, cr m~i sa~web~user~i sar 3, cust omi zi ng,

cr m~i sa~xcmadmi n~r esources "

nul l ="f al se" f act ory="com. sap. i sa. core. MessageResour cesFact ory"/ >

/ / get user sessi on data obj ect

User Sessi onData userSessi onData =

UserSessi onData. getUserSessi onData( r equest. getSessi on( ) ) ;




September 2006 48

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

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

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

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

This chapter contains neither a complete list of possible attacks nor a comprehensive tutorial

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

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

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

Parameters should be validated against a positive value:

Minimum and maximum length

Whether null is allowed

Whether the parameter is required or not

Numeric range

Specific legal values (enumeration)

Specific patterns (regular expressions)

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

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

The com. sap. i sa. cor e. ut i l . Dat aVal i dat or class provides some methods for validation (isInRange,idEmail, matchRegexp)

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

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

September 2006 49

Input FieldSemantics

Incorrect Data / BoundaryData

Example Possible ExpectedResult

Number Field Alphabetical Entries qwert Error Message

Number Field Wrong Number Formats 123.123,123 Error Message

Number Field Numbers out of normalapplication range

4711 if range: 1 to10

Error Message

Date / Time Alphabetical Entries 1234567 Error Message

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

Error Message

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

Search FieldCriterion

* All data


empty string none or all


Quotes "test" or 'test'

String of limitedlength

Very long string Message, either error or truncationwarning

String of limitedlength

Empty String valid, possibly

Mandatory Field Blank String Error Message(Based onapplication)

Field represents anid

same as limited lenght

Field is not a textarea, but input field

The character <Enter> (Based onapplication)

The basic handlingof the <Enter>character, specially

when encoded, it willtend to not show upat times.

Table 11: Input Validation

September 2006 50

Input FieldSemantics

Incorrect Data / BoundaryData

Example Possible ExpectedResult

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

Error Messages(Based onapplication)

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

XSS attack The following string:"><script>window.alert('Hello');</script>

No pop up after submiting therequest

Table 12: Input Validation

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

GuidelinePlease omit using HTTP header information

Persistent Cookies

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

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

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

User specific data

Internal Data

Application critical data

September 2006 51

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

Most severe attacks (general):

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

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

Exploitation of browser vulnerabilities by executing malicious Script

The following figure depicts a possible attack:

Web Server /

J2EE Engine

WebServer

Triggers XSS attacke.g. injects malicious script in guestbook

In case of

stored

attack injected

code is permanently

storedRequests

infected

page

Malicious code

is executed

e.g. session

cookies are

send to

attacker'sweb 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 sideout of a generated page on a server.

Identify JSPs for potential XSS vulnerabilities.

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

To protect against such an attack, encapsulate the outputted string by the method J spUt i l . encodeHt ml ( St r i ng i nput )




September 2006 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 usefulwhile testing the application. Which information is show in case of error should be controlled in a centralplace by one code base.

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

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

The application has to make sure that the user has a valid session and is authenticated before executingcode. => If this is overlooked, potentially a user could type in the URL and look at data not intended 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 thisinformation.

Guideline

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

Use the nol og_ prefix when naming parameters containing sensitive data e.g. nol og_myAccount Number

Comments in HTML CodeYou do make HTML comments in JSP.

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

September 2006 53

Guideline

Use JSP Comments or java comments.

Support of Web Standards (only B2C)

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

Frameless JSP pages

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

Figure 13: Layout areas of frameless JSP pages

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

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

workareaheader

n av i g a t or

mi ni b a s k e t

work area

<%- - pr i nt user name - - %><%

/ / pr i nt user name

out . pr i nt l n( name);

%>

September 2006 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 theUIInlude command for details).

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

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

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

<UI Layout s>

<UI Layout name="basket Layout" pat h=”/ appbase/ l ayout / gener i cLayout . j sp”>

<UI Ar ea name ="header " def aul t Component="header " cssI dName=”header” / > <UI Ar ea name ="wor kar ea" def aul t Component="basket " cssI dName =”wor kar ea” / >

<UI Ar ea name ="mi ni Basket " defaul t Component ="mi ni Basket "

cssI dName=”mi ni basket ” / >

</ UI Layout>

<UI Layout name="cat al ogLayout” pat h=”/ appbase/ l ayout/ gener i cLayout . j sp”>

<UI Ar ea name ="header " def aul t Component ="header " cssI dName =”header” / >

<UI Ar ea name ="navi gat or " def aul t Component="cat al ogcat egor i es"

cont r ol l edAr ea="workarea" css I dName =”navi gat or” / >

<UI Ar ea name ="workar ea" def aul t Component="cat al ogent r y"

css I dName=”wor kar ea” / >

<UI Ar ea name ="mi ni Basket " def aul t Component="mi ni Basket " css I dName=”mi ni Basket ” / >

</ UI Layout>

<UI Component name="header" page="b2c/ header. i nc. j sp" / >

<UI Component name="basketEmpty" page="b2c/ basketEmpty. i nc. j sp" / >

<UI Component name="basket " act i on="b2c/ showbasket . do" / >

<UI Component name="mi ni Basket " act i on="b2c/ showmi ni basket . do"/ >

<UI Component name="checkout1" act i on="b2c/ showcheckout1. do"/ >

<UI Component name="conf i r mat i on" act i on="b2c/ showconf i r mat i on. do" / >

<UI Component name="cat al ogcat egor i es" act i on="cat al og/ showcat egor i es. do" / >

<UI Component name="cat al ogcat egory" act i on="cat al og/ showcat al ogent r y. do" / >

<UI Component name="cat al ogent r y" act i on="cat al og/ showcat al ogent r y. do" / > <UI Component name="product Det ai l " act i on="cat al og/ showproduct det ai l s. do" / >

</ UI Layout s>

September 2006 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 areperformed. The last action which is called must extend thecom.sap.isa.isacore.action.ControlLayoutAction.

BodyAttribute 0..n html attribute tags

Form 0..1 form tag

UIArea 1..n area tags

Table 13: Structure of the UILayer Tag

<acti on path="/ base/ st art . do"

t ype="com. sapmarkets. i sacor e. core. b2c. acti on. St art Act i on">

<f or war d name="success" pat h="UILayout:catalogLayout[header=header,workarea=catalogentry] " / >

<f or war d name="er r or "

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

. . .

</ act i on>




September 2006 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 informationover 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 areacontrols the work area). The value could be used on JSP to provide the“uitarget” parameter.

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

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

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

Table 16: Structure of the UIArea Tag

September 2006 57

The structure of the UIAreaContainer tag

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

Field 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 theUIInclude command.

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

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

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

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

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

Table 18: Structure of the UIComponent Tag

<UI Layout name="cat al ogLayout” pat h=”/ appbase/ l ayout / gener i cLayout . j sp”>

<UI Area name ="header " def aul t Component ="header " cssI dName =”header” / > <UI Ar ea name ="navi gat or " def aul t Component="cat al ogcat egor i es"

cont r ol l edAr ea="workarea" css I dName =”navi gat or” / >

<UI Ar ea name ="mi ni Basket " defaul t Component="mi ni Basket " cssI dName=”mi ni Basket ” / >

<UI Ar ea name ="wor kar ea" def aul t Component="cat al ogent r y" cssI dName=”workar ea” / >

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

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

</ UI Layout>

September 2006 58

The structure of the UIConfiguration tag

The UIConfigurationobject includes a global configuration data which is valid for the complete layout.

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

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

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

Table 19: Structure of the UIConfiguration Tag

Create your component actions

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

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

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

Create your JSP 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 theHTML header and body tag. Remove also the isa:contentType and the isa:include tag.

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

If you plan to use the UIArea (see Control the layout on Page 3 for detail) you have to add the requestparameter com.sap.isa.core.Constants.RP_UITARGET.

Use always the constant instead of the value.

Example:

<% MyUI Cl ass ui = new MyUI Cl ass( ) %>



" / >

" val ue="<%=ui.getUiTarget()%>"/ >

September 2006 59

Use the method getUiTarget of the BaseUI class to get the name of the current displayed layout area or thename of the controlled area (see The structure of the UIArea tag on Page 3 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 whichshould be used within the area. If an area is not listed the currently used or the default component will beused.

Example:

2. Define only the areas in the current layout:

UILayout:[area1=componentX,area2=componentX]

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

Example:


t ype="com. sapmarkets. i sacor e. acti on. St art Appl i cati onAct i on">

<f or war d name="success"

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


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

. . .

</ act i on>


t ype="com. sapmarkets. i sacor e. acti on. St art Appl i cati onAct i on">


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


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

. . .

</ act i on>

September 2006 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 assignedto the layout and all actions which are assigned to the current valid components will be performed. After thispreparation the page assigned to the layout will be displayed.

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

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

<act i on path="/ base/ navi gate. do"

t ype="com com. sapmarket s. i sa. i sacore. act i on. EComGetForwardAct i on">

<f or war d name="cat al og"

pat h="UILayout:catalogLayout" / >

<f or war d name="basket "

pat h="UILayout:basketLayout" / >

. . .

</ act i on>

<act i on pat h="/ base/ updat eBasket "

t ype="com. sapmarket s. i sa. core. act i on. UpdateBasket Act i on">

<f or war d name="success" pat h="UILayout”>

</ act i on>

September 2006 61

Example:

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

Example:

The UIArea also starts the Layout processing.

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

Example:

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

UIJSInclude

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

<act i on path="/ b2c/ catal ogEnt r y"

t ype="com. sapmarkets. i sa. i sacor e. acti on. marketi ng. ShowCatal ogEnt r yAct i on">

<f or war d name="showcat al ogent r y"

pat h="UIInclude: / b2c/ mar ket i ng/ cat al ogent ry. i nc. j sp"/ >

</ act i on>

<act i on pat h="/ base/ swi t chToAr ea. do"

t ype="com. sapmarkets. i sacor e. core. b2c. acti on. SetCatal ogAr ea">

<f orward name="success" pat h="UI Ar ea: cat al ogcat egor i es" / >

<f orward name="err or" pat h="UI Ar ea: err or" / >

. . .

</ act i on>

<% Str i ng workarea = " workarea "; %>



"/ >

"

val ue="<%=ui . getUi Ar eaKey( wor kar ea) %>"

contextValue=”true” / >

September 2006 62

Example:

After the UIJSInclude command must follow always a UIInclude command.

Dynamic change of HTML tit le

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

Example:

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

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

<UI Layout s>

<UI Layout name="basket Layout" pat h=" / appbase/ l ayout / gener i cLayout . j sp"

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

<UI Ar ea name ="header " def aul t Component="header " cssI dName="header " / >

<UI Ar ea name ="workar ea" defaul t Component ="basket " cssI dName ="workar ea" / >

<UI Ar ea name ="mi ni Basket " def aul t Component="mi ni Basket " css I dName="mi ni basket " / >

</ UI Layout>

<Component name="basket Empty" page="b2c/ basketEmpty. i nc. j sp" / >

<Component name="basket " act i on="b2c/ showbasket . do"

title="b2c.title.basket" / >

<Component name="checkout 1" act i on="b2c/ showcheckout 1. do"

title="b2c.title.checkout" / >

<Component name="conf i r mat i on" act i on="b2c/ showconf i r mat i on. do"

title="b2c.title. confirmation"/ >

</ UI Layout s>

<act i on path="/ b2c/ catal ogEnt r y"

t ype="com. sapmarkets. i sa. i sacor e. acti on. marketi ng. ShowCatal ogEnt r yAct i on">

<f or war d name="showcat al ogent r y"

pat h="UIJSInclude: / b2c/ market i ng/ cat al ogent ry. j s. i nc. j sp;

UIInclude: / b2c/ market i ng/ cat al ogent ry. i nc. j sp "/ >

</ act i on>

September 2006 63

Example:

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

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

Layout changes are valid only for the current request.

Example:

<Component name="checkout 1" act i on="b2c/ showcheckout 1. do"

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

Wi t h

b2c. t i t l e. checkout =Checkout order wi t h number: {0}

<UI Layout s>

<UI Layout name="basket Layout" pat h=" / appbase/ l ayout / gener i cLayout . j sp"

action="/b2c/ajustBasketLayout.do">

<UI Ar ea name ="header " def aul t Component="header " cssI dName="header " / >

<UI Ar ea name ="workar ea" defaul t Component ="basket " cssI dName ="workar ea" / >

<UI Ar ea name ="mi ni Basket " def aul t Component="mi ni Basket "

css I dName="mi ni basket " / >

</ UI Layout>

</ UI Layout s>

r equest . set At t r i but e(“ order_Number ”, order. getDocNumber( ) ) ;

September 2006 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 thedisplay of an error message. For this case we will provide an easy mechanism to handle such issues.

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

UIStoreLayout & UIStoreForward

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

Unfortunately there is big restriction. The context values used in thi s layout wil l be lost!

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

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

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

Example:

publ i c cl ass Adj ust BasketAct i on ext ends Cont r ol Layout Act i on {

publ i c voi d cont r ol Layout (

Act i onMappi ng mappi ng,

Act i onFor m f orm,

Ht t pSer vl etRequest r equest ,

Ht t pServl et Response r esponse,

User Sessi onDat a userSessi onDat a,

Met aBusi nessObj ect Manager mbom,

UI Layout l ayout )

t hr ows I OExcept i on, Servl etExcept i on, Communi cat i onExcept i on

{

/ / hi de header

l ayout . get Ui Ar ea("header ") . set Hi dden( t r ue);

}

}

<acti on path="/ b2c/ gotoProf i l e"

t ype="com. sapmarkets. i sa. i sacor e. acti on. b2c. CheckLogi nAct i on">

<f or war d name=" l ogi n"

Pat h="UIStoreLayout; UIStoreForward: profile; UI Layout : l ogi nLayout "/ >

<f orward name="success" path="UI Ar ea: market i ngProf i l e"/ >

</ act i on>

September 2006 65

The UIStoreLayout and UIStoreForward can’t be the last command. There must always followthe 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 islost if you set a bookmark. Therefore you have to provide the fallback action “default” if thecontext is lost.

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

Example:

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

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 veryuseful in combination with the UIStoreLayout and UIStoreForward commands.

<act i on path="/ core/ f orwardToAct i on"

t ype="com. sap. i sa. i sacor e. act i on. EComGetFor wardAct i on">

<f or war d name="default"

path="UI Layout : catal ogLayout [ workar ea=catal ogent r y] " / >

</ act i on>

<act i on pat h="/ b2c/ showLogi n"

t ype="com. sapmarkets. i sa. i sacor e. acti on. b2c. Di spl ayLogi nAct i on">

<f or war d name="succes "

pat h="UIStoreAction:/b2c/display.do; UI Layout : l ogi nLayout "/ >

</ act i on>

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

<acti on path="/ b2c/ gotoProf i l e"

t ype="com. sapmarkets. i sa. i sacor e. acti on. b2c. CheckLogi nAct i on">

<f or war d name=" l ogi n" path="UI St oreLayout ; UI St oreForward: pr of i l e; UIAction: / b2c/ secur eLogi n. do"/ >

<f orward name="success" path="UI Ar ea: market i ngProf i l e"/ >

</ act i on>

<act i on pat h="/ b2c/ l ogi n" name=" l ogi nFor m"

t ype="com. sapmarkets. i sa. i sacor e. acti on. b2c. Logi nAct i on">

<f or war d name="success" path="UIGetLayout; UIGetForward ">

</ act i on>

<! - - UI PopForward cal l s al ways t he base/ getCoreForward act i on - - >

<act i on pat h="/ base/ get CoreFor ward"

t ype="com. sapmarket s. i sa. i sacor e. act i on. EComGetFor wardAct i on">

<f or war d name=" profile" pat h="/ b2c/ got oPr ofi l e. do">

</ act i on>




September 2006 67

Summary of the UI Commands

Global Commands

Command Position in the Path Start Layout Output Redirectallowed

UILayout Last command yes no

UILayout:name Everywhere Yes, if last command no

UIArea Everywhere yes, if last command no

UIAction Always last command. No yes

UIStoreForward Not the last command No -UIStoreLayout Not the last command No -

UIGetLayout Not the last command No -

UIGetForward Always the last command No yes

Table 20: Global UI Commands

Commands while Layout processing

Command Position in the Path Continued Layout Output Redirectallowed

UIInclude Last command yes no

UIJSInclude Not the last command No no

Table 21: Commands while Layout Processing

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

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

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

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

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

September 2006 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 samename.

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

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

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

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

Usage Action

Used in all EcommerceApplications

com.sap.isa.core.InitAction

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

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

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

Table 22: Registration of Context Values

Example

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

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

/ **

* I ni t i al i ze Cont ext val ues. 

*/

St at i c publ i c i ni t Cont ext Val ues ( ) {

Gl obal Cont ext Manager. r egi st erVal ue(Const ant s. CV_LAYOUT_NAME, t r ue, f al se) ;

Gl obal Cont ext Manager. r egi st erVal ue(Const ant s. CV_LAYOUT_STACK, t r ue, t r ue) ;

Gl obal Cont extManager . r egi st erVal ue( Const ant s. CV_FORWARD_STACK, t r ue, t r ue) ;

}

September 2006 69

Example

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

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

Name SingleValue

MultiValue

Description

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

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

changeContextValue X Change the context value in already existing context.

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

resetContextValue X Delete all existent multiple values.

addContextValue X Add a value to the context values.

Table 23: Overview Context Values

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

Example

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

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

<! - - I ni t i al i ze Cont ext val ues used by t he appl i cat i on - - >



<param name="1" val ue="com. sap. i sa. core. I ni t Act i on"/ ><param name="2" val ue="com. sap. i sa. cat al og. act i ons. I SAEnt r yAct i on" / >

<param name="3" val ue="com. sap. i sa. i sacor e. acti on. b2c. I ni t B2CAct i on"/ >



St r i ng product Key = get Context Val ue ( Const ant s. CV_PRODUCT_KEY);

…

set Cont extVal ue( Const ant s. CT_PRODUCT_KEY, product Key) ;

September 2006 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 totrue. This is by default set to false.

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

Example:

<% Str i ng workarea = " workarea "; %>



"/ >

"

val ue="<%=ui . get Ui AreaKey(wor kar ea) %>"

contextValue=”true” / >


<act i on path=”/ b2c/ di spl ay” f orward=”UI Layout ” / >

<act i on pat h="/ b2c/ addtobasket "

type="com. sap. i sa. i sacor e. acti on. order . AddToBasketAct i on">

<f orward name="success" path="/ b2c/ di spl ay. do" r edi r ect=”t r ue”/ >

</ act i on>

St r i ng product Key = get Context Val ue ( "CV_PRODUCT_KEY" ) ;

set Cont extVal ue( "CV_PRODUCT_KEY", product Key) ;

St r i ng pr oduct Key = (St r i ng)r equest . getPar ameter( "PRODUCT_KEY" ) ;

changeContext Val ue( Const ant s. CV_PRODUCT_KEY, product Key) ;

September 2006 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 aredirect after some action. E.g. the user adds a product to the basket. He doesn’t expect to add the productagain if he presses the F5 button. He rather expected that the current page will be refreshed.

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

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

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

Example: Here some examples how to introduce redirects:

<act i on path="/ b2c/ savePer sonal Detai l s"

t ype="com. sap. i sa. i sacor e. acti on. b2c. SavePersonal Detai l sAct i on">


path="UI Ar ea: addr essConf i r mati on; UI Act i on: / b2c/ di spl ay"

r edi rect="t r ue"/ >

</ act i on>

<! —l ast act i on cal l ed af t er t he succesf ul l ogi n - - >

<act i on path="/ b2c/ addBusi nessPart ner "

t ype="com. sap. i sa. i sacor e. acti on. order . AddBusi nessPart nerToBasketAct i on">

<f orward name="mai n_i nner " pat h="UI Get Forward" r edi r ect =”t r ue”/ >

</ act i on>

<act i on path=”/ b2c/ di spl ay” f orward=”UI Layout ” / >

<act i on pat h="/ b2c/ addtobasket "

type="com. sap. i sa. i sacor e. acti on. order . AddToBasketAct i on">

<f orward name="success" path="/ b2c/ di spl ay. do" r edi r ect=”t r ue”/ >

</ act i on>




September 2006 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 applicationbecause 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 definethe action which should be called after the application is re invoked. The command store also the availablecontext and request parameter and provide this information later on to the re invoked action.

September 2006 73

Example:

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

Example:

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

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

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

Figure 15: XCM admin - defaultShopId

<acti on pat h="/ catal og/ getPr oduct . do"

t ype="com. sap. i sa. catal og. acti on. GetPr oduct Act i on" >

<f or war d name="success" pat h="UI Layout " / >

<f orward name="sessi on_not _val i d" pat h="ReI nvoke " / >

</ act i on>

<acti on pat h="/ catal og/ getPr oduct . do"

t ype="com. sap. i sa. catal og. acti on. GetPr oduct Act i on" >

<f or war d name="success" pat h="UI Layout " / > <f orward name="sessi on_not _val i d" pat h="ReInvoke: / cat al og/ get Pr oduct. do"/ >

</ act i on>




September 2006 74

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

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

Init Application

e.g. /b2c/init.do

Store context requestparameter and the action

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

Restore Context andparameter

Action stored for Reinvoke

Figure 16: Prozess of re invoke of an invalid session

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

Business Object Layer Details

Design Considerations

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

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

September 2006 75

The standard concept for Servlets and JSPs entails storing this data in the session context. Thedisadvantage of this procedure is that the data is stored as name value pairs in a flat hierarchy (see also

j avax. servl et . ht t p. Ht t pSessi on). This can quickly lead to naming conflicts (data in the session isoverwritten by mistake) and confusion.

BO Layer

Item

Session

Context

BusinessObjectManager

<<creates>>

Action

<<creates>>

Order Order

Catalog BOM

Meta BOM

other BOMs

<<interface>>

OrderBackend

Figure 17: BO Layer Structure

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

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

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

The Met aBusi nessObj ect Manager is the only object that exists directly in the session context. Aconstant, Sessi onConst . MBOM_MANAGER, can be used to retrieve the object from the session, or aconvenience method, get MBOM( ), of the User Sessi onData object can also be used. To make the processeasier, you can call the get BOM( ) method of the MBOM directly on the User Sessi onData object, whichpasses the call through to the MBOM.

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




September 2006 76

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

September 2006 77

Business Logic Service Layer Details

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

«<<interface>>»

BasketBackend

+myOperation()

BasketCRM

+myOperation()

BackendBusinessObjectBaseSAP

+getDefaultJCoConnection()()+initBackendObject()

+destroyBackendObject()+getContext()

User defined

Interface to BackendSystem

Base class providingBackend Object with

access to frameworkfunctionality

Figure 18: Design of BLS

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

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

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

Backend Objects

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




September 2006 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. i sa. cor e. eai . sp. j co.

BackendBusi nessObj ect BaseSAPIPC Socket based communication com. sap. i sa. cor e. eai . sp. i pc.

BackendBusi nessObj ect I PCBase

Database JDBC based communication com. sap. i sa. cor e. eai . sp. j dbc.BackendBusi nessObj ect J DBCBase

Table 24: Connection Types to Backend

Lifecycle of Backend Object

Backend are 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 it is created by the Backend Object Manager, the i ni t BackendObj ect ( )method is called. Before the Backend Object is destroyed, the dest r oyBackendObj ect ( ) method iscalled 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 i ni t BackendObj ect ( ) method. TheBackendObj ect Manager calls this method after creating the Backend Object.

The properties object holds properties associated with the Backend Object in the backendobj ect -conf i g. xml configuration file.

publ i c voi d i ni t BackendObj ect ( Proper t i es props, BackendBusi nessObj ectPar ams par ams)

t hrows BackendExcept i on;

September 2006 79

There are two types of properties passed to the Backend Object when the i ni t BackendObj ect ( ) methodis called:

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

The BackendBusinessObjectParams are runtime parameters passed by the object that hasrequested a new Backend Object by calling the BackendBusinessObjectcreateBackendBusinessObject(String beBOType, BackendBusinessObjectParams params) method.

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

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

Destruction of Backend Objects

Before the Backend Object Manager becomes invalidated (for example: When a client session is removedfrom memory), it notifies all of its Backend Objects by calling the dest r oyBackendObj ect ( ) method. Thismethod 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 businessfunctions. Nevertheless, sometimes there are cases where data should be made available to all backendobjects. In this case the Backend Context can be used.

com.sapmarkets.isa.core.eai.BackendContext

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

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

Bac en Cont ext getCont ext

<busi nessObj ect t ype=‘ BASKET’ name=‘ Basket SAP’

cl assName=‘ com. sap. i sa. backend. cr m. basket CRM’

connect i onFact oryName=‘ J CO’

def aul t Connect i onName=‘ CRMStat el ess’ >

<par ams>

<param name=‘ i ni t ’ val ue=‘ val ue’ / >

</ par ams>

<busi nessObj ect /




September 2006 80

BackendObjectManager All Backend Objects are created and destroyed by a Backend Object Manager. A Backend Object Manager is accessed using the BackendObj ect Manager interface. This interface provides methods for creatingBackend Objects: cr eat eBackendBusi nessObj ect( )

com.sapmarkets.isa.core.eai.BackendObjectManager

+createBackendBusinessObject()

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

For information about how to write BOMs, Business Objects, and Backend Objects, please see chapter

'Introduction to Extension Concepts' on page 3.

Connection Management

Design Considerations

Backend Objects communicate with the backend system using backend-specific connectors. The BLS layer makes sure that the connection management is fully transparent to the backend objects:

Backend Objects are not aware of any connection configuration

o Connection parameter configuration takes place in XCM

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

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

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

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

RFC based connectivity using SAP Java Connector

JDBC based connectivity to a database

Working with JCo Based Connectivity

Within the BLS layer you never work directly on JCo connections (JCO.Client). Instead youwork on connections of the typ com. sap. i sa. cor e. eai . sp. j co. J CoConnect i on. Onlythis ensures that the BLS layer can take care of connection handling/cleanup correctly.




September 2006 81

JCoConnection

+getJCoFunction(funcName : String)

+execute(function : JCO.Function)+isValid() : boolean

BackendBusinessObjectBaseSAP

+getDefaultJCoConnection()

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

0..n

ConnectionFactory

+getConnection()

1..1

0..n

MyBackendObject

Figure 20: Class Diagramm about use of JCo Connection

A reference to the J CoConnect i on object is obtained from the BackendObject of typecom. sap. i sa. cor e. eai . sp. j co. BackendBusi nessObj ect SAP, which is the base class for allBackend 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 isreturned to the pool (pools can be monitored in the ISA administation; see chapter ‘JavaConnector Pools' on page 3.)

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

o Implementation class for this connection-type is:com. sap. i sa. cor e. eai . sp. j co. J CoConnect i onSt at el ess

Stateful connections

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

o Context is kept on the ABAP system between function calls

o Implementation class for this connection-type is:com. sap. i sa. cor e. eai . sp. j co. J CoConnect i onSt at ef ul

For further information why this is needed, please see

ABAP debugging: chapter 'ABAP Debugging' on page 3

Assigning connections to Backend Objects: chapter '




September 2006 82

Configuring Backend Objects' on page 3.




September 2006 83

Working with JCoConnections

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

1. Obtain a connection (a reference of J CoConnect i on)

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

3. Close the connection by calling J CoConnect i on. cl ose( ) . This should be located in the methodf i nal l y {}

Example:

The following units provide information on the different ways of obtaining a J CoConnect i on.

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 backendobj ect - conf i g. xmlfile. For information how to register backend object refer to chapter '

J CoConnect i on con = nul l ;

t r y {

/ / St ep1: Obt ai n a connecti on

con = getDef aul t J CoConnect i on( ) ;

/ / Step2: Do some work ( e. g. execute f unct i on)

J CO. Funct i on f unc = con. getJ CoFunct i on( ‘ RFC_PI NG’ ) ;

con. execut e(f unc) ;

} cat ch ( BackendExcept i on ex) {

/ / . . . er ror handl i ng of BLS l ayer

} catch ( J CO. AbapExcept i on) {

/ / handl i ng ABAP except i ons ( att ent i on! ! t hi s i s a r unt i me except i on)

} f i nal l y {

CoConnect i on con = get Def aul t J CoConnect i on( ) ;




September 2006 84

Configuring Backend Objects' on page 3.

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 getModDef aul t J CoConnect i on( Propert i es) method. Youuse a set of properties to overwrite/extend the connection definition properties used for the defaultconnection.




September 2006 85

Example:

Constants which can be used to set JCo properties are located in classcom. sap. i sa. cor e. eai . sp. j co. J CoManagedConnect i onFact or y

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

Getting a New Connection from a ConnectioFactory object

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

Example:

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

Working with JCO.Functions

After getting a J CoConnect i on you use it to get/execute J CO. Funct i ons. How this is done is described inthis chapter.

Creating JCO.Functions

A J CO. Funct i on is used to execute remote callable function modules in an SAP system. You obtain areference to a JCO.Function object by calling the following method:

Proper t i es conProps = new Proper t i es( ) ;

conProps. setPr opert y(‘ user’ , webUser) ;

conProps. set Proper t y( ‘ passwd’ , webUserPassword) ;

J CoConnect i on mJ CoCon =

( J CoConnecti on) getConnecti onFact ory( ) . getConnect i on( ‘ J CO’ , ‘ CRMSt atel ess’ , conProps) ;

J CoConnect i on mJ CoCon = ( J CoConnect i on) get Connect i onFact ory( )

/ / get connect i on f r om J CO connect i on f act or y

get Connect i on( ‘ J CO’ , ‘ CRMSt atel ess’ ) ;

Propert i es pr ops = new Propert i es() ;

props. set Proper t y( J CoManagedConnect i onFactor y. J CO_LANG, ‘ de’ ) ;

J CoConnect i on = get ModDef aul t J CoConnect i on( props) ;

CO. Funct i on J CoConnect i on . getJ CoFunct i on St r i ng




September 2006 86

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

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

Example:

Executing JCo Functions

JCo functions are executed using the following method:

After executing the function(s) do not forget to close the connection by calling J CoConnect i on. cl ose( ) .

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

as follows:execut e( J CO. Funct i on f unc) t hr ows BackendExcept i on;

Besides the BackendException, a JCO.AbapException runtime (!) exception can be thrown if the calling function module throws an ABAP exception.

Therefore, please do not forget to catch the BackendException and JCO.AbapException if youcall ABAP function modules and you expect that the Function Module throws an ABAPexceptions.

Example:

J CO. Funct i on myFunc;

J CoConnect i on con = getDef aul t J CoConnect i on( ) ;

myFunc = con. get J CoFunct i on( ‘ SAP_BASKET’ ) ;

t r y {

con. execute( myFunc) ;

} cat ch ( BackendExcept i on bex) {

/ / systemerr or

} cat ch ( J CO. AbapExcept i on abapEx) {

/ / appl i cat i on err or i n SAP system

} f i nal l y {

con. cl ose( ) ;

}

J CO. Funct i on myFunc;

J CoConnect i on con = getDef aul t J CoConnect i on( ) ;

myFunc = con. get J CoFunct i on( ‘ SAP_BASKET’ ) ;

J CoConnect i on. execut e( J CO. Funct i on) ;

September 2006 87

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

Configuration of BLS Layer The main configuration files of the BLS layer are:

WEB- I NF/ xcm/ sap/ modi f i cat i on/ eai - conf i g. xml

o Configures the Connection Management

WEB- I NF/ xcm/ sap/ modi f i cat i on/ backendobj ect - conf i g. 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- I NF/ xcm/customer

/ modi f i cat i on and use the XCM extension mechanism.For information how to register backend objects in customer projects refer to chapter 'Changes inbackendobject-config.xml' on page 3.

Configuring Connection Management

This guide assumes that you do not have to change the connection management configured ineai - conf i g. xml . If you think that this is necessary, create an OSS on component CRM- I SA-

TEC explaining why do you think this is necessary.

There is one exception which make it probably necessary to touch the eai - conf i g. xml file: The JCofunction cache. This one is exmpained in the next paragraph.

JCo Function Cache

When executing a J CO. Funct i on (for further information about JCo see [4] SAP Java Connector: On theSAP Service Marketplace: http://service.sap.com/connectors Java Connector) in the BLS layer, the resultof the call can be either served from the SAP system or from a cache maintained by the BLS layer. Thecache is useful for function modules returning static data and long execution times.

The cache is only implemented for function modues executed with connection typecom. sap. i sa. cor e. eai . sp. j co. J CoConnect i onSt at el ess.

An unambiguous key recognizes each JCo function served from the cache. The key is represented by aString constructed from the called JCo function. There are two key types:

Key Type A:

<l ogon cl i ent t o SAP syst em e. g. 805> + <l ogon l anguage t o SAP syst em> + <st r i ng

r epr esent at i on of i mpor t par amet ers> + <J CO f unct i on name>

http://service.sap.com/connectors

September 2006 88

Key Type B:

The JCo functions that have to be cached by the BLS layer are defined as name/value parameters of themanagedConnect i onFact or y element in the eai-config.xml file:

Cache type A:

Cache type B:

Example:

In this example you register the function 'BAPI_CUSTOMER_GETSALESAREAS to the cache in thecustomer version of eai-config.xml using the XCM extension mechanism. After the change the file looks asfollows:

The cache functions are provided by the com. sap. i sa. core. cache. Cache and configuredusing the cache- conf i g. xml file located in web- i nf \ cf g. If you want to change any cachesettings, you must apply these changes in the region named J CO(all numbers are in minutes).

You can check if functions have been cached in the ISA Administrator area => Java Connector Statistics => JCo Cache Statistics.

<backend ver si on=‘ 5. 0’ xml ns: i sa=‘ com. sap. i sa. cor e. conf i g’

xml ns: xi =‘ ht t p: / / www. w3. org/ 2001/ XI ncl ude’ xml ns: xml =‘ ht t p: / / www. w3. or g/ XML/ 1998/ namespace’ >

<conf i gs>

<xi : i ncl ude hr ef=‘ ${sap}/ modi f i cat i on/ eai - conf i g. xml #xpoi nt er ( backend/ conf i gs/ *) ’ / >

<conf i g i sa: ext ends=‘ . . / conf i g[ @i d=' def aul t ' ] ’ >

<managedConnect i onFact or i es>

<managedConnect i onFact or y name=‘ J CO’ >

<par ams>

<param name=‘ cacheType_A’ val ue=‘ BAPI _CUSTOMER_GETSALESAREAS’ / >

</ par ams>

</ managedConnect i onFact or y>

<param name=‘ cac eType_B’ va ue=‘ FUNCTI ON_MOD_A, FUNCTI ON_MOD_B, . . . ’ / >

<param name=‘ cacheType_A’ val ue=‘ FUNCTI ON_MOD1, FUNCTI ON_MOD2, . . . ’ /

<l ogon cl i ent t o SAP syst em e. g. 805> + <l ogon l anguage to SAP syst em> + <l ogon user - name t o

SAP syst em> + <st r i ng r epresentat i on of i mport paramet ers> + <J CO f unct i on name>

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

http://www.w3.org/XML/1998/namespace




September 2006 89

Configuring Backend Objects

SAP standard Backend Objects are registered in the file WEB-I NF/ xcm/ sap/ modi f i cat i on/ backendobj ect - conf i g. xml . You can register new objects or extendexisting objects. If you do this in customer projects you have to register your objects in the customer versionof backendobject-config.xml using the XCM extension mechanism. This file is located in WEB-I NF/ xcm/ cust omer / modi f i cat i on/ backendobj ect - conf i g. xml . In that case refer to chapter 'Changes in backendobject-config.xml' on page 3.

Backend Objects are registered using the busi nessObj ect XML element.

The busi nessObj ect element has the following attributes:


t ype Specifies the type of the Backend Object, (for example,BASKET). The value of the type attribute must bepassed to the BackendObj ect Manager when aBackend Object is created.

Yes

name Name of Backend Object. Currently not used byframework.

Yes

cl assName Name of implementation class of Backend Object. Yes

connect i onFact oryName Name of the connection factory that provides thedefault connection used by the Backend Object. EachBackendObject provides methods likegetDefaultConnection() returning a connection of the

specified type.

The possible values are:

J CO: for RFC based connectivity with the SAPsystem using SAP Java Connector

I PC: for socket based connectivity to the IPCServer

J DBC: for JDBC based connectivity to adatabase

Connection parameters for all these types are definedin XCM.

If you omit this parameter, then null is returned whencalling get Def aul t Connect i on( ) .

No

Table 25: Attributes of BusinessObject elements

September 2006 90


def aul t Connect i onName 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 specifiedby the connect i onFact oryName attribute.

The common values are:

JCO connection factory:

o I SASt at ef ul for stateful connections(type J CoConnect i onSt at ef ul )

o I SASt at el ess for statelessconnections (type

J CoConnect i onSt at el ess)

IPC connection

o I PC_SOCKET

JDBC connection

o J DBC_CON

no

Table 26: Attributes of BusinessObject elements

The body of the busi nessObj ect element can contain any number of name/value pairs. These propertiesare passed to the Backend Object via the i ni t BackendObj ect ( ) method when it is initialized.

Example taken from B2B:

The parameters (e.g. name=‘ di st r i but abl e’ val ue=‘ NO’ ) can be obtained when thei ni BackendObj ect ( ) method is called.

<busi nessObj ect

t ype=‘ Catal ogSi t e’

name=‘ Cat al ogSi t e’

cl assName=‘ com. sap. i sa. cat al og. i mpl . Catal ogSi t e’

connect i onFact or yName=‘ J CO’

def aul t Connect i onName=‘ I SASt atel ess’ >

<par ams>

<par am name=‘ di st r i but abl e’ val ue=‘ NO’ / >

<par amname=‘ cat al ogSi t eConf i gFi l e’ val ue=‘ WEB- I NF/ / cf g/ / cat al ogsi t e- conf i gR3. xml ’ / >




September 2006 91

Further ServicesThis chapter introduces generic services used in the SAP E-Commerce 5.0 solution.

Message FrameworkThis document gives you a guideline, how to use the generic message framework in your application. Theframework consists also of global message and error pages, which should be included in own application.

The message and handling consists of three parts

Message, MessageLi st Class and MessageLi st Hol der Interface

MessageTag to use on own Java Server Pages

Standardized Message and Error PagesBusiness Object can be implemented as Message Holder with no effort.

The Message class handles a message similar to R3 message. It consists of

Type (Success, Error, Warning, Info)

Description

Key (language independent resource key)

Arguments

Property (for example „Street“ for BusinessObject User)

The MessageList object manages a list of messages.

A message can be added to every object which implements the MessageListHolder interface. Here a list of

objects which already implement this interface:

MessageLi st ,

MessageLi st Di spl ayer ,

Busi nessObj ectBase

Busi nessObj ect Except i on.

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




September 2006 92

Message classes

Message, MessageList and MessageListHolder Class

The Message class handles a message similar to R3 message. It consists of:

Type (Success, Error, Warning, Info)

Description

Key (language independent resource key)

Arguments

Property (for example „Street“ for BusinessObject User)

The MessageList object manages a list of messages.

A message can be added to every object which implements the MessageListHolder interface. Here a list of

object which already implement this interface:MessageLi st , MessageLi st Di spl ayer , Busi nessObj ect Base and Busi nessObj ect Except i on.

A business object can either hold the messages to display it in the front end or log messages to provide it inlog files. In both cases the business object will be set to “invalid” if the message is of the type “error”.

Example

Adding messages from a CRM backend

For the CRM backend the class MessageCRM is used to create messages from the ABAP Structure

CRMT_ISALES_RETURN or BAPI_RETURN.

Example

St r i ng r et urnCode = export Params. get Str i ng( "RETURNCODE") ;

J CO. Tabl e messages =

prof Templ CharGet . getTabl eParameterLi st ( ) . get Tabl e( "MESSAGES") ;

att r i but eSet . cl ear Messages( ) ;

i f ( r eturnCode. l engt h( ) == 0) {

MessageCRM. addMessagesToBusi nessObj ect ( at t r i but eSet , messages) ;

}

el se{

MessageCRM. l ogMessagesToBusi nessObj ect ( at t r i but eSet , messages) ;

t hr ow ( new BackendRunt i meExcept i on( "Err or whi l e r ead at t r i but e set ") ) ;

}

Message message = new Message( Message. ERROR, "shop. l oadEr r or " , args, nul l ) ;

Shop. addMessage(message) ;




September 2006 93

A message could be logged or add to the business partner depending the field TARGET of the structure

CRMT_ISALES_RETURN

“ ” not defined

“A” user message “B” message for log file

“C” message for user and log file

The method spl i t MessagesToTarget 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 theJavaDoc of the corresponding class for further details.

St r i ng args[] = {shopKey. getI dAsSt r i ng( ) };

MessageLi st Di spl ayer messageDi spl ayer = new MessageLi st Di spl ayer ( ) ;

messageDi spl ayer . addToRequest ( r equest ) ;

messageDi spl ayer. set Onl yLogi n() ;

messageDi spl ayer . addMessage( new Message( Message. ERROR, "shop. l oadErr or" , args, nul l ) ) ;

r et urn mappi ng. f i ndForward(“message”) ;

St r i ng r et urnCode = export Params. get Str i ng( "RETURNCODE") ;

J CO. Tabl e messages =

prof Templ CharGet . getTabl eParameterLi st ( ) . get Tabl e( "MESSAGES") ;

att r i but eSet . cl ear Messages( ) ;

MessageCRM. splitMessagesToTarget ( att r i but eSet, messages);

September 2006 94

Example

Message Tag

The MessageTag can display messages of a MessageListHolder on JSP with the dependencies from type

and property.

Example

Exception Handling

Exceptions could be thrown in all level of the application. To prevent to mix up the exception in different levelthe exception should always be converting between different levels.

There exist some helper class to convert exception from a lower level to the according exception.

MessageDi spl ayer messageDi spl ayer = new MessageDi spl ayer( ) ;

messageDi spl ayer . addToRequest ( r equest ) ; messageDi spl ayer . copyMessages( sal esDoc) ;

/ / t he act i on whi ch i s t o cal l af t er t he message

messageDi spl ayer. setAct i on( "/ b2b/ document st atusdetai l pr epare. do") ;

messageDi spl ayer. set Act i onPar ameter( " t echkey="+sal esDoc. get TechKey( ) . get I dAsSt r i ng( )

+"&obj ect t ype="+mandoc. getDocType( )

+"&obj ect s_or i gi n=&obj ect _i d=" ) ;

r etur n mappi ng. f i ndForward( "message") ;

<! –– al l User err or - - >



<%=er r or %>



<! –- er r or s wi t hout a pr opert y - - >



proper t y=„“>

<%=er r or %>



<! –- er r or f or a gi ven pr oper t y - - >

st r eet

 propert y=„st r eet “>

<%=er r or %>




September 2006 95

Backend

Encapsulate the call of a function module always in an own function module.

Example

Use the method J CoHel per . spl i t Except i on(ex) to convert a JCO exception to an ECommerceBackend Exception.

Ensure that the JCO Connection will be closed if you create backend exceptions.

Example

J CoConnect i on connect i on = getDef aul t J CoConnect i on( ) ;

J CoHel per . Retur nVal ue r etVal = cr mI saPr of Templ Char Get( att r i but eSet ,

shop,

shopConf i g,

connecti on) ;

connect i on. cl ose( ) ;

i f ( r et Val . getReturnCode() . l engt h( ) > 0) {

/ / br i ng er r or s t o t he er r or page

MessageCRM. l ogMessagesToBusi nessObj ect ( att r i but eSet , r etVal . get Messages( ) ) ;

MessageCRM. addMessagesToBusi nessObj ect ( att r i but eSet , r etVal . get Messages( ) ) ;

t hr ow ( new BackendRunt i meExcept i on( "Err or whi l e r ead at t r i but e set ") ) ;

}

el se {

MessageCRM. addMessagesToBusi nessObj ect ( att r i but eSet , r etVal . get Messages( ) ) ;

}

l og. enter i ng(“cal l ( ) ” ) ;

t r y {

J CO. Funct i on f unct i on = connect i on. get J CoFuncti on( modul eName) ;

. . .

r eturn new J CoHel per. ReturnVal ue(nul l , "" ) ;

}

catch ( J CO. Except i on ex) {

J CoHel per . spl i t Except i on( ex);

}

f i nal l y {

l og. exi t i ng( ) ;

}




September 2006 96


Use the method Busi nessObj ect Hel per . spl i t Except i on( ex) to convert a backend exception to anECommerce Front end Exception.

Example

Action Layer

Use the EComBaseAct i on class as a base class for your own actions. Because this action handles allECommerce action in appropriate way and forward to the correct error pages (see next chapter). If you wantto check also if the user is logged in use the class EComExt endedBaseAct i on (see chapter ‘Pre Condition

check in the EComExtendedBaseAction’ on page 3).

Error Pages

The framework provides a set of error and message pages which could easily use in other application. Bestyou uses also the EComBaseAct i on as a base class for your own actions because this action handles thecommon exceptions and forward to appropriate pages (see global forwards in chapter ’How to integrate theglobal message pages in an application’ on page 3).

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.

t r y {

r eturn getMyBackendServi ce() . i sUserAut hori zed( user) ;

}

cat ch ( BackendExcept i on ex) {

Busi nessObj ect Hel per . spl i t Except i on( ex);

}

return f al se;

September 2006 97

appbase\relogin\invalidsession.jsp

This page should be displayed after the session is invalid. The /base/relogin/getcookie.do action (see global

forwards in chapter ’How to integrate the global message pages in an application’ on page 3) should becalled 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 willbe handled by the MessageLi st Di spl ayer class.

appbase\jspruntimeerror.jsp

This page displays runtime error on a JSP’s. Without this page the J2EE engine displays only a white screenwith no information that an error occurs. Insert the following line in your JSP to get a message page insteadof a white screen.

appbase\accessibilitymessages.inc.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 3) for details.

Message handling in accessibility modeThere is some support to generate messages in the accessibility mode. With the property pageLocation of

the Message object is possible to describe on which area of the page the error occurs. Please define a

resource key access. message. l ocat i on. <your Locat i on>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=" i t em_<%=J spUt i l . r emoveNul l ( i t em. getNumberI nt ( ) ) %>"></ a>

<a hr ef ="#" name="[location]_[position]"></ a>

message. set PageLocat i on( I TEM) ;

message. set Posi t i on( i t ems. get ( i ) . getNumber I nt ( ) ) ;

message. set PageLocat i on Sa esDocument DataUI . HEADER ;

<%@ page er r orPage="/ appbase/ j sprunt i meexcept i on. j sp" %>

September 2006 98

The message could be displayed with the help of the include appbase\accessibilitymessages.inc.jsp.

The messages which should be displayed could be added with method addAccessi bi l i t yMessages 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 al l messages f or accessi bi l i t y.

*/

publ i c voi d generat eAccMessages( ) {

MessageLi st messagel i st = header. getMessageLi st ( ) ;

f or ( i nt i =0; i <messagel i st. si ze( ) ; i ++) {

Message message = messagel i st . get ( i ) ;

message. set PageLocat i on( HEADER) ;

}

addAccessi bi l i t yMessages( messagel i st ) ; . . .

<%- - Show accessi bi l i t y messages - - %>

<% i f ( ui . i sAccessi bl e) { %>

<%@ i ncl ude f i l e="/ appbase/ accessi bi l i t ymessages. i nc. j sp" %>

<% } %>

<! - - base acti ons start - - >

<acti on path="/ base/ r el ogi n/ setcooki e"

t ype="com. sap. i sa. cor e. act i on. SetRel ogi nCooki eAct i on">

<f orward name="success" pat h="/ user/ per f ormLogi n. do" / >

</ acti on>

<acti on path="/ base/ r el ogi n/ getcooki e"

t ype="com. sap. i sa. cor e. act i on. GetRel ogi nCooki eAct i on">

<f orward name="success" path="/ appbase/ r el ogi n/ i nval i dsessi on. j sp"/ >

</ acti on>

<act i on path="/ appbase/ err or"

t ype="com. sap. i sa. i sacor e. act i on. EComDi spl ayErr orPageAct i on">

</ acti on>

<! - - base acti ons end - - >

September 2006 99

Define the used global forwards in your config.xml:

Define the init action you use to start the application in the web.xml under the parameter

initAction.core.isa.sapmarkets.com(e.g. “/b2b/init.do”) or insure that the action /init.do. starts your

application:

If an header should be included in the message page the header include must be defined in the init-config.xml:

Pre Condit ion check in the EComExtendedBaseAction

The EComExt endedBaseAct i on extends the EComBaseAct i on 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 User BaseAwar e interface.

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

(user_no_login)

Example:

<gl obal - f orwards t ype="or g. apache. st r ut s. acti on. Act i onFor ward">

<f orward name="l ogi n" path="/ b2b/ l ogi n/ l ogi n. j sp"/ >

<f orward name="user_ no_l ogi n" pat h=" / appbase/ err or. do"/ >


<! - - I ni t i al i ze UI - - >



<param name="s i mpl e- header" val ue="/ shopadmi n/ si mpl eheader . i nc. j sp"/ >


<! — support of t he gl obal i ni t acti on - - >

<acti on pat h="/ i ni t . do" f or war d "/ b2b/ i ni t . do"/ >

<! - - ========== Gl obal For war d Def i ni t i ons ========================= - - >

<gl obal - f orwards>

<f orward name="err or" pat h="/ appbase/ err or. do"/ >

<f or war d name="message" path="/ appbase/ message. j sp" / >

<f orward name="backender r or " pat h="/ appbase/ backender r or . j sp"/ >

<f orward name="sessi on_not _val i d" path="/ base/ r el ogi n/ getcooki e. do"/ >

<f orward name="r unt i meexcept i on" pat h=" / appbase/ r unt i meexcept i on. j sp"/ >

<f orward name="pani cexcept i on" path=" / appbase/ pani cexcept i on. j sp"/ >




September 2006 100

This leads to the following error message:

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

depending from the application in the initialize method.

Example:

/ **

* I ni t i al i ze the act i on.

* I n B2C t hi s act i on coul d be used by anonymous user.

*

* @see com. sap. i sa. i sacor e. act i on. I saCoreBaseAct i on#i ni t i al i ze( )

*/

publ i c voi d i ni t i al i ze( ) {

i f ( getAppl i cati on( ) . equal s( CONSTANTS. B2C) ) {

t hi s. checkUserI sLoggedI n = f al se;

}

}




September 2006 101

Generic Search FrameworkThe Generic Selection Framework provides a mechanism to build a Selection screen out of an XMLdescription. In CRM 5.0 the document selection and the customer selection (B2R scenario) are createdusing the Generic Search Framework.

B2B Document Selection Screen:

Figure 21: Generic Search Framework




September 2006 102

Architecture of the Generic Search Framework

Figure 22: Architecture of the Generic Search framework

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 tomanipulate the document search screen.

JSP

SelectionCriteria

JSP

Result list

UI Class

Request Context

MaintenanceObject

(and helper classes)

XCM

Action &

BusinessobjectsSearch /GenericSearchCommand

CRM Or

ERP …

UI Class

Class handlingthe dynamiccontent

September 2006 103

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)

Table 27: Main Components of the Generic Search Framework

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

First entry for each backend is the declaration of the available search screens and the result lists. The searchscreen 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 eachfound 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- / baskettypecombination.

<scr een- group name="search_cr i t er i a"

descri pt i on="search. cri t eri a"

ui Cl assName="com. sap. i sa. ui . ui cl ass. generi csear ch. Generi cSear chI SAUI "

t ype="search">

<pr opert y- gr oup>SearchCr i t eri a_B2B_Sal es</ pr opert y- gr oup>

<pr opert y- gr oup>SearchCr i t eri a_B2B_Cont r act s</ propert y- group>

…

</ scr een- group>

<scr een- gr oup name="r esul t _l i st "

descr i pt i on="r esul t . l i s t"

type="r esul t ">

<pr opert y- gr oup>sal esdoc_resul t l i st _B2B_i t eml i st </ pr opert y- gr oup>

<pr opert y- gr oup>order _r esul t l i st _B2B</ pr opert y- gr oup>

</ scr een- group>

<conf i gs i d="cr mdef aul t "> <! - - THI S I S THE BACKENDTYPE LEVEL ( e. g CRM, ERP, . . . )

<conf i g i d="cr mbasket _cr mt empl ate"> <! - - THI S I S THE BASKETTYPE LEVEL ( e. g cr mbasket ,

September 2006 104

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

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

<! - - **************** ***************** **************** **************** ************ *

START of t he sear ch cr i t eri a def i ni t i on f or B2B Sal es Document s

******************************************************************************* - - >

<proper t y- group name="Sear chCr i t er i a_B2B_Sal es" useSear chRequest Memor y="t r ue"> <pr oper t y name="show_me"

t ype="t ext "

val ue="gs. show. me"/ >

<propert y name="document_t ypes"

t ype="box"

i mpl emenati onFi l t er="t r ue"

r equest Par amet er Name="r c_document t ypes"

r esul t l i st Name="dummy"

maxHi t sToSel ect ="100"

UI J Scr i ptOnChange="GSl oadNewPage( t hi s) ; ">

<al l owedVal ue val ue="ORDER" descr i pti on="b2b. st atus. shuf f l er. key1val 2" r esul t l i st Name="order _r esul t l i st _B2B" defaul t ="t r ue"/ >

<al l owedVal ue val ue="BACKORDER" descr i pti on="gs. at t r . doc. t ype. backor der "

r esul t l i st Name="or der_r esul t l i st _B2B" maxHi t sToSel ect ="0"/ >

<al l owedVal ue val ue="QUOTATI ON" descr i pt i on="b2b. st atus. shuf f l er. key1val 1"

r esul t l i st Name="quot _r esul t l i st _B2B"/ >

<scr een- group name="r esul t _l i st "

descr i pt i on="r esul t . l i s t"

type="r esul t ">

<pr opert y- gr oup>sal esdoc_resul t l i st _B2B_i t eml i st </ pr opert y- gr oup>

<pr opert y- gr oup>order _r esul t l i st _B2B</ pr opert y- gr oup>

</ scr een- group>

September 2006 105

The definition of a result list is also surrounded by the <property-group> tag. It describes the fields whichshould be retrieved from the backend and being displayed on the screen.

Allowed att ributes for tag <screen-group>

Attr ibute Default Remark

uiClassName - Defines the UI class which should be used to buildup the search and result list screen. The classmust implement Interface GenericSearchUIData or more easily extend class GenericSearchBaseUI.

Table 28: Attributes for tag <screen-group>

Allowed att ributes 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 andafter a performed search represented to the webuser.

If set to false, the search screen will always bedisplayed according to default settings.

bodyInclTop - Defines the path/name of an include which will beplaced right after the <body> tag of the <html>page.

maxScreenAreas 1 Number of screen areas for this search screen.This allows splitting the search criteria into severalareas. The areas are <div> blocks and can becontrolled by the Cascading Style Sheet (CSS)file.

cssBodyClassName document-search

CSS class which will be added to the <bodyclass=”<…>”>; tag.

UIJScriptOnStartButton sendRequest(); Name of the JScript function which will be called atthe 'onclick' event of the “GO!” button.

linkTargetFrameName - Name of the frame where the result list should beplaced. This can be used if the result list should belocated into another frame as the search screen.

Table 29: Attributes for tag <property-group>

<propert y- gr oup name="or der_ r esul t l i st _B2B">

<proper t y name="GUI D"

t ype="hi dden" par amet er Type="r owkey" / >

<pr oper t y name="STATUS_SYSTEM"

col umnTi t l e="b2b. st at. cust . shuf . key102"

tr ansl at i onPrefi x="status. sal es. status. "/ >

</ pr opert y- gr oup>

September 2006 106


msgKeyObjectFound gs.result.msg. Resource key prefix for message of how manyobjects 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

Table 30: Attributes for tag <property-group>

Allowed att ributes 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 searchscreen definition where the property appears onthe screen. To separate properties with the samename add an index in form of (1), (2) to theproperty name (e.g. CREATED_AT_DATE(1),CREATED_AT_DATE(2), …)

The index will be automatically removed by theframework.

type - Defines the type of the search screen property:

- box (= drop down list box)

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

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 inattribute “param_function” (see details of component “CRM_ISA_GEN_DOCUMENT_SEL”)

By appending “UI” to the type, this property willonly be used on the screen, but not send to thebackend.

helpValuesMethod - Identifies a help value method defined in filesap\modification\helpvalues-config.xml. Adding thename of an <helpValuesSearch> will bring up anbinocular beside of an input field.

Table 31: Attributes for tag <property>

September 2006 107


implemenationFilter - If set to true the value send with the request will beused to first identify an backend object (see filesap\modification\backendobject-config.xml) and

second to select the ABAP class performing thesearch.

resultlistName - Default name of the result list which will be used, if not otherwise specified (see <allowedValue> tag.Only meaningful if flag “implemenationFilter” is setto “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. antoken from the CRM 1order reporting frameworklike “RAN”)

parameterType - Additionally describing attribute for the propertywhich 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 tobuild up the URL.

MUST be unique within the URL which will be sentto the web server. Since there is no further processing on this attribute, the name could befreely chosen (to be unique).

UIJScriptToCall - Defines a JScript function and event for thisproperty (e.g onBlur=’dosomething();’)

UIJScriptOnChange - Defines a JScript function which should be calledon the “onchange” event. The function will becalled BEFORE the standard JScript function of the framework will be triggered.

screenArea 1 Screen area to which this property belongs. Seealso attribute “maxScreenAreas” of tag <property-group>

label This will allow tagging a label to the property. Thevalue 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 Frameworkwill only return this amount of result list entries.Setting the value to “-1” will return ALL result listentries.

September 2006 108

Allowed att ributes for tag <depending> describing a search screen.


propertyName - Name of the property of which this one shoulddepend on.

Value - Value of the property of which this one shoulddepend on.

Table 33: Attributes for tag <depending>

The <depending> tag allows defining UI dependencies between search screen properties. By defining thisdependency this property will only be visible to a web user if the corresponding property is set correctly.

The dependency is ONLY valid for UI and not for backend selections!!

Allowed att ributes for tag <allowedValue> describing a search screen.


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

<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 isassigned to, has flag “implemenationFilter” set to“true”, an specific result list is assigned. (e.g. anorder document has other fields within its result listas 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’ theattributes “contentCreateClass” and“contentCreateMethod” will be used to instantiateand perform the defined method. Within thismethod the entries of the drop down box can begenerated, and by that reflecting user settings,shop settings or other customizing.

contentCreateClass - Full qualified class name

contentCreateMethod - Method in class given by “contentCreateClass”

Table 34: Attributes for tag <allowedValue>

This tag is only allowed for properties of type “dark” and “box” !!

If a <property> of type “box” has no select option after the evaluation of the <allowedValue> tag, thisproperty will not appear on the final <html> page.

September 2006 109

Allowed att ributes for tag <property> describing a resu lt li st .


name - Name of the property which will be requested inthe backend for the result list.

type - Type of the result list property.

- “date”- “number”- “hidden”

Set this attribute to “hidden” if the value is justneeded for internal purposes and not intended tobe visible to the web user.

“date” and “number” mark properties which are notmeant to be sorted as String!

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 translatedbefore issued on the <html> page

cssClassName - Assigns a special CSS class to this property. Bythat it is possible to control the layout of the valuevia the CSS class.

Hyperlink - Defines a hyperlink for this property value. Thevalue will be created with this hyperlink.

(e.g. b2b/documentstatusdetail.do)

To create the parameter for the hyperlink useattributes “linkParamClass” and“linkParamMethod”.

linkParamClass - Full qualified class name

linkParamMethod - Method in class given by “linkParamClass”

linkTargetFrameName - Defines the target frame where the hyperlinkshould point to.

writeUnderProperty - Allows creating multi-line result lists. This propertywill be written right under the <property> specifiedhere.

defaultSortSequence - Allows to sort the initially issued result list to besorted 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 ispossible for example to issue the value as an icon.

fieldOutputHandlerMethod - See attribute “fieldOutputHandlerClass”.

September 2006 110

Details of component “GenericSearchBaseAction”This Struts action is responsible for processing the search request. In Internet Sales theGeneri cSear chI SAAct i on 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 couldeither be the CRM Application server or the JavaBasket. Determined for the backend is the value of theproperty where attribute “implemenationFilter” is set to “true”. The object with this type will be picked up fromthe xcm\sap\modification\backendobject-config.xml file.

To communicate with the CRM or the JavaBasket the standard classes

- com. sap. i sa. backend. cr m. Gener i cSearchCRM- com. sap. i sa. backend. db. order . Or derTempl ateSt atusDB

should be used.

Details of component “ CRM_ISALES_SEARCH”This part of the description explains how an incoming search request will be processed in the CRM backend.

All communication from Java to CRM is handled by function module CRM_ISA_GEN_DOCUMENT_SEL.

Basically this function module can handle multiple search requests with one call. All search request optionsare linked together with a handle. From the <html> page generated by the genericsearch.jsp only ONEsearch request at the time will be send.

The function module itself is not responsible to handle the search request. It only determines the right BAdIimplementation and hands over the control to it. To determine this BAdI implementation, one of the searchrequest entries (import table IT_SEL_OP) with key SELECT_PARAM = ‘LIST_FUNCTION’ is picked up andits value used to instantiate the BAdI.

Known standard implementations for CRM Internet Sales are:Filter Value ABAP class Remark

ORDER CL_IM_CRM_ISA_GDS_ORDER This implementation is exclusively used toselect order documents.

ORDERTMP CL_IM_CRM_ISA_GDS_ORDERTMP This implementation is exclusively used toselect order templates.

CONTRACT CL_IM_CRM_ISA_GDS_CONTRACT This implementation is exclusively used toselect contract documents.

QUOTATION CL_IM_CRM_ISA_GDS_QUOT This implementation is exclusively used toselect quotations.

BILLINGDOC CL_IM_CRM_ISA_GDS_BILLDOC This implementation is used to select billing

documents. It first decides where to read thedocuments (ERP or CRM) and also what type of documents (invoice, credit memo or downpayment).

BACKORDER CL_IM_CRM_ISA_GDS_BACKORD This implementation is exclusively used toselect backorder documents

1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for itemswithin one sales document (1Order documents).It returns items instead of header objects.

BILLINGITM CL_IM_CRM_ISA_GDS_BILLDOCI This implementation is used to search for itemswithin CRM billing documents. It returns itemsinstead of header objects.

Table 36: Standard Implementations




September 2006 111

All of these BAdI implementations make usage of the powerful helper class“CL_ISA_GEN_DOC_SEARCH_HELP”.

Orders, order templates, quotations and contracts are documents from the CRM 1order application. Toselect documents from the CRM 1order the application provides the CRM 1order reporting framework. Tocommunicate with the reporting framework the helper class provides various methods to format the incomingsearch request and convert it into a reporting framework query. The reporting framework only return the mainkey (GUID) of the found documents. Enhancing these by other attributes like document description,document creation date and so on, the help class provides also an appropriated method.

All methods related to the reporting framework have the prefix ONEORDER_.

Same applies to the billing documents except the prefix of the methods is BILLING_ and the selection iscovert by the function module “/1BEA/CRMB_BD_O_GETLIST” or “CRM_ISA_INVOICE_LIST_GET” for R3billing documents.

If none of the prefixes is used the method has common character and can be used for reporting frameworkand billing.

Internet Sales specific implementation of the Generic Search

FrameworkThe section before gave a detailed overview of the different components of the Generic Search Framework.The components are designed to work in a generically way, independent from an application. This sectionnow focuses on the integration of the Generic Search Framework into the CRM Internet Sales application.

1. Known search definitions in Internet Sales:

Search Screen Definition Scenario Remarks

SearchCriteria_B2B_Sales B2B To search for sales documents.

- orders

- quotations

- order templatesEven billing documents are defined, onceone of those is selected, via JScriptsearch definition“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 largedocument handling is enabled in theshop)

SearchCriteria_B2B_Billing B2B To search for billing documents

- invoices- credit memos

- down payments

Even sales documents are defined, onceone of those is selected, via JScriptsearch definition“SearchCriteria_B2B_Sales” is called.

Table 37: Search Definitions

September 2006 112


SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items(used to find items in case of largedocument handling is enabled in the

shop)SearchCriteria_B2B_Auction B2B Only describes the search criteria, but the

actually search is not done by theGeneric Search Framework

SearchCriteria_BOB_Sales Business onBehalf

To search for sales documents

SearchCriteria_BOB_Customers Business onBehalf

To search for customers in a BOBscenario

SearchCriteria_HOM_Sales Hosted Order Management

To search for order document in a HOMscenario

Table 38: Search Definitions

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

3. Dynamically disabling document types which are not allowed by shop settings or user permissions.

Even in a search definition, for example “SearchCriteria_B2B_Sales”, all Internet Sales known documenttypes are defined, on the <html> page only appear the once allowed by the shop settings.

In the <screen-group> it is possible to define UI class, extending the base one.

For the standard search definitions, this class takes care to remove all document types which are not allowedby shop settings or where users permission are insufficient.

<scr een- group name="search_cr i t er i a"

descri pt i on="search. cri t er i a"uiClassName="com.sap.isa.ui.uiclass.genericsearch.GenericSearchISAUI"

t ype="search">

<component i d="shop">

<conf i gs>

<conf i g i d="cr mshop_b2b">

<par ams i d="shopset t i ngs" >

<param name="shopscenar i o" val ue="B2B" / >

<param name="documentsearch.name" value="SearchCriteria_B2B_Sales"/>




September 2006 113

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.

Logging/TracingLogging/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 InternetSales application.

Design Consideration

When the first Java version of E-Commerce was released there was neither a logging API within the JavaDevelopment Kit, nor an SAP logging API. Instead, an open source LOG4J logging API was well acceptedwithin the Java community.

When designing the E-Commerce architecture it was clear that there would be a time when a new loggingAPI (either from SUN or SAP) would be released. In order to be able to switch to this logging API withoutchanging the application coding it was decided to introduce an own logging facade (API) over the existinglog4j API. Since SAP E-Commerce 4.0 exclusively the SAP logging API below the ISALocation API is used.

Figure 23: Design of Logging / Tracing

Application classes

ISALocation

SAP Logging API

Extensions on

existing customer coding already usingISALocation

New Customer

Project

/ ** * Returns t he name of J Scr i pt f i l es whi ch shoul d be i ncl uded.

* @r etur n Resul t Data cont ai ni ng f i l e names

*/

publ i c Resul t Data getJ Scri pt Fi l esTab( ) {

Resul t Data r etObj = super. get J Scri pt Fi l esTab( ) ;

Tabl e t ab = r etObj . getTabl e() ;

Tabl eRow t abRow = t ab. i nsert Row( ) ;

t abRow. setVal ue(" FI LENAME", "b2b/ j scr i pt / showSol dTo. j sp") ;




September 2006 114

The used logging facade is represented by the class com. sap. i sa. cor e. l oggi ng. I saLocat i on.

Most of the E-Commerce coding is still using ISALocation. SAP Logging API is only used for newapplications in E-Commerce (e.g. Selling via Ebay), not for extensions on existing applications (e.g. B2B).

It is therefore recommended to stay with ISALocation in already existing coding (e.g. customer projectsmigration from ECO 4.0 to ECO 5.0).

For new customer projects it is recommended to use the SAP Logging API directly.

Difference between Logging/Tracing

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?

A trace message can have the following content:

Information about execution steps Value of important variables Important return codes Information about thrown Exceptions

LoggingLog messages are: Always turned on (log level INFO) Mechanism of normal operation

o Target group: Administrators

Logs write using Categories => what has happened?

A log message can have the following content:

Description of Message Possible Impact? Possible reasons?

Information about further information (notes, documentation, ...)

Logs are usually read by system administrators. It is therefore important to provide enoughinformation in order to enable the administrator to understand the message or to solve apotential problem. In order to have a uniform log output there are some helper methods in theclass com. sap. i sa. cor e. l oggi ng. Lot Ut i l for constructing log messages.




September 2006 115

Summary Types of log messages

Message Type Interested Party What to use

message customer or admin log recordmessage developer, support trace record

exception customer, admin log record

exception developer, support trace record

entering/exitingmethod

developer, support trace record

Table 39: Types of Log Messages

Tracing

Use the following severities to write trace messages:

Severity Description

DEBUG Developer trace. Any information useful for adeveloper in order to understand programexecution path

PATH For Information on entering/exiting methods.Useful for important methods.

ERROR Exception meaningful for developer

Table 40: Types of Tracing

APIs for Tracing: ISALocation

You should only use the ISALocation if you already enhanced the E-Commerce 4.0 solution. If you don’t have enhancements, or if you do enhancements for new applications, please use theSAP Logging API instead.

Initializing Location

Entering/exiting non trivial method

pr i vat e st at i c f i nal I saLocat i on l og = I saLocat i on. getI nst ance( Cl assName. cl ass. get Name() ) ;

publ i c voi d entering( St r i ng met hod)

publ i c voi d exiting( )




September 2006 116

Try to use only a single return statement in methods. This makes it easy to use the exiting()trace as well as debugging.

Throwing exception

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

DEBUG

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

ERROR


Coding Examples

Strings are traced as passed to the methods (no resource keys).

publ i c voi d throwing( St r i ng message, Thr owabl e t h)

publ i c voi d throwing( Thr owabl e t h)

publ i c voi d debug( Obj ect message)

publ i c voi d debug( Obj ect message, Thr owabl e t )

publ i c voi d error( Obj ect message)

publ i c voi d error( Obj ect message, Obj ect par ams[ ] , Thr owabl e t )

publ i c voi d error( Obj ect message, Thr owabl e t )




September 2006 117

APIs for Tracing: SAP Logging API

Initializing Location

Contrary to the IsaLocation you pass the class object instead of a string

DEBUG

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

pr i vat e st at i c f i nal Locat i on l oc = Locat i on. getLocat i on( Node. cl ass) ;

debugT( j ava. l ang. St r i ng msg)

debugT( j ava. l ang. St r i ng msg, j ava. l ang. Obj ect [ ] args)

debugT( j ava. l ang. St r i ng subl oc, j ava. l ang. St r i ng msg)

debugT( j ava. l ang. St r i ng subl oc, j ava. l ang. St r i ng msg, j ava. l ang. Obj ect[ ] ar gs)

pr ot ect ed st at i c I saLocat i on l og =

I saLocat i on. getI nst ance(Cl assName. cl ass. getName() ) ;

/ / si mpl e devel oper t r ace

l og. debug( "Thi s i s a t r ace message") ;

/ / ent eri ng exi t i ng method

l og. ent eri ng( "myMethod( ) ") ;

l og. exi t i ng( ) ;

/ / Tr aci ng when t hr owi ng except i on f or dev/ support . PATH i s i nt ernal l y used as severi t y.

/ / No stackt race i s pri nt ed

l og. t hr owi ng( ex);

/ / wi t h some addi t i onal i nf ormati on

l og. t hr owi ng( "except i on t r ace f or support ", ex);

/ / cat chi ng except i on. Tr ace onl y i f rel evant f or suppor t

l og. err or( " i sat est . err or. except i on", ex);




September 2006 118

ERROR


Entering/exiting non trivial method

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

Throwing exception

Use the following methods to write trace messages when an exception is thrown, that is only relevant for developers or the support:

errorT( j ava. l ang. St r i ng msg)

errorT( j ava. l ang. St r i ng msg, j ava. l ang. Obj ect [ ] args)

entering( j ava. l ang. St ri ng subl oc)

entering( j ava. l ang. St ri ng subl oc, j ava. l ang. Obj ect[ ] ar gs)

exiting( )

exiting( j ava. l ang. Obj ect res)

throwing( j ava. l ang. Thr owabl e exc)

throwing( j ava. l ang. St r i ng subl oc, j ava. l ang. Thr owabl e exc)

traceThrowableT( i nt sever i t y, j ava. l ang. St r i ng msg, j ava. l ang. Thr owabl e exc)

Tr ace message wi t h st ack t r ace of gi ven except i on, i nt o t hi s l ocat i on.

traceThrowableT( i nt sever i t y, j ava. l ang. St ri ng subl oc, j ava. l ang. St ri ng msg,

j ava. l ang. Throwabl e exc)




September 2006 119

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 anyfollow-up activity. It should help to understand the normal operation or could providefurther information for later reviews, audits or investigations.

Warning The application processing can and will proceed, but later follow-up activity bypeople responsible for the specific category is necessary to avoid error situations in thefuture. Information of how to solve the problem in the future should be available.

Error The application processing terminates without completing the desired tasks. Theapplication is still usable, but corrective actions need to be performed to avoid theerroneous termination in the future. Information o f how to solve the problem shouldbe 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 byexperts. Customers will normally need to open problem messages to solve the problem.

Table 41: 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. i sa. cor e. l oggi ng. LogUt i l

/Applications/Common/Archiving n.a. in ECO com. sap. i sa. cor e. l oggi ng. LogUt i l

/Applications/Common/Configuration everything related to(mis-)configuration

com. sap. i sa. cor e. l oggi ng. LogUt i l

/Applications/Common/Security everything related tosecurity


/Applications/Common/Infrastructure everything related toinfrastructure i.e.generic services (JCo,

cache, database, etc.)


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


/Applications/BusinessLogic functionality dealingwith business logic(e.g. E-CommerceBusiness Objects)


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


Table 42: Categories for Logs




September 2006 120

APIs for Logging: ISALocation

ERROR

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

FATAL

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

INFO

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

WARNING

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

publ i c voi d error( Category category, Obj ect key)

publ i c voi d error( Category cat egory, Obj ect key, Obj ect[ ] args)

publ i c voi d error( Category cat egory, Obj ect key, Obj ect[ ] args, Thr owabl e t)

publ i c voi d error( Category category, Obj ect key, Thr owabl e t)

publ i c voi d fatal( Category category, Obj ect key)

publ i c voi d fatal( Category cat egory, Obj ect key, Obj ect[ ] args)

publ i c voi d fatal( Category cat egory, Obj ect key, Obj ect[ ] args, Thr owabl e t)

publ i c voi d fatal( Category category, Obj ect key, Thr owabl e t)

publ i c voi d info( Category cat egory, Obj ect key)

publ i c voi d info( Category cat egory, Obj ect key, Obj ect[ ] args)

publ i c voi d warn( Category cat egory, Obj ect key)

publ i c voi d warn( Category cat egory, Obj ect key, Obj ect[ ] args)

publ i c voi d warn( Category category, Obj ect key, Obj ect[ ] args, Thr owabl e t)

publ i c voi d warn( Category category, Obj ect key, Thr owabl e t )




September 2006 121

Detailed Message Descript ions

It is recommended to use detailed message descriptions. These messages can be created using thefollowing methods in the class LogUt i l :

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:

publ i c st ati c LogMessage getLogMessage( St r i ng descri pt i onKey, Obj ect[ ] descr Par ams,

St r i ng i mpactKey, St r i ng r easonKey, St r i ng f ur t herI nf ormati onKey)

publ i c st ati c LogMessage getLogMessage( St r i ng descri pt i onKey, St r i ng i mpactKey,

St r i ng r easonKey, St r i ng f ur t herI nf ormati onKey)

/ / l og wi t h parameter s

l og. i nf o(Category. APPS_COMMON_SECURI TY, "i sa. secur i t y. l ogon. f ai l ur e", new Obj ect[ ]

{ user Name }) ;

/ / l oggi ng usi ng det ai l ed descri pt i ons

/ / exampl e of a l og ent r y i ndi cati ng t hat a user was l ocked

l og. i nf o( LogUt i l . APPS_COMMON_SECURI TY, LogUt i l . get LogMessage(

" l ogon. f ai l ure. descr i pt i on", " l ogon. f ai l ure. descr i pt i on. user. l ocked",

"l ogon. f ai l ure. descri pt i on. wrongl ogon",

" l ogon. f ai l ure. descri pt i on. howt ounl ock") ) ;




September 2006 122

APIs for Logging: SAP Logging API

INFO

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

WARNING

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

ERROR

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

FATAL

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

info( Locati on l oc, j ava. l ang. Obj ect msgCode)

info( Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] ar gs)

logThrowable( Sever i t y. WARNI NG, Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] ar gs, j ava. l ang. St r i ng msgCl ear, j ava. l ang. Thr owabl e exc)

logThrowable( Sever i t y. WARNI NG, Locat i on l oc, j ava. l ang. Obj ect msgCode,

j ava. l ang. St r i ng msgCl ear , j ava. l ang. Thr owabl e exc)

warning( Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] ar gs)

warning( Locati on l oc, j ava. l ang. Obj ect msgCode)

error( Locati on l oc, j ava. l ang. Obj ect msgCode)

error( Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] args)

logThrowable( Severi t y. ERROR, Locat i on l oc, j ava. l ang. Obj ect msgCode,

j ava. l ang. Obj ect [ ] ar gs, j ava. l ang. St r i ng msgCl ear, j ava. l ang. Thr owabl e exc)

logThrowable( Severi t y. ERROR, Locat i on l oc, j ava. l ang. Obj ect msgCode,





September 2006 123

How to Log/Trace: Usage patterns

As a general rule, trace messages are meant for developers to understand the execution flow of theprogram. Log messages are used by system administrators to monitor the health of an application. Thefollowing guidelines define some useful patterns a developer should follow when using log and trace.

1. Define the Location which is used for your class as static final.

2. Trace the entering and exiting of important method.

The severity level is PATH.

If you do trace the entry of a method, it is required that you trace the exit too! If the method mightthrow an exception causing the execution flow to exit the method, you have to trace the exit in afinally clause.

Use a final String object to hold the name of the method you are tracing.

In general following methods must be traced:

i. All UI actions, event handlers (struts actions, do* methods) of UI layer.

ii. All methods of business objects which lead to CRUD operations on data.

iii. All methods of backend objects which trigger backend calls.

iv. All init/close start/stop methods calls.

fatal( Locati on l oc, j ava. l ang. Obj ect msgCode)

fatal( Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] args)

logThrowable( Severi t y. FATAL, Locat i on l oc, j ava. l ang. Obj ect msgCode, j ava. l ang. Obj ect [ ] ar gs, j ava. l ang. St r i ng msgCl ear, j ava. l ang. Thr owabl e exc)

logThrowable( Severi t y. FATAL, Locat i on l oc, j ava. l ang. Obj ect msgCode,





September 2006 124

Example

3. Trace the throwing of exceptions.

The severity level is PATH.

Use throwing (String msg, Throwable err) or throwing(Throwable err) API to trace theexception.

In general, there is no need to log the throwing of an exception. It is up to the calling layer tointerpret the raised exception for appropriate logging.

Example

/ / I f Tr ace t hr owi ng except i on usi ng I SALocat i on

pr i vat e st at i c f i nal I SALocat i on l oc = I SALocat i on. getI nst ance( Cl assName. cl ass. get Name() ) ;

/ / I f Trace t hr owi ng except i on usi ng SAP l oggi ng API

pr i vat e st at i c f i nal Locat i on l oc = Locat i on. getLocat i on( Cl assName. cl ass) ;

/ / …

publ i c voi d met hodX( ) t hrows MyExcepti on {

/ / … f i nal St r i ng msg = “i nf ormat i on about t he except i on”;

MyExcept i on er r = new MyExcept i on(…) ;

l oc. t hr owi ng( msg, err ) ;

}

/ / I f t r ace ent er i ng/ exi t i ng i mpor t ant met hod usi ng I SALocat i on

pr i vat e st at i c f i nal I SALocat i on l oc = I SALocat i on. getI nst ance( Cl assName. cl ass) ;

/ / I f t r ace ent eri ng/ exi t i ng i mport ant method usi ng SAP l ocat i on API


/ / …

publ i c voi d methodX( ) {

f i nal St r i ng METHOD_NAME = " met hodX() " ;

l oc. enter i ng( METHOD_NAME) ;

/ / do some proecss i ng …

l oc.exi t i ng( ) ;

}




September 2006 125

4. Catching Exceptions. When catching an exception, following are some common cases which shouldbe handled differently.

Bubbling the caught exception i.e. the same exception is propagated to higher layers.

If in the catch clause, the caught exception is bubbling to the caller, in general, you should:

Log the catching exception. Use the appropriate Severity ERROR or FATAL Trace the throwing of exception.

Example

Recover from the caught exception or perform an alternate operation or ignore the caughtexception.

In case of recovering from the exception, i.e. the exception is handled in the catch clauseand an alternative operation is chosen to replace the normal operation, you should:

Use severity level WARNING

Trace the alternative operation.

/ / I f Log bubbl i ng caught except i on usi ng I SALocat i on

pr i vat e st ati c f i nal I SALocati on l og = I SALocati on. getI nst ance(Cl assName. cl ass. getName() ) ;

/ / I f Log bubbl i ng caught excepti on SAP l oggi ng API


/ / …

publ i c voi d met hodX( ) t hrows SQLExcepti on {

/ / …

t r y {

/ / do somethi ng …

} cat ch ( SQLExcepti on ex) {

/ / I f us i ng I SALocat i on

l oc. er r or ( Cat egory. APP_COMMON_SECURI TY, msg, args, ex) ;

/ / wr i t e t he cont ext i nf or mat i on t o hel p i n err or suppor t

l og. t hr owi ng( ex); t hrow ex;

}

/ / …

}




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

/ / I f Tr ace r ecover fr omcaught except i on usi ng I SALocat i on


/ / I f Trace r ecover f r omcaught except i on usi ng SAP l oggi ng API


/ / …

publ i c voi d methodX( ) {

/ / …

t r y {


} cat ch ( I nt ernal Except i on ex) {

/ / I f us i ng I SALocat i on

l og. warni ng( Category. Appl i cati ons, "messageKey", args, ex) ;

l og. i nf o(“Do somethi ng t o r ecover f r om except i on”) ;

/ / perf or m r ecover / al t ernat e operati on

}

/ / …

}




September 2006 127

Example

5. Never hide exceptions you cannot handle.

6. To help identify problems, it is important to log context information for the error condition. Useseverity INFO for events that need to provide information about the progress of an operation. For detailed context information including state variables use severity DEBUG. It is especially importantthat sufficient context information is logged and traced for an error condition.

/ / I f Trace t he t hr owi ng a wr apper except i on usi ng I SALocati on


/ / I f Tr ace t he t hr owi ng a wr apper except i on usi ng SAP l oggi ng API


/ / …

publ i c voi d met hodX( ) t hrows Wr apper Except i on {

/ / …

t r y {


} cat ch ( SQLExcepti on ex) { / / I f us i ng I SALocat i on

l og. err or ( Cat egory. APP_COMMON_SECURI TY, "messageKey", args, ex) ;

/ / l og cont ext i nf or mat i on t o hel p i n err or suppor t

Wr apper Except i on wr apper Ex = new Wr apper Except i on(ex) ;

l og. t hr owi ng(“messageKey”, args, wr apperEx) ;

t hrow wr apper Ex;

}

/ / …

}




September 2006 128

Example

/ / I f Trace t he t hr owi ng a wr apper except i on usi ng I SALocati on


/ / I f Tr ace t he t hr owi ng a wr apper except i on usi ng SAP l oggi ng API


/ / …

publ i c voi d save( ) t hr ows DBExcept i on {

/ / …

t r y {

/ / s tar t t r ansact i on

l og. i nf o( “st ar t ed t r ansact i on f or user ”, new Obj ect [ ] {user }) ;

/ / per f or m some sql operati on …

/ / commi t t r ansact i on

l og. i nf o( “commi t ed t r ansact i on”) ;

l og. i nf o(Category. Appl i cat i ons, ”saved busi ness obj ect {0}”, new Obj ect[ ] {obj }) ;

} cat ch ( SQLExcepti on ex) { / / I f us i ng I SALocat i on

l og. err or ( Cat egory. APP_COMMON_SECURI TY, ”Er r or savi ng busi ness obj ect {0}”,

new Obj ect [ ] {obj }) ;

l og. err or( Category. APP_COMMON_SECURI TY, ”er r or. sql err or” , ex) ;

/ / rol l back tr ansact i on

l og. i nf o( “rol l backed t r ansacti on”);

DBExcept i on wr apper Ex = new DBExcept i on(ex) ;

l og. t hr owi ng(“messageKey”, args, wr apperEx) ;

t hrow wr apper Ex;

}

/ / …

}

September 2006 129

All purpose CacheInternet 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 nameis 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 mostcommon attributes are:

IdleTime

Sets the maximum time the object will remain in the cache without being referenced (in minutes).

TimeToLiveSets the maximum time the object will stay in the cache before it becomes invalidated (in minutes).

Although you can initialise the cache in programming, we recommend you do it within the cache-config.xmlfile:

Example

In a customer project you have to add the cache configuration in the file

WEB- I NF/ xcm/ cust omer / modi f i cat i on/ cache- conf i g. 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:

<r egi ons>

<! - - i ncl udes SAP cache conf i gur at i on - - >

<xi : i ncl ude hr ef=‘ ${sap}/ modi f i cat i on/ cache- conf i g. xml #xpoi nt er ( cache/ r egi ons/ *) ’ / >

<! - - def i nes cust omer pr oj ect cache - - >

<r egi on name=‘ Z_AcmeCache’ i dl eTi me=‘ 60’ t i meToLi ve=‘ 300’ descr =‘ Proj ect ACME cache’ / >

</ r egi ons>

September 2006 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. i sa. core. i ni t . I ni t i al i zabl e interface

«<<interface>>»

Initializable

+initialize(env : InitializationEnvironment, props : Properties)+terminate()

MyInitHandler

+initialize()

+terminate()

The i ni t i al i ze( ) method is called when the application is started. This gives the handler the opportunityto perform some initialisation tasks.

The t er mi nat e( ) method is called when the application is stopped or the SAP J2EE engine is shuttingdown. This gives the handler the opportunity to perform some clean up work.

Initialisation handlers are registered in the i ni t - conf i g. xml file.

The file has the following structure:

The className attribute contains the class name of the handler. Any number of parameters can be definedin the body of the i ni t al i zat i on XML element. These parameters are passed as Pr oper t i es to thei ni t i al i ze( ) method.





<param name=‘ paramName’ val ue=‘ paramVal ue’ / >




t r y {

/ / The cache i s accessed usi ng an Access obj ect

Cache. Access access = Cache. get Access( ‘ Z_AcmeCache’ ) ;

/ / st or e an obj ect i n t he Cache

access. put ( ‘ msg’ , ‘ Thi s i s a str i ng’ ) ;

/ / get t i ng obj ect f rom Cache

System. out . pr i nt l n( access. get ( ‘ msg’ ) ) ;

} catch ( Except i on ex) {

l og. er r or ( ‘ z_cache. err or ’ , nul l , ex) ;

}




September 2006 131

If you write your own init handler in customer projects you have to add it to the file

WEB- I NF/ xcm/ cust omer / modi f i cat i on/ i ni t - conf i g. 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- I NF/ xcm/ customer/ modi f i cat i on/ i ni t - conf i g. 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 3.

September 2006 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 thecustomer.

The XCM Administrator tool has been developed for general configuration activities (for example, connectionparameters to the SAP system). The tool enables you to maintain the configuration for each deployed webapplication via the URL:

http://localhost:50000/<web application>/admin/xcm/init.do.

An XCM Administrator tutorial can be found within the ‘CRM Web Application Installation Guide’ on the SAPService Marketplace under the alias CRM-INST -> SAP CRM 4.0 -> Installation & Upgrade.

However, the XCM Administrator tool cannot be used for less common settings. In this case configurationchanges must be done manually.

Separation of Customer and SAP Configuration FilesXCM divides configuration data into two areas:

Data maintained by SAP

o This data must not be changed by the customer.

o It is located in the folder:<APPLI CATI ON_HOME>\ WEB- I NF\ 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:<APPLI CATI ON_HOME>\ WEB- I NF\ xcm\ cust omer

The customer files consist of empty templates. XInclude is used to include SAP configuration into thecustomer template. In most cases customer changes, done by customers, take place in i ni t - conf i g. xmlor backendobj ect - conf i g. xml

You should never change the files config-data.xml or scenario-config.xml . This is done using

XCM Administrator

September 2006 133

Example

This is the customer version of the file i ni t - conf i g. xml :

The xi : i ncl ude XML element includes the SAP version of configuration settings. If you want to changesettings you must use the XCM extension mechanism. The following chapter explains how the extensionmechanism works.

Separation of Configuration Data and Modification DataBesides the separation of SAP and customer data there is another separation of data. That is, data used for configuration of the application (for example, connection data to the SAP System; this is often changed), andmodification data (this data is rarely changed).

The location of the customer configuration data is located in the folder specified using the context parameter cust omer . conf i g. pat h. xcm. conf i g. i sa. sap. com. There are two files used for this kind of configuration:

Configuration of scenarios (scenar i o- conf i g. xml )

Configuration of components (conf i g- dat a. xml )

The XCM administ ration 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 <APPLI CATI ON_HOME>\ WEB- I NF\ xcm\ cust omer \ modi f i cat i on. Hereyou can:

Reassign backend classes to standard business objects, or assign backend classes to customer specific business objects (backendobj ect - conf i g. xml )

Reassign business object managers or add new BOMs (bom- conf i g. xml )

Modfiy cache configurations (cache- conf i g. xml )

Modify connection definitions (eai - conf i g. xml )

Modify parameters in the standard i ni t - conf i g. xml (for example, change the event capturehandler to Tealeaf (i ni t - conf i g. xml )

Add configuration scope parameters accessible from the Interaction Layer (i nt er acti on-conf i g. xml )

Activate ABAP-debugging for JCO-connections, replace function module calls in the backendsystem, assign event listener classes to function module calls, or activate tracing for functionmodules in the backend system (modi f i cat i on- conf i g. xml )

Customer extensions to XCM Admin meta-data (xcmadmi n- conf i g. xml ); This is not covered in

this guide.



<! - - customer changes i n i ni t - conf i g shoul d be done here by

extendi ng/ over wr i t i ng t he base conf i gur at i on- - >

<xi : i ncl ude hr ef =‘ ${sap}/ modi f i cat i on/ i ni t - conf i g. xml #xpoi nt er( i ni t i al i zat i ons/ *) ’ / >

September 2006 134

XCM Extension MechanismThe XCM extension mechanism enables you to manipulate XML nodes using inheritance. If you want tochange existing configuration you have to perform the following steps:

1. Use the i sa: ext ends XML tag to inherit from the configuration you would like to change.

2. Change existing configuration.

3. Add new configuration information, where applicable.

The i sa: ext ends XML element has the following syntax:

i sa: ext ends=‘ XPoi nt er t o base node’

The following example illustrates how the extension mechanism works:

The node with the id Test Conf i gDat a extends the node with id conf i gdat a.

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

<conf i gs>

<conf i g i d=“conf i gdata“>

<params i d=“l ogoncr m“>

<param name=“user “ val ue=“j ohn“/ >

<param name=”passwor d” val ue=”secr et ”/ >

</ par ams>

</ conf i g>

<conf i g i d=“Test Conf i gData“ i sa: ext ends=”. . / conf i g[ @i d=’ conf i gdata’ ] ”>


<param name=“passwor d“ val ue=“t opsecr et “/ >

<param name=”l anguage” val ue=”de”/ >

</ par ams>

</ conf i g>

</ conf i gs>

September 2006 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 totopsecret.

<param name=‘language’ value=‘de’/> was added by the extending node.

<param name=‘user’ value=‘john’/> was inherited from the base node.

If you only want to change certain settings from the base configuration it is sufficient to specify only 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 releaseswithin the XCM Administrator.

The XCM Administration tool is used for creating a web application configuration. Each application providesone or more pre-defined configurations. You have to create your own configuration based on one of thedelivered configurations and then adjust it to your needs. A customer configuration consists of the following:

Configuration name

Base configuration (the SAP configuration on which the customer bases his configuration)

A number of configuration parameters with associated values

o Some of these values refer to a component configuration (e.g. the JCO componentconfigures connection parameters to the SAP system)

Refer to chapter ‘

<conf i gs>

<conf i g i d=“conf i gdata“>


<param name=“user “ val ue=“j ohn“/ > <param name=”passwor d” val ue=”secr et ”/ >

</ par ams>

</ conf i g>

<conf i g i d=“Test Conf i gData“ i sa: ext ends=”. . / conf i g[ @i d=’ conf i gdata’ ] ”>


<param name=“passwor d“ val ue=“t opsecr et “/ >

<param name=”l anguage” val ue=”de”/ >

<param name=”user ” val ue=”j ohn”/ >

</ par ams>

</ conf i g>

</ conf i gs>




September 2006 136

Extending XCM with Customer Settings’ (page 3) to get information how to do customextensions in the XCM.




September 2006 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 Web Application Server and is called JRFC.

TechnologyJRFC communicates with the SAP system via Remote Function Call (RFC). The RFC is SAP’s ownrepresentation of the Remote Procedure Call (RPC). Since the RFC is an ABAP component, it is f requentlyused when at least one of the communication partners is an ABAP program.

The RFC is frequently used in the following scenarios:

Both programs are written in ABAP, and an ABAP program calls a different ABAP function (functionmodule) in a different program or SAP system

An ABAP program calls a function in a non-SAP system

A program in a non-SAP System calls a function module in an SAP system

A program in a non-SAP system calls a function in a non-SAP system

The Java developer uses the JRFC Java API to communicate with the SAP system. The JRFC middlewarelayer ensures that communication with the SAP system is transparent for the Java developer. This includes,

for example, mapping ABAP data types to Java, or table handling.

September 2006 138

Development EnvironmentThis 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 andERP Java Web Applications.

The Netweaver Development Infrastructure supports integration of patches, Service Packs and upgrades tonew releases without loosing modifications or enhancements and it supports team development.

We will discuss the following components:

Java Development Kit (JDK)

NetWeaver’04s Java Development Infrastructure (NWDI)

NetWeaver’04s Java Integrated Development Environment (IDE)

NetWeaver’04s Java Application Server CRM 5.0 Java Components

All examples and operating system specifications in this document refer to Windows.

The following diagram shows a typical Development landscape:

< Local Installation on Developer‘s PC > <--------------- Central Infrastructure ------------------>

NWDI – Landscape Overview

SAP NetWeaver Developer Studio

C h a n g e M a n a g e m e n t S e r v i c

e

( C M S )

Run

Time

J2EE

Systems

Run

Time

J2EE

Systems

Deploy

Local File

System

Component

Model

Local J2EE

Engine

ComponentBuild Service

(CBS)

Design Time

Repository

(DTR)

Name Server

System Landscape

Directory (SLD)

The first of this unit deals with configuring the SAP NetWeaver Development Infrastructure which is aprecondition for the development.

The second part handles the installation and configuration of a developer workplace.




September 2006 139

Development Tools and Concepts

The SAP NetWeaver Developer Studio provides access to the SAP NetWeaver Java DevelopmentInfrastructure. It enhances the concept of an IDE by server-side services, centrally provides the developmentteams with a consistent development environment and supports the software development during the entire

life cycle of a product.

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 andthe transports covering the entire software life cycle.

Software Deployment Manager (SDM): Manual and automatic deployment of archives in centralruntime systems.

System Landscape Directory (SLD): Information on the system landscape.

Name Service Central check instance for the uniqueness of names.

Java Dictionary: Supports the global definition of tables and data types

SAP Java Test Tools: Predefined static tests and runtime tests for the Java development

You use the development configuration to configure the development environment. The access paths for the used services are automatically set by importing a development configuration, for example, the URI of the used DTR.

You can develop in the development infrastructure either according to the component model.

External documentationThis document refers to the following official documents delivered by SAP in the help portal (http://help.sap.com ) :

Administration manual of NWDI :

o http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/f rameset.htm

Overview of processCRM Software Components delivered by SAP are imported in a track. Some of the components aredesigned to be modified. Others are required for compiling and building the application.

http://help.sap.com/

http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/f

http://help.sap.com/saphelp_nw04/helpdata/en/49/e98876e9865b4e977b54fc090df4ed/f





September 2006 140

Software Component Architecture of the CRM or ExtendedEcommerce 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-CommerceApplications, the IPC Web Applications and the Workforce Management Applications.

For E-Commerce for mySAP ERP

SAP-SHRWEB.sca

SAP-SHRAPP.sca

are designed to be modified.

If you plan to extend database tables you can modify the component

SAP-CRMDIC.sca,

in the NWDI as well.

The components

sap.com~STRUTS.sca

sap.com~SAP-IPCMSA.sca

sap.com~SAP-CRMJAV.sca

sap.com~SAP-SHRJAV.sca

TEALEAF.sca

are designed not to be extended or modified in the NWDI. They are required for compiling and building theapplications.

September 2006 141

The following table shows all components at a glance:

Software Component SoftwareComponentfo r Developement

Used inERP

Used inCRM

Usage

SAP-SHRWEB.sca Yes Yes Yes Contains Web Modules for E-Selling,IPC Web Applications and WorkforceManagement

SAP-SHRAPP.sca Yes Yes Yes Contains J2EE Applications anddeployable Libraries.

SAP-CRMWEB.sca Yes No Yes Contains Web Modules for other E-Commerce Applications

SAP-CRMAPP.sca Yes No Yes Contains J2EE Applications anddeployable Libraries.

SAP-CRMDIC.sca Yes Yes Yes Contains Data Dictionary

Development Componentssap.com~STRUTS.sca No Yes Yes Contains required jar Files for

compiling and building

TEALEAF.sca No Yes Yes Contains required jar Files for compiling and building

SAP-IPCMSA.sca No Yes Yes Contains required jar Files for compiling and building

Table 43: Software Components

Thus, you must add the components SAP-SHRWEB.sca and SAP-SHRAPP.sca into the list of the Software

Components for Development. The required Software Components will be selected automatically.

Modifications and Extensions of the Web User Interface

The web user interface of the CRM Applications is contained in the Software Components SHRWEB or CRMWEB.

For each web application there is one Development Component. The naming convention for the Web ModuleDevelopment Components is as follows:

crm/<shortcut for business scenario>/web/<application name>

where <shortcut for business scenario> is either isa (E-Commerce), ipc (Internet Pricing and Configuration)

or wfd (Workforce Management), eservice (service parts management), icss (Internet Customer Self Service)Proceed as follows to modify the Web User Interface:

Open the Netweaver IDE and connect to the CRM Track.

Open the Development Configuration Perspective:Choose Window -> Open Perspective -> -> Development Configuration in the Netweaver IDE menu.

Select the “Inactive DC’s” Panel

Open the Software Component sap.com_SAP-SHRWEB or SAP-CRMWEB

Select the Development Component of the web application you want to modify (E.g.crm/isa/web/b2b) and Choose “Create Project” from the context menu (right mouse click). Accept thelist of Components to be synched.




September 2006 142

Figure 24: Extend and Modify CRM Web Apps

• Do all modifications in SAP-CRMWEB or SAP-SHRWEB

• Put own Java classes in Development component crm/home/shr/ext or crm/home/crm/ext

• Add the used relationship to these components to all web modules which need the java extensions

• Modify the jsp‘s in the SAP original components in order to be able to do conflict resolution when

applying new patches

Extensions of the Java Code

The Software Component SHRWEB contains the Development Component crm/home/shr/ext. It’s designedto contain customer Extensions. By default it contains no classes. Create new Java classes as follows:

Open the Netweaver IDE and connect to the CRM Track.

Open the Development Configuration Perspective:Choose Window -> Open Perspective -> -> Development Configuration in the Netweaver IDE menu.

Select the “Inactice DC’s” Panel

Open the Software Component sap.com_SAP-SHRWEB

Select the Development Component crm/home/shr/ext and Choose “Create Project” from the contextmenu (right mouse click). Accept the list of Components to be synched.

Now you can add new classes to the Development Component in the Java Perspective of the NWDI.Refer to the NWDI Online help for more detailed informations.

The web applications Development Components have no Used Relationships to crm/home/shr/ext. If theclasses are required by a web application, the Used Relationship to the public part “assembly” must beadded for the Web Module Development Component of the application. Search for “Changing Used DC” inthe online documentation of the SAP Netweaver IDE to find out how to do this.

E.g. If crm/isa/web/b2b needs classes of crm/home/shr/ext, the Used Relationship must be created in

crm/isa/web/b2b. It must refer to crm/home/shr/ext.




September 2006 143

Merged Web Applications

All CRM Java applications have the same structure. There are some files which need to be available in allapplications.

For this reason, there is a shared web component DC introduced. This development component type is

based on a regular Java Development Component with a public part of purpose "compilation". Despitenormal java development components the shared web components contain web files to be shared in thesrc/packages directory. These files can be merged into other web archive Development Components bydefining a used relationship in the web module to the shared web component.

Figure 25: Merged Web Files

Shared components are java Development Components.

CRM web archive must not contain java classes, because the compile time dependancy has aspecial meaning!

Files in src/packages directory of the shared component will be merged into the web archive at buildtime

Shared files can be overwritten by files in the web archive if they have the same name and directory

Handling of duplicate files

If the a file with the same name and directory exists in two different shared web components, it's notpredictable which version of the file will be merged into the web module.

If a file is contained in one shared web component DC and in the web module DC, the version of the file fromthe web module will be in the generated web application.

Restrictions

Due to the fact, that the used relationships to java development components are used for merging web files ,

they can't be used for compiling. So, CRM java applications should not contain java source files.




September 2006 144

Init ial Configuration of the NWDIThis section describes how to configure the JDI in order to start modifying the CRM software components.The steps in this chapter are relevant immediately after an installation (the next chapter describes the stepsneeded to handle a Support Package upgrade).

Pre-requisitesThis chapter assumes that you have met the following pre-requisites:

You know how to work with the NWDI. Please refer to the documentation mentioned in chapter “Centrally: SAP NetWeaver Java Development Infrastructure”, if you need more informationabout this.

NWDI has been installed

The NWDI online configuration has been executed

The System Landscape Directory (SLD) has the new content (of the Software Componentsdelivered with this release).

Creating a project specific Web Application withown context rootIn order to be able to compare the SAP standard web applications with the extended applications, it makessense to have two deployments. The first one is the one delivered by SAP, the second one contains projectspecific extensions. This chapter describes how to set up such an application.

Figure 26: Project specific application in CUSTCRMPRJ

• Copy original Software Component from SAP-SHRAPP to CUSTCRMPRJ

• Change Context Root

• Exclude SAP-SHRAPP from deployment




September 2006 145

Basic conceptCreate a new project specific software component in the SLD. Enable deployment in the track.

Add this component to your track for modification.

Create a development component of type “Enterprise Application” for each application you plan to modify

Copy all files of the SAP standard Enterprise Application to your own Software component (exceptapplication.xml).

Add the used relationship to the public part of the Web Module Development Component to the newDevelopment Component.

Check in the files.

Only the new Software Component will get the extended version of the application. These versions will bedeployed on the Web AS Java System by NWDI.

The SAP standard component SAP-CRMDIC, SAP-SHRAPP and/or SAP-CRMAPP can be deployed directlyto the Web AS Java Server.

Step by step process

Check SLD content and create a new Software Component

If you installed the NWDI Infrastructure by installing usage type DI, the SLD content was importedautomatically. This content may not be up-to-date.

Check whether the Software Component CRM JAVA CUSTOMER PROJECT 5.0 exists in the SLD:

If tbis component is missing, you import an update of the CIM Model from the service market place. Refer to

Note 669669 for more details.You'll find more information about SLD and maintenance of Software Dependancies at http://help.sap.com

Create a new Track using the Landscape Configurator

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

Figure 27: Creating a new Track

Substitute the URLs with the appropriate ones from your landscape.






September 2006 146

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 + Archive)

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 + Archive)

If you need to modify the Java Data Dictionary:

SAP-CRMDIC (Package Type: Source + Archive optional)

An example is shown below:

Figure 28: Adding Software Component

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




September 2006 147

Figure 29: Required Software Components

As shown, the following “Required Software Components” are automatically populated:

SAP_JTECHS SAP-JEE SAP_BUILDT …

Save your changes by clicking on the “Save” button on this tab.

Configure Runtime Systems in the track

Configure your runtime systems as described in the following topic in the help portal:

http://help.sap.com/saphelp_nw04/helpdata/en/35/1cd66947184aa8915ca1831c59b6c1/content.htm



September 2006 148

Import Software Components into this track

Download Archives

The Software Component archives ( .sca files ) must be downloaded from the Service Marketplace (http://service.sap.com/patches ) and placed into the “inbox” folder of the CMS. (The “inbox” folder can befound under the following path: “<CMS Transport Directory>\CMS\inbox”, where the <CMS TransportDirectory> is specified in the “Domain Data” tab of the CMS Landscape Configurator).

The following .sca files must be placed into the CMS inbox folder:

o SAP_JTECHS.scao SAP_BUILDT.scao SAP-JEE.scao SAP-SHRJAV.scao SAP-SHRWEB.scao SAP-SHRAPP.scao SAP-CRMJAV.scao SAP-CRMWEB.scao SAP-CRMAPP.scao SAP-CRMDIC.scao SAP-IPCMSA.scao STRUTS.scao TEALEAF.sca

The names of .sca files could be different – they may include version numbers, vendor name,etc.

Check-In archives

In the “Check-In” tab of the CMS Transport Studio CMS perform a “Check-In” : select each of the abovearchives and click on the “Check-In” button.

Figure 30: Check-In of the Archives

http://service.sap.com/patches

http://service.sap.com/patches




September 2006 149

Import the checked in archives into the Development system

In the “Development” tab, select the checked-in components and click the “Import” button.

Figure 31: Development System

This import will run for several hours (if all the components are selected together). After the import the “state”(field on the extreme right in the picture above) will be shown as “Import Finished”

Import the checked in archives into the Consolidation system

Repeat the above step in the “Consolidation” tab.

Create your own Enterprise Applications

The following steps need to be done:

Import the Development Configuration into your Netweaver IDE.

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 EnterpriseArchive into the META-INF directory of the new Development Component.

If you want to modify or extend the crm/b2b application, open the project for crm/b2b. A projectfor the previously created development should already be open.

Open the java perspective and copy the following files from the META-INF directory of the crm/b2bcomponent to the META-INF directory of the home/b2b component:

o application-j2ee-engine.xml

o data-source-aliases.xml

o log-configuration.xml

o monitor-configuration.xml

o monitor-configuration.dtd

Check in the new Development Component.

Look at the online help of the Netweaver IDE for more details on how to execute these steps.




September 2006 150

Test the CRM Java appl ication on a local Web AS Java Engine

In order to be able to run CRM Java applications you need to deploy the SAP-CRMDIC software componenton your local Web AS Java engine. It contains all required database table definitions.

Additionally you need to deploy the enterprise application of the application you want to test.

The deployment of the enterprise application Development component can be started in the Developmentconfiguation perspective of the Netweaver IDE:

Look at the online help of the Netweaver IDE for more details.

Creation or Extensions of Java ClassesThis chapter describes how to create new java classes or extend existing ones in the NWDI.

In Software Component SAP-CRMWEB and SAP-SHRJAV, java development components are prepared to

be extended in the NWDI. For SAP-CRMWEB the java DC is crm/home/crm/ext, for SAP-SHRWEB it’scrm/home/shr/ext. These components are empty when shipped.

A used relationship in the web module development components of the applications to the java developmentcomponents needs to be added, for each application which uses the new classes.

In the java development components a lot of used relationships to the most common SAP standard javadevelopment components are already defined. If a new java class needs further references to other javadevelopment components, new used relationships need to be added.

E.g. If a new class in the cr m/ home/ shr / ext needs a class contained in crm/isa/isacorer3 for compiling, anew used relationship in cr m/ home/ shr / ext to the public part default in crm/ i sa/ i sacor er 3 needs tobe added.

More details of Used Relationships can be found at

http://help.sap.com/saphelp_erp2005/helpdata/en/1c/bca99c220c0e45a1cae3c4cccf4346/frameset.htm

or in the online help to the SAP Netweaver IDE.



September 2006 151

Importing Modifications and Extensions from older ReleasesThis chapter describes how to import modifications and extensions from former Releases (CRM 3.0, 3.1 and4.0). It assumes that the buildtool was used to build the modified application and that there is a new CRM 5.0NWDI track available to import the extensions and modifications. It further assumes that basic knowledgeabout NWDI is available.

The “SAP Customer Relationship Management 5.0 Java on <Operating System> : <Database>” guidedescribes how to install the NWDI

See http://help.sap.com for informations about administrating the NWDI

See Online help of the Netweaver IDE for informations about usage of DTR and DevelopmentConfigurations.

In general the following steps are required:

1. Replace “sapmarkets” with “sap” in all source codes and web files2. 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)

There is a new version of the buildtool attached to note 594370. 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 executethe other targets like build “extract.ears”.

The following table lists all steps which are required to import the modifications and extensions of a webapplication into a CRM 5.0 NWDI track.

Step Descripti on

1 Update the build toolNote 594370 contains a description of the upgrade procedure.

2 Execute target “nwdi” with the buildtoolThe documentation of the buildtool contains a description how to execute an 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 ComponentSHRJAV. Crm/home/crm/ext ist designed to hold extensions of the java classes in SoftwareComponent CRMJAV.

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 besetup on the nameserver and the used relationships to the Development Components need to bemaintained.

Table 44: Steps of Importing Modifications and Extensions


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

September 2006 152

Step Descripti on

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>/<ConfigurationNumber>/DCs/sap.com/crm/home/shr/ext/_comp or to <NWDI Configurationroot>/DCs/sap.com/crm/home/crm/ext/_comp

<NWDI Configuration root> stands for the root of the NWDI. See Windows->Preferences->JavaDevelopment Infrastructure -> Development Configuration -> root Folder in the Netweaver IDE toget this value

<Configuration Number> stands for the number of the imported DevelopmentConfiguration(normally this is 0)

5 Execute a build for the java Development Component in the IDE.Hint: For the predefined DC’s the most important used DC relationships are already established.However it might be necessary to add further Used Relationships to make the extensionscompilable.

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 SHRWEBSoftware 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 Componentname>/_comp

Hint: If the IDE will not automatically check that the new files have been added. After executing arefresh 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 5.0 Web Module _compfolder.

The buildtool target nwdi created a directory <buildtool root>/nwdi/<application name>_<projectname>.

This directory has the same structure as the same directory structure as the Web ModuleDevelopment Components.

Some of the files shipped in the new release might differ from the older versions of the files, so it’snot possible to copy the modified files into the _comp directory but the changes need to bemerged into the new version.




September 2006 153

Step Descripti on

10 If you added java classes and you want to use them in the modified web application, you need toadd the java Development Component to the list of Used DC’s of the Web Module. Look at thenetweaver 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


Developer Workplace

When we look at the architecture of SAP E-Commerce 5.0 we will discuss the following components: Java Development Kit (JDK)

SAP Web AS Java

o SAP J2EE Application Server

o SAP Java Connector (JCo)

o SAP Java Basis

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.

InternetInternetBusiness

Execution

Business

ExecutionBusiness ServiceBusiness Service

R/3-System

Presentation

BW

APO = Adva nced Plann er & Optim izer

BW = Business Warehouse

IPC = Internet Pricng & Configurator

BLS = Business Logic Service Layer

JCO = Java Connector

BP = Business Partner

PC = Product Catalog

PM = Product Master

APO = Advan ced Plann er & Optim izer

BW = Business Warehouse

IPC = Internet Pricng & Configurator

BLS = Business Logic Service Layer

JCO = Java Connector

BP = Business Partner

PC = Product Catalog

PM = Product Master

mySAP CRM

J2EE Appl.

Server Browser Browser

Browser Browser

Browser Browser

APO

R/3 3.1H + CRM 3.0

Interaction and

Presentation Layer

Interaction and

Presentation Layer

Business Obj. Layer Business Obj. Layer

BLS Layer BLS Layer

PM

BP

BPOrder

PM PC

Order

P l u gI n

Mi d d l ew ar e

Web

Server

Web

Server

Index

Server

Index

Server

IPCIPC

JCO

Figure 32: Overview Developer W orkplace

September 2006 154

Required tools and versionsmySAP CRM 5.0 is based on SAP NetWeaver’04s. There the following software component versions arecontained or required:

Component Version

SAP Web AS Java 7.00

JDK 1.4.2

IDE SAP NetWeaver’04s Developer Studio

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

Installation of JDK 1.4.2

Download the JDK from the sun homepage ht t p: / / j ava. sun. com/ pr oduct s/ .

Select the version you require from the drop down list box ‘Java 2 Platform, Standard Edition (J2SE)’.

Make sure that you download the ‘SDK’ and not the ‘JRE’!

Once j2sdk-1_4_2_XX-windows.exe (where XX is the number of the patch) has been downloaded, you haveto execute it. A destination location <J AVA_HOME>must be chosen and you have to select the followingcomponents for installation:

Program files

Native interface header files

Old native interface header files

Demos

Java sources

Once JDK 1.4.2 has been successfully installed, the J AVA_HOME environment variable must still be set insuch a way that the Java compiler can be found (SET J AVA_HOME=<J AVA_HOME>). You also have toappend the ‘<J AVA_HOME>\ bi n‘ directory to your environment variable ‘path’. These settings can beconfigured, for example, in the Windows environment in the system properties, which can be accessed viathe control panel (System Settings Control Panel) and by double clicking on the Systems icon. Pleasemake sure that the PATH environment variable is expanded to the binary directory underneath the jdk1.4.2directory. If this was not done automatically, for example, during the manual installation of JDK, you can dothis as illustrated in the graphic above or with the command:

(SET PATH = . . . ; %J AVA_HOME%\ bi n).

Then the SDK is ready to run and can be tested by typing in j ava – versi on in the command prompt.

http://java.sun.com/products/




September 2006 155

Developer Workplace for SAP NetWeaver 2004sThe SAP Developer Workpace consists of the following Componentes:

SAP NetWeaver Developer Studio

Max DB or MS SQL Server

SAP J2EE Central Instance (J2EE dispatcher, J2EE server process, SDM)

SAP J2EE Central Service (Message Server, Enqueue Server)

Figure 33: Developer Workplace for SAP NetWeaver 2004s

Instal ling the Developer Workplace for SAP NetWeaver 2004s

The installation of the SAP Developer Workplace is described in the “Installation Guide - Developer Workplace for NW2004s”, that is available on the SAP Service Marketplace quick link instguides

(http://service.sap.com/instguides) SAP NetWeaver Release 2004s Installation (in the list 3 -Installation - Standalone Engines & Clients).

http://service.sap.com/instguides


September 2006 156

Directory Structure of the Web AS Java 7.0

Once it has been installed, the directory of the Web Application Server is structured as follows:

Root

SAP SID

JC<INSTANCE_NUMBER>

Visual Administrator

Server directoryContains deployed web applications

Logfile directory (also contains the ECO log entries)

SAP Web AS Configuration Tool

SDM directory

Figure 34: Directory Structure of Web AS Java 7.0

TCP-Ports

The ports used by the Central J2EE Instance are determined by the instance number, which is entered withinthe installation and can be calculated with the following formula:

<Base port> = 50000 + 100 * <INSTANCE_NUMBER>

Name Formula 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)




September 2006 157

Example

The SAP WebAS Java has been installed on the server with instance number 00. The used HTTP port isthen 50000.

The actual used ports can be checked using the configuration tool under Cluster/Dispatcher -> services ->http, p4, telnet.

Starting and Stopping the WebAS Java

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

The Central J2EE Instance and

The database instance.

To start/stop the Web AS Java, open the SAP Management Console, select the Web AS Java Instance andpress the start/stop button in the button bar.

Figure 35: SAP Management Console

Configuration of SAP WebAS Java 7.0

The SAP WebAS Java 7.0 can be configured using the configuration tool.

Central J2EE Instance

Database Instance

September 2006 158

Uninstalling the Developer Workplace for SAP NetWeaver 2004s

How to uninstall the Developer Workplace for SAP NetWeaver 2004s is described in Appendix of the“Installation Guide - Developer Workplace for NW2004s”, that is available on the SAP Service Marketplace

quick link instguides (http://service.sap.com/instguides) SAP NetWeaver Release 2004s Installation(in the list 3 - Installation - Standalone Engines & Clients).

Configuring and Working with Developer StudioThis section describes manual deployment of an SAP E-Commerce web application. The focus of this guideis to enable consultants to quickly get started using the new concepts used by SAP and set up a localdevelopment landscape that enables them to implement customer requirements. This local developmentlandscape can differ from the production environment. Consultants can install variants on their laptops.

Configuration of the web applicationThis section describes the configuration of the Internet Sales application. In Internet Sales 5.0 the ExtendedConfiguration Management (XCM) is used to configure the web applications. The tool, used to configurethem, is the XCM Admin. This tool is contained in every web application. You have to configure eachapplication with it’s own XCM Admin. For more details how to configure the web applications please see the

1. To access the XCM Admin please use the following URL:http://localhost:50000/<APPLICATION_NAME>/admin/xcm/init.do (for example:http://localhost:50000/b2b/admin/xcm/init.do).

Create customer specific ‘Application Configurations’ or configuration ‘Components’ from SAPconfiguration default templates.

2. Restart the web application through the SAP J2EE Visual Administrator, for example,

<J 2EE_HOME>\ admi n\ go. bat -> Server -> Services -> deploy. Click to tab strip Runtime Selectapplication and click -> Stop Application -> Start Application.

3. Create shop definitions refering the corresponding backend system using the Shoadmin webapplication.

4. You can call the application via the URL, for example, http://localhost:50000/b2b/b2b/init.do. Pleasenote that links that end in ‘. do’ are forwarded as events to the ActionServlet that is defined andconfigured in the web. xml file. The following entry is required in the web. xml file to ensure correctforwarding:

5. The servlet mappings are configured in the config.xml in the directory WEB-INF of your webapplication.

We recommend you perform all customer enhancements on a copy of the original EAR file. You

can create a copy with the ISA Buildtool.

<! - - Act i onServl et Mappi ng - - >

<ser vl et - mappi ng>

<ser vl et name>act i on</ ser vl et name>

<ur l - patt ern>*. do</ ur l - pat t er n>

</ servl et - mappi ng>

September 2006 159

Remote DebuggingThis 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 itis being executed on the server.

Setting up remote debugging for SAP WEB AS Java 7.0This section describes the necessary configuration of Eclipse for remote debugging of a web applicationrunning on the SAP J2EE server.

To debug your coding, you have to:

- Enable debugging on the Web AS (either temporarily or permanently)

- Start Remote Debugging

Enabling/Disabling Debug Mode Permanently

To enable/disable the debug mode of the SAP Web Application Server Java 7.0 permanently, perform thefollowing steps:

1. Start the Visual Administrator by executing

<DRIVE>:\usr\sap\<SID>\JC<INSTANCE-NUMBER>\j2ee\admin\go.bat.

2. Connect to the Web AS with an user of the role Administrator.

3. Navigate to Cluster Server Services Configuration Adapter.

4. In the Display configuration tab navigate to Configurations cluster_data and select Propertysheetinstance properties IDXXXXXXX.

5. Change to the Edit mode by pressing the change/view button in the button bar of the tab andconfirm this by pressing yes.

6. Press the Edit button . A new popup will appear.

7. Select IDXXXXXXX.DebugMode , change the Custom value to ‘yes’ and press the button ‘ ApplyCustom’.

You could also change the debug port by clicking on IDXXXXXXX.DebugPort.

8. Restart the server.




September 2006 160

Figure 36: Visual Admin - Setting Up Debug Mode

Enabling/Disabling Debug Mode TemporarilyTo enable/disable the debug mode of the SAP Web Application Server Java 7.0 temporarily, perform thefollowing steps:

1. Start the Net Weaver Developer Studio.

2. Switch to the J2EE Engine View (menu Window Show View Other… J2EE J2EE Engine)

3. Select the Server Node.

4. Open the context menu (by clicking the right mouse button) and select Enable Debugging of Processes.

Figure 37: J2EE Engine - Enabling Debugging




September 2006 161

Starting Remote Debugging

Perform the following steps in your SAP NetWeaver Developer Studio:

Open the menu Run Debug… Select Remote Java Application and press the button New

Host name. The host, where the process being debugged runs.

Type: dt_socket

Address: the port. This has to correspond with the -Xrunjdwp:address setting.

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

September 2006 162

ABAP DebuggingSince 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 5.0.In SAP E-Commerce 5.0, you have to use HTTP/external debugging to analyze ABAP code called from theJava side. The following procedure is necessary to start a debug session:

PrerequesitesTo be able to perform external debugging, the following prerequisites must be met:

- the SAPGui has to be installed on the host, where the RFC (of HTTP/HTTPS/SMTP) calls areperformed, e.g. the host, where the SAP Web AS is running on.

- Since load balancing is not supported, yu have to configure your web application to connect to a

single server. To do this perform the steps listed below:

o Open a browser and access the XCM Admin of your web application (URL:htt p: / / <host name>: <por t >/ <appl - name>/ admi n/ xcm/ i ni t . do):

o Navigat through the tree on left to Start Components Customer and select jco

o Press the Edit button in the upper right corner.

o Enter an arbitrary name and press the Create button.

o Choose server_connect from the drop down list box as Base Configuration

o Enter the connection data of the particular server. You can get the values for the parametersashost and the system number from the SAPGui:

Start SAPGui and switch to the System tab Press the button New Entry

Enter the System ID and double click on the particular entry in the list.

Open the properties of the message server you want to connect by double clickingon it.

Enter the message server as value of the parameter ashost.

Enter the System number

o Navigate in the tree on the left to Start Application Configuration Customer and selectthe configuration you want to use.

o Change the value of the parameter jcodata to the component you just createdo Press the Save button.

o Press the Display button in the upper right corner.




September 2006 163

Activating ABAP Debugging

1. Start the SAPGui and logon to the server you configured in the XCM

2. Go to any Development Workbench (transactions SE37, SE38, SE80).

3. Select the menu item Utilities Settings, switch the tab ABAP Editor and there the tab HTTPDebugging.

4. Enter the ID of the SU01 user, you use to logon to your webapplication

You have to maintain the ID of the SU01 user, not the alias!

For debugging the user must have debug authorizations. Please ensure this via settingappropriate roles or profiles via transaction SU01. Normally the profile “S_ENTW_SHOW”should be adequate (for detailed information see note 668252).It’s recommended to create new “Debug users” for such function. Do not add theseauthorizations to existing “producti ve users” because of security reasons.

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

the button Set/Delete External Breakpoint .

6. Start your web application. When within the web application, with the specified user the ABAPcoding will be called, the set breakpoint will be executed.

For detailed information and further questions please refer to the notes 668256, 668252 and751872.

Java Debugging

If you want to debug the Java coding deliverd by SAP, but the coding has not been attached to

the .jar files, refer to note 932457. There you’ll find instructions how to attach the SAP Javacoding to the jar files.




September 2006 164

Introduction to Extension Concepts

Extensions in the ISA FrameworkThe first part of this unit gives an overview of possible extensions and extension concepts. It should help youto find an appropriate extension concept for specific requirements. The subsequent parts of the unit givetheoretical introduction to the various extension concepts of the Internet Sales framework. The concepts inthis unit provide the basis for the Examples and Tutorials provided in the ‘Development and Extension Guide:E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3).

The following table gives an overview of possible changes in different layers:

Layer Possible Extensions

Interaction Layer Action flow has to be interfered in order to get/set additional data.

Business Object Layer Custom Business Objects process additional data.

Business Logic Service Layer Custom Backend Object provides connectivity to backendfunctions

Calls to function modules are interfered (before and after function call)

Custom function modules are called instead of the standardmodules

Backend (e.g. CRM) New/enhanced functions (for example, extension of existingfunction modules, new function modules).

These extensions are not covered by this document.

Table 47: Overview of possible changes in different layers




September 2006 165

CustomAction

Custom

BusinessObject

Custom

BackendObject

Custom

Function Module

customer data

has to be entered

or disp layed

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 theISA Framework and, as a consequence, supports the extensions to the ISA Framework.




September 2006 166

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 dependingon your individual requirements. Each diagram has one starting point referring to different branches. Thebranches describe different requirements (i.e. what you want do), where you have to check according to your requirements which branch is the right one for you. The result of each branch could be a reference toanother lower level diagram, or a description of what to do, together with a reference to the detaileddescription of the available extension concept, with examples.

Overview

Start here to find the appropriate extension concepts or just to get an overview of different categories of extensions.

Static extensions to theUI-Layer (colors,

images, texts)

Additional data shouldbe exchanged betweendifferent layers (UI, BO,

BE)

End

Extensions toexchange additional

data

StartExtension to ISA

Terminator Reference to sub

diagram withmore details

What to do -Reference to detailed

descriptionDecision

Requirement -What you want

to do

Legend:

Action flow should bemodified or extended

Extensions to theaction flow

Static extensions tothe UI layer

Figure 40: Overview of different categories of extensions




September 2006 167

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 shouldbe changed/added/

removed

Colors of the UI shouldbe changed

End

StartStatic extensions to the

UI layer

Change/add text in thetext property file (language

dependent!)

Rearrange UI elementswithin JSP and/or to other

JSP

Images on the UI shouldbe changed/added/

removed

Arrangement of UIelements should be

changed (e.g. frames,texts, buttons, images)

Change colors in styledefinition (CSS)

Replace (standard) imageor add new image

Add/remove text from JSPChange colors of staticimages (e.g. buttons,

frames)

Add/remove image fromJSP

(If required) Adjust frametargets in JSP’s and in

action flow configuration.

Figure 41: Statis extensions to the UI layer

For details see:

Chapter Extensions to the UI layer below

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




September 2006 168

Extensions to the Action Flow

This diagram gives an overview of how to realize extensions to the action flow, like adding or replacingactions, and writing new actions.

The action flow shouldbe modified by adding/

removing other (standard or customer

specific) actions

The action flow shouldbe modified by changingthe action forward of a

specific (standard)action

End

StartExtensions to the

action flow

Modification of the actionflow in configuration3)

Derive new action fromstandard action andimplement user exit2)

Appropriate user exitavailable in standard action1)

Create new action fromstandard action2)

no

yes

Register new action flow inconfiguration3)

Figure 42: Extensions to the action flow

For details see:

1) Standard Actions providing User Exits below

2) Create a Customer Action below

3) Modifications in the Struts Configuration

below




September 2006 169

Extensions to Exchange Additional Data

This diagram is the entry point to all extensions related to the exchange of additional data, which are themost common types of extensions. Typically, the additional data has to be displayed on the UI and has to beretrieved from a backend system, or should be entered on the UI and have to be transferred to a backendsystem. These kind of extensions always affect all ISA layers.

Should the additional databe exchanged with a

backend system?

Additional data shouldbe displayed or should

be entered on the UI

Additional data shouldbe transfered between

the web applicatiion anda backend system

no

End End

yesExtensions toexchange data with

the UI-layer

Extensions toexchange data with a

backend system

StartExtensions to exchange

additional data

Figure 43: Extensions to exchange additional data




September 2006 170

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 thisadditional data with the underlying action classes.

Figure 44: Extensions to exchange data with UI layer

For details see:

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




September 2006 171

This diagram shows how to transfer additional input data from the http request (from submitting the HTMLform) to the action class and, from there, to the busines object layer.

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

For details see:

1) Standard Actions providing User Exits ci-dessous

2) Create a Customer Actionbelow

3) Create a Customer Actionbelow

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

5) Create a Customer Business Object below




September 2006 172

6) Request Context ci-dessous

7) ’Extension Demo 1 – Add New Entry Fields’ in the ‘Development and Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3).




September 2006 173

This diagram shows how to transfer additional output data in the action class to the JSP.

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

For details see:

1) Standard Actions providing User Exits below

2) Create a Customer Action below and Modifications in the Struts Configuration below




September 2006 174

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

Accessing the Session Context below

4) Accessing the Session Context below





September 2006 175

Extensions to Exchange Data with Backend-Systems

This diagram is the entry point to extensions related to exchange of additional data between the businessobject layer and any backend system.

Retrieve data from abackend system

Transfer data to abackend system

End

StartExtensions to exchange data

with a backend system

Extensions toexchange data withthe Web Catalog

Extensions toexchange data with

an IPC system

Extensions to retrievedata from a R/3

system

Extensions to retrievedata from a CRM

system

End


Web Catalog


an IPC system

Extensions totransfer data to a

R/3 system

Extensions totransfer data to a

CRM system


the Java Basket


the Java Basket

Figure 47: Extensions to exchange data with the backend systems




September 2006 176

This diagram shows how to retrieve additional data from a SAP CRM system to the business object layer.

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 standardprocess flow. The function module itself does not have to be a standard function call (see ReplacingCalls to Standard Function Modules (Backend System) below)

2) Create a Customer Business Object below and Create a Customer Business Object Manager below

3) Supported Function Modules and Business Objects below Table 62: User exits for for Pricing or Configuration

Creating new Customer Backend Object below

5) Create a Customer Backend Object below

6)

Interception of Calls to Standard Function Modules below

7) Request Context below




September 2006 177

This diagram shows how to transfer additional data from the business object layer to a SAP CRMsystem.

Data stored in therequest context

Data stored in a(customer) business

object

StartExtensions to transfer data to

a CRM system

Implement JCO eventlistener class.2)

Read data from requestcontext3)

Create new backendcIass. Implement method

to call CRM functionmodule4)

Data stored within astandard business

object as extension data

yes

End

Call function modulein CRM system

No action required

Processingwith other data or

preprocessing beforetransfer required

Extension data of CRMfunction module can be

used1)

no

yes

no

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

For details see:

1) Supported Function Modules and Business Objects below

2) Interception of Calls to Standard Function Modules below

3)

Request Context below





September 2006 178

This diagram shows how to call a SAP CRM system from the backend layer.

No extension of interface or of the logicof the standard function

module required

Extension of interfaceand of the logic of the

standard functionmodule required

StartCall function module in CRM

system

No extension of interface but extension

of the logic of thestandard functionmodule required

Create customer functionmodule with extended

interface of standardfunction module

Create customer

implementation of BADI1)

recomm.concept

recomm.concept

Create customer function

module

End

Use standard backendobject and implement JCO

event listener class3)

Use standard backendobject -

no action required

Create customer backendobject.

Register new backendobject in configuration4)

Configure BADI in CRM

Assign customer functionmodule and event listener class to standard functionmodule in configuration3)


module with interface of standard function module2)


no action required

Assign customer functionmodule to standardfunction 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 below

2) Replacing Calls to Standard Function Modules (Backend System) below


4) Create a Customer Backend Object below; it is assumed at this point, that a customer businessobject and a customer BOM are already available.




September 2006 179

This diagram shows how to retrieve additional data from a SAP ERP system to the business object layer.

Data is retrieved withina standard call from the

backend system(e.g. at order save, at

ship to read)1)

StartExtensions to retrieve data

from a R/3 system

Configure extension data6)

Create new backend

class. Implementmethod(s) to call function

module.5)

Data is retrieved by anew (customer specific)call from the backend

system

End

Derive new backend classfrom standard backend

class. Overwrite method(s)to call function module

and/or to process data.5)


postprocessing after transfer

required

yes

no

Extension data of R/3function module can be

used3)

Implement JCO event

listener class.7)

Write additional data torequest context.8)

no

yes

Create new backendinterface.4)

Create new businessobject 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 standardprocess flow. The function module itself does not have to be a standard function call (see ReplacingCalls to Standard Function Modules (Backend System) below)

2) Create a Customer Business Object below and Create a Customer Business Object Manager belowTable 71: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects. belowTable 62: User exits for for Pricing or Configuration

Creating new Customer Backend Object below


6) Modification of Communication Structures in SAP and Configuration of the Web Application below


8) Request Context below




September 2006 180

This diagram shows how to transfer additional data from the business object layer to a SAP ERP system.

Data stored in a requestcontainer

Data stored in a(customer) business

object

StartExtensions to transfer data to

a R/3 system

Implement JCO eventlistener class.2)

Read data from requestcontainer.3)

Create new backendclass. Implement method

to call R/3 functionmodule5)

Data stored within astandard business

object as extension data

yes

End

Call function modulein R/3 system

Configure extension data4)


preprocessing beforetransfer required

Extension data of R/3function module can be

used1)

no

yes

no

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

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

Supported Function Modules and Business Objects. below.



4) Modification of Communication Structures in SAP and Configuration of the Web Application below

5)

Create a Customer Backend Object below




September 2006 181

This diagram shows how to call a SAP ERP system from the backend layer.

No extension of interface or of the logicof the standard function

module required

Extension of interfaceand of the logic of the

standard functionmodule required

StartCall function module in R/3

system

No extension of interface but extension

of the logic of thestandard functionmodule required

Create customer functionmodule with extended

interface of standardfunction module


module with interface of standard function module1)

recomm.concept


module

End

Use standard backendobject and implement JCO

event listener class2)


no action required

Create customer backendobject.

Register new backendobject in configuration3)

Assign customer functionmodule to standardfunction module in

configuration1)

Assign customer functionmodule and event listener class to standard functionmodule 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) below


3) Create a Customer Backend Object below; it is assumed at this point, that a customer businessobject and a customer BOM are already available.




September 2006 182

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

Additional data shouldbe transferred to the

IPC for Pricing

Additional data shouldbe transferred to theIPC for configuration


with an IPC system

End

Derive new backendobject from standard

(CRM/R/3) backendobject. Implement user exit.1)


(CRM/R/3) backendobject. 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 below

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




September 2006 183

This diagram shows how to exchange additional data with the web catalog.

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) below and New Fieldsin the Web Catalog (SAP ERP Backend and TREX) below

2) Show Additional Keys for Extended Search in B2B below

3) See note 684119 (for ISA ERP) and ‘Extensions to Exchange Additional Data’ in the ‘Developmentand Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References onpage 3).

For displaying additional data in web catalog, see Show Additional Attribute in Product List belowand Show Additional Attribute in Product Details and in Compare Products below




September 2006 184

This diagram shows how to exchange additional data with the Java basket.

Additional data isattached as extension

data to the basketheader or to the basket

item

Additional data isattached as extensiondata to other business

objects


with the Java Basket

End

Extension data isautomatically transferred

with the header or with theitem of the Java Basket -no action required.1)


(JDBC or DB) backend

object.2)

Overwrite method toexchange extension data.

Figure 56: Exchange additional data with the Java basket

For details see:

1) Java Basket-Extensions ci-dessous


September 2006 185

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

Replacing existing Mimes

No

Changing text displayed onthe screen

On JSP

In language dependentresource files

No

Changing colors On JSP

In cascading style sheets

No

Replacing existing JSP Register new JSP inStruts configuration file(conf i g. xml )

Depending on the functions of the new JSP, changes in other layers could be necessary.

Table 48: 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 ContextIn order to access the User Sessi onData object from the JSP you have to do the following:

Accessing the Request ContextFor information about how to access the RequestContext within a JSP refer to chapter 'Request Context' onpage 3.

Extensions in the Action FlowThe action flow is realized using the STRUTS framework. In order to get/display additional data on the UI it isoften necessary to change the existing Action flow. This is done by adding/replacing custom Struts Actions:

<%@ page i mpor t =‘ com. sap. i sa. cor e. User Sessi onData’ %>

<% User Sessi onDat a userSessi onDat a =

UserSessi onData. getUserSessi onData( pageCont ext . get Sessi on( ) ) ;

%>




September 2006 186

Figure 57: Action flow with CustomActions

Create a Customer ActionYou would like to modify a specific interaction within the application. A reason for doing this could be that youwant to perform some additional checks that are not part of the original Actions before you continue with theprocess flow. Or you are modifying a dispatcher Action (for exampleMai nt ai nBasket Di spat cher Act i on) and extending its functions.

When you extend existing Actions you usually overwrite one of the methods provided by the base Action andprovide your own implementation for it.

Depending on the type of modification, you can use different possible base classes for your Action.

com. sap. i sa. cor e. BaseAct i on

o Base class of all Actions. Use these Actions if you do not need to access the standard ISAfunctions (for example, you extend the functions of Internet Sales without using currentfunctions). In that case you have to overwrite doPerf or m( ) .

com. sap. i sa. i sacor e. act i on. I saCor eBaseAct i on

o Base class providing easy access to Business Object Managers of the ISA core functions,IPC, and catalog. Extend these Actions if you write extensions to the Internet Salesapplication which use available functions. You have to overwrite the i saPer f or m( )method.

com. sap. i sa. i sacor e. act i on. EComBaseAct i on

o Base class providing MetaBOM.

All the action classes of the E-Service Extended Complaints and Returns application extend thecom.sapmarkets.isa.isacore.action.EComBaseAction, either directly or indirectly (through other classinheritance).

Depending on the type of modification, you can use different possible base classes for your Action in theExtended Complaints and Returns application:

com. sapmarket s. i sa. i sacor e. act i on. EComBaseAct i on

o Base class providing MetaBOM

com. sap. eservi ce. common. act i on. CommonBaseAct i on

o Inherit from EComBaseAct i on; This base class providing access to the Common businessobject manager which handles several business objects such as user, business partner manager, delivery, recall, generic search, etc.




September 2006 187

com. sap. eservi ce. common. act i on. CommonCont r ol AccessBaseAct i on

o Inherit from CommonBaseAct i on; checks whether the user is properly logged in beforeproceeding to the execution of the action

com. sap. eser vi ce. cr b2b. act i on. Eser vi ceBaseAct i on

o Inherit from CommonBaseAct i on; gives access to the Eservice business object manager which handles the Help Value Search Handler business object.

com. sap. eservi ce. cr b2b. act i on. Eservi ceCont r ol AccessBaseAct i on

o Inherit from Eservi ceBaseAct i on; checks whether the user is properly logged in beforeproceeding to the execution of the action

com. sap. eservi ce. cr b2b. act i on. Compl ai nt BaseAct i on

o Inherit from CommonBaseAct i on; gives access to the Complaint business object manager which handles several business objects: complaint, complaint dynamic fields, complaintitems list.

com. sap. eservi ce. cr b2b. act i on. Compl ai nt Cont r ol AccessBaseAct i on

o Inherit from Compl ai nt BaseAct i on; checks whether the user is properly logged in beforeproceeding to the execution of the action

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

com. sapmarket s. i sa. i sacor e. act i on. EComBaseAct i on

o Base class providing MetaBOM

com. sap. eservi ce. common. act i on. CommonBaseAct i on

o Inherit from EComBaseAct i on; This base class providing access to the Common businessobject manager which handles several business objects such as user, business partner manager, delivery, recall, generic search, etc.

com. sap. eservi ce. common. act i on. CommonCont r ol AccessBaseAct i on

o Inherit from CommonBaseAct i on; checks whether the user is properly logged in beforeproceeding to the execution of the action

com. sap. eser vi ce. i nspb2b. act i on. Eser vi ceI nspBaseAct i on

o Inherit from EComBaseAct i on

com. sap. eservi ce. i nspb2b. act i on. Eservi ceI nspCont r ol AccessBaseAct i on

o Inherit from CommonContr ol AccessBaseAct i on; checks whether the user is properlylogged in before proceeding to the execution of the action

com. sap. eser vi ce. cr b2b. act i on. Compl ai nt BaseAct i on

o Inherit from CommonBaseAct i on; gives access to the Complaint business object manager which handles several business objects: complaint, complaint dynamic fields, complaintitems list.

com. sap. eser vi ce. cr b2b. act i on. Compl ai nt Cont r ol AccessBaseAct i on

o Inherit from Compl ai nt BaseAct i on; checks whether the user is properly logged in beforeproceeding to the execution of the action

com. sap. eser vi ce. sr vconf i r mat i ons. act i on. Conf i r mat i onBaseAct i on

o Inherit from CommonBaseAct i on; gives access to the Confirmation business object

manager.




September 2006 188

com. sap. eser vi ce. sr vconf i r mat i ons. act i on. Conf i r mat i onCont r ol AccessBaseAct ion

o Inherit from CommonContr ol AccessBaseAct i on; gives access to the Confirmationbusiness object manager and checks whether the user is properly logged in beforeproceeding to the execution of the action

Standard Actions providing User 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 thestandard action class. The advantage of predefined user exits is that extensions or changes in the standardaction classes by SAP within support packages or future releases are aware of user exits:

Basket

Class / Methode Description

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

customerExitParseRequestHeader Modify the header data; called after the header data isparsed from the request.

customerExitParseRequestItem Modify the item data; called after the item data is parsed fromthe request.

customerExitParseRequest Modify the document; called after the header and item dataare parsed from the request.

MaintainBasketDeleteItemAction Action to delete an item from the current document.

customerExitParseRequestModify the document; called after the header and item dataare parsed from the request.

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


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


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

customerExitDispatcher Set forward; called after standard forward is determined.




Table 49: User exits within the Basket




September 2006 189

Order


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




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


MaintainOrderNewShiptoAction Action to add a new ship to to a document.customerExitParseRequest Modify the document; called after the header and item data

are parsed from the request.

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


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


Table 50: 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.

customerExitDispatcher Set forward; called after standard forward is determined.userExitCheckRequest The result of the standard method „checkRequest’ can be

modified.

userExitModifyItemListBeforeConvertRequest

Read additional data from OCI message.

userExitModifyItemListBeforeAddToBasket

Read additional data from OCI message.

Table 51: User exits within the OCI




September 2006 190

As in the Internet Sales application, some action classes provide user exits in the form of predefined, butempty, methods.

Extended Complaints and Returns Application

Class / Method DescriptionComplaintEntryBaseAction 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 isinvoked, either when the user presses the “update” or “send”button on the complaint entry or return entry. It is called beforethe document is actually updated in the CRM system.

customerExitParseRequestHeader This method is called when the update of the header is invoked,either when the user presses the “update” or “send” button on thecomplaint entry or return entry. It is called before the header isactually updated in the CRM system.

customerExitParseRequestItem This method is called when the update of an item is invoked whenthe user presses “update” or “send” on the complaint/return mainentry page, the complaint/return item entry or complaint/returnitem resubmission. It is called before the item is actually updatedin the CRM system.

Table 52: User exits within the Extended Complaints

Remanufacturer’s Inspection Appl ication

Class / Method Description

ConfirmationEntryBaseAction Base action for all actions providing functions tocreate an inspection confirmation.

customerExitParseRequest This method is called when the user submits aninspection, before the inspection is actually created inthe CRM system.

Table 53: 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 Actionscom. sap. i sa. cor e. BaseAct i on provides methods enabling you to communicate with the sessioncontext.

Within the ISA framework you are only allowed to communicate with the session using thecom. sap. i sa. cor e. UserSessi onData object.

The following code sequence retrieves a reference to a User Sessi onData object:

After that you can get/set objects in the session using the methods Obj ect get At t r i but e( St r i ngname) and set At t r i but e( St r i ng name, Obj ect obj ect ) .

/ / get user s essi on data obj ect

User Sessi onDat a user Sessi onDat a =

UserSessi onData. getUserSessi onData( r equest. getSessi on( ) ) ;




September 2006 191

Access ing Business Objects from Act ions

Actions act as a mediator between the HTTP world and the BO Layer. Business Objects do not knowanything about HTTP. Actions are responsible for retrieving data from the HTTP-based environment andpassing this data to Business Objects when accessing business functions.

Before an Action can communicate with a Business Object it needs a reference to it. To get a reference thefollowing steps have to be performed:

If your base cl ass i s com. sap. i sa. cor e. BaseAct i on

o Get a reference to the user session data. You need a reference to this object before you canget a reference to the Business Object Manager, which manages the Business Object youare interested in:

o The next step is to get a reference to the Business Object Manager. The easiest, andrecommended, way is to use the convenience method get BOM( ) of theUser Sessi onData class:

If your base class is com. sap. i sa. i sacor e. act i on. I saCor eBaseAct i on you get passed thereference to the Business Object Manager in the i saPer f or m( ) as a parameter (please seeJavaDoc).

Now you can use the reference to the BOM to get a reference to a Business Object or to create a BusinessObject:

Before this reference is used, you should checked whether it is null or not:

The business methods can then be executed on the BO:

user . set Name(‘ Muel l er’ ) ;

i f ( user == nul l ) {

/ / Er ro r

}

Basket basket = bom. get Basket ( ) ;

User user = bom. cr eateUser ( ) ;

Busi nessObj ect Manager bom =

( Busi nessObj ect Manager ) userSessi onDat a.

getBOM( Busi nessObj ect Manager . I SACORE_BOM) ;

User Sessi onDat a user Sessi onDat a = UserSessi onData. get UserSessi onData(s essi on) ;

September 2006 192

The Business Object Manager you get a reference to is defined in the / web-i nf / cf g/ bom- conf i g. xml file:<Busi nessObj ect Manager

name=‘ I SACORE- BOM’

cl assName = ‘ com. sap. i sa. busi nessobj ect . Busi nessObj ectManager’ / >

The references to the Busi nessObj ect Manager and the corresponding objects remain valid and can bereused within the Action as often as required. These references should never be passed onto other Actionsvia the session context, since this would undermine the purpose of the Object Manager. This rule forcesevery Action to retrieve the Business Objects using the technique described above.

Accessing the Request Context

For information about how to access the RequestContext within an JSP refer to chapter 'Request Context' on

page 3.

Modif ications 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 \ web- i nf \ conf i g. xml .

In the E-Service applications Extended Complaints and Returns and Remanufacturer’s Inspection, this file is

located in <esr v>\ web- i nf \ st r ut s- conf i g. 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 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3).


Storing Additional Data - Extension Mechanism

This modification concept uses the previously mentioned extension mechanism that enables you to store anydata in a Business Object. The base class of each Business Object provides this mechanism.




September 2006 193

Additionally, this data can be passed transparently to the backend system. This is the preferred extensionconcept when you have to pass data between the Business Object and the SAP CRM or the SAP ERPsystem. For further information on this concept please refer to chapters BADIs/SAP CRM Extensions onpage 3 or BAPIs/SAP ERP-Extensions on page 3.

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

Figure 58: BOBase class

Each Business Object extends the com. sap. i sa. core. busi nessobj ect . BOBase class. This baseclass provides the following methods to store any data:

Method Name Function

addExt ensi onData(Obj ect key, Obj ect name) Stores any data within the BusinessObject.

Obj ect getExtensi onData(Obj ect key) Retrieves extension data associated withthe Business Object.

get Extensi onDataVal ues( ) Retrieves all extension data associatedwith the Business Object.

r emoveExt ensi onDat a( Obj ect key) Removes extension data from theBusiness Object.

Table 54: Methods of the BOBase class

VersionThis feature is available in all versions of Internet Sales.

It is also available in the E-Service applications Extended Complaints and Returns and Remanufacturer’sInspection.




September 2006 194

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 youwant to replace the functions of an existing method with your own implementation. In either case, you haveto derive from the existing Business Object and extend/replace its functions.

Figure 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 thatmanages the Business Object you have extended. In order to make the new version of the Business Objectavailable for use, you have to overwrite the get/create method of the BOM that creates this Business Object.

Figure 60: Create own BOM

Str i ng extBasketHeaderData =

( St r i ng) i saBOM. getBasket( ) . getExtensi onData( ‘ ext HeaderData’ ) ;

/ / set ext ended data as ext ended dat a of t he Basket Busi ness Obj ect

i saBOM. getBasket ( ) . addExt ensi onData(‘ ext HeaderData’ , ext Basket HeaderData) ;




September 2006 195

The new modified version of the BOM creates an instance of the new Business Object. The return valuemust be the class which represents the old Business Object.

All existing Actions do not have to be changed:

New Actions can use the new/extended functionality of the Business Object:

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 andRemanufacturer’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 acorresponding 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. get User ( ) ;

user . doNew( ) ;

User user = bom. get User ( ) ;

September 2006 196

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 isidentified by a GUID: com. sap. i sa. cor e. busi nessobj ect . Obj ect Base.

o Otherwise extend com. sap. i sa. cor e. busi nessobj ect . BOBase

2. If the business object has a corresponding Backend Object it should implementcom. sap. i sa. cor e. busi nessobj ect . BackendAware

3. Place this class in a package like com. <your company>. i sa. busi nessobj ect

o If you have only few Business Objects, you can place them directly under thebusi nessobj ect package. If you have a lot of custom Business Objects, create a deeper package structure that reflects the business functions provided by your custom businessobjects.

Version

This feature is available in all versions of Internet Sales.


Example

'Extensions Demo 7: Copy –Template for Customer Actions' in the ‘Development and Extension Guide: E-

Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3) provides you atemplate you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

Create a Customer Business Object Manager

A Business Object Manager usually has a method to generate a BO (cr eateXX), a method to interrogateexisting BOs (get XX), and a method to drop all references to the existing object (r el easeXX).

The semantics are defined in such a way that the cr eat eXX method generates a new BO if one does notalready exist, or functions in the same way as get XX with existing BOs. Calling cr eat eXX, therefore,always returns a reference to a BO. By contrast, get XX returns nul l if the object has not yet beengenerated with cr eateXX.




September 2006 197

The cr eat eXX, getXX, and r el easeXX methods must be re-implemented for new BOs, whereby XX isreplaced by the exact name of the BO class in question. If the class is called User , for example, one methodis created with the signature User get User ( ) , one with the signature User cr eat eUser ( ) , and onewith the signature voi d r el easeUser ( ) .

When the BOs are created by the BOM they can be assigned a reference to the BackendObj ect Manager .

BOs that require this information must implement the BackendAwar e interface, which means that they alsoimplement the set BackendObj ect Manager method.

BOs that do not have to communicate with the backend should not implement the interface unnecessarily.Even if it turns out later on that the BO does need to communicate with the backend, changes do not have tobe made to the BOM. In this case, it is sufficient to implement the interface on the BO side.

+ setBackendObjectManager()

«interface»BackendAware

+ setBackendObjectManager()

+ setUserId(id : String)

+ setPassword(pwd : String)

+ login()

- bem : BackendObjectManager

User

Figure 63: Creating interface for Business Object

To make it easier to develop Business Object Managers, you can use theGener i cBusi nessObj ect Manager as a base class for your own Business Object Manager. This classcan already manage Business Objects and using it makes it easier to implement BOMs.

All you have to do is write the required method (for example, create/get), and call the corresponding genericmethods of the superclass by passing the class object of the Business Object you want to manage.

BusinessObjectManagerBase

DefaultBusinessObjectManager

+setBackendObjectManager()

+assignBackendObjectManager()

GenericBusinessObjectManager

+getBusinessObject()

+createBusinessObject()

+releaseBusinessObject()

Z_CustomBusinessObjectManager

+getCustomFunc()

Figure 64: Creating own Business Object Manager

September 2006 198

After implementing a BOM, you have to register it in the customer version of the bom- conf i g. xml file andadd an entry to it for the new manager.

The file is located in WEB- I NF\ xcm\ cust omer \ modi f i cat i on\ bom- conf i g. xml :

Version



<Busi nessObj ect Manager s>

<xi : i ncl ude

hr ef =‘ ${sap}/ modi f i cati on/ bom- bonf i g. xml #xpoi nt er( Busi nessObj ect Managers/ *) ’ / >

<Busi nessObj ect Manager name=‘ Z_CUSTOM- BOM’

cl assName=‘ com. acme. i sa. busi nessobj ect . Z_Cust omBusi nessObj ect Manager ’ / >

</ Busi nessObj ect Managers>

publ i c c l ass Z_Cust omBusi nessObj ect Manager

extends Def aul t Busi nessObj ect Manager

i mpl ement s BOManager , BackendAwar e {

. . . .

/ / r ef er ence t o busi ness obj ect pr i vat e Z_Cust omFunc mCust omFunc;

/ / key used f or t he Busi ness Obj ect Manager i n cust omer ver si on of bom- conf i g. xml

/ / used i n Act i ons as a const ant t o i dent i f y t he BOM

publ i c st at i c f i nal Str i ng CUSTOM_BOM = ‘ Z_CUSTOM- BOM’ ;

/ **

* Returns cust ombusi ness obj ect

*/

publ i c Z_Cust omFunc get Cust omFunc( ) {

i f ( mCust omFunc == nul l ) {

mCust omFunc = new Z_Cust omFunc( ) ;

/ / assi gns Backend Obj ect Manager t o Busi ness Obj ect i f / / Busi ness Obj ect i mpl ement s t he BackendAware i nt erf ace

ass i gnBackendObj ect Manager ( mCust omFunc) ;

}

r et ur n mCust omFunc;

}

}




September 2006 199

Example

'Extensions Demo 7: Copy-Template for Customer Extension' in ‘Development and Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3) provides you a

template you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

Business Logic Service Layer Many Business Objects (e.g. basket) in the Business Object layer have a corresponding Backend Object inthe BLS layer. The functionality of a Backend Object is accessed via a well-defined Java interface (for example: Basket Backend). The implementation of such an interface is backend-dependent (for example:Basket CRM).

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 bethat you want to perform some additional checks that are not part of the original processing, before youcontinue with processing. Or, you want to add additional data before you continue with processing. Or, youwant to execute self written remote callable function modules in the SAP system.

In order to create a customer Backend Object the following two scenarios have to be separated:

The Backend Object extends a standard Backend Object:

Re-implement the methods which cannot be used from the standard Backend Object and/or addadditional Methods.

Overwrite customer exits

The Backend Object is needed for a customer Business Object and can not be derived from 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 backendobject class derived from the standard backend object class. The advantage of predefined user exits is thatextensions or changes in the standard backend object classes by SAP within support packages or futurereleases are aware of these user exits:




September 2006 200

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 backendobj ect - conf i g. xmlconfiguration file. For further information refer to 'Changes in backendobject-config.xml' on page

3

Call IPC for Pricing (ISA CRM)


PriceCalculatorInitDataCRMIPC Price calculator for the SAP CRM backend. It determineslist/scale prices from catalog attributes, as well as dynamicprices through IPC, based on the settings in the web shop.

customerExitBeforeIpcDocumentCreate

Called after preparing the IPCDocumentProperties, butbefore creating the document in IPC. Overwrite this method if you want to add or modify document properties, for exampleto pass additional attributes to the document.

customerExitAfterIpcDocumentCreate

This exit is called after creating the IPCDocument. Overwritethis method if you want to change the IPC document in someway.

customerExitBeforeIpcItemsCreate This exit is called after preparing the IPCItemProperties, butbefore creating the items in IPC. Overwrite this method if youwant to add or modify item properties, for example to passadditional attributes to the item.

customerExitAfterIpcItemsCreate This exit is called after creating the IPCItems. Overwrite thismethod if you want to change the IPC items in some way.

customerExitCreatePrices This exit is called when creating the Prices from the IPC item.

It cretaes PriceInfo Objects and stores them in a Pricesobject which is then returned. Overwrite this method if youwant to subclass PriceInfoIPC, and use your subclass.

customerExitGetPriceType This exit is called for PriceType determination. When thePriceCalculator is initialized, the price types used are readfrom eai-config.xml. For each String in that list, this method iscalled and it returns a PriceType object.

Table 55: User exits for IPC for pricing

IPC-Basket (ISA CRM)


BasketIPC Basket implementation for IPC

customerExitAfterAddBusinessPartnerInBackend

This method provides the possibility to extend or modifiy theIPC document. The exit is called within the methodaddBusi nessPart ner I nBackend when a user hasalready logged on, and after the basket has been created.

customerExitSetDocumentProperties This method provides the possibilty, to easily extend thedocument properties of a sales document according tospecial customer requirements. The exit is called within themethod cr eat eI nBackend when a basket is created, butbefore the IPC-document is created.

Table 56: User exits for IPC basket




September 2006 201


customerExitSetItemProperties This method provides the possibilty, to easily extend the itemproperties of a sales document according to special customer requirements. The exit is called within the methodupdat e(Basket Dat a) when a new item is created, butbefore an IPC item is created.

Table 57: User exits for IPC basket

Order and Order Status (ISA ERP)


CreateStrategyR3 Algorithms for creating and simulating an order. Both tasksare done with the function moduleSD_SALESDOCUMENT_CREATE.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function moduleSD_SALESDOCUMENT_CREATE is called.

performCustExitAfterR3SimulateCall This method can be used to set additional tables or tablefields after the function moduleSD_SALESDOCUMENT_CREATE is called. It is called after the ISA sales document has been filled with the functionmodule data.

ChangeStrategyR3 Algorithms used for sales document change.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function module

SD_SALESDOCUMENT_CHANGE is calledperformCustExitAfterR3Call This method can be used to modify the ISA sales document

after the function module SD_SALESDOCUMENT_CHANGEis called. It is called only if no error messages from havebeen returned and after re-reading the ISA sales documentfrom ERP.

DetailStrategyR3 Contains the algorithms for reading an entire sales documentfrom ERP.

performCustExitBeforeR3Call This method can be used to set additional tables or tablefields before the function moduleBAPI_ISAORDER_GETDETAILEDLIST is called.

performCustExitAfterR3Call This method can be used to set additional tables or tablefields after the function moduleBAPI_ISAORDER_GETDETAILEDLIST is called. It is calledafter the ISA sales document has been filled with the functionmodule data.

Table 58: User exits for Order and Order Status




September 2006 202


ReadStrategyR3 Contains base functionality for transferring data from functionmodule tables to the ISA sales document that is used from allother algorithm groups. For example reading the item andschedule line info is used from all strategies that deal withorder change simulation, order change, order read and order create simulation.

setUpMessageMap List of ERP messages which raised by function moduleswhen simulating or saving orders and which should bedisplayed on the UI or should be ignored (in case of error messages).See notes 640735 and 641132.

Table 59: 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 exitis only called for the standard main memory implementation.

Table 60: User exits for Web Catalog

See also: Extension of the Web Catalog below.

Call IPC for Pricing or Conf iguration (ISA ERP)


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

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

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

customerExitAfterItemCreation Customer exit that is called after an IPC item has beencreated. This customer exit can be used to set the context if reference characteristics are involved.

customerExitBeforeItemCreation Customer exit that is called before an array of IPC items arecreated.

customerExitAfterItemCreation Customer exit that is called after an array of IPC items hasbeen created. This customer exit can be used to set thecontext if reference characteristics are involved.

customerExitBeforeHeaderAttributeCall Customer exit that is called directly beforeISA_PRICING_HDRDATA_GET is called. Can be used to setadditional parameters in table EXTENSION_IN.

Table 61: User exits for for Pricing or Configuration




September 2006 203


customerExitBeforeItemAttributeCall Customer exit that is called directly beforeISA_PRICING_ITEM_ATTRIBUTE is called.

Can be used to set additional parameters in tableEXTENSION_IN.

Note that the backend context is available here with e.g. theshop customizing.

Only relevant for the non-TREX case.

Table 62: 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 BackendBusi nessObj ect interface

o If the Backend Object has to communicate with an SAP system using JCo, derive your implementation from the com. sap. i sa. cor e. eai . sp. j co.BackendBusi nessObj ect BaseSAP class.Stateless classes should use I saBackendBusi nessObj ect BaseSAP as in this case thecorrect logon language is used in the connection.

Within the Backend Object implementation, communicate with the backend system using theconnection management provided by the BLS layer

Add configuration information to the customer version of the backendobj ect - conf i g. xmlconfiguration file

Create an Interface of Backend Object

The interface of the new Backend Object extends the com. sap. BackendBusi nessObj ect interface:

Additionally, you define any set of methods needed to access business functions located in the backendsystem.

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 thebusiness object to the backend object, but instead use a data access interface instead. This interface shouldprovide all necessary access methods. Place the data interface in the same package as the Backend Objectinterface.

publ i c i nter f ace Z_Cust omFuncBackend ext ends BackendBusi nessObj ect {

publ i c St ri ng get I nf o( ) ;

}

September 2006 204

Create an Implementation of Backend Object

Write an implementation for the interface of the Backend Object. Use theBackendBusi nessObj ect BaseSAP class as the base class for backend objects communicating with anSAP 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 backendobj ect - conf i g. xml usingXCM extension mechanism:

Accessing Backend Objects from Business Objects

If Backend Objects need access to the BLS layer they have to implement thecom. sap. i sa. cor e. busi nessobj ect . BackendAwar e interface.

This interface defines the method:

publ i c voi d set BackendObj ect Manager( BackendObj ect Manager 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):

. . . .

pr i vat e BackendObj ect Manager bem;

. . .

publ i c voi d set BackendObj ect Manager( BackendObj ect Manager bem) {

t hi s. bem = bem;

}

<busi nessObj ect t ype=‘ Z_Cust om’ name=‘ Z_Cust om ‘

cl assName=‘ com. acme. i sa. backend. cr m. Z_Cust omFuncCRM’


def aul t Connect i onName=‘ CRMStatel ess’ >

<par ams> <par am name=‘ myi ni t ’ val ue=‘ myval ue’ / >

publ i c cl ass Z_Cust omFuncCRM

ext ends BackendBusi nessObj ect BaseSAP

i mpl ement s Basket Backend, Z_CustomFuncBackend {

publ i c St ri ng get I nf o( ) {

J CO. Funct i on f unc = getDefaul t J CoConnecti on( ) . getJ CoFunct i on( ‘ Z_GETI NFO’ ) ;

getDef aul t J CoConnecti on( ) . execut e(f unc) ;

r et ur n f unc. ge t Expo r t Pa r a met e r L i s t ( ) . g et St r i ng( ‘ i nf o ’ ) ;

}

}

September 2006 205

The Backend Object Manager is assigned to the Business Object within theassi gnBackendObj ect Manager( ) .

Having a reference to the Backend Object Manager enables the Business Object to create a instance of abackend object using the cr eat eBackendBusi nessObj ect ( St r i ng backendObj ectType) method.The value of backendObj ect Type corresponds to the value of the t ype XML element within thebackendobj ect - conf i g. xml

Version


<busi nessObj ect type=‘Z_Custom’ name=‘ Z_Cust om’ . . . >

. . .

<busi nessObj ect / >

publ i c cl ass Z_Cust omFunc {

pr i vat e Z_Cust omFuncBackend mCust om;

pr i vat e Z_Cust omFuncBackend get Cust omFuncBackend( ) {

i f ( mCust om== nul l ) {

t r y {

mCust om = ( Z_Cust omFuncBackend)

bem. cr eateBackendBusi nessObj ect ( ‘ Z_Cust om’ ) ;

} cat ch ( BackendExcept i on bex) {

l og. err or( ‘ acme. er ror. z_get bo’ , bex);

}

}

r et ur n mCust om;

}

publ i c St ri ng get I nf o( ) {

r etur n get Cust omFuncBackend() . get I nf o( ) ;

}

. . . .

publ i c Z_Cust omFunc get Cust omFunc( ) {

i f ( mCust omFunc == nul l ) {

mCust omFunc = new Z_Cust omFunc( ) ;

/ / assi gns Backend Obj ect Manager t o Busi ness Obj ect i f

/ / Busi ness Obj ect i mpl ement s t he BackendAware i nt erf aceassignBackendObjectManager(mCustomFunc);

}

r et ur n mCust omFunc;

}




September 2006 206


Example

'Extension Demo 7: Copy-Templates for Customer Extensions' in the ‘Development and Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3) provides you atemplate you can use for your own projects when writing own Business Objects, Business Object Managersand Backend Objects.

BADIs/SAP CRM Extensions

This section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with SAP CRM as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer. Youonly need to extend the Interaction Layer with actions to fill your additional fields.

The solution consists of two parts: the extension concept for Business Objects in the Java layer and theBADIs and the ABAP extension structure in the SAP CRM BLS layer.

Use St r i ng objects when storing extension data, if you want to access this data from thebackend.

To extend a Business Object with your own fields, you need to implement a BADI in SAP CRM, where thefields are filled in extension structures as name value pairs. After that you can access the f ield using the keyfrom the extension in the Java layer. The extensions in the Java layer are also key value pairs that areassigned to the corresponding Business Objects.

Due to time constraints we couldn’t implement all of the BADIs in the first step. Therefore, you must fill theextension structure in SAP CRM as a modification of your function modules in this ‘pre BADI’ period. 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 theJDBC backend objects and DB basket.

As in the Internet Sales application, the E-Service Extended Complaints and Returns application providessome BADIs that you can implement in the CRM system to let you do additional processing.

Some function modules have as a parameter an extension data structure (typeCRMT_ISALES_EXTENSION_INT). For those function modules, this data extension structure can beprocessed in the CRM system by implementing the BADI definition. Note that some function modules do notuse the extension data structure but still offer BADI methods.

This following table lists the function modules and business objects where the extension data is stored in the java application. It also lists the BADIs method where your processing can be inserted. If there are nobusiness objects, it means that the data structure extension is not used as parameter for the functionmodule.

Note that the Complaint business object handles both complaints and returns. The separation of complaintsand returns is merely done on the user interface only: the process, and as a consequence, the businessobjects, backend objects and ABAP function modules are basically the same.




September 2006 207

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_GUI D CRMT_OBJ ECT_GUI D_C Guid of the business object.

ALT_HANDLE CHAR30 Alternative handle, if no guid exists.

Normally only used when new businessobjects are created.

NAME CRMT_ ISA_ EXTENSI ON_KEY Name of the extension.

VALUE CRMT_I SA_EXTENSI ON_VALUE Value of the extension.

Table 63: ABAP Extension Structure (CRM)

Take care of the field ALT_HANDLE for creating table-like objects, like the items in the basket. Since theguids are normally generated from the backend, the guids are empty when new entries are created. In thiscase, the handle is filled and, with it, you can associate the extension with the related item.

Supported Function Modules and Business Objects

Order Function module Business object

CRM_I SA_BASKET_GETI TEMS ItemSalesDoc

CRM_I SA_BASKET_CHANGEI TEMS ItemSalesDoc

CRM_I SA_BASKET_GETHEAD HeaderSalesDoc

CRM_I SA_BASKET_CHANGEHEAD HeaderSalesDoc

CRM_I SA_BASKET_STATUS HeaderSalesDoc ItemSalesDoc

CRM_I SA_SALESDOC_GETLI ST OrderStatus

CRM_I SA_BASKET_STATUS_ENH OrderStatus

Table 64: CRM - Supported Function Module / Business Object - Order

User

Function module Business object

CRM_I SA_BP_BPARTNER_GETDETAI L User

CRM_I SA_BP_CONSUMER_CHANGE User

CRM_I SA_BP_CONSUMER_CREATE User

Table 65: CRM - Supported Function Module / Business Object - User




September 2006 208

Contract


CRM_I SA_CNT_GETCONTRACTS ContractHead ContractItem

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

Shop


CRM_I SA_SHOP_DATA_GET Shop

CRM_I SA_SHOP_GETLI ST Shop

Table 67: 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_I NV 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_I NI TI ALI ZE Complaint

CRM_ESRV_COMPL_SAVE Complaint

CRM_ESRV_COMPL_DELETE_ I TEMS Complaint

Table 68: CRM - Supported Function Module / Business Object - Complaint

ComplaintHeader (E-Service)


CRM_ESRV_COMPL_CHANGE_HEADER ComplaintHeader

CRM_ESRV_COMPL_GET_HEADER ComplaintHeader

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

Complaint Item (E-Service)


CRM_ESRV_COMPL_CHANGE_I TEM ComplaintItem

CRM_ESRV_COMPL_CHANGE_I TEMS ComplaintItem

CRM_ESRV_COMPL_GET_I TEM ComplaintItem

CRM_ESRV_COMPL_GET_ I TEMS ComplaintItem

Table 70: CRM - Supported Function Module / Business Object – ComplaintItem




September 2006 209

Reading data from the Backend

If you are reading additional fields from the backend you have to fill the extension tables properly. Here aresome extensions for the basket, as an example:

* l s_header i s a l ocal st r ucture wi t h header dat a

l s_ext ensi on- r ef _gui d = l s_header - gui d.

l s_ext ensi onal t _handl e = l s_header- handl e.

* ext ensi on are name val ue pai r s

l s_ ext ensi onname = ‘ Z_CUSTOMER1’ ‘ name

l s_ext ensi on- val ue = l s_header- zcust omer1. ‘ val ue

APPEND l s_extensi on t o extensi on_header_out

* now addi ng extensi ons t o t he i t ems

LOOP AT l t _i t ems I NTO l s_ i t em.

l s_ext ensi on- r ef_ gui d = l s_i t em- gui d.

l s_ext ensi onal t _handl e = l s_i t em- handl e.

l s_ext ensi onname = ‘ Z_CUSTOMER2’ ‘ name

l s_ext ensi on- val ue = l s_i t em- zcust omer2. ‘ val ue

APPEND l s_extensi on t o extensi on_i t em_out

ENDLOOP.




September 2006 210

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. Inthis case, no guids table items exist, and we need to use the handle to identify the extensions.

Example

(no example available)

* l s_header i s a l ocal st r ucture wi t h header dat a

LOOP AT extensi on_header _i n I NTO l s_extensi on.

* check t he name t o f i nd the accor di ng f i el d

I F l s_ext ensi on-name = ‘ Z_CUSTOMER1’ .

l s_header- zcust omer1 = l s_ext ensi on- val ue.

ENDI F.

ENDLOOP.

* sor t t he extensi on t abl e by r ef _gui d and handl e t o obt ai n a bett er access

* wi t h bi nary sear ch.

SORT ext ensi on_i t em_i n BY r ef _gui d, al t _handl e.

LOOP AT l t _i t ems I NTO l s_ i t em.

* f i nd t he start i ng poi nt f or a l oop over ext ensi ons

* use gui d and handl e as one l ogi cal key t o access t he ext ensi on

READ TABLE ext ensi on_i t em_i n

WI TH KEY r ef _gui d = l s_i t em- gui d

al t _handl e = l s_i t em- handl e

BI NARY SEARCH.

I F SY- SUBRC = 0.

LOOP AT ext ensi on_i t em_i n I NTO l s_ext ensi on

FROM SY- TABI X.

* check, i f t he ent ry i s r el evant

I F NOT l s_ext ensi on- r ef _gui d = l s_i t em- gui d

OR NOT l s_ext ensi onal t _handl e = l s_i t em- handl e.

BREAK.

ENDI F.

I F l s_extensi onkey = ‘ Z_CUSTOMER2’ .

l s_i t em- zcust omer2 = l s_ext ensi on- val ue.

ENDI F.

ENDLOOP.

ENDI F.

ENDLOOP.




September 2006 211

BAPIs/SAP ERP-Extensions

This section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with SAP ERP as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer. Youonly need to extend the Interaction Layer with actions to fill your additional fields.

The solution consists of two parts: the extension concept for Business Objects in the Java layer and theABAP extension structure in the SAP ERP BLS layer.

Use St r i ng objects when storing extension data, if you want to access this data from thebackend.

To extend a Business Object with your own fields, you need to implement the corresponding appendstructures in SAP ERP, where the fields are filled in extension structures as name value pairs. Furthermore,you have to declare all additional data fields transferred via the extension structure in the configuration of theweb application. After that you can access the field using the key from the extension in the Java layer. Theextensions in the Java layer are also key value pairs that are assigned to the corresponding BusinessObjects.

Version


ABAP Extension Struc ture (BAPIPAREX)

Field Type Description

STRUCTURE TE_STRUC Structure name of BAPI table extension.

VALUEPART1 VALUEPART Extension data (240 characters).




Table 71: ABAP Extension Structure (ERP)

Supported Function Modules and Business Objects.

Order


SD_SALESDOCUMENT_CREATE HeaderSalesDoc ItemSalesDoc

SD_SALESDOCUMENT_CHANGE HeaderSalesDoc ItemSalesDoc

BAPI SDORDER_GETDETAI LEDLI ST HeaderSalesDoc

Table 72: ERP - Supported Function Module / Business Objects – Order

Please also check the chapter ‘

September 2006 212

Generic Search Framework’ (page 3).

Modification of Communication Structures in SAP ERP

In contrast to the BADI/SAP CRM extension concept, where additional data are transferred by name / valuepairs, in the BAPI/SAP ERP extension concept only values of additional data are transferred. The sequenceof data, as well as the data length of the individual data fields within the extension structure BAPIPAREX, isdefined in the SAP ERP DDIC by so-called communication structures (e.g. BAPE_VBAK).

These communication structures have to be modified/extended by the data fields which have to betransferred between the extension structure and the data structures in SAP ERP. By default, data istransferred to specific SAP ERP data structures based on equal field names (using move-corresponding):

Communication structure ERP Data structure Description

BAPE_VBAK VBAK Order header data (default structure).

BAPE_VBAP VBAP Order item data (default structure).

BAPI _VBKD VBKD Order business data.*

Table 73: Communication Structure in SAP ERP

* If the structure BAPI_VBKD should be used for transferring data on order header and/or order item level tothe ERP data structure VBKD also parameter structure and/or str ucturei t emhas to be changed in theconfiguration backendobject-config.xml (see bellow).

If the data should be transferred to other data structures in SAP ERP you have to implement an additionalform routine for data transfer (see below).

Configuration of the Web Application

Corresponding to the SAP ERP system, You have to define the data definition of the communicationstructure in ISA, in configuration backendobj ect - conf i g. xml (see Changes in backendobject-config.xmlbelow), for transfer of data between the extension structure and the business object extension data. Thedefinition of the fields must contain name/length pairs separated by comma:

<busi nessObj ect t ype=‘ EXTENSI ON_DOCUMENT_CREATE’

name=‘ EXTENSI ON_DOCUMENT_CREATE’

cl assName=‘ com. sap. i sa. backend. r 3base. Ext ensi onParamet ers’

att r i but es=‘ st andal one’ >

<par ams>

<par am name=‘ st r ucture’ val ue=‘ BAPE_VBAK’ / >

<par am name=‘ st r uctureI t em’ val ue=‘ BAPE_VBAP’ / >

<param name=‘ f i el ds’ val ue=‘ LI FSK, 2’ / >

<param name=‘ f i el dsI t em’ val ue=‘ LPRI O, 2, WERKS, 4’ / >

</ par ams>

</ busi nessObj ect>




September 2006 213

Reading Data from the Backend

If the additional data should be read from the default data structure (see above), no further activities arenecessary.

Only character type data can be transferred through this mechanism, binary data has to beconverted before transfer.

If the additional data should be read from a different data structure, an additional form routine for datatransfer has to be implemented, as shown in the following example:

Writing Data to the Backend

If the additional data should be transferred to the default data structure (see above), no further activities arenecessary.

The extension structure can only used for character type data, binary data in the data structurehas to be converted before transfer.

If the additional data should be transferred to a different data structure, an additional form routine for datatransfer has to be implemented, as shown in the following example:

* Ext ensi ondata wr i t e - Header

MOVE SALES_DOCUMENTS TO WA_BAPE_VBAK- VBELN.

MOVE ORDER_BUSI NESS_OUT- PMNTTRMS TO WA_BAPE_VBAK- ZZPMNTTRMS.

READ TABLE EXTENSI ON_OUT WI TH KEY STRUCTURE = ’ BAPE_VBAK’ .

TABLE_TABI X = SY- TABI X.

I F SY- SUBRC NE 0.

CATCH SYSTEM- EXCEPTI ONS CONVERSI ON_ERRORS = 1.

MOVE ´BAPE_VBAK ́ TO EXTENSI ON_OUT- STRUCTURE.

MOVE WA_BAPE_VBAK TO EXTENSI ON_OUT+30.

ENDCATCH.

APPEND EXTENSI ON_OUT.

ELSE.


MOVE WA_BAPE_VBAK TO EXTENSI ON_OUT+30.

ENDCATCH.

MODI FY EXTENSI ON_OUT I NDEX TABLE_ TABI X.

ENDI F.




September 2006 214

Example

Chapter ‘Extensions Demo 5 – Maintain Delivery Block Indicator in ECO ERP’ of the ‘ Development and

Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3).

Java Basket-Extensions

This section describes a solution for modifying Business Objects without modifying the standard backendimplementation, with the Java basket as the backend system. This means that you can extend the standardBusiness Objects with your own data without changing anything in the Business Object and BLS layer.

An automatic transfer of extension data from the Business Object to the Java Basket is onlypossible for extension data attached to the basket header or to the basket items. Extension data

attached to other business objects, for example the ship to have to transferred manually byextending the corresponding standard backend objects.

Version


Example

(no example available)

Request ContextThe request context is a container enabling you to easily exchange data between layers in an Internet Salesapplication. The context is accessible from nearly everywhere within the ISA framework, making it a verypowerful way to exchange data. Using the request context violates some rules defined for standard ISAdevelopment. It is therefore not used within the standard coding of Internet Sales.

The Request context is represented by the class com. sap. i sa. core. Request Cont ext .

The follwing table shows how to access the Request Context in the various places:

Location Method for Accessing Request Context

* Ext ensi ondat a read - Header

READ TABLE EXTENSI ON_I N WI TH KEY STRUCTURE = ’ BAPE_VBAK’ .

I F SY- SUBRC EQ 0.


MOVE EXTENSI ON_I N+30 TO WA_BAPE_VBAK. ENDCATCH.

ENDI F.

MOVE _BAPE_VBAK- ZZPMNTTRMS TO ORDER_BUSI NESS_ I N-PMNTTRMS.




September 2006 215

JSP Request Cont ext . getRequest Cont ext ( r equest )

Action getRequest Cont ext ( )

Business Object getRequest Cont ext ( )

Backend Object getBackendObj ectSupport ( ) . get Request Cont ext ( )

Function Moduleexecution listener

Within the connect i onEvent( J CoConnect i onEvent event ) method of afunction module execution listener (com. sap. i sa. cor e. eai . sp. j co.

J CoConnect i onEvent Li st ener )

event . getRequestCont ext ( )

For further information about execution listeners refer to chapter 'Interception of Callsto Standard Function Modules' on page 3.

Table 74: How to access the Request Context

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

addData(Obj ect name, Obj ect val ue)o Stores any kind of data

Obj ect get Data( Obj ect name)

o Returnes the stored data or null if not data with the given name is available in the RequestContext

For more information about the Request Context refer to the Java Doc of com. sap. i sa. core. Request Cont ext

The scope of the request context is one request (usually one HTTP request). After the request is finished thecontext is cleared. If you want to store data between requests use the Business Object layer or use the

session context instead.

Version

This feature is available in CRM 5.0.

Example

This example demonstrates how to pass data from Function Module Execution Listener to a JSP:

You would like to pass the value of an export parameter of a function module, called by the standard to theJSP:

September 2006 216

Retrieve the value within the JSP

This function event listener must be registered in the file

/ WEB- I NF/ xcm/ cust omer / modi f i cat i on/ modi f i cat i on- conf i g. xml in order to be notified whenthe function module is executed.

For information how to work with function module execution listeners refer to chapter 'Interception of Calls toStandard Function Modules' on page 3.

Adding additional Function Modules (Backend System)Function modules are accessed by Backend Objects. If you have to access your own custom functionmodules you usually do it by writing a Backend Object. Backend Objects are accessed by Business Objectsvia well-defined Java interfaces.

. . .

<%@ page i mpor t =‘ com. sap. i sa. cor e. Request Cont ext ’ %>

<%

St r i ng myVal ue = Request Cont ext . getRequest Cont ext ( r equest ) . get Data(‘ z_Val ue’ ) ;

%>

. . .

publ i c cl ass MyLi st ener i mpl ement s J CoConnect i onEvent Li st ener {

publ i c voi d connect i onEvent ( J CoConnect i onEvent event ) {

/ / Thi s event l i stener i s cal l ed t wi ce: bef ore t he f uncti on

/ / modul e i s execut ed and af t er

/ / we ar e onl y i nt erst ed i n t he event af t er f unct i on cal li f ( event . get I d( ) == J CoConnect i onEvent . AFTER_J CO_FUNCTI ON_CALL) {

/ / get r ef er ence t o J CO Funct i on

J CO. Funct i on f unc = event . getJ CoFunct i on( ) ;

/ / get cust om val ue f r om i mport parameter name z_val ue

St r i ng z_Val ue = f unc. get Export Par ameterLi st ( ) . get St r i ng( ‘ z_val ue’ ) ;

/ / pass val ue t o Request Cont ext

event . getRequestCont ext ( ) . addData( ‘ z_Val ue’ , z_Val ue);

}

}

}




September 2006 217

Figure 65: Adding additional Function Modules

In this case you must do the following1. 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 3.

'Create a Customer Business Object' on page 3

'Create a Customer Backend Object' on page 3

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 ERPsystem, without changing the Java coding provided.

You can use this extension concept to intercept calls

To any function module called by ISA

To function modules you have registered as described in chapter 'Replacing Calls to StandardFunction Modules (Backend System)' on page 3.

The basic idea behind this concept is to register a Java event listener, which is notified before/after a functionmodule is called. The listener can be used to manipulate the function call, and has access to theRequestContext, meaning that it can communicate with other parts of the application (Action, JSP, BusinessObject, Backend Object).

The following diagramm shows the how this concepts works at runtime:




September 2006 218

BLS Connection

Management

Standard ISA

class

Customer execution

listener

execute

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

needed return

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 optionalparameters and pass/retrieve additional data. Nevertheless, this extension concept should only be usedwhen the function module, which you would like to extend, has no extension table (see 'chapter BADIs/SAPCRM Extensions' on page 3).

Please keep in mind, when you extend these interfaces, that the interfaces of existing functionmodules can change with subsequent releases of ISA. It is also possible that the functionmodule will be replaced in subsequent releases.

A common modification is the addition of optional parameters to the interface of the function module. In thiscase you will usually perform one, or both, of the following modifications:

Provide additional data by using the optional parameters, before the function module is called. Youcan pass data to the execution listener using the Request Context

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 Request ContextWhen 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 Request Context . This gives you the opportunity toprovide/retrieve additional data from other layers of the application (Action, JSP, Business Object, BackendObject).

Within the event you have access to the J CO. Funct i on, which is called. This gives you the opportunity toprovide/retrieve additional data in your optional parameters.

September 2006 219

Thread Safety in Execution Listeners

Please note that every listener has configuration scope! That means that you shouldn’t define instancevariables within the listener if the data have to have session scope. If the listener wants to access session-specific data, it has to use the backend context or the Request Context .

VersionThis feature is available in all versions of ISA 5.0.


What to Do

The following steps describe the tasks you have to perform:

1. Write an execution event listener by implementing thecom. sap. i sa. cor e. eai . sp. j co. J CoConnect i onEvent Li st ener interface.

2. Register the listener within WEB- I NF/ xcm/ cust omer / modi f i cat i on/ modi f i cat i on-conf i g. xml . You can define for which function module the exection listener should be notified

Within the listener the connect i onEvent( J CoConnect i onEvent event ) method is called when afunction module is executed. Within this method you have the follwing possibilites:

o You can find out which function module has been called by callingevent . get J CoFunct i on( ) . get Name( )

o You can find out if this is an event before, or after, the function call by retrieving the event idevent . get I d( ) , and comparing with event . AFTER_J CO_FUNCTI ON_CALL or event . BEFORE_J CO_FUNCTI ON_CALL.

o Access the RequestContext by calling event . getRequest Cont ext ( )

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 tothe J CO. Funct i on object.

Example

For an example on this modification, see ‘Extension 5: Maintain Delivery Block Indicator for ECO ERP in the‘Development and Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’ (see [1] in chapter References on page 3).

Replacing Calls to Standard Function Modules

<f unct i on- modul e- l i st ener>

<par am

name=‘ f mevent : NAME_OF_ FUNCTI ON_MODULE’

val ue=‘ Cl assNameEvent Li st ener’ / >

</ f unct i on- modul e- l i st ener>




September 2006 220

(Backend System)This concept allows you to replace calls to remote callable function modules in a SAP CRM or SAP ERPsystem without changing the Java coding provided.

You can use this extension concept to let the application call your function modules, instead of the standard

function modules.Prerequisite is that the interface of your function module is compatible with the interface of the standardfunction module called by ISA, that means your function module can only provide additional parameters butyou must not change/or delete parameters of the standard function module.

To allow the ISA application to call your function module you have to register it in the WEB-I NF/ xcm/ cust omer / modi f i cat i on/ modf i cat i on- conf i g. 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



What to Do

Create an own Z_ function module having the same or an compatible interface as an functionmodule called by the ISA standard coding (e.g. Z_CRM_I SA_SHOP_GETLI ST)

September 2006 221

Register the function module within WEB- I NF/ xcm/ cust omer / modi f i cat i on/ modf i cat i on-conf i g. 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) below

Extension of the Web Catalog

New Fields in the Web Catalog (SAP CRM Backend)Showing more attributes in the web catalog is very easy, since no java class needs to be touched. Just addthe attribute in product catalog maintenance in SAP CRM and adapt the JSPs accordingly.

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 anattribute Z_COLOR, for the color of the product. Ensure that this attribute is maintained for the products inyour catalog, otherwise you will only see an empty field in the web catalog. Replicate the catalog variant.

Create a resource key that has the name cat al og. i sa. at t r i but e. Z_COLOR with a value like color inyour language resource file ISARessources.

Show Addit ional Attribute in Product ListOnly some attributes of the item are displayed in the product list, due to space constraints.

The JSP responsible for the product list is / b2b/ cat al og/ Pr oductsI SA. i nc. j sp for B2B, and

/ b2c/ cat al og/ Pr oduct sB2C. j sp for B2C. Both are similar.

For this example we will use the B2B JSPs. In ProductsISA.jsp the part between <thead> and </thead> isresponsible for the table headings. For the new attribute, we need an additional heading in the area betweenthese.

For example, after:

add the line:

<f unct i on- modul e- r epl acement >

<param name=‘ f m: CRM_I SA_SHOP_GETLI ST’ val ue=‘ Z_CRM_I SA_SHOP_GETLI ST’ / >

</ f unct i on- modul e- r epl acement >

<t h></ t h>

September 2006 222

This will ensure that the heading of the column Color is displayed.

After that, the items are iterated in the JSP and the data is displayed. We put the heading after that of thedescription, so we also need to put the content after the content of the description. The content of thedescription field is displayed with:

After this, insert the display of the content of the new attribute:

The row span is needed in B2B, because if contracts are displayed, an additional row will be displayed 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 CompareProducts

There are two types of attributes; category-specific and catalog-specific. By default, only the category-specific attributes are displayed.

The Pr oductDet ai l sI SA. j sp, Compar eI t emsI SA. j sp (for B2B), and the Pr oduct Det ai l B2C. i nc,CompareItemsB2C (for B2C) respectively, are designed in such a way that all catalog-specific attributes thathave a non empty description and their names conatin a “_“ (i t em. get At t r i but eDescr i pt i on( ) ! =

nul l && i t em. get At t r i but eName( ) . i ndexOf ( "_" ) ! = 0) are shown, or all catalog-specificattributes that have a resource key corresponding to the patterncat al og. i sa. at t r i but e. <at t r i but e_name>are shown. This means, if an additional catalog specificattribute Z_MyAt t r i but e should be displayed, an appropriate resource key has to be added to theISAResource file(s):

cat al og. i sa. at t r i but e. Z_MyAt t r i but e=At t r i but eName

See also note 452751.

<t d r owspan=‘ <%= noOf Contr act I t ems %>‘ al i gn=‘ center ’ >

<%= i t em. getAt t r i bute( ‘ Z_COLOR’ ) %>

</ t d>

<t d r owspan=‘ <%= noOf Contr act I t ems %>‘ al i gn=‘ center ’ >

<a hr ef =‘ j avascri pt : seeSi ngl eI t em( ' <%= i t em. getI t emI D( ) %>' ) ’ >

<%= i t em. get At t r i but e( ‘ OBJ ECT_DESCRI PTI ON’ ) %>

</ a>

</ t d>

<t h r owspan=2 al i gn=cent er>

</ t h>

September 2006 223

Show Addit ional Keys for Extended Search in B2B

The extended search is done with respect to catalog-specific attributes. By default, only the OBJ ECT_I D andOBJ ECT_DESCRI PTI ON attributes are taken into consideration. However, it is very easy for bi gSear ch. j sp to display new search keys. Each attribute that has a resource key corresponding to thepattern cat al og. i sa. bi gSear ch. <at t r i but e_name>gets an input field displayed, and can, therefore,be used as a search key. See also note 482338.

New Fields in the Web Catalog (SAP ERP Backend andMemory Catalog)This unit describes how additional attributes can be transferred from the SAP ERP system to the ISA productcatalog, using the memory catalog. In addition to the extensions described in this unit, the ISARessource filehas 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.

Loading additional Product Attributes from the SAP ERPBackend to the Memory Catalog

Additional product attributes can be transferred from the SAP ERP Backend to ISA using a predefinedcustomer exit per f ormCust omerExi t Af t erCatal ogRead in the classcom. sap. i sa. backend. r 3. cat al og. R3Catal ogSer ver Engi ne. The method is shipped empty andcalled after reading the catalog. The parameters of the method are the catalog and a JCO connection to theSAP ERP system. In the method additional data can be read from the SAP ERP system and added to thecatalog.

The following steps have to be performed:1. Create a new class extending

com. sap. i sa. backend. r 3. cat al og. R3Catal ogSer ver Engi ne.

2. Implement the method perf ormCust omerExi t Af t er Catal ogRead. Use the JCO connectionprovided as call parameter to read additional information from SAP ERP, if necessary, and add theresults to the catalog object.

3. Register your individual class instead of com. sap. i sa. backend. r 3. cat al og. R3Catal ogSer ver Engi ne in with the ISA extensionconcept as described in Changing existing Backend Object below.

VersionThis feature is available in all versions of ISA 5.0.

Example

See note 610393.




September 2006 224

New Fields in the Web Catalog (SAP ERP Backend andTREX)This unit describes how additional attributes can be transferred from the SAP ERP system to the ISA productcatalog, using the TREX. In addition to the extensions described in this unit, the ISARessource file has 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, theappropriate JSP has to be extended as for ISA CRM.




September 2006 225

Loading additional Product Attributes from the SAP ERPBackend to the TREX

Additional products attributes can be transferred from the SAP ERP Backend to TREX by using the methodsATTRI BUTE_NAMES_GET and NODE_GET_ATTRI BUTE_VALUES of classCL_ I SA_REPLI CATI ON_CATALOG. The first method is used to define the names and types of the attributeson TREX, the second method is called for every catalog area and item to add values for the additionalattributes. The methods are delivered empty in the standard class and have to be redefined in a customer class inheriting from CL_ I SA_REPLI CATI ON_CATALOG. The usage of the new class is controlled by theBAdI BADI _I SA_REPL_CAT.

The following steps have to be performed:

1. Use the class builder (transaction SE24), to create a new class named ZCL_ I SA_REPLI CATI ON_CATALOGinheriting from CL_ I SA_REPLI CATI ON_CATALOG(use the button “Define inheritance” next to the file namein the creation dialog).

2. Redefine the methods I F_ I SA_REPLI CATI ON_CATALOG~ATTRI BUTE_NAMES_GET andI F_ I SA_REPLI CATI ON_CATALOG~NODE_GET_ATTRI BUTE_VALUES. See the example below for further details.

3. Create a new implementation for BAdI BADI _I SA_REPL_CAT. The BAdI implementation is used to return aninstance of your catalog class instead of the standard class. The standard implementationI SA_REPL_CAT_I MP_DEF can be used as a template.

After the replication using transaction I SA_CAT_REPLI CATI ON, 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 WebCatalog (SAP ERP Backend and TREX)” on page 3) and an additional attribute MAT_GROUP that will containthe material group of a catalog item.

The first method defines the attribute names and specifies the attribute type. Available attribute types are:

I ( I nt eger)

F ( Fl oat i ng Poi nt ) D (Dat e YYYYMMDD)

S ( St r i ng) N ( Char ) T ( Ti me)

U ( UTC Dat e- Ti me)

The attribute definitions must be put into the 2 separate changing parameters (tables) I TEM_ATTRI BUTESand AREA_ATTRI BUTES. This example only deals with item attributes:




September 2006 226

The second method is called once for each catalog node (i.e. for each area and each item). Therefore itsinterface contains only one parameter ATTRI BUTES 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 materialmaster data to the attribute MAT_GROUP. Furthermore, it assigns the material’s industry sector (field MARA-MBRSH) to VI EWS_I D. Hence, we create one catalog view per industry sector throughout the catalog. If moreview assignments shall be made, it’s important to increase the multi-value counter per view id. See thecoding comment below.

METHOD i f _i sa_repl i cati on_catal og~att r i but e_names_get.

DATA: i t em_at t r i but e LI KE LI NE OF i t em_at t r i but es.

i t em_att r i but e- at t r name = ' VI EWS_I D' . "speci al at t r i but e f or vi ews

i t em_at t r i but e- at t rt ype = ' S' . "St ri ng APPEND i t em_at t r i but e TO i t em_at t r i but es.

i t em_at t r i bute- at t r name = ' MAT_GROUP' . "materi al group

i t em_at t r i but e- at t rt ype = ' S' . "St ri ng

APPEND i t em_at t r i but e TO i t em_at t r i but es.

ENDMETHOD.

September 2006 227

Customer Specif ic Views in the Web Catalog (SAP ERPBackend and TREX)This unit describes how to get customer specific views of the product catalog with an SAP ERP backendsystem and the TREX catalog (see also note 696095).

METHOD i f _i sa_repl i cati on_catal og~node_get_att r i but e_val ues.

DATA: l v_at t r i but e LI KE LI NE OF att r i but es,

l v_mar a TYPE mar a.

I F NOT i t em I S I NI TI AL. " creat e at t r i but e val ues for the i t em* r ead mater i al master data f or t he gi ven catal og i t em

CALL FUNCTI ON ' MARA_SI NGLE_ READ'

EXPORTI NG

mat nr = i t em- mat er i al

I MPORTI NG

wmar a = l v_mar a

EXCEPTI ONS

l ock_on_materi al = 1

l ock_syst em_er r or = 2

wr ong_cal l = 3

not_f ound = 4 OTHERS = 5.

I F sy- subr c <> 0.

MESSAGE I D sy- msgi d TYPE sy- msgt y NUMBER sy- msgno

WI TH sy- msgv1 sy- msgv2 sy- msgv3 sy- msgv4

RAI SI NG err or_i n_catal og_api .

ENDI F.

* assi gn mater i al gr oup t o the corr espondi ng att r i but e

l v_at t r i but e- at t r name = ' MAT_GROUP' .

l v_at t r i but e-at t r val ue = l v_mara-matkl .

APPEND l v_at t r i but e TO att r i but es.

* bui l d catal og vi ews accordi ng t o i ndust r y sect or

l v_at t r i but e- att r name = ' VI EWS_I D' .

* when assi gni ng the i t em t o more t han 1 vi ew, each l i ne has t o use a

* di f f er ent number f or t he mul t i - val ue count er . I n t hi s exampl e i t ' s

* onl y 1 val ue, t heref ore you coul d even ski p the counter assi gnment .

l v_at t r i but e-mul t at r cnt = 1. "t he mul t i - val ue count er

l v_at t r i but e- att r val ue = l v_mara- mbr sh.

APPEND l v_at t r i but e TO att r i but es.

ENDI F.




September 2006 228

Customer specific views of the product catalog are created by matching ‘catalog view’ attributes, attached tothe (ECO) product catalog area/item, with the (ECO) customer. These attributes have to be transferred fromthe SAP ERP Backend to ECO via the SAP ERP function modules I SA_READ_CATALOG_COMPLETE andI SA_CUSTOMER_READ_CAT_VI EWS. Neither function module retrieves any ‘catalog view’ attributes instandard, but both have to be extended due to individual requirements.

The following steps have to be performed:

1. Create a new SAP ERP function module Z_READ_CATALOG_COMPLETE by copying the standardfunction module I SA_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 tableATTRI BUTES.

o attributes-layout - catalog layouto attributes-area - internal area number o attributes-item - internal item number (if required)o attributes-name – ‘ VI EWS_I D’ (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

I SA_READ_CATALOG_COMPLETE with the E-Commerce extension concept as described in Changesin Configuration below.

4. Create a new SAP ERP function module Z_CUSTOMER_READ_CAT_VI EWS with an interface asdescribed in note 677319 for function module I SA_CUSTOMER_READ_CAT_VI EWS.

5. Implement a new form routine to retrieve the ‘catalog view’ attributes and to fill the data to the tableCATALOG_VI EWS.

o catalog-views-string – value of ‘catalog view’ attribute

6. Register the new SAP ERP function module instead of the standard SAP ERP function moduleI SA_CUSTOMER_READ_CAT_VI EWS with the E-Commerce extension concept as described inChanges in Configuration below.

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 andTREX)” on page 3.




September 2006 229

Extensions of the IPCThe IPC (Internet Pricing And Configurator) is a reusable component for pricing and interactive configuration.

It consists of the pricing engine (SPE) the sales configuration engine (SCE) and the interactive configurationuser interface. SCE and SPE are components of the SAP application server. The interactive configurationuser interface is a web application based on the E-Commerce application framework.

The main focus of this chapter is with regards to the IPC is on the Interactive Configuration user interface.SCE and SPE engines that form the IPC “server” have their own extension mechanisms (user exits asdescribed in notes 809820 and 870201).

The following unit introduces some modification concepts related to the IPC user interface as part of the E-Commerce web applications (b2b and b2c) or as a separate web application (ipc) which is used in SAPscenarios (Interactive configuration in CRM Order, Mobile Sales order, ERP order, Vehicle Manager ...).

Since the Interactive Configuration UI uses the E-Commerce framework, it also supports the modificationconcepts of the framework.

The section below explains additions and differences to the E-Commerce extension concept.Please give your feedback (corrections, additions) about the IPC chapter to [email protected].

Architecture of the IPC 5.0 UI in CRM Order ScenarioThis unit gives an introduction to the IPC UI concepts.

SAP R/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 Marketplaceunder alias /crm-inst.

mailto:[email protected]

mailto:[email protected]




September 2006 230

In summary:

There is a clear separation between the IPC engines as part of the CRM or ERP system and the IPCWeb Application, which is the JSP UI used for interactive product configuration and runs on the SAPJ2EE Engine.

As of release 5.0 the IPC is not a separate server anymore. The IPC comes with the CRM or ERPand exchanges data with its client applications via RFC.

In all scenarios (including ISA CRM, ISA ERP), the IPC reads master data directly from the SAPCRM or ERP server; The former dataloader is not required anymore.

Instead of directly calling RFC function modules, the interactive configuration (JSP) UI uses anabstraction layer (Client Object API) very similar to the ISA Business Object/Backend Object APIswith Java methods.

Internet Sales; CRM online;

Vehicle Management System;

ERP

JSP Pages

UIBeans UIClasses

Client Object Layer Interface

Remote Function Call TCP/IP

Vi rtual Machine Container MSA IPC Server

SPE/SCE Integration

Pricing Engine Configurator

Act ions

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 UIcommunicates with the IPC over remote function calls

2. Mobile Sales: The IPC is a process running on the mobile client. The UI communicates with the IPCover a string based socket protocol (as in 4.0).

Design of the JSP Web Application:

The IPC UI uses the ISA Framework (Layout, Backend communication, XCM, Tags, …)

The IPC UI does not use html frames

The Javascript is separated into script files

Action Forms are not used




September 2006 231

Action Flow

Act ion:

setCharacteristicValues

Act ion(s):

displayLayout

P o s t

F o r w a r d t o

d i s p l a y L a y o

u t

redirect Get

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 dividethe action flow into two blocks:

1. Data processing actions: Receives user input via http post request and changes the state of theconfiguration

2. Data display actions: Reads the current state of the configuration, creates the html according to thelayout and sends the response

Use of the E-Commerce Layout FrameworkThe interactive product configuration user interface takes advantage of the E-Commerce Layout Framework.For detailed explanation of the E-Commerce Layout Framework refer to chapter Fehler! Verweisquellekonnte nich t gefunden werden. for more details.

UI Components

The XCM file / sap/ modi f i cat i on/ i pcl ayout - conf i g. xml defines the UI Components that arecommon for SAP’s standard applications that include the interactive configuration ui (b2b; b2c; ipc).

UI Layouts

The XCM f i l e / sap/ modi f i cat i on/ l ayout - conf i g. xml defines the layouts of the application. Thecommon UI components of the interactive configuration ui together with the UI components of the standard

application form these layouts.




September 2006 232

Figure 71 Example for layout with UI components from both files (layout-config and ipclayout-config)

The XCM file / sap/ modi f i cat i on/ l ayout - conf i g. xml includes/ sap/ modi f i cat i on/ i pcl ayout - conf i g. xml so that at runtime both files form one XCM file.

Technical background of this separation between layout-config and ipclayout-config is that UI componentsfrom ipclayout-config can be reused.

UI Areas

The picture below shows the partitioning of the interactive configuration UI in different UI Areas. Theses UIareas are filled with UI components at runtime.

Figure 72 UI areas of the config UI




September 2006 233

Tiles

The layout of the interactive configuration is highly dynamic. The work area for example lists a variablenumber of characteristics that may differ in their presentation to the user.

In order to support modifications on such a fine-grained level of UI parts, the interactive configuration 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 insoftware component SAP- SHRWEB in development component crm/ipc/web/ipcshared in folder i pc/ t i l es.

Low level layouts

In order to reuse tiles, the UI combines tiles with low level layouts. This low level layout technique is differentfrom the UILayouts of the E-Commerce Framework.

Low level layout pages carry only layout information. Tiles carry content.

The picture below demonstrates how layout and tiles are combined. The layout JSP page is very simple andholds only a table in which the tiles are included. You’ll find layouts in software component SAP- SHRWEB indevelopment component cr m/ i pc/ web/ i pcshared in folder i pc/ l ayout s.




September 2006 234

Figure 74 Combining low level layout and tiles

Dynamic IncludesThe application calculates at runtime which layouts to combine with which tiles. Layouts and tiles carry keysthat the application replaces at runtime by the physical file path of the JSP page for the layout or tile. Theapplication does this with a XCM customizing table lookup in file j spi ncl ude- conf i g. xml for eachrequest before sending the response back to the users browser.




September 2006 235

Figure 75 JSP Key and Path

The indirection -> key -> XCM table lookup -> physical path gives application programmers the possibility toeasily replace SAP’s standard JSP pages by their own pages inxcm/ cust omer / modi f i cat i on/ j spi ncl ude- conf i g. xml . You will find an example for this techniquein Change UI Components.

The Interactive Configuration UI performs dynamic includes using static methods (“include”) of UIClasses.You’ll find UIClasses in software component SAP- SHRJ AV in development component crm/ i pc/ i pc infolder com/ sap/ i sa/ i pc/ ui / j sp/ ui cl ass. The include methods offer a typesafe api to the page. Theymake sure that the parameters passed to the included page do not interfere with parameters used by other included pages.

publ i c stati c voi d i ncl ude(

PageContext pageContext ,

Str i ng charact er i st i cCont rol l er ,

UI Cont ext ui Cont ext ,

I nst anceUI Bean i nstance,

Gr oupUI Bean char Gr oup,

Charact eri st i cUI Bean csti c, UI Ar ea ui Ar ea,

Hasht abl e cust omer Params) {




September 2006 236

The included page retrieves the parameters by the following call:

Charact eri st i cUI . I ncl udeParams i ncl udeParams = Character i st i cUI . getI ncl udeParams( pageCont ext ) ;

I nst anceUI Bean curr ent I nst ance = i ncl udeParams. get I nstance( ) ;

Gr oupUI Bean char act er i st i cGr oup = i ncl udePar ams. get Char Gr oup( ) ;

Charact eri st i cUI Bean charact eri st i cUI Bean = i ncl udeParams. getCst i c( ) ;

UI Cont ext ui Cont ext = i ncl udeParams. get I pcBaseUI ( ) ;

UI Ar ea cst i csAr ea = i ncl udeParams. get Ui Ar ea( ) ;

Hasht abl e cust omerParams = i ncl udeParams. get Cust omer Params( ) ;

You may pass parameter between jsp pages only via the session or request context. The interactiveconfiguration UI consists of recursively nested JSP pages. Include parameter are supposed to be valid onlyfor the current include method and not visible for all the included pages. The parameter stack ensures thatgetIncludeParams retrieves those parameter that are passed with the last include method. That means onthe top of each included page you need to call get I ncl udeParams( pageCont ext ) .

Extension To Transfer Data To JSP

In addition to the standard ways to transfer data to JSP pages described in this document, the dynamicincludes with UIClasses used in the interactive product configuration offer a possibility to pass extension datato JSP pages. All include methods of UIClasses offer a customerParams parameter. All IncludeParamsobjects have a method get Cust omerParams( ) that returns a Hashtable.

UIBeans

UIBeans form an intermediate layer between the JSP pages and the Business objects (IPC client objectlayer). Methods of UI Beans are optimized for use within the JSP pages and reduce the complexity of theJSP pages.




September 2006 237

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 cachingand provides convenient Java API’s to its calling applications. It performs communication with the IPC in thebackend via RFC function calls or Socket commands (Mobile Sales). Please see Figure 69 IPC Architecturemore in detail.

Finding The Appropriate Extension Concept For IPCThe chapter Fehler! Verweisquelle konnte nicht gefunden werden. applies also to the InteractiveConfiguration User Interface. Specific concepts are described in this chapter.




September 2006 238

Static extension to UI layer

Changing StylesheetsIn order to define your own styles to change the appearance of the application, you will need to

1. Create your own stylesheet file as a copy of SAP’s standard stylesheet

2. Register your own stylesheet in / xcm/ cust omer / modi f i cat i on/ i ni t - conf i g. xml .You will find an example on how to do this in / xcm/ cust omer / modi f i cat i on/ i ni t -conf i g. xml .

3. Change SAP’s standard style definitions in your own stylesheet or add new styles for your own JSPpages.

IPC shared styles are located in software component SAP- SHRWEB development componentcr m/ i pc/ web/ i pcshar ed/ folder i pc/ mi mes/ st yl e/ st yl esheet . css. Shared styles means thosestyles are common to b2b, b2c, and ipc web applications.




September 2006 239

Create New Layout Or Change Standard Layout

The only thing that differs here from the E-Commerce framework is the location of UIComponents for theinteractive configuration UI. UIComponents are located in / sap/ modi f i cat i on/ i pcl ayout -conf i g. 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 areawithout modification to the UI component header.

In order to do this you need to define those customer buttons in the xcm customizing under componentscustomerbutton1 to customerbutton3.

Figure 77 XCM settings for customer buttons

The parameter forward is not supported in SAP’s standard UI. The parameter target allows the three valuesfor html hyperlink targets: _self, _parent, top. By default the result will be displayed in the same frame as theinteractive configuration UI.




September 2006 240

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 i n the text

pr oper t y f i l e ( l anguage dependent ! ) )

The customer buttons call the actions that you have defined in the parameter customerbutton1.action. SAPprovides three placeholders for action mappings / i pc/ cust omer But t onXAct i on in the i pc-conf i g. xml .

Example: Adding Customer Tab To Multifunctional Area

The interactive configuration UI gives you the possibility to add a customer specific tab to the multifunctionalarea (area on the right side of the standard interactive configuration UI).




September 2006 241

Figure 79 Component configuration for customer tab

You activate this area when setting the parameter “cust omert ab. show” of the XCM componentmultifunctional area to “T”.




September 2006 242

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 actioncom. cust omer . i sa. i pc. ui . j sp. act i on. Get Cust omer TabAct i on. This action will display the page/ i pc/ cust omer / component s/ cust omerTab. j sp in the multifunctional area. The customer tab will beactive. The example delivered by SAP displays the characteristic details in the cust omerTab. j sp.

You may either change the content of the action and the cust omerTab. j sp page or change the actionmapping to use your own action and forward to your own JSP page.




September 2006 243

Figure 82 Customer tab with characteristic details

Example: Display Characteristic Header And Values In OneLine

Depending on the space on screen and your configuration model (length of characteristic names andvalues), you may want to display the name of the characteristic and its values in one line to save verticalspace. Software component SAP- SHRWEB, development component cr m/ i pc/ web/ i pcshared, folder i pc/ customer/ t i l es/ charact er i st i c. j sp shows the modified JSP page./ xcm/ cust omer / modi f i cat i on/ j spi ncl ude- conf i g. xml shows an example how to include thismodified page instead of the SAP standard page.




September 2006 244

Extensions To The UIBean Layer The interactive configuration creates UIBeans using a generic factory that you may subclass and replaceSAP’s standard UIBean factory.

You may register your own UIBeanFactory in / xcm/ cust omer / modi f i cat i on/ f act or y- conf i g. 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 typecom. cust omer . i sa. i pc. ui . j sp. beans. Val ueUI Bean which in turn is a subclass of com. sap. i sa. i pc. ui . j sp. beans. Val ueUI Bean and overwrites the getLanguageDependentNamemethod.

I recommend extensions to the UIBean layer if you want to:

1. Perform complex calculations in methods that are relevant for the way you display data but not thebusiness data itself. A good example is the method det ermi neLayout ( ) incom. sap. i sa. i pc. ui . j sp. beans. Char acteri st i cUI Bean. This method calculates the

characteristic layout to be used from a number of characteristic attributes (multi value, intervaldomain, …). This calculation is neither business logic nor should the calculation been done on the jsp page.

2. You extended the business object layer (IPC client object layer) and want to display additional datafrom the business object layer in the JSP pages. The UIBean passes the data through.

Extensions In The Action Layer Since struts 2.1 allows the definition of multiple config-files, SAP introduced a new / cust omer / i pc-conf i g. xml f i l e.




September 2006 245

Customers may place their own action mappings there.Example:The customer replaces a tile in the application. In this tile he adds a hyperlink that requestsZ_Set Char act er i st i cVal ues. do.The action mapping for Z_Set Char act er i st i cVal ues. do can be done in / cust omer / i pc-conf i g. xml

In cases where the customers wants not only to add additional action flow, but to change the action flowdelivered from SAP, those changes i n / Web- i nf / i pc- conf i g. xml will be supported by the Netweaver Development Infrastructure. The NWDI will support merges of SAP’s corrections and your changes of thosefiles.

You will find an example for an extension in the action layer incom. cust omer . i sa. i pc. ui . j sp. act i on. Get I nst ancesAct i on. This action implements acustomerExit that shows all instance nodes of the instance tree expanded. The example how to change theaction flow is in i pc- conf i g. 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 requestattributes, the userSessionData or mbom.




September 2006 246

Create Customer Backend ObjectTo get additional data from a backend system and to use these data in the interactive configuration UI or inconjunction with IPC pricing functions you would need to either use the E-Commerce extension frameworktechniques like function call interception, calling additional function modules or you need to extend the clientobject layer.

The IPC Client object layer is not only used by the interactive configuration UI, but also by the E-Commercecatalog and the E-Commerce b2c shopping basket for price determination and interactive configuration .

The client object layer provides you analog to the E-Commerce backend layer with connection objects tobackend systems. Using these connections you may call virtually all remote function modules in the backendsystem. You are not limited to IPC function modules. Defining your own connections in XCM, you may callother RFC enabled systems as well.

As with UI Beans, a factory creates the client objects. Analog to the UIBeans you may register your ownIPCClientObjectFactory in / xcm/ cust omer / modi f i cat i on/ f act or y- conf i g. 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 Cust omer I PCCl i ent Obj ect Fact ory overwrites the factory method newConfiguration. Theclient object class com. cust omer . cl i ent . obj ect . Cust omer Def aul t Conf i gur at i on introduces anew method “checkAvailibility()”. This method is then used bycom. cust omer . i sa. i pc. ui . j sp. beans. Cust omer Conf i gUI Bean in method“get Avai l abi l i t yI mage( ) ” which in turn is used byi pc/ customer/ t i l es/ statusbar Wi t hAvai l i bi l i t yCheck. j sp. The private methodcal l ATPCheck 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 I PCCl i ent Obj ect Fact or y (in the example) Cust omer Cl i ent Obj ect Fact or y

2. Implement the factory method for the client object that you want to modify (in the examplenewConf i gur at i on)

3. Register your Cust omer Cl i ent Fact or y in t he cust omer / modi f i cat i on/ f act or y-conf i g. 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 exampleCust omer Def aul t Conf i gur at i on. checkAvai l abi l i t y

6. Use the method of your customer object in the corresponding UIBean or any action (in the exampleCust omerConf i gUI Bean)

You may also use IPC client objects as container for extension data. Client objects inherit from BOBase andprovide the methods addExtensi onData(…) , getExtensi onData( ) and r emoveExtensi onData( ) .You would typically use these methods in actions in order to transport your data to JSP pages. You mayacess these data on JSP pages with UI Bean. get Busi nessObj ect ( ) . get Extensi onData() .




September 2006 247

Figure 85 Handling extension data at client objects

SCE user functionsPlease 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 ECOStandard E-Commerce backend objects used by ECO CRM or ECO ERP provide different customer exits toexchange additional data between E-Commerce and the IPC for pricing, configuration or creating the IPCbasket (only ECO CRM).

For details see Standard Backend Objects providing User Exits above. Examples see ’Extending ExistingBackend Objects’ in the ‘Development and Extension Guide: E-Comemrce 5.0 – Examples and Tutorials’(see [1] in chapter References on page 3).




September 2006 248

Extensions of the Document HandlingThis unit describes the UpdateDocumentView Module used to manage the behavior of the user interface

with respect to the display of documents.

OverviewIn the B2B application you can have up to two active documents (documents having a tab strip in thedocuments frame, and technically with corresponding objects in the business layer); an document you canedit, and a document you cannot edit. Additionally, a catalog page can be displayed. This complexconstellation raises some questions:

Which document should be displayed, if the catalog is closed?

What should be displayed, if a document is closed?

What should be displayed, if the user presses refresh on the browser?

To solve these problems we have introduced an object, which knows the status of the graphical user interface (GUI), the DocumentHandler . Together with some other objects and actions they form theUpdat eDocument Vi ewmodule.

The Updat eDocument Vi ew module is responsible for representing the following frames:

f orm_i nputThis is the working area. The documents and the catalog are displayed here.

document sDisplays the tab strips of the documents.

_hi st or yDisplays a list (history) of the last used documents.

Often these frames must be updated together. For example, if a document is opened, it will be displayed inthe f orm_i nput frame. A corresponding tab strip is displayed in the document s frame, and the documentmust be set at the beginning of the history.

ImplementationThe diagram shows the main objects of the Updat eDocument Vi ewmodule:




September 2006 249

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 thecatalog, a document, or a default page must be displayed. There is only one Document Handl er 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 historyneed additional information, for example the text which is displayed on the tab strip and in the history. Thisinformation is stored in a ManagedDocument object. Additionally, a ManagedDocument holds a referenceto the corresponding business object, for example, a reference to the Basket.

The Document Handl er manages ManagedDocument s. For this, it is generic. You can add new types of documents in the business layer, without modifying the Updat eDocument Vi ewmodule.

The UpdateDocumentViewAction is responsible for updating the f orm_i nput , the document s, and the _hi st or y frame.

Since it is an Action, it must return a string for the forward mapping. The diagram shows the activities of thei saPer f or m( ) method of the Updat eDocumentVi ewAct i on.

September 2006 250

Figure 87: Activities of the isaPerform() method of the UpdateDocumentViewAction

The forward strings of the UpdateDocumentVi ewAct i on are mapped to special JSPs (Refresher JSPs) inthe file conf i g. xml (see <act i on pat h=‘ / b2b/ updat edocument vi ew’ ...>). The file name of aRefresher JSP always has the prefix r ef r esher _ . A Refresher JSP loads with JavaScript functions thedocument s, _hi st or y, and f orm_i nput frame. The necessary Actions and JSPs are coded in ther ef r esher JSP. Because of this, each document type needs its own r ef r esher JSP.

Example

This example shows the creation of a new order. (ISA B2B).




September 2006 251

Figure 88: Creation of a new order. (ISA B2B)

The user enters the welcome page and selects Create a new basket. The Cr eateBasket Act i on is called.It performs certain preparation actions, for example, creates a new Basket object, error handling, andcreates a new ManagedDocument for the basket.




September 2006 252

Updat eDocument Vi ewAct i on is called. It asks the Document Handl er what should be displayed andgets the ManagedDocument for the basket. It reads from the ManagedDocument thatr ef r esh_basket . j sp should be loaded.

The r ef r esh_basket . j sp calls Wor kAr eaNavAct i on to update the document s frame (tab strips),and UpdateHi st or yAct i on to update the _hi st ory frame. This should be performed in every refresher

JSP. Finally, it loads the f r ameset _order . j sp into the f orm_i nput frame. This is document-specific.

The f r ameset _order . j sp calls the ShowBasket Act i on for the posi t i ons frame. This framedisplays header information and all positions of the basket. The ShowBasket Act i on reads all necessaryinformation from the Basket object and puts it in the request context. The order. j sp will display it. Thef r ameset _order . j sp also loads the det ai l s and the cl oser _det ai l s frame.

Integrating own documentsThere are two phases which must be considered when integrating new documents; prepare and display. Theprepare phase is passed if a new document is created or opened. The display phase is passed if the

document is displayed. For a specific document, normally the prepare phase is passed only once, while thedisplay phase is passed more than once, for example if the user selects the browser refresh-button.

Figure 89: Display a new Document type with the UpdateDocumentView Module

September 2006 253

When integrating a new document, the following steps are necessary:

1. Write an action for the prepare phase. In this case, Pr epar eNewDocAct i on.

2. Write the refresher JSP. In this case, r ef r esh_newdoc. j sp.

3. Write an Action for the display phase. In this case, Di spl ayNewDocAct i on.

4. Write a JSP which displays the new document. In this case, newdoc. j sp.

Only Pr epar eNewDocAct i on and r ef r esh_newdoc. j sp wi l l be descr i bed bel ow, because theother actions are not relevant for the Updat eDocumentVi ew module.

PrepareNewDocAction

The action for the prepare phase (Pr epar eNewDocAct i on):

Must create a new, or use an available business object, for example, by asking the BOM for it. Thisobject must implement the interface DocumentState.

Must create a new ManagedDocument object.

Must hand over this object to the Document Handl er .

Creating a ManagedDocument

A ManagedDocument is created by calling its constructor with the following parameters:

DocumentState docReference to the corresponding business object.

String docTypeType of the document, for example, order, quotation, contract. The document type is displayed 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, andtwodocnav.jsp). You have to add an entry in your project specific XLF file ( see chapter “Changinglanguage dependand resource keys” for more details) .

String docNumber docNumber is a unique string, automatically assigned by the backend for every document. It isdisplayed on the tab strip for the document and in the history list. If docNumber is equal to ‘new’,then the value of b2b.docnav.new from your project specific XLF file ( see chapter “Changinglanguage dependand resource keys” for more details) is displayed instead. docNumber may be null.

String refNumber, refNamerefNumber and refName are the number and name which can be assigned by the customer for 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 docDatedocDate 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 forwardThis string is used by Updat eDocument Vi ewAct i on for the forward mapping. In the fileconf i g. xml a path must be assigned for this string. The corresponding tag is <act i onpat h=‘ / b2b/ updat edocument vi ew’ . . . >.If forward is null then the Document Handl er will directly hand over the ManagedDocument to thehistory list. It is not managed by the Document Handl er and so it will not be displayed. This meansyou have a way of adding entries to the history without displaying it.




September 2006 254

String href, hrefParameter

These strings are used by hi story. j sp. Every entry in the history is a link to a document. Withhref and hrefParameter the anchor of the link is built, hr ef +’ ?’ +href Par ameter . The result mustbe the action with the parameters for displaying the wanted document.If href is null, the document is not added to the history. So there is a way for displaying documentswithout adding themto the history. If hrefParameter is null, then no '?' is generated behind href .

Example

The business object is or der St at usDet ai l .(See JavaDoc for Document Handl er , DocumentSt at e and ManagedDocument .)

Get the Document Handl er object from the session context.

The state of the document is set. It must be Document St at e. VI EW_DOCUMENT or Document St at e. TARGET_DOCUMENT. If the state is not set to one of these, then the document cannot beadded to the Document Handl er .

The ManagedDocument is created.

The ManagedDocument is handed over to the Document Handl er .

The Document Handl er is told, that the document order St at usDet ai l (the corresponding businessobject to the new ManagedDocument ) should be on top of th other document. But this does not remove thecatalog if it is displayed. To remove the catalog, youmust add the additional line:

document Handl er. set Catal ogOnTop( f al se) ;

document Handl er. set OnTop( orderSt atusDetai l ) ;

documentHandl er . add( mDoc) ;

ManagedDocument mDoc = new ManagedDocument ( or der St at usDet ai l ,

header Sal esDoc. getDocumentType( ) , headerSal esDoc. get Sal esDocNumber ( ) ,

headerSal esDoc. get Pur chaseOr derExt ( ) ,

headerSal esDoc. getDescri pt i on( ) ,

headerSal esDoc. get ChangedAt ( ) ,

‘ or der_st at us’ ,

href_acti on,

hr ef _par ameter) ;

or der Stat usDetai l . set State( Document Stat e. VI EW_DOCUMENT) ;

DocumentHandl er documentHandl er =

( DocumentHandl er ) userSessi onDat a. getAt t r i but e( Sess i onConst . DOCUMENT_HANDLER) ;

St r i ng hr ef _act i on = ‘ b2b/ document st atusdetai l pr epare. do’ ;

St r i ng hr ef _par ameter = ( ‘ t echkey=‘ . concat ( document Key. getI dAsSt r i ng( ) ) ) . concat( ‘ &’ ) ;

September 2006 255

PrepareNewDocAction

The refresh JSP loads the document s frame, which displays the tab strips of the documents, the _hi st or y frame, which displays the history list, and the f orm_i nput frame, which displays thedocument. The JSP should contain the following lines:

In the first script block, the JavaScript f r ames. j s is loaded. It provides, amongst others, the functions:

document s( ) , which returns the address of the document s frame.

get Hi st or yFr ame( ) , which returns the address of the _hi st or y frame.

f or m_i nput ( ) , which returns the address of the f orm_i nput frame.

In the second script block, the frames are loaded. In the bold faced line, the f orm_i nput frame is loaded. Itloads the action, which is mapped to the path / b2b/ di spl aynewdoc in the file conf i g. xml . In this

example it should be the action Di spl ayNewDocAct i on. If your document consists of a frameset withseveral 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 flowis different). They load the WorkareaNavAct i on and the UpdateHi st or yAct i on, which are configuredin conf i g. xml .

<head>

<scr i pt sr c=‘ <%=WebUt i l . getMi meURL( pageCont ext , ‘ b2b/ j scr i pt / f r ames. j s’ ) %>‘

type=‘ t ext / j avascri pt ’ >

</ scri pt >

<scri pt t ype=‘ t ext/ j avascri pt ’ >

<% i f ( ! r ef r esh) { %>

document s( ) . l ocat i on. href = ' ' ;

get Hi st oryFr ame( ) . l ocat i on. href =' ' ;

<% } %>

form_input().location.href = '<isa:webappsURL name=‘/b2b/displaynewdoc.do’/>';

</ scri pt >

</ head>




September 2006 256

Structure of the Internet Sales applicationBefore an Internet Sales application can be extended it is necessary to know how it is structured. This unitgives an overview of the structure of the application. After reading this unit you should be able to identify thelocation of the major components of the Internet Sales application.

Enterprise Application Archive (ear file)

The Internet Sales application is delivered as an Enterprise Application Archive (EAR). An EAR is a JAR(zip) file containing all components of an enterprise application. The most important part of the EAR file is theInternet Sales web archive (WAR) file.

Web Archive (war f ile)

The web archive file is a JAR (zip) file containing all parts of the Internet Sales application. The followingtable gives an overview of the content of the archive.

Directory within the war fi le Description

auct i onb2bcat al ogecal li pcMet a- i nf mi mes

User interface components (for example, JSPs, Mimes, …).

The folder names are Internet Sales application specific.

Admi n JSPs of Internet Sales administration pages and the XCMAdministrator tool. Every Internet Sales application (e.g. B2B, B2C,etc.) has this folder.

Access to the administration pages must be restricted.See note 646140 for further information .

WEB- I NF Contains configuration files not accessible using HTTP.

WEB- I NF\ cf g SAP Internet Sales application specific configuration files (e.g.logging, catalog).

WEB- I NF\ cf g\ ci c Customer Interaction Center (CIC) specific settings for the SAPInternet Sales application.

WEB- I NF\ cl asses Internet Sales resource files contain language dependent texts usedwithin the application.

WEB- I NF\ doc Legal statements regarding the usage of third party products.

Application version information (Ver si on. t xt ).

WEB- I NF\ l i b SAP Internet Sales application specific libraries (e.g. Struts, core.jar,…).

WEB- I NF\ t l ds Descriptors for custom JSP tags.

Table 75: Overview of the content of the web archive




September 2006 257

Directory within the war fi le Description

WEB- I NF\ xcm Configuration files managed by the Extended ConfigurationManagement (XCM).

WEB- I NF\ xcm\ sap These configuration files contain default application configuration andmust not be changed by the customer.

WEB- I NF\ xcm\ cust omer These configuration files are used to adjust the default application-configuration to customer needs.

WEB-I NF\ xcm\ cust omer\ conf i gurat i on

This folder contains configuration files used for common configurationsettings. These settings are done using the XCM Administrator.

Files in this folder should never be changed manually, only usingXCM Administrator.

The files in this folder usually do not contain the actualsettings. The files in this folder are copied to a folder placed outside the SAP J2EE Engine installation directoryduring initial deployment.

WEB-I ND\ xcm\ cust omer \ modif i cat i on

This folder contains files used to change less common settings. Thesefiles are usually touched when extending functions of the webapplication. SAP delivered default settings are changed manuallyusing XCM extension mechanism.

Table 76: 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 theweb archive.

Folder Description

WEB- I NF\ web. xml Deployment descriptor of Web application.

Most settings in this file are related to the Servlet Runtime:

Session timeout

Declaration of custom tags

In contrast to previous versions of Internet Sales, thereare only a few application related parameters in this file.Most of the application specific parameters are managedby XCM.

WEB- I NF\ conf i g. xml Configuration of the Struts Interaction Layer .

This file should be modified if you perform changes in the process flowof the application.

WEB-I NF\ xcm\ cust omer \ modif i cat i on\ bom-conf i g. xml

The settings in this file are related to the Business Object Layer.

This file should be modified if you want to use your own customBusiness Object Manager.

Table 77:Overview of configuration files




September 2006 258

Folder Description

WEB-I NF\ xcm\ cust omer \ modif i cat i on\ eai -conf i g. xml

Central file for configuration of the BLS layer. You usually do notchange this file. You only need to change it if you are using JCofunction execution cache.

See chapter 'JCo Function Cache' on page 3

WEB-I NF\ xcm\ cust omer \ modif i cat i on\ i ni t -conf i g. 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 availableinitialization handlers.

See chapter 'Initialization Handler' on page 3

WEB-I NF\ xcm\ cust omer \ modif i cat i on\ cache-conf i g. xml

Configuration for application caches. You can change settings of existing caches or register your own caches.

See chapter 'All purpose Cache' on page 3

WEB-I NF\ xcm\ cust omer \ modif i cat i on\modi f i cat i on-conf i g. xml

File used to register function module execution listeners, turning onABAP debugging, enabling JCo function tracing and register customfunction modules

See chapter 'Interception of Calls to Standard Function Modules' onpage 3

See chapter 'ABAP Debugging' on page 3

See chapter 'Tracing Function Modules' on page 3

See chapter 'Replacing Calls to Standard Function Modules (BackendSystem)' on page 3

WEB- I NF\ cf g\ l og-

conf i g. pr oper t i es

Starting from ISA SP07 this file replaces the previously used l og-

conf i g. xml configuration file.

The settings in this file configure the logging and tracing capabilitiesof the ISA application. You make changes in this file if you want tochange the logging/tracing settings.

TODO: See chapter ‘Generic Search Framework’ on page 3.

Table 78:Overview of configuration files

September 2006 259

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 Commentcom. sap. i sa Root for all classes in the ISA application.

. <NameAppl i cat i on> Subproject, for example catalog, cic,eauction.

. <NameAppl i cat i on>. act i on Struts Actions.

. <NameAppl i cat i on>. act i onf orm Struts actionsforms.

. busi nessobj ect . user . busi nessobj ect . basket

. busi nessobj ect . or der

Packages for business objects.

. backend. cr m

. backend. r 3

. backend. i pc

Packages for backend-specificimplementation of the business objects.

. core Core ISA functionality (no applicationlogic).

. i sacoreCore application logic functionality.

Table 79: Overview of the package structure of E-Commerce

September 2006 260

Conventions when Enhancing the E-Commerce ApplicationThe following chapter gives recommended conventions for enhancing the E-Commerce application.

Separation of SAP-Software / Customer ExtensionsIt is necessary to strictly distinguish between the components delivered by SAP and extensions made by thecustomer.

Changes can only be made by integrating new Java code into the existing application framework. Applicationlogic extensions should be placed in customer-specific Java packages. For example, Java-side businesslogic of Internet Sales is located in the com. sap. i sa. busi nesobj ect package. If the name of thecustomer is ACME, the customer should place his business objects in the

com. acme. i sa. busi nessobj ect package.

The following unit gives you information on recommended conventions for customer extensions.

Naming ConventionsAll extensions made by the customer should follow naming conventions that are described in the followingunits.

Java Server Pages

The following table gives you information about some naming conventions recommended when working withJSPs.

Type of Modification Naming convention

All additional elements in JSP (for example: inputfield)

z_<name> or Z_<Name>

Example: z_extendedBasket Header I nc

Adding a customer written JSP z_<name>. j sp of J SP or Z_<name>. j sp

Table 80: Naming conventions for JSPs

Changes in conf ig.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

September 2006 261

The conf i g. xml for this process flow is as follows:

Example:

This process flow is interfered by introducing a customer written Cust omAct i on.

Figure 91: Changed flow of actions

<act i on pat h=‘ / f i r st act i on’

t ype=‘ com. sap. i sa. acti on. Fi rst Acti on’ >

<f orward name=‘ success’ path=‘ / secondact i on. do’ / >

</ acti on>

<! - - or i gi nal pat h modi f i ed - - >

<act i on pat h=‘ / Z_secondaction’

t ype=‘ com. sap. i sa. acti on. SecondAct i on’ >

<f orward name=‘ success’ path=‘ / t hi r dacti on. do’ / >

</ acti on>

<!- - customact i on - - >

<act i on path=‘ /secondaction’

t ype=‘ com. acme. i sa. act i on. Z_Cust omAct i on’ >

<f or ward name=‘ success’ pat h=‘ / Z_secondaction. do’ / >

</ acti on>

<act i on path=‘ / f i r st act i on’

t ype=‘ com. sap. i sa. acti on. Fi r stActi on’ >

<f orward name=‘ success’ path=‘ / secondact i on. do’ / >

</ act i on>

<act i on path=‘ / secondact i on’

t ype=‘ com. sap. i sa. acti on. SecondAct i on’ >

<f orward name=‘ success’ path=‘ / t hi r dact i on. do’ / >

</ act i on>

September 2006 262

The original path /secondact i on. do is used to route the flow to Z_Cust omAct i on. WhenZ_Cust omAct i on has finished, the flow continues with SecondAct i on. Since the original path/ secondact i on. do is used by Z_Cust omAct i on, the path of SecondAct i on has to be changed.

The naming convention for the original path is: Z_<name of ori gi nal pat h>

If you have a chain of custom Actions (more than one), use the following naming convention:

Z_<number st ar t i ng wi t h 2>_<name of or i gi nal pat h>

Example:

/ Z_secondact i on, / Z_2_t hi r dact i on, / Z_3_f our t hact i on

The advantages of this naming convention are

Customer changes are easily distinguished.

It works well when original flow is intercepted by multiple custom Actions.

Some Actions are triggered by JSPs (e.g frame-sets) but it is not recommended to change JSPsin order to call custom Actions. For interfering the process it is recommended to limit changes tothe conf i g. xml file only.

Changes in bom-config.xml

When you write a Business Object Manager you have to register it in the bom- conf i g. xml file.

When you name your Business Objects Managers please use the following naming convention:

Type of Extension Naming Convention

Name of Business ObjectManager in bom- conf i g. xml Z_<name>- BOMexample:

Z_CUSTOM- BOM

Accessing name of new BusinessObject Manager from an Action

Place a constant containing the above name in the class of thenew BOM.

exampl e:

publ i c cl ass Z_Cust omBusi nessObj ect Manager

extends Busi nessObj ect ManagerBase

i mpl ement s BOManager , BackendAwar e{

publ i c stat i c f i nal St r i ng CUSTOM_BOM = ‘ Z_CUSTOM- BOM’ ;

Table 81: Naming conventions for Business Object Managers

September 2006 263

Example

The following example shows how these naming conventions work together:

Entry in bom-config.xml:

Definition of constant:

Acc essing 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 inthe delivered E-Commerce source code are not allowed.

. . .

/ / get user sessi on data obj ect

User Sessi onData userSessi onData =

UserSessi onData. getUserSessi onData( r equest. getSessi on( ) ) ; / / get t t i ng cust omBOM

Z_Cust omBusi nessObj ect Manager myBOM =

( Z_Cust omBusi nessObj ect Manager ) userSessi onData.

get BOM( Z_Cust omBusi nessObj ect Manager . CUSTOM_BOM) ;

publ i c c l ass Z_Cust omBusi nessObj ect Manager

ext ends Busi nessObj ect Manager Base

i mpl ement s BOManager , BackendAwar e {

publ i c st at i c f i nal Str i ng CUSTOM_BOM = ‘ Z_CUSTOM- BOM’ ;

. . .

}

<Busi nessObj ect Manager

name=‘ Z_CUSTOM- BOM’

cl assName=‘ com. acme. i sa. busi nessobj ect . Z_Cust omBusi nessObj ect Manager ’ / >

September 2006 264

Packages

When Java classes are written they should be put in packages using the following naming conventions:

Type of Java Code Name of PackageActions com. <name of your company>. i sa. act i on

Exampl e: com. acme. i sa. act i on

Business Objects com. <name of yourcompany>. i sa. busi nessobj ect

Exampl e: com. acme. i sa. busi nessobj ect

Backend Object Interfaces com. <name of yourcompany>. i sa. backend. boi

Exampl e: com. acme. i sa. backend. boi

Implementation of Backend Objects com. <name of yourcompany>. i sa. backend. <t ype of backend>

cur r ent backend- t ypes are: <cr m>,

Exampl e: com. acme. i sa. backend. cr m

Table 82: 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_<Ar bi t r ary name>Act i on for self written classes

Z_<Or i gi nal Act i on name>Act i onwhen deriving from existing ECO actions

Business Objects Z_<Name of BO e. g. Basket >for self-written classes

Z_<Or i gi nal Busi ness Obj ectname> when deriving from existing ECO

business objectsThe name of a business object should be a noun.

Do not use BO or Busi nessObj ect in the nameof the business object.

Exampl e:com. acme. i sa. busi nessobj ect . Z_Basket

Table 83: Naming conventions for Java classes

September 2006 265

Type of Java Code Naming conventions

Business Object Manager Z_<Name of BOM e. g.Cust omBusi nessObj ect Manager >for

self-written classes Z_<Or i gi nal BOM name> when

deriving from a existing ECO BusinessObject Manager

Exampl e:com. acme. i sa. busi nessobj ect . Z_Busi nessObj ect Manager

Backend Object Interfaces Z_<Name of Busi nessObj ect >Backend for self written classes

Z_<Or i gi nal Backend Obj ecti nterf ace name> when deriving fromexisting ECO business objects

Example:com. acme. i sa. backend. cr m. Z_Or der CRM

Implementation of Backend Objects Z_<name of Busi nessObj ect ><t ype of backend i nupper case>

Z_<Or i gi nal Backend Obj ecti mpement at i on name>

Exampl e:com. acme. i sa. backend. cr m. Z_Cust omBask

et CRM, this class provides additional basketfunctionality but does not derive from the CRMspecific ECO basket.

Table 84: 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. set t i ngs=My Set t i ngs

after changing:

acme. b2b. header . z_set t i ngs=Myper sonal Set t i ngs

Table 85: : Naming conventions for resource files

September 2006 266

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. di spl ay. z_extheader data_i nc

Table 86: : Naming conventions for resource files

Place all additional/changed keys at the end of the resource file. This makes it easier when you upgrade theapplication.

Changes in ConfigurationThe following chapter explains changes to the configuration using Extended Configuration Management(XCM).

Application Configuration and ComponentConfigurationApplication configuration and component configuration can be created and maintained using the XCMAdministrator tool. A detailed description can be found in the XCM Administrator tutorial which is part of themySAP CRM Java Installation Guide (see [1])

Common Configuration ChangesThis section details how you make common configuration changes to the settings in i ni t - conf i g. xml or backendobj ect - conf i g. xml . These changes cannot be made using the XCM Administration tool. Youcan, of course, use the same extension mechanism in other configuration files, but changes to these two filesare the most common.

Changes in init -config.xmlThe following example is taken from Internet Sales 5.0 B2C, to change the catalog cache settings.

In the SAP version of WEB- I NF\ xcm\ sap\ modi f i cat i on\ i ni t - conf i g. xml the following i ni t -handl er is responsible for initializing the catalog cache:



<param name=‘ expi r at i on’ val ue=‘ 24’ / >

<! - - t i me i n hour s - - >

<par am name=‘ r emoval ’ val ue=‘ 48’ / >

September 2006 267

You want to change the value of the removal attribute from 48 to 4711. You make the changes in thecustomer version of i ni t - conf i g. xml located in the folder:

<web appl i cat i on>\ WEB- I NF\ xcm\ cust omer\ modi f i cat i on.

Example:

Add the following code after the xi : i ncl ude XML element:

In this example you are extending the catalog cache i ni t - handl er . You only need to provide theparameter you wish to change (removal), all others are inherited (for example, expiration).

Changes in backendobject-config.xml

You use this file to register backend objects in the Business Logic Service Layer (BLS). In previous releasesthe file eai - conf i g. xml was used for registering Backend Objects.

Changing existing Backend Object

If you need to change configuration for existing backend objects, and there is no appropriate switch in theXCM Administrator, you need to carry out the changes manually, using XCM extension mechanism. Allcustomer changes must be done in WEB- I NF\ xcm\ customer\ modi f i cat i on\ backendobj ect -

conf i g. xml .

The following example illustrates how to change a setting in the Pr i ceCal c Backend Object (example istaken from Internet Sales B2C).

You have to derive your changes from the base backend object, located in

WEB- I NF\ xcm\ sap\ modi f i cat i on\ backendobj ect - conf i g. xml :

<conf i g i d=‘ cr mdefaul t ’ >

<busi nessObj ect t ype=‘ Pri ceCal c’ name=‘ CatPri ceCal c’

cl assName=‘ com. sap. i sa. backend. cr m. webcatal og. pr i ci ng. Pri ceCal cul ator CRMI PC’


def aul t Connect i onName=‘ I SAStat el ess’ >

<par ams>

<param name=‘ pr i ceTypes’ val ue=‘ t otal Gr ossVal ue’ / >

<! - - f or al l owed val ues see def i ned const ant s i n

com. sap. i sa. backend. boi . webcat al og. pr i ci ng. Pr i ceType - - >

</ par ams>


</ conf i g>



<par am name=‘ r emoval ’ val ue=‘ 4711’ / >

September 2006 268

To change the value of pr i ceTypes from t ot al Gr ossVal ue to netVal ueWi t hout Fr ei ght , carry outthe following steps:

1. Locate the backend object Pr i ceCal c in SAP configuration using the i d=' cr mdef aul t ' .

2. Extend this configuration using i sa: ext ends=‘ . . / conf i g[ @i d=' crmdef aul t ' ‘ . In doing this youderive the complete base configuration cr mdef aul t .

3. Make a note of the backend object you need to change. Please note, you only have to write down thoseyou are changing (in this case, pr i ceTypes), and not all attributes (for example, name, cl assName).You need the backend object attribute 'type', because this is the key identifying the backend object. Youneed it to tell XCM which backend object you are extending.

The following coding in the customer version of backendobj ect - conf i g. xml is placed after thexi : i ncl ude:

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 backendobj ect - conf i g. xml . Perform thefollowing step. (Example taken from ISA B2C)

You can always extend the base configuration cr mdef aul t when registering your object. (even if you useECO ERP).The reasons is that this is the base configuration for all other configurations.

<! - - t he crmdefaul t conf i gur ati on can be al ways be extended f or sel f wr i t t en backend obj ects

- - >

<conf i g i sa: ext ends=‘ . . / conf i g[ @i d=' crmdef aul t ' ‘ >

<! - - r egi st er your backend obj ects here - - >

<busi nessObj ect t ype=‘ Z_Cust om’ name=‘ z_cust om’

cl assName=‘ com. acme. i sa. backend. cr m. Z_Cust om’

connect i onFact oryName=‘ J CO’ def aul t Connect i onName=‘ I SAStat el ess’ >

<par ams> <param name=‘ myPar am’ val ue=‘ myVal ue’ / >

</ par ams>


</ conf i g>

<conf i g i sa: ext ends=‘ . . / conf i g[ @i d=' crmdef aul t ' ‘ >

<busi nessObj ect t ype=‘ Pri ceCal c’ >

<par ams>

<param name=‘ pr i ceTypes’ val ue=‘ netVal ueWi t hout Fr ei ght’ / >

</ par ams>


</ conf i g>




September 2006 269

Extending XCM with Customer SettingsIf you extend the application and would like to make your extensions configurable, you can extend the XCMconfiguration tool with your own settings.

There are two types of information you have to provide when adding new parameters to XCM:

1. The new parameter with a name and default value.

2. Meta data of the new parameter like description, allowed values etc.

What to Do

The first step consists of adding the name (myParam) and the default value (defaultValue) of the newparameter and the name of the component (project) the parameter is assigned to. In addition to that youhave to provide meta data like the descirption (custom parameter) and the type of the parameter (text).

After adding the new parameter you will be able to configure it using the XCM Admin tool as shown in thefollowing figure:

Figure 92: Adding and configuring new parameter (XCM)

September 2006 270

Adding Parameter Name and default Value

The XML file used for storing the name/value of parameters is stored in the DB. You have therefor first to download it from the Database

o Open the XCM tool (e.g. b2b/admin/xcm/init.do)

o Select 'XCM Settings' in the tree

o Click the ' Component configuration data download' button

o Store the file you have downloaded in the file system

In this step you have to add the component name the paramter name and the default value of theparamter.

Make a backup of this file before doing any changes in case you need to restrore the original file

The naming rule for the config id is is always: <component id>config e.g. projectconfig.

In the next step you have to add metdata of the paramter like descrition and type

o Open t he f i l e xcm\ cust omer \ modi f i cat i on\ xcmadmi n- conf i g. xml

Add the metadata like shown in the following example:

<?xml vers i on="1. 0" encodi ng="UTF- 8"?>

<xcmadmi n>

<component met adat a>

<component i d=" project" short t ext="Proj ect speci f i c set t i ng" scope="appl i cat i on">

<l ongt ext >Detai l ed overvi ew on par ameters conf i gur ed her e</ l ongt ext > <par ams>

<par am name=" myParam " t ype="t ext " short t ext ="cust ompar ameter "/ >

</ par ams>

</ component>

</ componentmet adat a>

<scenar i omet adat a>

<! - - add addi t i onal scenari ometadata here - - >

</ scenar i omet adata>

</ xcmadmi n>

<component i d=" project">

<conf i gs>

<conf i g i d=" projectconfig">

<par ams i d="def aul t ">

<par am name=" myParam " val ue="defaultValue" / >

</ par ams>

</ conf i g>

</ conf i gs>

</ component>




September 2006 271

You have to restart the application in order to activate the setting

In the last step you have to upload the conf i g- data. xml file back to the database:

o Start the XCM and select XCM Settings

o Click the 'Edit' button

o Select the path of your modified config-data file in the 'Path to component configuration data'entry field

By uploading the file manually you overwrite the DB content of this file. Make sure that the XMLfile is valid and well formed before uploading it to DB. Uploading invalid files can cause theapplication to not start or work properly.

o Press the upload button

After uploading the file you should be able to see/changfe the new parameter in the XCM UI.

Adding Meta data of XCM parameters

This paragraph gives some information on how adding component meta data.

The component XML element has the following attributes:


i d The id of the component. Used to identify the component. yes

shorttext One sentence describing what this component is good for. This will beused in a summary table giving the customer an overview on theavailable components.

yes

t estcl ass This class is used to test the component configuration. This can bedone in the XCM Admin by the user during configuration (e.g. testingconnection to SAP system using JCO). The test class has toimplement the interfacecom. sapmarket s. i sa. core. t est . Component Test

No

l ongt ext Provide a detailed description of the component.

What is the component good for?

yes

scope The scope of the component. Either appl i cat i on or sessi on. If thisattribute is omitted the default value is 'sessi on'

It is recommended to only use the 'application'scope in customer projects

no

status value 'obsol et e’ . This attribute indicates that a component isobsolete and should not be used any longer. An obsolete componentis marked with an icon in the tree. You should update the short/longtext and describe the consequences of the deprecation

See [5] Chapter Changing XCM Parameters for rules when changingconfiguration parameters

no

Table 87: Adding Meta data of XCM parameters

September 2006 272

A component is configured using parameters. Each parameter should have a one sentence long shorttextgiving information what the parameter is good for. It can also have a longtext with detailed information aboutthe parameter.

There are two types of parameter values: text and singleselect . text is used to for any kind of text,singleselect is represented by a dropdown-listbox giving the user a limited number of choices.

The screenshot below shows where the parameter shorttexts are shown. If there is a test class registered,the test can be executed using the 'run test' button. You can see entry fields of type text (e.g. mail.smtp.port)as well as one entry field of type singleselect (securemode)

Figure 93: XCM - parameter shorttexts

Example:

Example of text type:

<par am t ype="t ext " name="myParam" shor t t ext ="myVal ue" / >

September 2006 273

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 printablesummary of component parameters.

If one sentence is enough to describe the meaning of theparameter then this is sufficient

yes

conver si oncl ass A class used to convert the value. This can be used to convertthe value before it is stored. The class has to implementcom. sapmarket s. i sa. core. xcm. admi n. conv.Par amConvert er

no

l ongt ext If the parameter is of type text you can provide additionalinformation here helping the customer to maintain this parameter correctly

no

t ype Either text or singleselect . In case of single select you have to

define the allowed values

yes

St at us New in 5.0: Allowed value 'obsol et e’ . This attribute indicatesthat a parameter is obsolete and should not be used any longer.An obsolete parameter is marked with yellow color int the table.The short text visible in the UI has the following format:OBSOLETE <shorttext>. Please describe in the long text theconsequences of the deprecation

See [5] Chapter Changing XCM Parameters for rules whenchanging configuration parameters

No

Table 88: Attributes of the param XML element

<param name="secur emode" t ype="si ngl esel ect "

shor t t ext ="Enabl es or di sabl es secur i t y r el at ed f eat ur es">

<l ongt ext >

When set t o t r ue, LWC f eat ur es r el eat ed t o secur i t y wi l l be di sabl ed. Act i veX cont r ol s

and document push are t he f eat ures whi ch pose t hreat t o secur i t y.

By def aul t , secur emode i s set t o t r ue.

</ l ongt ext >

<const r ai nt >

<allowedvalue val ue=" t r ue" shor t t ext ="secur emode i s t urned on" / >

<allowedvalue val ue="f al se" shor t t ext ="secur emode i s t ur ned of f "/ >

</ const r ai nt >

</ par am>




September 2006 274

Definition of a allowedvalue located in the body of the par amXML tag.


val ue The value of the parameter yes

shorttext One sentence describing what this parameter is good for.

This description is shown in the XCM Admin tool to givethe user an idea what the value is used for as well in aprintable summary of component parameters.

If one sentence is enough to describe the meaning of theparameter then this is sufficient

yes

l ongt ext More details about the value. no

Table 89: 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. i sa. cor e.Fr amewor kConf i gManager . XCM

Firstly get your the component configuration: Fr ameworkConf i gManager . XCM. get Appl i cat i onScopeConf i g( ) . get Component Conf i g( "pr oj ect " ,"pr oj ectconf i g")

The component configuration is of type com. sap. i sa. core. xcm. conf i g. Component Conf i g. Itprovides access methods for XCM parameters:get ParamConf i g( "def aul t " ) . get Pr oper t y( "myPar am") ;

Configuration of Dynamic fields in E-ServiceDynamic fields are fields that a customer can add to be included in the complaints and returns. They can bedefined on the following one-order structure: CUSTOMER_I, PRICING and PRODUCT_I. These dynamicfields 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 webapplication, then the dynamic-fields-config.xml file must be updated. The file under the root of the application…\ WEB- I NF\ xcm\ cust omer \ modi f i cat i on\ dynami c- f i el ds- conf i g. xml is the one that must bemodified. (The delivered standard file is placed under …\ WEB- I NF\ xcm\ sap\ modi f i cat i on\ dynami c-f i el ds- conf i g. xml and should not be changed.)

September 2006 275

Here is an example of the dynamic-fields-config.xml file:

Immediately below the statement <xi:include…>, you will have to define a property-group namedComplaintItemDynFieldsPG and define underneath it all the properties that you want to appear in the webapplication.

<mai ntenance- obj ect xml ns: i sa="com. sap. i sa. core. conf i g"

xml ns: xi ="ht t p: / / www. w3. org/ 2001/ XI ncl ude" >

<! - - cust omer changes i n dynami c- f i el ds- conf i g shoul d be done here by ext endi ng/ overwr i t i ng t he base conf i gur at i on - - >

<xi : i ncl ude hr ef ="${sap}/ modi f i cat i on/ dynami c- f i el ds-

conf i g. xml #xpoi nt er( backendobj ect/ conf i gs/ conf i g[ @i d=' ${backendt ype}' ] / *) "/ >

<proper t y- group name="Compl ai nt I t emDynFi el dsPG">

<pr oper t y name="DANG_TO_RETURN" t ype="sel ect box"

descri pt i on="esr v. cr b2b. cl . dyn. dang"

obj ect Type="CUSTOMER_I "

f i el dName="DANG_TO_RETURN">

<al l owedVal ue val ue="A" descri pt i on="esr v. cr b2b. cl . opt . scr " / >

<al l owedVal ue val ue="B" descri pt i on="esr v. cr b2b. cl . opt . mov" / > </ propert y>

<propert y name="CARRI ER_CLAI M" t ype="checkbox"

descri pt i on="esrv. crb2b. cl . dyn. car "


f i el dName="CARRI ER_CLAI M">

</ propert y>

<propert y name="HS_OF_PRI ME_QTY" t ype=" i nput "

descri pt i on="esrv. crb2b. cl . dyn. hsq"


f i el dName="HS_OF_PRI ME_QTY"

si ze="10">

</ propert y>

<propert y name="HS_OF_PRI ME_UNI T" t ype=" i nput "

descri pt i on="esrv. crb2b. cl . dyn. hsu"


f i el dName="HS_OF_PRI ME_UNI T"

hel pVal uesSearchName="Uni t Of Measure"

si ze="10">

</ propert y>

<propert y name="SCRAP_VALUE" t ype=" i nput "

descr i pti on="Scr apVal ue"

obj ect Type="PRI CI NG"

f i el dName="SCRAP_VALUE"

si ze="12">

</ propert y>

</ pr opert y- group>

</ mai ntenance- obj ect >

September 2006 276

Allowed attributes for tag <property>:

Attr ibute Remark

Name Name of the property.

The name must be unique within one screen group.

Type Defines the type of the search screen property:

input (= simple input field)

selectbox (= drop down list box)

checkbox (= simple checkbox)

Description The resource file key containing the field label that will be displayed on theweb application UI. This key must exist incrm~eservice~cr_b2b~resources.properties file.

objectType Database entity where this field can be found, either: CUSTOMER_I,

PRICING, or PRODUCT_I.fieldname the name of the field which must match the field in the backend system

Size The maximum length of this field on the web application UI

helpValuesMethod Identifies a help value method defined in file sap\modification\helpvalues-config.xml. Adding the name of an <helpValuesSearch> will bring up anbinocular beside of an input field.

Table 90: 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 optionto a <html> select box (e.g.

<select id…>

<option value=”value” …)

Description - The resource file key containing the value thatwill be displayed on the web application UI. Thiskey must exist incrm~eservice~cr_b2b~resources.properties file.

Hidden False Hide this value (not included on the <html> page)

Table 91: Allowed Attributes for the tag <allowedValue>




September 2006 277

Generic Search Framework

Main Components of the Generic search framework for E-Service Extended Complaints and Returns:

Component Application layer Specific or Sharedcomponent?

\appbase\genericsearch.jsp Web server Re-usefromInternetSales

\xcm\sap\modification\generic-searchbackend-config.xml Web server E-Servicespecific

com.sap.isa.ui.uiclass.genericsearch.GenericSearchBaseUI.java Web server Re-usefrom

InternetSales

com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory.java Web server Re-usefromInternetSales

com.sap.isa.isacore.action.GenericSearchBaseAction.java Web server Re-usefromInternetSales

com.sap.isa.isacore.action.GenericSearchSortAction.java Web server Re-usefrom

InternetSales

CRM_ISALES_SEARCH Application server (Dev.class)

Re-usefromInternetSales

CRM_ICSS_CR Application server

(Dev. class)

E-Servicespecific

CRM_ISA_GEN_DOCUMENT_SEL Application server (func. Mod)


CL_ISA_GEN_DOC_SEARCH_HELP Application server (class)


Table 92: Main Components of the generic search framework

Details of component “generi c- sear chbackend- conf i g. xml ”

Location: xcm \ sap \ modi f i cat i on \ gener i c- sear chbackend- conf i g. xml .

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




September 2006 278

BAdI Implementations in component “CRM_ICSS_CR”

Filter Value ABAP class Remark

CAMPAIGN CL_IM_CRM_ESRV_CAMPAIGN This implementation is exclusively used toselect marketing campaign elements.

COMPL CL_IM_CRM_ESRV_COMPLAINT This implementation is exclusively used toselect complaints.

COMPL_I CL_IM_CRM_ESRV_COMPLAINT_I This implementation is exclusively used toselect complaints. It returns items instead of header objects.

DELIVERY CL_IM_CRM_ESRV_DELIVERY This implementation is exclusively used toselect deliveries.

DELIVERY_I CL_IM_CRM_ESRV_DELIVERY_I This implementation is exclusively used toselect deliveries. It returns items instead 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 toselect returns.

RETURN_I CL_IM_CRM_ESRV_RETURN_I This implementation is exclusively used toselect returns. It returns items instead of header objects.

Table 93: BAdI Implementations in Component "CRM_ICSS_CR"

BAdI Implementations in component “CRM_ISALES_SEARCH” (Those BAdI implementations are re-usedfrom Internet Sales application).

Filter Value ABAP class Remark

BILLINGDOC CL_IM_CRM_ISA_GDS_BILLDOC This implementation is used to select billingdocuments.

BILLINGITM CL_IM_CRM_ISA_GDS_BILLDOCI This implementation is used to search for itemswithin CRM billing documents. It returns itemsinstead of header objects.

ORDER CL_IM_CRM_ISA_GDS_ORDER This implementation is exclusively used toselect order documents.

1O_ITEMS CL_IM_CRM_ISA_GDS_1O_ITEMS This implementation is used to search for itemswithin one sales document (1Order documents).It returns items instead of header objects.

Table 94: BAdI Implementations in Component “CRM_ISALES_SEARCH”

E-Service Extended Complaints and Returns specificimplementation of the Generic Search Framework

The section before gave a detailed overview of the different components of the Generic Search Framework.The components are designed to work in a generically way, independent from an application. This sectionnow focuses on the integration of the Generic Search Framework into the CRM E-Service Extended

Complaints and Returns.

September 2006 279

1. Known search definitions in E-Service Extended Complaints and Returns


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

SearchCriteria_B2B_Sales_OrderStatus_Items B2B To search for sales document items(used to find items in case largedocument handling is enabled)

SearchCriteria_B2B_Billing_BillingStatus_Items B2B To search for billing document items(used to find items in case large

document handling is enabled)

SearchCriteria_Delivery_Items B2B To search for delivery documentitems (used to find items in caselarge document handling is enabled)

SearchCriteria_B2B_Claim_Items B2B To search for claim document items(used to find items in case largedocument handling is enabled)

SearchCriteria_B2B_Return_Items B2B To search for return document items(used to find items in case largedocument handling is enabled)

SearchCriteria_RejectedItems B2B To search for complaints and returns

items which are in statusrejected

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

2. First search screen to come up in the B2B scenario on the left side of the application (Shuffler / Navigator).

In the E-Service Extended Complaints and Returns application, the navigator is always set to display thecomplaints and returns search (as opposed to reference documents search).

This is defined in the java class Eser vi ceSt ar t Appl i cat i onAct i on.

3. Dynamically disabling document types which are not allowed by user permissions.

All the search definition in the E-Service Extended Complaints and Returns application relate to a UI classcom. sap. eservi ce. cr b2b. ui cl ass. Gener i cSearchCr UI . This class makes sure that the user hassufficient authority to view each document types for either his company or a company in his hierarchy beforedisplaying the search criteria.

If you wish to override these conditions, it is possible to define your own UI class, extending the base oneand specifying it in the <scr een- gr oup> of the gener i c- sear chbackend- conf i g. xml .




September 2006 280

Checking configuration during runtimeAfter changing configuration in customer files you need to check your extension mechanism is workingproperly. The XCM processed configuration files only exist in the memory. You must therefore check theXCM processed files using XCM Administrator:

1. Change settings in customer version of configuration files.2. Restart web application.

3. Start the application with the XCM scenario (application configuration) you are using.

4. Access the XCM Administrator.

5. Press the button “monitoring” in the upper right corner. Select the configuration you are interested infrom the dropdown list box.

6. Open the runtime version of the configuration file you are interested in by clicking on the links.

7. Check if your change was processed correctly.

September 2006 281

Best Practices

Getting Information about the ApplicationThe following units give you hands-on information needed for performing extensions.

Getting Information about JSPs

Some applications (e.g. b2b) consist of many frames. After changing a JSP you can update thecorresponding page in the browser by placing the mouse pointer on a particular page, and

selecting Ref r esh 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 showmodul ename. cor e = t r ue.

This activates the feature permanently.

You can specify the following additional request parameter when invoking the application:showmodul ename=t r ue

This activates the feature for one session

Example

By starting the B2B application with the following URL:

ht t p: / / <host name>/ b2b/ b2b/ i ni t . do?showmodul ename=t r ue

You get the following screen showing the name of the JSP in the upper left corner:

September 2006 282

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 keyin the resource file.

Providing an additional request parameter in the URL activates this feature. Possible values are:

Request Parameter Description

t r ansl at e. show. key. onl y Value: <any value>The language independent resource key isdisplayed instead of the corresponding text.

t r ansl at e. show. key. concat Value: <any value>The language independent resource key as wellas text is displayed in the form:

<r esour ce key>: <t ext>

Table 96: Displaying text of keys




September 2006 283

Example

By starting the B2B application with the following URL:

http://localhost:50000/b2b/b2b/init.do?translate.show.key.concat=99You get the following screen:

Table 97: 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 confi g.xml File (or other Struts conf iguration files)

There is currently no tool support for analyzing the content of the conf i g. xml file. To analyze this file youshould be familiar with the Struts framework.

September 2006 284

Session TracingSession tracing enables you to write all trace entries of a user session to a separate file, in addition to thestandard log files. The log level used for this is always DEBUG, regardless of how the other logging settingsare. Session logging offers the following:

Tracing a client session

Debug log level (highest level of detail) independent of further logging settings. This function allows adetailed tracing in a production system, whereby it is not possible to raise the log level globally

The trace messages are written in the default trace files of the SAP Web AS Java, which are located in thedirectory <DRI VE>: \ usr \ sap\ <SI D>\ J C\ j 2ee\ cl ust er \ <SERVER>\ l og (e.g.c: \ usr\ sap\ C51\ J C10\ j 2ee\ cl ust er \ ser ver 0\ l og). There you’ll find the filesdef aul t Trace. <COUNTER>. t r c, 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 followingsteps:

Open the XCM UI by opening the following URL in the web browser:http: <host >: <port >/ <appl i cat i on>/ admi n/ xcm/ i ni t . do, where <HOST> ist the name of the host, your SAP Web AS Java is running on, and <PORT>is the http port of your SAP Web ASJava.

Open the application specific component in the XCM admin tree view: "General and ApplicationSettings/Customer/<APPLICATION>/<APPLICATION>config", where <APPLI CATI ON>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 tracingTo activate the session tracing in an E-Commerce application, proceed as described below:

The following procedure describes how to generate a session trace:

Remove unused DefaultTrace file in the log directories of your Web AS Java server node directories.

Start the application by opening this url: ht t p: <host >: <port >/ <appl i cat i on>

The application start page lists all application configurations you configured in the XCM and providesa "Single Session Trace" link for each of them. The application will start a web session based on theselected XCM application configuration. A second browser window will open where the session id

will be displayed.

September 2006 285

Replay the session to generate the application specific trace file content.

Open the Netweaver Administrator by opening the following URL ht t p: / / <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 tracesimport/export and table parameters. It is useful if you need to know which parameters were used when thefunction module was called. Additionally, you can decide whether you want to trace the function module

before it is called, or after it has been executed.

The function module trace is enabled in the file WEB-I NF/ xcm/ cust omer / modi f i cat i on/ modi f i cat i on- conf i g. xml

You should make sure that you do not trace sensitive data. If you have such data it is possible toomit tracing some of the parameters. For information on how to do this, please see thecomments in the file modi f i cat i on- conf i g. xml

Example:

For examples see comments in file modi f i cat i on- conf i g. xml




September 2006 286

Additional Request Parameters

General Request ParametersThe following table gives you an overview of HTTP request parameters which can be passed to theapplication, when it is started.


Aut oent r y Value: Rel3.1 = X, Rel4.0 = yes (X) | no;Comes with 3.1: Until SP03, parameter allowed to automaticallypass shoplist and sold-to party selection without any user action.First entry of the shoplist or sold-to party list had been selected. For

SP04 and higher, an error page will be presented if autoentry isused, but no shop is passed via URL parameter, and a sold-toselection is necessary.

For ward The page the Logi nAct i on should forward to.

hook_ur l URL for the outside page to return to Internet Sales.

Language Language to be used, for example, de, or en.

oci _ver si on Version of the oci-interface.

oppor t uni t y_i d Id of the auctions opportunity.

Passwor d The password of the logged on user.

Portal Value: yes| noTriggers visual modifications necessary for displaying the shop inthe portal. Also disables the display of billing documents.

scenar i o. 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:t heme. core. i sa. sap. com=wi nt er modfies the normale

search path / b2b_dev/ b2b/ mi mes/ i mages/ shopHeader. gi f to / b2b_dev/ winter/ b2b/ mi mes/ i mages/ shopHeader. gi f

User i d The ID of the logged on user.

Secure Possible value: on

This parameter is needed if you run the following infrastructure:

browser => HTTPS => Web Server => HTTP => J2EE Engine

Since the protocol between the web server and the SAP J2EEEngine is HTTP, the application is never accessed using HTTPS. Inorder to let the application know that HTTPS is used it should bestarted using the additional request parameter secure=on

Table 98: General Request Parameters

September 2006 287

ECO Version


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

Request parameters for B2CTo directly display the product details of a certain product, you can start the application with some extraparameters in the URL.

There are three parameters that should be in the request to display the details for a certain product. Theparameters are:


ar eaI D This parameter specifies the GUID for the areathat contains the product. This parameter can beobtained for a certain item (WebCatItem object)by calling item.getAreaID().

pr oduct I D This parameter specifies the product Id that isassociated with every product from the catalog bythe ISA B2C application. It can be obtained bycalling item.getItemID().

Shop This parameter is used to specify the shop thatcontains the desired product.

Table 99: 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 selectedshop area:




September 2006 288

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

r equest . set At t r i but e( ‘ Name’ , val ue) ;

Data is retrieved using (for example, in the JSP):

St r i ng dat a = ( St r i ng) r equest . get At t r i but e( ‘ Name’ ) ;




September 2006 289

Action Flow is Interrupted by a JSPIn this scenario a JSP (for example, frameset) interrupts the server-side Action flow.

In this case you have to interfere the Action flow after the JSP, by adding your own Action. In this Action youhave to retrieve the data from the Business Object layer and set it as a request attribute as described above.

Before

Figure 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 fromcom. sap. i sa. i sacor e. act i on. I saCor eBaseAct i on.

The Servlet concept for managing request parameters is based on strings and causes a lot of work whenconverting the data into other data types. This class is a wrapper around the request object and allows youto retrieve parameters of the right type and test them for valid values:

An additional feature is that you can use arrays in the context of form variables. You may, for example,group related variables together, or use this feature to retrieve values from a multiple select input:

Request Parser par ser = new Request Parser ( r equest ) ;

RequestParser. Par ameter pr i ce = parser . getPar ameter ( ‘ pr i ce’ ) ;

Request Parser . Paramet er name = par ser . get Par ameter ( ‘ name’ ) ;

i f ( pr i ce. i s Set ( ) ) {

i f (pr i ce. get Val ue( ) . i sDoubl e( )) {

doubl e d = pr i ce. getVal ue() . getDoubl e() ;

}

St r i ng n = name. getVal ue() . getSt r i ng( ) ;

}

September 2006 290

The data of this form contains two associative arrays ‘personal’ and ‘beer’. You can retrieve the data usingthis wrapper class in the following way:

Writing Thread Safe CodeInternet Sales is used by many concurrent users, at the same time, during runtime. You therefore have to becareful when writing customer extensions. This chapter gives you some hints:

Writing thread safe Actions

Refer to chapter 'Threads in Actions' on page 3

Writing Execution Event Listeners

There is only one instance of an event listener for each XCM configuration. It is therefore used bymany concurrent threads from different sessions. For further information, please see chapter 'Interception of Calls to Standard Function Modules' on page 3.

Request Parser par ser = new Request Parser ( r equest ) ;

RequestParser. Par ameter param = parser . getPar ameter ( ‘ personal [ ] ’ ) ;

i f ( param. i sSet () ) {

/ / gi ves you t he val ue of personal [ emai l ]

St r i ng emai l = par am. get Val ue( ‘ emai l ’ ) . getStr i ng( ) ;

St r i ng name = param. getVal ue( ‘ name’ ) . get Str i ng() ;

}

par am= par ser . getPar amet er( ‘ beer [ ] ’ ) ;

f or ( i nt i = 0; i < parm. get NumVal ues( ) ; i ++) { %>

param. get Val ue( i ) . get I nt ( ) ;

}

<f orm act i on=‘ arr ay. php’ method=‘ post ’ >

Name: 

Emai l : 

Beer : 

<sel ect mul t i pl e name=‘ beer [ ] ’ > <opti on val ue=‘ 122’ >War t hog

<opti on val ue=‘ 33’ >Gui nness

<opt i on val ue=‘ 7373’ >Stut t gar t er Schwabenbräu

</ sel ect >



</ f or m>

September 2006 291

Administration ConsoleThere are some administration pages which help you to administer the following technical aspects of theapplication:

Aplication Cache statistics

Catalog cache statistics

Application System Cache Statistics

Java Connector Pools

Java Connector Pools

pool name Name of the connection pool

max pool size The maximum number of connections to the SAPSystem that are required per pool up to that point in

time

max cons used The maximum number of connections to the SAPSystem that are required per pool up to that point intime

num current used cons The number of connections that are currentlyavailable in the pool

Table 100: Attributes of Java Connector Pool

The page displays all of the SAP Java connector pools, that are available on the applicationserver, and not just the pools of the Web application in which the administration page is.

Getting Application VersionSince the SAP Web Application Server Java provides a central web page, were the versions of all deployedcomponents are shown, the E-Commerce page has been removed. The version information was moved tohttp://<hostname>:<port>/sap/monitoring/ComponentInfo.

The following software components are contained in the SAP E-Commerce 5.0 solution:

- SAP-CRMAPP (not contained in ECOERP)

- SAP-CRMDIC

- SAP-SHRAPP

LoggingIn SAP E-Commerce 5.0, the E-Commerce logging was replaced with the standard logging of the SAP WebAS. For more information please refer to chapter Logging/Tracing on page 3.




September 2006 292

Updating Appl icationThis 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 J2EEadministration console.

Java files Restart application through SAP J2EEadministration console.

Table 101: Updating the application




September 2006 293

Web Diagrams

Syntax of Web Diagrams




September 2006 294

B2B - Start Page




September 2006 295

B2B - Create Basket




September 2006 296

B2B - Display Order Status




September 2006 297

References[1] “SAP E-Commerce Development and Extension Guide: Examples and Tutorials” on SAP Service

Marketplace: http://service.sap.com/crm-inst mySAP CRM 2005 CRM Core.[2] SAP CRM 5.0 Java. InstallationGuide on SAP Service Marketplace: http://service.sap.com/crm-inst

mySAP CRM 2005 CRM Core and follow the link “Installation mySAP CRM 2005 (SAP CRM 5.0)”.Follow the “Java” link that is applicable for the database and operating system, you want to use.

[3] Struts documentation: http://jakarta.apache.org/struts/userGuide/index.html

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

Update History

Version Date Remarks

1.0 March 2006

1.1 May 2006

2.0 September 2006



http://jakarta.apache.org/struts/userGuide/index.html



http://jakarta.apache.org/struts/userGuide/index.html



September 2006 298

Table IndexTable 1: List of the variables used in this guide ............................................................................................ 3

Table 2: Parameters of the MimeURL .......................................................................................................... 3

Table 3: Parameters of the WebappsURL .................................................................................................... 3

Table 4: Parameters of the translate Tag...................................................................................................... 3

Table 5: Parameters of the iterate Tag ......................................................................................................... 3

Table 6: Parameters of th contentType Tag.................................................................................................. 3

Table 7: Parameters ot the moduleName Tag.............................................................................................. 3

Table 8: Parameters of the imageAttribute Tag ............................................................................................ 3

Table 9: The structure of the UI element object ............................................................................................ 3

Table 10: The structure of the UI element group object................................................................................. 3Table 11: Input Validation............................................................................................................................. 3

Table 12: Input Validation............................................................................................................................. 3

Table 13: Structure of the UILayer Tag......................................................................................................... 3

Table 14: Structure of the Form Tag............................................................................................................. 3

Table 15: Structure of the HTML Attribute Tag ............................................................................................. 3

Table 16: Structure of the UIArea Tag.......................................................................................................... 3

Table 17: Structure of the UIAreaContainer Tag........................................................................................... 3

Table 18: Structure of the UIComponent Tag ............................................................................................... 3

Table 19: Structure of the UIConfiguration Tag............................................................................................. 3

Table 20: Global UI Commands ................................................................................................................... 3

Table 21: Commands while Layout Processing ............................................................................................ 3

Table 22: Registration of Context Values...................................................................................................... 3

Table 23: Overview Context Values ............................................................................................................. 3

Table 24: Connection Types to Backend...................................................................................................... 3

Table 25: Attributes of BusinessObject elements.......................................................................................... 3

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

Table 27: Main Components of the Generic Search Framework ................................................................... 3Table 28: Attributes for tag <screen-group> ................................................................................................. 3

Table 29: Attributes for tag <property-group> ............................................................................................... 3

Table 30: Attributes for tag <property-group> ............................................................................................... 3

Table 31: Attributes for tag <property> ......................................................................................................... 3


Table 33: Attributes for tag <depending>...................................................................................................... 3

Table 34: Attributes for tag <allowedValue> ................................................................................................. 3


Table 36: Standard Implementations............................................................................................................ 3




September 2006 299

Table 37: Search Definitions ........................................................................................................................ 3

Table 38: Search Definitions ........................................................................................................................ 3

Table 39: Types of Log Messages................................................................................................................ 3

Table 40: Types of Tracing........................................................................................................................... 3

Table 41: Log Levels.................................................................................................................................... 3

Table 42: Categories for Logs ...................................................................................................................... 3

Table 43: Software Components .................................................................................................................. 3

Table 44: Steps of Importing Modifications and Extensions .......................................................................... 3



Table 47: Overview of possible changes in different layers........................................................................... 3

Table 48: Overview of simple modifications related to the UI ........................................................................ 3

Table 49: User exits within the Basket.......................................................................................................... 3

Table 50: User exits within the Order............................................................................................................ 3

Table 51: User exits within the OCI .............................................................................................................. 3

Table 52: User exits within the Extended Complaints ................................................................................... 3

Table 53: User exits within the Remanufacturer’s Inspection Application ...................................................... 3

Table 54: Methods of the BOBase class....................................................................................................... 3

Table 55: User exits for IPC for pricing......................................................................................................... 3

Table 56: User exits for IPC basket.............................................................................................................. 3

Table 57: User exits for IPC basket.............................................................................................................. 3

Table 58: User exits for Order and Order Status........................................................................................... 3

Table 59: User exits for Order and Order Status........................................................................................... 3

Table 60: User exits for Web Catalog........................................................................................................... 3

Table 61: User exits for for Pricing or Configuration...................................................................................... 3

Table 62: User exits for for Pricing or Configuration...................................................................................... 3

Table 63: ABAP Extension Structure (CRM)................................................................................................. 3

Table 64: CRM - Supported Function Module / Business Object - Order....................................................... 3

Table 65: CRM - Supported Function Module / Business Object - User ........................................................ 3

Table 66: CRM - Supported Function Module / Business Object - Contract................................................... 3

Table 67: CRM - Supported Function Module / Business Object - Shop........................................................ 3

Table 68: CRM - Supported Function Module / Business Object - Complaint ................................................ 3

Table 69: CRM - Supported Function Module / Business Object – ComplaintHeader.................................... 3

Table 70: CRM - Supported Function Module / Business Object – ComplaintItem......................................... 3

Table 71: ABAP Extension Structure (ERP) ................................................................................................. 3

Table 72: ERP - Supported Function Module / Business Objects – Order..................................................... 3

Table 73: Communication Structure in SAP ERP.......................................................................................... 3

Table 74: How to access the Request Context ............................................................................................. 3

Table 75: Overview of the content of the web archive................................................................................... 3

Table 76: Overview of the content of the web archive................................................................................... 3

September 2006 300

Table 77:Overview of configuration files ....................................................................................................... 3

Table 78:Overview of configuration files ....................................................................................................... 3

Table 79: Overview of the package structure of E-Commerce ...................................................................... 3

Table 80: Naming conventions for JSPs....................................................................................................... 3

Table 81: Naming conventions for Business Object Managers...................................................................... 3

Table 82: Naming conventions for packages ................................................................................................ 3

Table 83: Naming conventions for Java classes ........................................................................................... 3

Table 84: Naming conventions for Java classes ........................................................................................... 3

Table 85: : Naming conventions for resource files ........................................................................................ 3

Table 86: : Naming conventions for resource files ........................................................................................ 3

Table 87: Adding Meta data of XCM parameters.......................................................................................... 3

Table 88: Attributes of the param XML element............................................................................................ 3

Table 89: Definition of a „allowedvalue“........................................................................................................ 3

Table 90: Allowed Attributes for the tag <property> ...................................................................................... 3

Table 91: Allowed Attributes for the tag <allowedValue> .............................................................................. 3

Table 92: Main Components of the generic search framework...................................................................... 3

Table 93: BAdI Implementations in Component "CRM_ICSS_CR"................................................................ 3

Table 94: BAdI Implementations in Component “CRM_ISALES_SEARCH” .................................................. 3

Table 95: Search definitions in E-Service Extended Complaints and Returns ............................................... 3

Table 96: Displaying text of keys.................................................................................................................. 3

Table 97: Displaying language dependent keys............................................................................................ 3

Table 98: General Request Parameters ....................................................................................................... 3

Table 99: Request parameters for B2C ........................................................................................................ 3

Table 100: Attributes of Java Connector Pool............................................................................................... 3

Table 101: Updating the application ............................................................................................................. 3




September 2006 301

Figure IndexFigure 1: SAP J2EE three-tier architecture................................................................................................... 3

Figure 2: Components of the SAP J2EE Application Server.......................................................................... 3

Figure 3: SAP E-Commerce for mySAP ERP architecture............................................................................ 3

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

Figure 5: Layered Architecture..................................................................................................................... 3

Figure 6: Internal processes within the interacton and presentation layer...................................................... 3

Figure 7: BO Layer and the Business Object Manager ................................................................................. 3

Figure 8: Business Logic Service Layer (BLS Layer).................................................................................... 3

Figure 9: Component configuration within XCM............................................................................................ 3

Figure 10: Actions within ECO Framework................................................................................................... 3Figure 11: Error Message user_no_login...................................................................................................... 3

Figure 12: Possible Attacks.......................................................................................................................... 3

Figure 13: Layout areas of frameless JSP pages.......................................................................................... 3

Figure 14: Bookmark Support....................................................................................................................... 3

Figure 15: XCM admin - defaultShopId......................................................................................................... 3

Figure 16: Prozess of re invoke of an invalid session.................................................................................... 3

Figure 17: BO Layer Structure...................................................................................................................... 3

Figure 18: Design of BLS............................................................................................................................. 3

Figure 19: Lifecycle of Backend Object ........................................................................................................ 3

Figure 20: Class Diagramm about use of JCo Connection............................................................................ 3

Figure 21: Generic Search Framework......................................................................................................... 3

Figure 22: Architecture of the Generic Search framework............................................................................. 3

Figure 23: Design of Logging / Tracing......................................................................................................... 3

Figure 24: Extend and Modify CRM Web Apps............................................................................................. 3

Figure 25: Merged Web Files ....................................................................................................................... 3

Figure 26: Project specific application in CUSTCRMPRJ.............................................................................. 3

Figure 27: Creating a new Track.................................................................................................................. 3Figure 28: Adding Software Component....................................................................................................... 3

Figure 29: Required Software Components.................................................................................................. 3

Figure 30: Check-In of the Archives ............................................................................................................. 3

Figure 31: Development System .................................................................................................................. 3

Figure 32: Overview Developer Workplace................................................................................................... 3

Figure 33: Developer Workplace for SAP NetWeaver 2004s ........................................................................ 3

Figure 34: Directory Structure of Web AS Java 7.0....................................................................................... 3

Figure 35: SAP Management Console ......................................................................................................... 3

Figure 36: Visual Admin - Setting Up Debug Mode....................................................................................... 3




September 2006 302

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

Figure 38: Starting Remote Debugging ........................................................................................................ 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Figure 58: BOBase class ............................................................................................................................. 3

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

Figure 60: Create own BOM......................................................................................................................... 3

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

Figure 62: Creating own BOM...................................................................................................................... 3

Figure 63: Creating interface for Business Object......................................................................................... 3

Figure 64: Creating own Business Object Manager ...................................................................................... 3

Figure 65: Adding additional Function Modules ............................................................................................ 3

Figure 66: Java event listener for Standard Function Modules...................................................................... 3

Figure 67: Replacing calls to Standard Function Modules............................................................................. 3

Figure 68 The IPC and its UI in the CRM Online Landscape......................................................................... 3

Figure 69 IPC Architecture more in detail ..................................................................................................... 3

Figure 70 General Action Flow..................................................................................................................... 3

Figure 71 Example for layout with UI components from both files (layout-config and ipclayout-config)........... 3

Figure 72 UI areas of the config UI............................................................................................................... 3

Figure 73 Example for tiles........................................................................................................................... 3

Figure 74 Combining low level layout and tiles ............................................................................................. 3

Figure 75 JSP Key and Path........................................................................................................................ 3

Figure 76 Interaction of UIBeans with the JSP pages and the Busines Object Layer..................................... 3



Development and Extension Guide – SAP E-Commerce 5 0

sap isa50 devandextguide

Documents