SAP E Commerce 5.0 Examples

  

       !"#$%

  Neurottstraße 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 ((( (((

JAVA® is a registered trademark of Sun Microsystems,

© Copyright 2004 SAP AG. All rights reserved.

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

J2EE™ is a registered trademark of Sun Microsystems,

information contained herein may be changed without prior notice.

Inc.

Some software products marketed by SAP AG and its distributors distributors contain

JAVASCRIPT® is a registered trademark of Sun

proprietary software components of other s oftware vendors.

Microsystems, Inc., used under license for technology invented and implemented by Netscape.

®

®

®

®

®

®

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

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

®

®

®

®

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 Intelligent Miner, WebSphere , Netfinity , ®

®

Tivoli , Informix and Informix Dynamic Server

TM

are trademarks of

IBM Corp. in USA and/or other countries.

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.

®

ORACLE is a registered trademark of ORACLE Corporation.

All other product and service names mentioned are the trademarks of their r espective companies.

®

®

®

®

UNIX , X/Open , OSF/1 , and Motif are registered trademarks of the Open Group. Disclaimer

LINUX is a registered trademark trademark of Linus Torvalds and others.

Some components of this product are based on Java™. Any code change in these components may cause

®

®

®

®

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

®

®

unpredictable and severe malfunctions and is therefore

WinFrame , VideoFrame , MultiWin and other Citrix product names

expressively prohibited, as is any decompilation of these

referenced herein are trademarks of Citrix Systems, Inc.

components.

HTML, DHTML, XML, XHTML are trademarks or registered

Any Java™ Source Code delivered with this product is

®

trademarks of W3C , World Wide Web Consortium, Massachusetts

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

Institute of Technology.

be modified or altered in any way.

Documentation in the SAP Service Marketplace

You can find this documentation at the following Internet address: &' &'

  Neurottstraße 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 ((( (((

JAVA® is a registered trademark of Sun Microsystems,

© Copyright 2004 SAP AG. All rights reserved.

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

J2EE™ is a registered trademark of Sun Microsystems,

information contained herein may be changed without prior notice.

Inc.

Some software products marketed by SAP AG and its distributors distributors contain

JAVASCRIPT® is a registered trademark of Sun

proprietary software components of other s oftware vendors.

Microsystems, Inc., used under license for technology invented and implemented by Netscape.

®

®

®

®

®

®

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

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

®

®

®

®

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 Intelligent Miner, WebSphere , Netfinity , ®

®

Tivoli , Informix and Informix Dynamic Server

TM

are trademarks of

IBM Corp. in USA and/or other countries.

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.

®

ORACLE is a registered trademark of ORACLE Corporation.

All other product and service names mentioned are the trademarks of their r espective companies.

®

®

®

®

UNIX , X/Open , OSF/1 , and Motif are registered trademarks of the Open Group. Disclaimer

LINUX is a registered trademark trademark of Linus Torvalds and others.

Some components of this product are based on Java™. Any code change in these components may cause

®

®

®

®

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

®

®

unpredictable and severe malfunctions and is therefore

WinFrame , VideoFrame , MultiWin and other Citrix product names

expressively prohibited, as is any decompilation of these

referenced herein are trademarks of Citrix Systems, Inc.

components.

HTML, DHTML, XML, XHTML are trademarks or registered

Any Java™ Source Code delivered with this product is

®

trademarks of W3C , World Wide Web Consortium, Massachusetts

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

Institute of Technology.

be modified or altered in any way.

Documentation in the SAP Service Marketplace

You can find this documentation at the following Internet address: &' &'

)'*

+

Type Style

Represents

Icon

Example Text

Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths and options. Cross-references to other documentation

Example text

Emphasized words or phrases in body text, titles of graphics and tables

EXAMPLE TEXT

Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example, SELECT and INCLUDE.

Example text

Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, source code as well as names of installation, upgrade and database tools.

Example text

Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation.

Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.

EXAMPLE TEXT

Keys on the keyboard, for example, function keys (such as F2) or the ENTER key.

Meaning Caution Example Note Recommendation Syntax

Development and Extension Guide – S AP E-Commerce 5.0

Contents Development and Extension Guide - SAP E-Commerce 5.0: Examples and Tutorials ........................................................................................................... 7 General Introduction ............................................................................................... 7 Where the Current Version of this Document is Located ............................................ 7 Naming Conventions....................................................................................................... 7 Terminology...................................................................................................................................................7 Variables........................................................................................................................................................7

Structure of this Document ............................................................................................ 8

Examples of Extensions.................................................................................. 9 Prerequisites ............................................................................................................ 9 Abbreviations........................................................................................................... 9 Extensions Limited to the UI Layer...................................................................... 10 Prerequisites.................................................................................................................. 10 Changing the Global Look and Feel of the UI ............................................................. 10 Purpose .......................................................................................................................................................10 Version ........................................................................................................................................................ 10 What to Do...................................................................................................................................................10 Example.......................................................................................................................................................11

Changing Text in JSP Pages ........................................................................................ 13 Purpose .......................................................................................................................................................13 Version ........................................................................................................................................................ 13 What to Do...................................................................................................................................................14 Example.......................................................................................................................................................14

Replacing/Adding Mimes.............................................................................................. 15 Purpose .......................................................................................................................................................15 Version ........................................................................................................................................................ 15 What to Do...................................................................................................................................................15 Example.......................................................................................................................................................15

Extensions within the Process Flow ................................................................... 16 Prerequisites.................................................................................................................. 16 Enhancing/Modifying the Action Flow......................................................................... 16 Purpose .......................................................................................................................................................16 Version ........................................................................................................................................................ 16 What to Do...................................................................................................................................................17 Example.......................................................................................................................................................17

Extensions within Data Processing ..................................................................... 18 Prerequisites.................................................................................................................. 18 Extending Existing Backend Objects .......................................................................... 18 Purpose .......................................................................................................................................................18 Version ........................................................................................................................................................ 18 What to Do...................................................................................................................................................18

Extensions to Exchange Additional Data............................................................ 19 Data Associated to an Existing Business Object ....................................................... 19 Version ........................................................................................................................................................ 19 What to Do...................................................................................................................................................19 Example.......................................................................................................................................................20

September 2005

4


Data Not Associated to an Existing Business Object ................................................ 20 Version ........................................................................................................................................................ 20 What to Do...................................................................................................................................................20 Example.......................................................................................................................................................20

Extension of the Document Search Screen ................................................................ 21 Adding a new search criteria for the order document search in the B2B scenario ..................................... 21 Adding the currency field to the result list ...................................................................................................22 Troubleshooting...........................................................................................................................................26

Extension Tutorial ......................................................................................... 27 Installing Examples ............................................................................................... 27 Prerequisites.................................................................................................................. 28 Creating Web Applications with Extension Examples............................................... 28

Extension Demo 1 – Add New Entry Fields ........................................................ 29 Click through the Application....................................................................................... 29 Finding out which JSP has to be Changed ................................................................. 30 Adding an Entry Field to order.jsp............................................................................... 30 Modify the JSP ............................................................................................................................................ 32

Changing the Process Flow.......................................................................................... 34 Getting Information about the Standard Process Flow ............................................................................... 34 Intercepting the Process Flow with a Custom Action .................................................................................. 36 Creating a Custom Action.......... ............ .............. ............. .............. ............ .............. ............. ............ .............. ........... 36 Adding Custom Action to Process Flow...... ............ .............. ............. ............ .............. ............. .............. ............. ...... 37

Storing Extension Data in an Existing Business Object............................................ 38 Retrieving Extension Data from Existing Business Objects ..................................... 39 Displaying Extended Data in JSP................................................................................. 39

Extension Demo 2 – Extensions in the Business Object Layer........................ 41 Adding a Business Object ............................................................................................ 41 Adding a Business Object Manager ............................................................................ 41 Testing application........................................................................................................ 43

Extension Demo 3 - Extensions in the BLS Layer.............................................. 44 Writing Interface for the Backend Object .................................................................... 45 Writing Implementation of Backend Object Interface ................................................ 45 Registering Backend Object in BLS Layer.................................................................. 46 Writing a new Backend-Aware Business Object ........................................................ 46 Creating a Backend-Aware Business Object in BOM................................................. 47 Testing the Application................................................................................................. 47 Communication with the SAP CRM system ................................................................ 47 Enabling Logging .......................................................................................................... 49 Testing Communication to the SAP CRM System...................................................... 49

Extension Demo 4 – Store Additional Data as Extension Data......................... 50 Action Structure ............................................................................................................ 50 Changing the Process Flow.......................................................................................... 51 Replace Standard Action with Custom Action in the Process Flow ............................................................ 51

Displaying Extended Data in JSP................................................................................. 52

September 2005

5


Extension Demo 5 - Displaying additional Document Type on User Interface in ISA CRM.................................................................................................................. 54 Create New Template for Content Management Folders ........................................... 54 Create New Catalog Type for Product Catalogs ......................................................... 55 Create New Product Catalog from New Catalog Type................................................ 55 Extension of JSP to Display Additional Document in Product Catalog ................... 55

Extension Demo 6: Copy-Template for Customer Extensions .........................57 Working with the Objects ............................................................................................. 57 Implementation Details ................................................................................................. 58 How to Use the Template for Own Extensions ........................................................... 59

References ..................................................................................................... 60 Update History............................................................................................... 60

September 2006

6


Development and Extension Guide - SAP ECommerce 5.0: Examples and Tutorials In mySAP CRM 5.0, the Development and Extension Guide for SAP E-Commerce has been splitted into two documents. The document Landscape, Basics and Concepts contains information about how the SAP E-Commerce applications are designed, how to setup the development environment and explains t he 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 Located The current version of this document is located in SAPNet under the alias CRM-INS T => 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 embraces E-Selling and E-Service .



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

Variables The following table contains a list of the variables, w hich are used in this guide. Variables

Description

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

Number of the service pack (two decimals), you want to upgrade to (e.g ‘03’).

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

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

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

System ID you entered during installation of the SAP Web Application Server Java with the SAPInst.

September 2005

7


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

Installation directory for the SAP system. If you have installed the SAP Web AS with t he SAPInst, the default installation path is: C:\usr\sap\\JC

\j2ee

\SDM

Name of the deployed Internet Sales application (e.g. b2b or b2c).

Directory where the application is deployed. (e.g. \cluster\server0\apps\sap.com\crm~b2b servlet_jsp\b2b\root)

Directory where the ISA build tool is located. (e.g. C:\isa_build_tool)

Server on which your Internet Sales application is installed.

Port on which the deployed application can be reached. For more details on the SAP J2EE Ports, please refer to the chapter Additional Information 'Error! Reference source not found.' on page Error! Bookmark not defined.

Structure of this Document Before we start the general introduction to the various subjects covered in this document, we would like to explain a few things about its structure and handling. This cookbook is intended for consultants who have knowledge of the SAP CRM (ERP) environment, Internet Sales versions, and basic Java skills, and who want to understand the concepts of the Internet Sales 5.0 SAP J2EE solution and wish to set up their own local development environment independently. After you have read this extension guide, you should be able to make changes to both the local Internet Sales application and perform customer installations. The first unit provides a short general introduction to SAP J2EE that is needed in order to understand the concepts of the Internet Sales framework discussed in the next unit. The next unit gives an introduction to the SAP Java Connector required by the Internet application when communicating with an SAP s ystem. Unit 4 provides an introduction to handling and installing the tools required for running the Internet Sales application and modifying it. The second part of this document begins with unit 5. This unit introduces various extension concepts needed in order to understand the Example of Etensions in the next unit. The extension tutorial in the following unit gives you the opportunity to get hands-on experience of t he various extension concepts. Best practices useful when extendion the application can be found in the last unit.

September 2006

8


Examples of Extensions This unit provides an overview of possible extensions within the ISA application. The following information is provided for each type of extension: •

Purpose Why should I perform such an extension? W hat is the goal of the extension?

•

Version Which ISA support packages support the technology required by this extension?

•

What To Do This unit usually provides a list of tasks that have to be performed in order to perform the modification. Cross references show units that provide further information.

•

Example An example that demonstrates the extension.

Prerequisites For a detailed description on how to set up a development environment, refer to unit Error! Reference source not found. Error! Reference source not found.. The examples provided in this chapter assume the following infrastructure •

JDK 1.3.1, or higher

•

SAP J2EE 6.20

•

Installed SAP Java Connector 2.0, or higher

•

Development environment (e.g. Eclipse) with installed I nternet Sales libraries

•

Ant 1.5, or higher

•

Installed ISA Build Tool

•

Internet Explorer 5

•

o

For testing the application

o

For reading JavaDoc

Following deployed ISA applications: o

The original B2B application, which acts as the template for the modified application

o

A copy of the B2B application called B2B_mod. All custom modifications are performed in this copy

o

The original B2C application, which acts as the template for the modified application

o

A copy of the B2C application called B2C_mod. All custom modifications are performed in this copy.

Abbreviations The following abbreviations are used in this catalog:

September 2005

9


Description

Abbreviation

Root of original B2B application in the SA P J2EE environment

Root of original B2C application in the SAP J2EE environment

Root of B2B copy application in the SAP J2EE en vironment

Root of B2C copy application in the SAP J2EE environment

The root of an arbitrary ISA web application

The WEB-INF path of an arbitrary ISA web application

Business Object Manager

BOM

Backend Object Manager

BEM

Internet Sales Application

ISA

Extensions Limited to the UI Layer All changes to the user interface take place in the Interaction and Presentation Layer. Changes related to the UI: •

Modifying existing JSPs/HMTL, style sheets

•

Adding new JSPs/HTML

Prerequisites In order to understand this unit you should be familiar with the following concepts: •

HTML

•

Cascading stylesheets

•

Java Server Pages

•

ISA custom tags

Changing the Global Look and Feel of the UI Purpose You want to change the look and feel of the application, such as colors, font size, t ext alignments, and so on.

Version All versions.

What to Do Settings related to the look and feel of the application are located in the global cascading stylesheet file. This file can be found in \mimes\shared\style\stylesheet.css. September 2006

10

Development and Extension Guide – S AP E-Commerce 5.0 The overall frame-structure of B2B is displayed in the following graphic:

Figure: B2B Frameset structure This picture gives you some orientation for finding out which classes in the global style sheet are responsible for which parts of the UI.

Example This first example details how to change the background color of the history part: 1. Open the file located \mimes\shared\style\stylesheet.css.

2.

Search for body.history.

3.

In the stylesheet.css file change the following: Change body.history { background: none #F0F4FA; } to body.history { background: none #1010FA; }

4.

Clear the temporary files of the browser, close the browser, and restart the web application.

5.

After the changes the UI should appear as follows:

September 2005

11


The second example details how to change the frame sizes of the B2C application. The overall frame-structure of B2C is depicted below:

Figure: B2C Frameset structure

September 2006

12


The ISA application is structured using three nested frame sets that are defined in the JSPs mainFS.jsp, mainFS_inner.jsp, catalogFS.jsp, and accountFS.jsp. Please note that you can change the size and arrangement of the frames in one of the existing frame sets, but you cannot add a new one, as this w ould require more comprehensive modifications. In this specific example, you want the right frame to appear on the left-hand side, and you want to reduce the size of the left and right frames to 20% of t he screen. Please note that you have to change catalogFS and accountFS in parallel. To change the sequence of the frames, move the description of the right frame in the source code of catalogFS and accountFS. To change the size of the individual frames, change the tag.

Changing Text in JSP Pages Purpose You want to change the descriptions on the pages or add new text.

Version These changes can be performed in all versions of ISA.

September 2005

13


What to Do All texts shown in the UI of the application are stored in language-dependent property files. These files are located in \web-inf>\classes. They are named ISAResources.properties where is used to distinguish files of different l anguages. Examples for names are ISAResources_de.properties and ISAResources_en.properties. In this case, ISAResources_de.properties contains German texts, and ISAResources_en contains English texts. Additionally, there is one file named ISAResources.properties. This file contains text in a default language. These texts are used if there is no suitable property file for a requested language (for example, Greek). If you want to change texts, or add new texts, you have to do this in all files belonging to the languages you support. To find out which text key corresponds to a text shown in the application, enable the translate.show.key.only feature (see Adding an Entry Field to order.jsp on page 7) To find out the page name where the text you want to change is located, enable the showmodulename feature on (see Finding out which JSP has to be Changed on page 30). When you add new text keys, please follow the naming conventions described in chapter Naming Convention in the Development and Extensionsguide SAP E-Commerce 5.0. After changing/adding a property key you have t o restart the application.

Example In this example, you want to change the GO! text of the submit button to START . To do this, you first have to identify the translation key in the file navigationbar.jsp (b2c.navigationbar.go in this case). You then have to change the value of this translation key in the Java property file ISAResources_en.properties.

September 2006

14


Replacing/Adding Mimes Purpose You want to replace/add mimes in the application. For example, you want to add a new logo in the header of the application.


What to Do Find out the page where the mime you would like to change is located by enabling the showmodulename feature on (see Finding out which JSP has to be Changed on page 30). Hint •

•

Run two sessions simultaneously. One with original texts, and one with development features. After changing the content of a JSP, select the appropriate JSP with the mouse, and select Refresh from the context menu.

Example This example details how to include a company logo in the B2C scenario. A standard field is reserved for the customer’s company logo. You only have to find the appropriate place in the source code of the corresponding JSP file, navigationbar.jsp, and enter the name of the new logo. Please note that this logo has to be saved in folder /b2c/mimes/images.

September 2005

15


Extensions within the Process Flow You want to change the interactions within the application. Such changes could, for example, be: •

Modifying one or more process steps within the application

•

Removing one or more process steps from the application

•

Adding new process steps to the application

The descriptions in this chapter assume t hat you are not changing application logic. You perform changes in the interaction layer of the application. The main components of the interaction layer that are changed are: •

•

Struts Actions (= action) o

By modifying existing Actions (deriving from them)

o

Adding new self-written Actions

Struts configuration file

When changing the config.xml or adding new Java classes to the application, please follow the naming conventions described in chapter in chapter Naming Convention in t he Development and Extensionsguide SAP E-Commerce 5.0.

Prerequisites In order to understand the following unit you should be familiar with the following c oncepts: •

Struts

•

Java programming language

•

Internet Sales framework

Enhancing/Modifying the Action Flow Purpose You would like to modify the action flow within the application. A reason for doing this could be that you want to perform some additional process steps that are not part of the original process flow before you continue (for example, an early log on to the b2c scenario – see example).


September 2006

16


What to Do The following steps describe the t asks you have to perform: •

•

•

Find out which Actions and JSP’s are responsible for the interaction you want to modify. For f urther information, see unit Getting Information about the Standard Process Flowon page 34. Identify the existing Action or write a new Action, which has to intercept the process flow Modify the Struts configuration file, located in \web-inf\c \web-inf\config.xml onfig.xml (config_user.xml) (config_user.xml)

Example For a detailed example see chapter Changes in config.xml (or other Struts configuration files) in the Development and Extensionsguide SAP E-Commerce 5.0

Calling the Login Page (login.jsp): The B2B scenario of the Internet Sales application is started by calling the URL http://localhost:50000/b2b/b2b/init.do.. Both Servlets and URL mappings are described in the web.xml file. http://localhost:50000/b2b/b2b/init.do action *.do

An excerpt of the definition of the web.xml ActionServlet appears below: action com.sap.isa. com.sap.isa.core.ActionSer core.ActionServlet class> config /WEB-INF/confi /WEB-INF/config.xml,/WEB-INF g.xml,/WEB-INF/xcmadmin-con /xcmadmin-config.xml, fig.xml, /WEB-INF/ccmsims-config.xml /WEB-INF/ccmsims-config.xml,/WEB-INF/ipc ,/WEB-INF/ipc-config.xml, -config.xml, /ipc/customer/config.xml, /ipc/customer/config.xml, /WEB-INF/config_lwc_b2b.xm /WEB-INF/config_lwc_b2b.xml, l, /WEB-INF/scheduler-config.x /WEB-INF/scheduler-config.xml,/WEB-INF/i ml,/WEB-INF/ipcpricing-conf pcpricing-config.xml ig.xml config/user /WEB-INF/confi /WEB-INF/config_user.xml ram-value>

The URL mapping above forwards all URLs with extension .do to the ActionServlet. Therefore, for example, the statement will also call the ActionServlet defined in the web.xml file. In this excerpt from the web.xml configuration file, the config parameter is used to address the /WEBINF/config.xml and /WEB-INF/config_user.xml file. The Struts framework is configured within these files.

September 2005

17


As specified in web.xml, calling a URL with extension .do forwards the request to the ActionServlet. This ActionServlet refers to config.xml / config_user.xml config_user.xml , where the different Actions are defined and mapped. Every ActionMapping contains, at least, the r equired attributes path and path and type , and thus assigns the implementing class to an URI. These Actions either lead directly to a f ollow-on JSP page, or call another Action themselves. You can append any number of consecutive Actions.

Extensions within Data Processing You want to modify the data processing within the application. Such changes could for example be: •

Modifying one or more processing steps

•

Adding new processing steps

The descriptions in this chapter assume t hat you do not change application logic. You perform changes in the interaction layer of the application. The main components that are changed are: •

Backend Objects By modifying existing backend objects (deriving from t hem).

Prerequisites In order to understand the following unit you should be familiar with the following c oncepts: •

Java programming language

•

Internet Sales framework

Extending Existing Backend Objects Purpose You would like to enhance a specific processing step within the application. A reason for doing this could be that you want to perform some additional checks that are not part of the original processing, before you continue with the processing. Or you want to add additional data before you continue with the processing.


What to Do The following steps describe the t asks you have to perform: •

Find out which backend object is responsible for the processing steps you want to modify

•

Identify the existing backend object or write a new backend object

•

Register the new backend object in the customer version of backendobject-config.xml backendobject-config.xml and modify the configuration file located in \webinf\xcm\customer\modificat inf\xcm\customer\modification\config.xm ion\config.xml l

September 2006

18


Extensions to Exchange Additional Data You have extended the application UI and want to pass additional data to the backend. Or, you would like to provide the user interface with additional data retrieved from the backend. An example of such a extension is an additional basket header field shown in the UI. These extensions go beyond simple changes to the UI. Depending on your requirements, and the support package of ISA, there are several ways in which these extensions can be achieved. The decision on the concept for implementation of one specific customer extension should also take into account all other project customer extensions.

Data Associated to an Existing Business Object If you have to show/add s how/add data associated to an existing Business Object (f or example, additional header attributes in the basket), then you will most likely use the extension data extension concept. This is the preferred extension concept when passing data between the Business Object layer and the backend system.


What to Do The following steps describe the t asks you have to perform: 1. Check in chapter Standard Actions providing User Exits in the Development and Extensionsguide Extensionsguide SAP E-Commerce 5.0 whether there are function modules supporting the extension concept associated with the Business Object that you would like to associate data with. 2. If you have found a suitable function function module you can pass data data to the Business Object using the extension data mechanism (see chapter Extensions in Action Flow, Create a Customer Action in Development and Extensionsguide SAP E-Commerce 5.0). 3. You do this, usually, using using predefined User-Exits or a self-written self-written Action interfering the default process flow, if no User-Exit is provided. For further information, see unit Changes in config.xml (or other Struts configuration files) in the Development and Extensionsguide SAP E-Commerce 5.0. 4. The data passed passed to the function module module has to be processed in the function module. module. If there is not a suitable BADI you have to modify the delivered ABAP source code. Note: (ISA CRM and ECO ERP) For handling extension data within the basket, you have to take care that business objects (e.g. the basket) are stateless from the applications point of view. This means, whenever a request is received the business object is completely rebuilt from the request information, thus overwriting all header and item information. This is normally also the point where extension data that was entered on the JSP is attached to the business object. Changes to a business object that incl ude extensions are only persisted if the backend object is updated before the next read. Therefore, whenever you modify the business object by adding extension data you must make sure the business object is first updated in the backend object before the next read is done (otherwise the extension data will be overwritten).

September 2005

19


Note: (ECO ERP) If additional data should be transferred, as extension data attached to the sales document, to the SAP ERP system, the extension data is transferred through SD_SALESDOCUMENT_CREATE, table EXTENSIONIN. In the standard, the extension data has to be transferred back from SAP ERP to ISA using table parameter EXTENSIONEX, to make it available, later on, for the second call of SD_SALESDOCUMENT_CREATE, used to save the order. If, for some reason, this is not possible, you have to store the extension data ISA before the call to the SAP ERP system, and you have to set to sales document again, after the call to the SAP ERP system. Otherwise, the extension data will be lost, and not available within the subsequent order save. For an example see note 671711.

Example For an example on how to pass extension data to the backend, refer to Extension Demo 3 - Extensions in the BLS Layer on page 44.

Data Not Associated to an Existing Business Object If you have to show/add data not associated to an existing Business Object, you have to write your own objects to transfer data between the different ISA layers.


What to Do The following steps describe the t asks you have to perform: 1.

Write a Backend Object providing additional functions. For further information, see unit Create a Customer Backend Object in the Development and Extensionsguide SAP E-C ommerce 5.0.

2.

Write a corresponding Business Object and a Business Object Manager. For further information, see Create a Customer Business Object and Create a Customer Business Object Manager in the Development and Extensionsguide SAP E-Commerce 5.0.

3.

Write Actions that intercept the process flow and communicate with standard and self-written Business Objects. For further information, see unit Create a Customer Action in the Development and Extensionsguide SAP E-Commerce 5.0.

Example For an example of how to write your own Business Objects refer to Extension Demo 2 – Extensions in the Business Object Layeron page 41.

September 2006

20


Extension of the Document Search Screen This section will include multiple examples on how to extend the document selection screen in Internet Sales.

Adding a new search criteria for the order document search in the B2B scenario Preface : Since the Generic Search Framework has a generic interface to the CRM 1order reporting framework it is very easy to have new selection criteria added to a search request. But attention, the CRM 1order reporting framework has also its limit and can not support all possible document attributes for a document. Please consult the CRM 1order reporting framework documents on what’s supported in standard and how to extend the reporting framework for new fields. This simple example explains on how to add the currency to the order search. This extension can be done by just adding a new to the standard search description “SearchCriteria_B2B_Sales”. The extension itself will be made in the \ customer\ area of the XCM to be free of modifications. 1.1 Open file generic-searchbackend-config.xml in path xcm\customer\modifcation After line
add following entry.

description="gs.z.curr.all" /> description="gs.z.curr.eur" /> description="gs.z.curr.usd" />

ATTENTION !! If copying the entry from this document it might be possible the quotes are not correct for the xml file. The log file will contains an error message parsing the generic-searchbackend-config file.

September 2005

21


1.2 Add the resource keys to the appropriated language file •

\WEB-INF\classes\ crm~isa~isacore~resources

gs.z.curr.all=any Currency gs.z.curr.eur=Euro gs.z.curr.usd=Dollar Before change

After change

Because of the tag referencing the ORDER value in document_types, the new selection criteria will only be available for the selection of order documents.

Adding the currency field to the result list Preface: As for the selection, which technically only returns the document keys (GUIDs), the CRM 1order reporting framework offers additionally functionality to enhance further document attributes. Please consult the CRM 1order reporting framework documents on what’s supported in standard and how to extend the reporting framework for new fields. This example shows how add the net value of the order document and its currency. To combine net value and currency in one result list field, a f ield output handler class/method will be created and assigned.

September 2006

22


2.1 Adding the entries to the generic-searchbackend-config.xml after the above entries.

2.2 Adding the resource key for the net value gs.z.netvalue=Net Value 2.3 Creating the field output handler class Best way to create it is extending standard class •

com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIDynamicContent

If not, interface •

com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIDynamicContentData

must be implemented.

September 2005

23


Example for implementation of this class extending the standard class: package zcom; import com.sap.isa.core.util.table.ResultData; import com.sap.isa.core.util.table.Table; import com.sap.isa.core.util.table.TableRow; import com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIFactory; public class GenericSearchUIDynamicContent extends com.sap.isa.ui.uiclass.genericsearch.GenericSearchUIDynamicContent {

public Table getNetValueAndCurrency() { ResultData rsData = (ResultData)pageContext.getAttribute("singlerow"); Table fieldT = GenericSearchUIFactory.getUIReturnTable( GenericSearchUIFactory.TYPE_RETURNTABLE_OUTPUTFIELD); // Fill Table TableRow tabrow = fieldT.insertRow(); tabrow.setValue("TYPE", "FIELD"); String value = rsData.getString("NET_VALUE"); String currency = rsData.getString("CURRENCY"); String ffield = (value + " " + currency); tabrow.setValue("VALUE", ffield);

return fieldT; } }

What happens in this class: 1. PageContext attribute “singlerow” provides the currenly processed row in the result list. By using the names defined in the generic-searchbackend-config.xml file, each value is accessible. 2. Using standard class GenericSearchUIFactory to create an appropriated table of type “TYPE_RETURNTABLE_OUTPUTFIELD” to return the field (please see JavaDoc for more documentation about this type). The different attributes of the return table describe only one field, not the entire row!! Only the first row of the table will be process be framework further on.

September 2006

24


Before change

After change

Additionally the type of the is declared as “number” (to be handled right for sorting) and a CSS class is assigned to have the field adjusted to the right. The CURRENCY had been set to type “hidden” since it is only necessary to retrieve the field from the backend.

September 2005

25


Troubleshooting This troubleshooting guide is focused on the design phase for a new or changed search description / result list. During this time small errors mostly lead to NullP ointerExceptions or other fatal errors. Symptom

Solution

NullPointerException on genericsearch.jsp

1. Use XCM administrator to check file generic-search-config.xml. If the file doesn’t contain any content, this is caused mostly by an syntax error in the xml structure. => Check your entries in files

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

OR

\xcm\customer\modifcation\generic-searchbackend-config.xml 2. Check log file for entry “GSPropertyGroup '' as search description found”. => Make sure the right search description is used (To find the used search description for a screen use Url parameter “showmodulename=true” when starting the Internet Sales application. The “search description” will be issues for a search screen) Drop down list boxes on page don’t react correctly or ‘GO!’ button doesn’t work.

=> Check the names are unique within t he search description.

Selection parameter is not transferred into backend

=> Check your requestParameterName attributes are unique within one search request. If the framework builds up the URL which will be send to the web server, the http protocol supports only unique parameter names. Once a parameter occurs a second time, its value will replace the fir st occurs.

No selection criteria on the screen or only a few ones

1. Dependencies of the search criteria to each other (tag ) might be wrongly defined. => Check your entries in files \xcm\sap\modification\generic-searchbackend-config.xml

OR

\xcm\customer\modifcation\generic-searchbackend-config.xml 2. Check the used search description is of type search and not of type result list => Make sure the right search description is used (To find the used search description for a screen use Url parameter “showmodulename=true” when starting the Internet Sales application. The “search description” will be issues for a search screen)

September 2006

26


Extension Tutorial The following unit describes extension examples to demonstrate the following extension concepts: •

Adding entry fields to JSPs

•

Using the extension data mechanism

•

Using BADI/extension and BAPI/extension mechanism

•

Writing Actions

•

Writing Business Objects

•

Writing Business Object Managers

•

Writing Backend Objects

•

Writing Backend Object Managers

•

Plugging in Business Objects, Business Object Managers, and Backend Objects

•

Using the Connection Event mechanism

If you are new to the extension concepts you can consider the following examples as a tutorial, detailing various extension possibilities. It is recommended that you work through all of the examples so that you can understand the extension concepts. The extensions become more complex with each demo.

Installing Examples The examples are delivered in a zip-file within a note. The extension examples consist of two p arts: •

•

Java code is delivered in the folder examples_java and have to be imported in the DC crm/home/shr/ext in the SC sap.com_SAP_SHRWEB_1 into the folder src/packages. These classes will then be deployed as a sap.com~crm~home~shr~ext~assembly.jar file to the application. Changes in the JSP and configuration of the B2B application. These changes are already preconfigured in the standard objects but commented out. They are delivered in the folder examples_xml_jsp in the zip-file and can be copied to the DC crm/web/isa/b2b in the SC sap.com_SAP_SHRWEB_1 to the folder webContent/examples. To run the examples it is necessary to copy the files to your local customer project (or by removing the comments of the original f iles).

If the backend system is a SAP CRM system, additional objects needed for some extension examples are part of the backend system: •

Remote function modules, which are shipped together with SAP CRM, and are called by the modified Java application. No further installation steps are required

September 2005

27


Prerequisites •

SAP J2EE o

The server is running on the local machine, that is, it can be accessed using the following URL http://localhost:

•

ISA Application o

Installed ISA B2B web application

o

The source code of the Java examples i s delivered via a separate note.

o

You have access to the corresponding backend system, an SAP CRM system, an SAP ER P or an SAP ERP system, respectively, can browse a product catalog, and create orders. Note: Some extension demos are set up to work only with one type of backend system, a SAP CRM system or a SAP ERP system

Creating Web Applications with Extension Examples For creating a B2B application with the extension described in the demos, you have to create your own customer b2b application (see chapter Creating a project specific Web Application with own context root in the Development and Extensionsguide SAP E-Commerce 5.0 ().

September 2006

28


Extension Demo 1 – Add New Entry Fields In this demo you carry out the following tasks: •

Add a new entry field to a JSP

•

Add custom Actions to the process flow

•

Store custom data as extension data in an appropriate Business Object

Files: •

See java-classes in folder examples_java\src\packages\com\sap\isa\mod\demo1

•

The other files (jsp, config.xml and resource-files) are located in your application.

Click through the Application The goal of this modification is to provide an additional basket header field. The first step is to click through the (standard) application in order to reach the JSP in which this field i s to be located: 1.

Start the B2B application: http://localhost:/b2b/b2b/init.do.

2.

Log on to the system by providing a user id and password.

3.

Select a shop.

4.

Go to the product catalog.

5.

Select some products from the product catalog.

6.

Add a product to the shopping basket.

7.

Create a new purchase order.

8.

Go to the shopping basket. You should see something similar to the following screenshot:

September 2005

29

Development and Extension Guide – S AP E-Commerce 5.0 9.

The circle shows where the additional entry field is to be added (under the requested delivery date input field).

Finding out which JSP has to be Changed Finding out the name of the JSP which has to be changed: The first changes take place in the Presentation Layer. You add the entry field to the appropriate JSP page. Firstly, you have to find out the name of the JSP page. 1.

Start the application: http://localhost:/b2b/b2b/init.do?showmodulename=true This displays the names of the JSP pages in the upper left corner of the JSP.

2.

Click through the application until you see the contents of the shopping basket.

3.

Now you can find out the name of the JSP you have to change.

Adding an Entry Field to order.jsp Files: •

\b2b\order.jsp

•

\web-inf\classes\ISAResources_en.properties

In this step you add a new entry field into the order.jsp. •

Open file \b2b\order.jsp

When you take a look at the contents of this file, you will see that it is quite complicated. At first glance it is not easy to see where the entry field should be added. To locate the correct place: •

Activate the feature translate.show.key.only: http://localhost:/b2b/b2b/init.do?translate.show.key.only=99). If you activate this feature, you will find out that the text 'Requested Delivery Date' corresponds to the b2b.order.disp.reqdeliverydate key

September 2006

30

Development and Extension Guide – S AP E-Commerce 5.0 Hint: Open a second browser window when you activate this feature. This makes navigation within the application easier.

September 2005

31


Modify the JSP In the next step you add a new text input field in the page. •

Search the key b2b.order.disp.reqdeliverydate in the order.jsp file.

You will find the following content: <% if (ui.isBasket() || ui.isQuotation()) { %> <% } %> <% if (ui.isBasket() || ui.isQuotation()) { %> title="" <% } %> value="<%= JspUtil.encodeHtml(ui.header.getReqDeliveryDate()) %>" onblur="checkReqDateChange();"/> <% if (!ui.isAccessible) { %> ', 'headerReqDeliveryDate');"> " alt=""/> <% } } %> <%-- Header Cancel date --%> <% if (ui.isElementVisible("order.latestDeliveryDate")){ %> …………………. <%-- end of header cancelDate --%>

The relevant parts of the JSP´s content are highlighted. You will notice that the is located in a table row which is indicated by the tag three lines above. Now you should search for the corresponding tag.

•

Place the following code segment just below the tag (below the list l ine in the code snippet above) and save the changes: this is a test

•

•

Place the mouse pointer in the browser on the order.jsp and select the refresh button from the context menu The result should be as follows:

September 2006

32


In the next step you add the description and the new input field. •

Open the resource property file ISAResources_en.properties located in \webinf\classes

•

Add the following text key to the end of the fi le ISAResources_en.properties: mod.demo.b2b.z_customBasketHeaderField=Custom Basket Header Value

•

Add the following code sequence after the tag shown in the code snippet above (file: order.jsp):

•

Build and deploy the project.

•

Start your application.

•

The result of the changes should appear as follows:

September 2005

33


Later on in this example, you add code to the JSP, which fill s up the text field with data, when the page is refreshed.

Changing the Process Flow You want to get the value of the newly created text fiel d. To do this you have to intercept the process flow wit h your own Actions. But, before you can do this, you need more information on the standard process flow. The following section describes one possible way to investigate this flow.

Getting Information about the Standard Process Flow Files: •

\j2ee\cluster\server0\log\defaulttrace.X.log

The data entered in the added text field has to be retrieved by an Action when the Update button is pressed. In this step you will find out what happens in the i nteraction layer when the Update button is pressed.

In this example we obtain information on the process flow by analyzing the log files. 1.

Open the file \j2ee\cluster\server0\log\defaulttrace.X.log in a text

editor. 2.

Go to the end of the text file and set a bookmark (or remember the line number).

3.

Select the Update button in the application.

4.

Go to the isaruntime.log file and examine the log entry found and the previous entry: [actionxecution]='begin' [actionclass]='com.sap.isa.isacore.action.order.ShowBasketAction' [path]='/b2b/showbasket' [actionxecution]='end' [actionclass]='com.sap.isa.isacore.action.order.ShowBasketAction' [path]='/b2b/showbasket' [forward]='/b2b/order.jsp' [exectime]='0'

September 2006

34

Development and Extension Guide – S AP E-Commerce 5.0 [actionxecution]='begin' [actionclass]='com.sap.isa.isacore.action.order.MaintainBasketDispatcherAction'

[path]='/b2b/maintainbasket' [actionxecution]='end' [actionclass]='com.sap.isa.isacore.action.order.MaintainBasketDispatcherAction' [path]='/b2b/maintainbasket'

[forward]='/b2b/basketrefresh.do'

[exectime]='10'

[actionxecution]='begin' [actionclass]='com.sap.isa.isacore.action.order.MaintainBasketRefreshAction' [path]='/b2b/basketrefresh' [actionxecution]='end' [actionclass]='com.sap.isa.isacore.action.order.MaintainBasketRefreshAction' [path]='/b2b/basketrefresh' [forward]='/b2b/updatedocumentview.do' [exectime]='20'

5.

From the [actionxecution]='begin' entry you can find out the path of the called Action path=/b2b/maintainbasket.

6. The corresponding [actionxecution]='end' entry is created after performing the Action and showes the forward /b2b/basketrefresh.do. 7. After searching all the log entries as shown above you will find the following process flow:

Please note that the last Action is triggered by the frameset_order.jsp. This has an effect when you intercept the process flow with our own Actions. You should not change JSPs in order to call your own custom Actions.

September 2005

35


Additional resources: •

•

Take a look in the \web-inf\config.xml (config_user.xml) file to verify the found results Read the JavaDoc of the Actions in order to get additional information about their responsibilities

Intercepting the Process Flow with a Custom Action In the next steps you intercept the process flow by providing a custom Action. Your custom Action acts as an interface between the user UI and the Business Object Layer, and performs the following tasks: •

Reading the value of the Z_CustomHeaderField input field

•

Retrieving the GUID from the basket Business Object

•

Calling a custom Business Object, which stores the value of the input field

Creating a Custom Action Files: •

Struts Action: com.sap.isa.mod.demo1.action.Z_TestAction

In this step you create an Action, which retrieves the value Z_CustomHeaderField, and prints it on the system console. •

Take a look at the com.sap.isa.mod.demo1.action.Z_TestAction

In the doPerform method you find the following code sequence:

// get extended basket header data from the http-request String extBasketHeaderData = request.getParameter(‘Z_CustomHeaderField’); System.out.println(‘Value of new header field: ‘+ extBasketHeaderData);

Each time an Action is executed the doPerform() method is called by the framework, the implementation above retrieves the value of the Z_CustomHeaderField from the HTTP request, and prints it out on the console.

September 2006

36


Adding Custom Action to Process Flow Files: •

Struts config file: \web-inf\config.xml

In this step you intercept the original process flow with the custom Action. The Action is called after the MaintainBasketDispatcherAction, and before the basket is called.

Please note that the ShowBasketAction is called by a frameset JSP. If you wanted to place your Action before the ShowBasktetAction you would have to change the source code of the frameset_order.jsp. This is not recommended. Try to restrict changes in the Struts framework to the config.xml only.

Carry out the following steps: 1.

Open the \web-inf\config.xml file.

2.

Search in the config.xml for path=‘/b2b/basketrefresh’.

3.

Change the path of the MaintainBasketRefreshAction from /b2b/basketrefresh to /b2b/Z_basketrefresh.

September 2005

37


4.

Go to the end of the file and add new Action mapping for CustomBasketHeaderAction just before the tag.
path=‘/b2b/Z_basketref resh.do’/>

•


•

Start your application.

Storing Extension Data in an Existing Business Object Files: •

Struts Action: com.sap.isa.mod.demo1.action.Z_CustomBasketRefreshAction

You can store any arbitrary data in existing Business Objects by calling the addExtensionData(Object key, Object name) method. All Business Objects derive from com.sap.isa.core.businessobject.BOBase which provides this functionality. In this example, you store the value of the new text field Z_CustomHeaderField as extension data of the basket Business Object. •

The source code for this example is provided by the com.sap.isa.mod.demo1.action.Z_CustomBasketRefreshAction

•

Take a look at the doPerform() method

•

Before you can store extension data you need a reference to the Business Object: // get user session data object. This is used to communicate with the // session context UserSessionData userSessionData = UserSessionData.getUserSessionData(request.getSession()); // get Internet Sales core functionality BOM BusinessObjectManager isaBOM = (BusinessObjectManager)userSessionData. getBOM(BusinessObjectManager.ISACORE_BOM);

•

From the BOM you get an instance of the basket Basket basket = isaBOM.getBasket();

•

Get data from http request String extBasketHeaderData = request.getParameter(‘Z_CustomHeaderField’);

•

Store extension data using the key ' ZEXTENSION': basket.addExtensionData(‘ZEXTENSION’, extBasketHeaderData);

September 2006

38


Retrieving Extension Data from Existing Business Objects Files: •

Struts Action: com.sap.isa.mod.demo1.action.Z_CustomBasketRefreshAction

•

Struts configuration file: \web-inf\config.xml

To test the extension data mechanism, the data stored in the basket Business Object is retrieved and displayed on the console. •

The source code for this example is provided by the com.sap.isa.mod.demo1.action.Z_CustomBasketRefreshAction String test = (String)basket.getExtensionData(‘ZEXTENSION’); System.out.println(‘Value of new basket header field: ‘+ test);

•

To test the Z_CustomBasketRefreshAction, open the \web-inf\config.xml and change the class name of the /b2b/basketrefresh Action:
path=‘/b2b/Z_basketrefre sh.do’/

•


•

Start your application.and check the extension

Displaying Extended Data in JSP Files: •

\b2b\order.jsp

•

Struts Action: com.sap.isa.mod.demo1.action.Z_CustomShowBasketAction

•


You may have noticed that after selecting the Update button, the Z_CustomHeaderField text field in the order.jsp is empty. You have to set the value again before the page is displayed. Since the server-side process flow is interrupted by a JSP it does not make sense to use request.setAttribute() to pass data between the Actions. In this case (see figure below), the considered Actions are MaintainBasketRefreshAction and ShowBasketAction. You have to add a custom Action just before the ShowBasketAction. •

You can find the class for this new Action in com.sap.isa.mod.demo1.action. Z_CustomShowBasketAction

•

The interesting part of this Action is the code sequence, which puts the extended data into the request attribute. This value can be retrieved later on in the order.jsp: String extBasketHeaderData = (String)isaBOM.getBasket().getExtensionData(‘ZEXTENSION’); if (extBasketHeaderData != null) request.setAttribute(‘Z_CustomHeaderField’, extBasketHeaderData);

•

The action is called by the /b2b/frameset_order.jsp

September 2005

39


•

To configure this, add the following entry to the config.xml:

•

In the config.xml, change the path of com.sap.isa.isacore.action.order.ShowBasketAction from /b2b/showbasket to /b2b/Z_showbasket

•

Open the order.jsp. Add the following code to the fir st Scriptlet in the page: String z_extHeaderData = ‘‘; if (request.getAttribute(‘Z_CustomHeaderField’) != null) z_extHeaderData = (String)request.getAttribute(‘Z_CustomHeaderField’);

•

In the order.jsp, go to the Z_CustomHeaderField text field. Add the following attribute to this field: value=‘<%= z_extHeaderData %>‘

After making these changes you have the follow ing process flow:

September 2006

40


Extension Demo 2 – Extensions in the Business Object Layer This demo shows you how to create a Business Object. Note: You usually write your own Business Object if you want to provide some kind of f unction that is not provided by the Internet Sales standard delivery (for example, accessing self written function modules in the SAP CRM system). This unit acts merely as an introduction to creating and accessing a Business Object from an Action.

According to the ISA architecture, an Action acts as an interface between the Business Object layer and the HTTP world. The Business Object layer provides a backend-independent view of the business logic. This means that the additional data has to be processed by an appropriate Business Object before it can be stored in the backend. In this example we will introduce a new Business Object Z_CustomBasket that can store the extended basket data in the Java layer. The Business Object will take over data from the Z_CustomBasketRefreshAction and store it. Files: •

See demo2 examples of the zip-file.

•

Struts configuration file: \web-inf config.xml

•

The Java classes are located in examples_java\src\packages\com\sap\isa\mod\demo2 , package com.sap.isa.mod.demo2

Adding a Business Object Files: •

The Java classes located in package com.sap.isa.mod.demo2.businessobject.Z_CustomBasket

The Business Object is represented by the com.sap.isa.mod.demo2.businessobject.Z_CustomBasket class. It provides a method setExtHeaderData() for storing extended header data and a method getExtHeaderData() for retrieving

extended basket header data. It is important that the Business Object extends the com.sap.isa.core.businessobject.BOBase class. Only this ensures that future framework extension can be utilized by the custom Business Object.

Adding a Business Object Manager Files: •

Business Object Manager: com.sap.isa.mod.demo2.businessobject. Z_CustomBusinessObjectManager

•

Configuration file for customer BOMs: examples_xml_jsp\demo1to4\WEBINF\xcm\customer\modification\bom-config.xml

•

Copy the examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\bomconfig.xml to your customer application \WEB-INF\xcm\customer\modification

September 2005

41

Development and Extension Guide – S AP E-Commerce 5.0 In order to make the Z_CustomBasket Business Object accessible from an Action, you have to add a new Business Object Manger to the framework. W e recommend you provide self-written Business Objects by a custom BOM. •

The source code for the new BOM is represented by the class com.sap.isa.mod.demo2.businessobject.Z_CustomBusinessObjectManager

•

The BOM has to implement the BOManager interface and to extend the DefaultBusinessObjectManager class

public class Z_CustomBusinessObjectManager extends BusinessObjectManagerBase implements BOManager { ... •

Each BOM is recognized by an unambiguous constant. The value of the constant is used in the bomconfig.xml file to register the BOM. In order to be able to access this value programmatically, a constant, containing the values, should be declared in t he BOM class public static final String CUSTOM_BOM = ‘Z_CUSTOM-BOM’;

•

The Business Object is accessed using a getCustomBasket() method. You have to create it if it does not already exist: public Z_CustomBasket getCustomBasket() { if (mCustomBasket == null) { mCustomBasket = new Z_CustomBasket(); } return mCustomBasket; }

•

The next step is to register the newly created Business ObjectManager in the Internet Sales framework by adding the following line in the configuration file: examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\bom-config.xml

file:

September 2006

42


Testing application Files: •

Struts configuration file: \web-inf \config.xml

Before you can test the application, you have to adjust the package name of the custom Actions in the config.xml file. When testing the application there is no visible difference to Demo 1. The only diff erence is that the custom data is stored in the Business Object layer.

September 2005

43


Extension Demo 3 - Extensions in the BLS Layer It is now time to pass the extended header data to the backend system via the BLS layer. A Business Object never communicates directly with a Backend Object. Communication always takes place via an interface. Only this ensures that the Business Object is not aware of the real i mplementation of the Backend Object. When you write a new Backend Object from scratch you have to perform the following steps: •

Write the interface for the Backend Object (e.g. Z_CustomBasketBackend)

•

Write an implementation of this interface (e.g. Z_CustomBasketCRM)

•

Register the new Backend Object as customer extensions in the file

examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\backendobjectconfig.xml

Files: •

•

•

See demo3 examples of the zip-file. Copy logging configuration file log-config.properties from \web-inf\cfg to \web-inf\cfg Configuration file for customer extensions in the BLS layer: examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\backendobjectconfig.xm

•

•

Copy the examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\bomconfig.xml to your customer application \WEB-INF\xcm\customer\modification Struts configuration file: \web-inf\config.xml

•


September 2006

44


Writing Interface for the Backend Object Files: •

Backend Object interface: com.sap.isa.mod.demo3.backend.boi.Z_CustomBasketBackend

The Backend Object has to enable you to read/write custom basket header data fr om the backend system. In order to do this you define the following interface: package com.sap.isa.mod.demo3.backend.boi; public interface Z_CustomBasketBackend { public void setExtHeaderData(String basketId, String orderNumber, String data); public String getExtHeaderData(); }

It is important that the interface is placed in t he backend.boi package and does not have any dependencies from other classes. It must be possible to compile the backend.boi package independent of other packages.

Writing Implementation of Backend Object Interface Files: •

Source code for the Backend Object can be found in: com.sap.isa.mod.demo3.backend.test.Z_CustomBasketTest

In this step you write an implementation of the interface that does not communicate with a real backend. It simply stores the passed data to memory. In this step you: •

Write a Backend Object

•

Register the Backend Object in the backendobject-config.xml file

Later on you will write a new implementation of the interface that stores the custom basket data in the CRM system. You will also see how easy it is t o switch implementations of Backend Objects without having to change anything in the Business Object La yer. The following code demonstrates an implementation of the Backend Object storing additional basket data in memory: •

•

The Backend Object has to be deri ved from BackendBusinessObjectBase, so that it is manageable by the BLS layer. The base depends on the type of backend system. For a CRM system it is, for example, the class: com.sap.isa.core.eai.sp.jco.BackendBusinessObjectBaseSAP . This class provides some very useful methods for communicating with a CRM system. Since the first implementation of the Backend Object will not communicate with any real backend system, it is sufficient to derive from the: com.sap.isa.core.eai.BackendBusinessObjectBase . The Backend Object also has to implement the Z_CustomBasketBackend interface. public class Z_CustomBasketTest extends BackendBusinessObjectBase implements Z_CustomBasketBackend {...

September 2005

45


Registering Backend Object in BLS Layer Files: •

Configuration file for customer extensions in the BLS layer: examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\backendobjectconfig.xml

In this step you register the newly created Backend Object to make it available in t he BLS layer. Add the following entry in the backendobject-config.xml:

Writing a new Backend-Aware Business Object Files: •

Business Object source code: com.sap.isa.mod.demo3.businessobject.Z_CustomBasket

In this step you create a Z_CustomBasket Business Object that is aware of a corresponding Backend Object: •

Since the Business Object has to create the backend via the BLS layer, it must implement the com.sap.isa.core.businessobject.BackendAware interface: public class Z_CustomBasket extends BOBase implements BackendAware { ...

•

This interface has a method setBackendObjectManager(BackendObjectManager bem) . When a Business Object is created, this method is used to assign a Backend Object Manager(BEM) to this Business Object. The Business Object uses the BEM to get a reference to the corresponding Backend Object: public void setBackendObjectManager(BackendObjectManager bem) { this.bem = bem; }

•

The Backend Object is created using the Backend Object Manager. The return value has t o be typecasted to the appropriate interface that provides the business methods ( Z_CustomBasketBackend): private Z_CustomBasketBackend getCustomBasketBackend() { if (backendCustomBasket == null) { //create new backend object try { backendCustomBasket = (Z_CustomBasketBackend)bem.createBackendBusinessObject(‘Z_CustomBasket’); } catch (BackendException bex) { System.out.println(‘Error creating backend object: ‘ + bex); } } return backendCustomBasket; }

September 2006

46


Creating a Backend-Aware Business Object in BOM Files: •

Source code of the Business Object Manager: com.sap.isa.mod.demo3.businessobject.Z_CustomBusinessObjectManager

The BOM derives from com.sap.isa.core.businessobject.management.DefaultBusinessObjectManager . This class implements the BackendAware interface by providing a setBackendObjectManager(BackendObjectManager bem) method. It also comes with the method assignBackendObjectManager(Object obj), which checks if a Business Object is backend-aware and,

if this is the case, automatically assigns a BEM to it. Since the BOM itself is backend-aware it also implements the setBackendObjectManager() method. The MBOM uses this method to assign a reference of the BEM to the BOM.

Testing the Application Files: •


•

Business Object configuration file for customer extensions: examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\bom-config.xml

•

Copy the examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\bomconfig.xml to your customer application \WEB-INF\xcm\customer\modification

Before testing the application do not forget to register the two Actions from package com.sap.isa.mod.demo3 in the config.xml, and the new BOM in the bom-config.xml file. After performing all changes the application should work as before. The only difference is that the extended basket data is stored in the BLS layer and not in the Bu siness Object Layer.

Communication with the SAP CRM system Files: •

Backend Object communicating with SAP CRM system: com.sap.isa.mod.demo3.backend.crm.Z_CustomBasketCRM

•

Configuration file for customer extensions in the BLS layer: examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\backendobjectconfig.xml

•

Copy the examples_xml_jsp\demo1to4\WEB-INF\xcm\customer\modification\ backendobject-config.xml to your customer application \WEBINF\xcm\customer\modification

You write a new Backend Object that stores custom basket data in the SAP CRM system.

September 2005

47


The following customer written function module is used to store the custom data: Function Module Name

Interface

CRM_ISA_ADD_DATA_SAVE

*’ *’ *’

IMPORTING VALUE(BASKET_GUID) TYPE CRMT_OBJECT_GUID_C VALUE(OBJECT_ID) TYPE CRMT_OBJECT_ID

*’

VALUE(DATA) TYPE

TEXT50

It is important to note that when the function module is called, the data is written in the database using the update task, that is, this function does not perform a COMMIT on the database. This has to be done by another function module. •

In the Backend Object the function module is called within the following method (see below). The default JCo connection is used to get an instance of a JCO.Function, and to execute this function. It is important to use the default connection in order to perform the function call in the same transaction context as the calls in the ISA application. When you take a look at t he eai-config.xml file you will see that the basket Backend Object uses the ISAStateful connection as default connectionas well. This is a stateful connection (it is not closed as long as th e client session exists) which is indicated by the implementation class in this connection: com.sap.isa.core.eai.sp.jco.JCoConnectionStateful. public void setExtHeaderData(String basketId, String orderNumber, String data) { try { ... JCO.Function func = getDefaultJCoConnection().getJCoFunction(‘CRM_ISA_ADD_DATA_SAVE’); func.getImportParameterList().setValue(basketId, ‘BASKET_GUID’); func.getImportParameterList().setValue(orderNumber,

‘OBJECT_ID’);

func.getImportParameterList().setValue(data, ‘DATA’); getDefaultJCoConnection().execute(func); } catch (BackendException ex) { log.error(ex); }}

Note: The default connection in the example above, is based on the ISAStateful connection. This connection is not valid before the user has successfully logged on to the application. This is done by the login action. (Please see the web diagram). When the user logs on, the connection definition is completed with the user's password and name. Then a connection to the SAP CRM system is established. From this point in time the connection based on the ISAStateful connection can be used.

•

The next step is to activate the Backend Object by performing some changes in the backendobjectconfig.xml file. In this example it i s assumed that the custom function modules are hosted by the same CRM system as the rest of the application. It uses the ISAStateful connection to communicate with the CRM system.

Note: The ISA application uses the CRM_ISA_BASKET_ORDER function module to create a sales order. This function module is part of the Order Backend Object. It uses the ISAStateful (see \webinf\xcm\sap\modification\backendobject-config.xml file) connection and performs a commit on the database. The commit is performed by the ISA application when an order is created.

September 2006

48

Development and Extension Guide – S AP E-Commerce 5.0 This behavior can be used when calling the CRM_ISA_ADD_DATA_SAVE function module. Since this function module does not write the data in the database directly, the transaction is committed when the CRM_ISA_BASKET_ORDER function module is called. This is the case when the Order now button is selected.

Enabling Logging Files: •

Logging configuration file: \web-inf\cfg\log-config.properties

You will have noticed that the class com.sap.isa.mod.demo3.backend.crm.Z_CustomBasketCRM uses the Internet Sales logging capabilities. •

Before you can view the log entries you have to add the following configuration to the \web-inf\cfg\log-config.properties:

# Location for modification examples com.sap.isa.mod.severity = DEBUG com.sap.isa.mod.logs

= +log[z_custom]

# Logger for modification examples log[z_custom]

= FileLog

log[z_custom].pattern

= %[isa:path]/z_custom.log

log[z_custom].formatter = formatter[isa]

Testing Communication to the SAP CRM System •

Select a product from the catalog, and add it to the basket

•

Create an order

•

In the detail view of the basket, enter a value in t he new text field

•

Choose Update o

•

Choose Order Now o

•

The data is written in the SAP CRM system, but not yet committed

At the end of this process a commit is performed. This also writes the custom data to the database

Check the data in SAP CRM in the table crm_isa_add_data

September 2005

49


Extension Demo 4 – Store Additional Data as Extension Data In this demo, you extend the basket object properly with additional fields. You perform the following steps •

Add a new entry field to a JSP (see demo 1)

•

Insert custom Actions to the process flow

•

Store custom data as extension data in the Business Object

Files: •

See demo4 examples of the zip-file.

•

JSP order.jsp located in \b2b, see demo 1.

•


Note :

The extension is added to the header object in this demo, instead of to the basket object lik e in Demo 1. This is because only header and item extensions will be transferred to the backend.

Action Structure The important point when adding additional fields is: •

The basket data, like the header and items, is not persistent in the frontend and will always be read from the backend, and is cleared after the y it is displayed on the order.jsp page. On the other hand, all data must be firstly read from the order.jsp, before it can be written to the backend. This is done in the method parseRequest from the class MaintainBasketBaseAction.

All Actions that handle basket data inherit from the MaintainBasketBaseAction class and use the parseRequest method to build the basket object. The sales document will be built only in the MaintainBasketDispatcherAction. If you want to extend the basket with your own data, you must extend DispatcherAction with your own action, which overwrites the p arseRequest method. Example /** * Custom action which retrieves additional basket * header data and forwards this data to the * Business Object Layer * You must overwrite the parseRequest action to add your data to the extension * object */ public class Z_CustomBasketDispatcherAction extends MaintainBasketDispatcherAction { /* overwrite parseRequest */ protected void parseRequest( RequestParser parser, UserSessionData userSessionData,

September 2006

50

Development and Extension Guide – S AP E-Commerce 5.0 SalesDocument salesDocument, IsaLocation log) throws CommunicationException {

// first call the super class to parse the standard parameters super.parseRequest(parser, userSessionData, salesDocument, log);

// get the sales document header and change the data HeaderSalesDocument header = salesDocument.getHeader();

// get extended basket header data from the http-request String extBasketHeaderData = parser.getParameter(‘Z_CustomHeaderField’) .getValue().getString(); // set extended data as extended data of the Basket Business Object header.addExtensionData(‘ZEXTENSION’, extBasketHeaderData); }

Changing the Process Flow Replace Standard Action with Custom Action in the Process Flow Files: •


In this step you interfere the original process flow with the custom Action. The Action is called after the MaintainBasketDispatcherAction and replaces the standard Action.

September 2005

51


/b2b/maintainbasket.do MaintainBasketDispatcherAction

/b2b/maintainbasket.do Z_CustomBasketDispatcherAction

[refresh]

/b2b/basketrefresh.do MaintainBasketRefreshAction

[refresh]

[showbasketframe]

/b2b/frameset_order.jsp

[forward]

/b2b/showbasket.do ShowBasketAction

Please note that the ShowBasketAction is called by a frameset JSP. If you want to place your Action before the ShowBasktetAction, you have to change the source code of the frameset_order.jsp. This is not recommended. Try to restrict changes in the Struts framework to the config.xml only. Perform the following steps: •

Open the config.xml file

•

Search in the config.xml for path=‘/b2b/maintainbasket’

•

Replace the class with your own:

•

•

Build and deploy the project. Start your application and test the extension. Each time you update the content of the basket you should see an output on the SAP J2EE server console showing the content of the new text field.

Displaying Extended Data in JSP See demo 1 for further details on displaying extension data in the modified order.jsp page. Here you can see the complete process flow:

September 2006

52


/b2b/maintainbasket.do MaintainBasketDispatcherAction

/b2b/maintainbasket.do Z_CustomBasketDispatcherAction

[refresh]

/b2b/basketrefresh.do MaintainBasketRefreshAction

[refresh]

[showbasketframe]

/b2b/frameset_order.jsp

[forward]

/b2b/showbasket.do ShowBasketAction

[forward]

/b2b/showbasket.do Z_CustomShowBasketAction

[success]

b2b/order.jsp

September 2005

[success]

53


Extension Demo 5 - Displaying additional Document Type on User Interface in ISA CRM This unit shows how to display an additional document type in the ISA product catalog. The following steps have to performed: •

Create a new template for content management folders

•

Create a new catalog type with new folder template

•

Create a new product catalog of new catalog type and assign additional documents

•

Create a new web shop with the new product catalog

•

Extension of ProductDetailISA.jsp to display products in the ISA catalog

Note: This extension is specific to ISA CRM.

Create New Template for Content Management Folders Create a new template for content management folders within the SAP CRM system by selecting: Customer Relationship Manangement -> Basic Fucntions -> Content Management -> Define Templates for Folders •

•

•

Create a new template MANU-MW by copying the template MANU-ITEM. Add a new folder CRM_HIRES. Select properties and assign the new document type CRM_HIRES to the attribute document type.

Save the new template

September 2006

54


Create New Catalog Type for Product Catalogs Create a new catalog type for product catalogs within the CRM system by selecting: Customer Relationship Manangement -> Master Data -> Product Catalogue -> Define Catalogue Type •

Create a new catalog type ZMW by copying the catalog type MANU

•

Assign new areas and items to the template MANU-MW

•

Save the new catalog type

Create New Product Catalog from New Catalog Type Create a new product catalog from the new catalog type ZMW and assign documents/mime objects to additional document type.

Extension of JSP to Display Additional Document in Product Catalog The additional document type should be displayed in product detail view of the product catalog (\catalog\ProductDetailISA.jsp):

September 2005

55


..

‘ width=100 height=100 > ‘ width=100 height=100 > ..

September 2006

56


Extension Demo 6: Copy-Template for Customer Extensions Files: •

See buildtool project extensiontemplate

Note: This example acts as a copy template if you need to execute self-written function modules, or function modules not called by the standard application. You can take this example, copy it, and adjust it t o your own needs. The example implements a Business Object, B ackend Object, and Business Object Manager, and demonstrates how to register these classes in the Internet Sales Framework as a customer extension. Additionally, it demonstrates how to retrieve data from a Business Object and display it in a JSP. The demo provides the following functionality: •

•

A Business Object providing a method to retrieve the description for a given shop id A Backend Object executing the CRM_ISA_SHOP_GETLIST function module, in order to retrieve the description

•

An Action retrieving the data from the Business Object

•

A JSP displaying the description for the given shop id

Working with the Objects The Z_CustomFunc Business Object provides the business logic usi ng the following method: getShopDescription(String shopId)

The reference to the Business Object is obtained from the Z_CustomBusinessObjectManager Business Object Manager by calling: Z_CustomFunc getCustomBasket()

The Z_CustomAction Action uses the Business Object by first getting a reference to the BOM UserSessionData userSessionData = UserSessionData.getUserSessionData(request.getSession()); Z_CustomBusinessObjectManager myBOM = (Z_CustomBusinessObjectManager)userSessionData. getBOM(Z_CustomBusinessObjectManager.CUSTOM_BOM);

And then calling the business logic: String shopDescr = myBOM.getCustomBasket().getShopDescription(shopId);

In order to pass the data to the JSP, the result is assigned to the HTTP Request as attribute: request.setAttribute(‘shopdescr’, shopDescr);

And is retrieved within the JSP: String descr = (String)request.getAttribute(‘shopdescr’);

September 2005

57


Implementation Details «Typ» Z_CustomFuncBackend

+getShopDescription()

«Typ» BackendAware

+setBackendObjectManager() Z_CustomFuncCRM

Z_CustomBusinessObjectManager

+getShopDescription()

Z_CustomFunc 1

+getCustomBasket() +assignBackendObjectManager()

1 +getShopDescription() -getCustomFuncBackend() +setBackendObjectManager()

BackendObjectManager

1

+createBackendBusinessObject()

The Business Object Z_CustomFunc provides the Business Logic via the getShopDescription()method. The implementation of the method just delegates the call to the backend Object Z_CustomFuncCRM via the Z_CustomFuncBackend interface. Before the Business Object is able to delegate the call, i t needs a reference to the Backend Object. This reference is obtained from the BackendObjectManager by calling the createBackendBusinessObjecr() method. (Z_CustomFuncBackend) bem.createBackendBusinessObject(‘Z_Custom’);

The Backend Object Manager knows which class to instantiate as the class is registered in the backendobject-config.xml using the Z_Custom id:

To get the reference to the BackendObjectManager (bem), the Business Object implements the BackandAware interface. When the Backend Object Manager is created in the Z_CustomBusinessObjectManager, it is assigned by calling assignBackendObjectManager(mCustomFunc): private Z_CustomFunc mCustomFunc; public Z_CustomFunc getCustomBasket() { if (mCustomFunc == null ) { mCustomFunc = new Z_CustomFunc(); assignBackendObjectManager(mCustomFunc); }

return mCustomFunc; }

The only thing left is to obtain a reference to t he BOM from the Action. This is done as follows: Z_CustomBusinessObjectManager myBOM = (Z_CustomBusinessObjectManager)userSessionData. getBOM(Z_CustomBusinessObjectManager.CUSTOM_BOM);

The CUSTOM_BOM constant has the value Z_CUSTOM-BOM. This value was used when registering the BOM in bom-config.xml:

September 2006

58

Development and Extension Guide – S AP E-Commerce 5.0 The ISA framework knows now which class to instantiate when the customer BOM is r equested. To obtain a connection to the SAP CRM system the Backend object relies on the I SA framework. The ISA framework only needs to associate the backend object with the JCO connection factory and the ISAStateless (or alternatively ISAStateful for steful connectivity) connection (see above). You get the function module: •

JCO.Function func = getDefaultJCoConnection().getJCoFunction(‘CRM_ISA_SHOP_GETLIST’); •

Set the import parameters: func.getImportParameterList().setValue(‘B2B’, ‘SCENARIO’);

•

Execute the function: JCO.Table table = func.getTableParameterList().getTable(‘SHOPS’);

How to Use the Template for Own Extensions 1.

Copy the files of the template-folder (of the examples-zip-file) to your local application.

2.

You have to add the following action mapping to your config.xml

3.

Run the example and check it works: o

Call application using init.do (an existing session is required for the demo)

o

Call /customdemo.jsp

o

Enter shop id

o

As a result you get the shop description

4.

Import Java classes in your development environment.

5.

Adjust/Extend the classes.

September 2005

59

Report "SAP E Commerce 5.0 Examples"

Your name

Email

Reason

Description

Copyright © 2024 IDOC.TIPS. All rights reserved.
About Us | Privacy Policy | Terms of Service | Copyright | Contact Us | Cookie Policy

Sign In

Email

Password

Remember me Forgot password?

Our partners will collect data and use cookies for ad personalization and measurement. Learn how we and our ad partner Google, collect and use data. Agree & close

: <%= currentItem.getProduct() %>

SAP E Commerce 5.0 Examples

Recommend Documents