Sie sind auf Seite 1von 140

Version 1

Consultants Cookbook
Interaction Center (IC) WebClient
Valid for SAP CRM 4.0 Add-On for Service Industries


September 2004

Please provide feedback:
crm.feedback@sap.com





















Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 2

Table of Contents
0 Introduction....................................................................................................................................................6
1 Interaction Center (IC) WebClient Architecture .............................................................................................7
1.1 Interaction Center (IC) WebClients Architectural Layers ............................................................................7
1.2 Business Server Page (BSP) Architecture.......................................................................................................9
1.2.1 Business Server Page ..................................................................................................................................9
1.2.2 Interaction Center (IC) WebClient BSP Applications...................................................................................11
1.2.3 Navigation ...............................................................................................................................................14
1.3 Additional Information................................................................................................................................16
1.3.1 Debugging Remarks..................................................................................................................................16
1.3.2 Inheritance of Classes and Class Hierarchies...............................................................................................16
1.3.3 Relevant Methods Overview......................................................................................................................17
2 Tutorial: Advanced Customizing...................................................................................................................20
2.1 Configuring the Transaction Launcher........................................................................................................20
2.1.1 System Connection Basic Settings..............................................................................................................20
2.1.2 7 Steps to Include a New Launch Transaction .............................................................................................23
2.1.3 How to Add New Current Objects to the BDC (Modification) ......................................................................41
2.2 Interactive Scripting: Architecture and Configuration.................................................................................42
2.2.1 Interactive Scripting Runtime Architecture .................................................................................................42
2.2.2 Creating New Actions ...............................................................................................................................43
2.2.3 Creating New Templates ...........................................................................................................................46
2.2.4 Creating New Dynamic Content.................................................................................................................50
2.3 Alert Service (Alert Modeler).......................................................................................................................56
2.3.1 Architecture .............................................................................................................................................57
2.3.2 Customizing.............................................................................................................................................57
2.3.3 Creating New Events ................................................................................................................................58
2.3.4 Creating New Alert Classes .......................................................................................................................60
2.4 E-Mail Response Management (ERMS) Enhancements ...............................................................................60
2.4.1 Adding Additional Business Partner Attributes to the ERMS Attribute List ...................................................60
2.4.2 Implementing New Fact Gathering Services and New Attributes ..................................................................62
2.4.3 Implementing Input Support for Industry Sector ..........................................................................................65
2.4.4 Example: Implementing New Action Handler .............................................................................................68
3 Tutorial: Working with Views and View Sets ................................................................................................74
3.1 Preparation .................................................................................................................................................74
3.2 Working with Views ....................................................................................................................................75
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 3

3.2.1 Replacing One Input Field with Another Input Field....................................................................................75
3.2.2 Replacing Input Fields with Dropdown Boxes.............................................................................................81
3.2.3 Adding Buttons to Views...........................................................................................................................84
3.3 Using Different Fields from the Business Object Layer (BOL) in Views .......................................................87
3.3.1 Identifying Business Object Layer (BOL) Objects .......................................................................................88
3.3.2 Identifying and Changing Context Nodes....................................................................................................88
3.3.3 Changing View Layouts ............................................................................................................................90
3.4 Working with Customer-Specific View Sets .................................................................................................92
3.4.1 Creating the View Set and Controllers ........................................................................................................92
3.4.2 Creating the View and Controllers..............................................................................................................94
3.4.3 Adjusting IC WebClient Framework ..........................................................................................................99
Glossary ..........................................................................................................................................................103
4 Appendix A: Business Object Layer (BOL) Programming...........................................................................105
4.1 Business Object Layer ...............................................................................................................................105
4.1.1 Abstract .................................................................................................................................................105
4.1.2 Introduction............................................................................................................................................105
4.1.3 Overview...............................................................................................................................................105
4.1.4 Application Programming Interface..........................................................................................................106
4.1.5 Execution of Entity Methods ...................................................................................................................111
4.1.6 Advanced BOL Programming..................................................................................................................111
4.1.7 Business Error Handling..........................................................................................................................114
4.1.8 Buffering Issues......................................................................................................................................115
4.1.9 Interface Classes.....................................................................................................................................117
4.2 Architecture Details...................................................................................................................................118
4.2.1 Entities ..................................................................................................................................................118
4.2.2 Collections.............................................................................................................................................118
4.2.3 Context Nodes........................................................................................................................................120
4.2.4 Controller Context ..................................................................................................................................121
4.2.5 Data Binding..........................................................................................................................................122
4.2.6 Mixed Context Nodes .............................................................................................................................123
5 Appendix B: Additional Information and Further Examples ......................................................................124
5.1 Extending Existing Views...........................................................................................................................124
5.1.1 Output Formatting ..................................................................................................................................124
5.1.2 Tables (TableViews, Iterators) .................................................................................................................126
5.1.3 Checkboxes and Radio Buttons................................................................................................................129
5.1.4 Button Linking to Websites .....................................................................................................................132
5.1.5 Links .....................................................................................................................................................132
5.1.6 Dynamic View Replacement....................................................................................................................133
5.1.7 Reusing Views .......................................................................................................................................133
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 4

5.2 Error Handling / Messages Display in the ErrorViewSet............................................................................134
5.3 User Interface Design Extras .....................................................................................................................134
5.3.1 Integrating Stylesheets ............................................................................................................................134
5.3.2 Special Cases in the Tray Layout (New Look & Feel)................................................................................134
5.3.3 Tableviews and Overflow Container.........................................................................................................135
5.3.4 F4 Help..................................................................................................................................................135
5.3.5 Tips and Tricks.......................................................................................................................................137
5.3.6 View Sizes .............................................................................................................................................138
5.4 Page Setup What is Where? ....................................................................................................................139
5.5 Transaction Codes .....................................................................................................................................140

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 5


Change History

Version Status / Changes Date
1 New version for SAP CRM 4.0 Add-On for Service
Industries release
September 20,
2004















Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 6

0 Introduction

This cookbook is aimed at members of Interaction Center (IC) WebClient implementation teams, for
example, consultants or project leads. It supplements the CRM 4.0 standard documentation and has the
following structure:

Part 1
Explains the technical concepts and architecture used by the IC WebClient, like Business Server
Pages (BSPs) and the communication between IC WebClients main components.

Part 2
Is a tutorial that provides in depth information on how to make extended use of IC WebClient
customizing tools.

Part 3
Is a tutorial on how to work on views and view sets. The structure of this part is similar to a
customer request. It was tested and implemented by consultants.

For Parts 2 and 3, the following skills are required:
Basic programming skills
Ability to read HTML/XML
Familiarity with SE80 (ABAP Workbench)
Basic understanding of Part 1

Appendix A
Contains in depth information required for Business Object Layer (BOL) programming. Since BOL
programming is not expected to be a usual project task, this section is not included in the main
part of this cookbook.

Appendix B
Contains many valuable and reliable tips on developments that may be useful in customer
projects. This is included, even though it has not been tested with the latest software release, to
provide a starting point for similar changes in your project.

Expect Appendix B to be included in the main part of this cookbook in further editions.

We also recommend the following additional documentation:

IC WebClient Installation Guide
Client Installations for IC WebClient_V1.0.doc
SAP Online Library Documentation (http://help.sap.com)
SAP Solution Manager
Implementation Guide (IMG) Activity Documentation
Release Notes

We would very much appreciate your feedback about this document. Please send your comments to:
crm.feedback@sap.com

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 7

1 Interaction Center (IC) WebClient Architecture
Within this chapter, you will learn about the overall architecture of Interaction Center (IC) WebClient:
Section 1.1 introduces the architectural layers. IC WebClient consists of mainly three Business
Server Page (BSP) applications.
Section 1.2 explains BSP, starting with the underlying design pattern and relevant components.
Section 1.3 provides useful further information.
1.1 Interaction Center (IC) WebClients Architectural Layers
The Interaction Center (IC) WebClient is built to run within a Web browser. Therefore, on the client side it
is only necessary to install a Web browser and maintain its settings. A SAP Graphical User Interface (SAP
GUI) is not necessary.

All data displayed in the Web browser is sent by HyperText Transfer Protocol (HTTP) from the Web
Application Server (Web AS) to the client (the Web browser).

Architecture Schematic


Web services communicate between the Web browser and the mySAP Customer Relationship
Management (CRM) system. Web services are controlled by the Web AS. With the versions of Web AS,
which IC WebClient is built on, it is possible to use Advanced Business Application Programming (ABAP)
and Java equally. In addition, BSP extensions are available, which provide HyperText Markup Language
Business (HTMLB) tags for a consistent look and feel throughout all applications. HTMLB tags include
complex and extensible capabilities which are much more powerful than normal HTML tags.

RFC HTTP(s) XML SOAP
Web Browser Web Application Server 6.20
Internet Communication Manager
Presentation Layer

Business Layer
Business Server Pages (BSPs)
BSP Extensions (such as. HTMLB)
J2EE
Java VM
ABAP
ABAP VM
Backend CRM
HTTP
Web
Services
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 8

The Internet Communication Manager handles all inbound and outbound connections to the Web AS. It is
responsible for caching and works with a great variety of protocols, including:
Simple Object Access Protocol (SOAP)
HTTPs
Simple Mail Transfer Protocol (SMTP)
Remote Function Call (RFC)

The GUI (presentation layer) and the business logic (business layer) are separated in layers so that any
user interface (UI) can request data from the business layer. The presentation layer is based on BSPs,
and the business layer is based on two virtual machines, which can interpret Java and ABAP code at
runtime.

For more information about the Java 2 Platform Enterprise Edition (J2EE), see the corresponding section
of this document. Communication with ABAP systems is accomplished with RFCs.

The following figure illustrates the functions and relationships of the presentation layer and the business
layer in the IC WebClient.

The presentation layer consists of BSPs, which are implemented using a combination of HTML, HTMLB,
ABAP, and JavaScript.

Business Layer
The business layer is divided into two sub layers: the Business Object Layer (BOL) and the Generic
Interaction Layer (GENIL). The model (see Model View Controller design pattern) is assigned to the
GENIL. For more information, see transaction GENIL_MODEL_BROWSER (select component set ALL).
The BOL offers a certain set of objects. There are two main types of objects in the BOL: business objects
(entities) and query services. You can use query services to search for specific business objects within the
BOL.

There are BOL objects for business partner, one order, product master, marketing campaigns, call lists,
IBase, and so on. Each of these BOL objects appears in a tree structure with exactly one root node. The
actual attributes of the BOL objects form the leaves of the tree. You can find an overview of the available
User Interface (UI)
Business Server Page (BSP) +
Extensions
Business Object
Layer (BOL)
GENIL Generic Interaction
Layer (GENIL)
Model
Application Programming
Interface (API)
Presentation Layer
Business Layer
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 9

query services and BOL objects in the BOL browser (Transaction GENIL_BOL_BROWSER, component
set ALL).

The composition of BOL objects is generic and is based on the model of the GENIL. This can be extended
or changed in Customizing. If you add new entries to Customizing, you may need to add new dynamic
relations for the GENIL.

The presentation layer and the business layer are linked together, as BOL objects are bound to attributes
by context nodes of BSP view controllers. To fill the BOL object, the GENIL accesses its particular data
through Application Programming Interfaces (APIs). In this layer, access to different APIs is already
implemented, so the BOL gets clearly defined access to the defined structures. In this way GENIL could
be used for a BOL implementation with Java, for example. For more information on the business layer,
see Appendix A.

The presentation layer is described in more detail in the following sections.

1.2 Business Server Page (BSP) Architecture
1.2.1 Business Server Page
1.2.1.1 Model View Controller Design Pattern

Business Server Pages (BSPs) can be created using different programming paradigms - from the creation
of simple pages with server side scripting to applications that use the Model View Controller (MVC)
paradigm. MVC is a widely accepted design pattern for developing object oriented user interfaces (UI). It
provides an effective way of relating UI layouts to an underlying data model. As the name implies, a MVC
application consists of a model, views and controllers. These are briefly described as follows:

View
The view handles the visual output. It is responsible for rendering the output and relevant UI
controls, such as text fields and push buttons. It is also responsible for accepting user input. All
input is passed to the controller for processing and all output is received from the controller for
rendering.

Controller
The controller handles the interaction logic and provides the link between a view and a model for
a MVC application. A controller receives all keyboard and mouse input from the view. Based on
this input, the controller can decide how to react by either sending the input to the model or
navigating to a different view or some other programmed step.

Model
The model delivers or receives data to or from the controller and applies the relevant business
logic to the data. The model has no reference to a view or a controller it only processes the data
within the context of the model.
Using a business partner as an example, the model fills the relevant attributes of the business
partner object, for example, name or address, where it is processed and saved to the database if
required. Any result is made available to the controller. It is up to the controller to decide how to
react, for example, the result is displayed on the view. The model is not reliant on any specific
controller and this separation means many different UIs could potentially use the same model.

When looking at a BSP MVC application inside the Web Application Builder (Transaction SE80), it is easy
to locate the various views and controllers defined for the application as each has a specific node in the
application tree. Views consist primarily of a layout definition which is mostly implemented in HTMLB, a
SAP tag library.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 10

Controllers consist of a controller definition and the assignment of an ABAP class. The controller logic is
coded inside this ABAP class which is always a sub class of the base BSP controller class. The linking to
the model is done inside the methods of the controller class. The model is not defined as part of the BSP
application in the Web Application Builder.

The Interaction Center (IC) WebClient application has some further specifics that are worth noting. The
first is each view has its own view controller. This controller has exactly the same name as the view, so if
a view called ServHeader.htm exists then a controller called ServHeader.do exists. The ABAP class that
implements this controller can be found in the controller definition or in the view properties.

In addition, IC WebClient includes a special type of view called a view set. This view set calls one or more
other views and displays them in a particular format. This way a number of views can be combined on a
screen in a particular layout. A view set also has a corresponding view controller. The important difference
is seen in the layout where only a grid and calls to other views are defined.

1.2.1.2 Custom Controllers

The IC WebClient also consists of a special type of controller, called custom controllers. These controllers
have a slightly different interface compared to view controllers but the important difference is their
lifespan.

When a view is displayed, the application calls the view controller which is instantiated (an instance is
created of this controller in memory). The controller then instantiates the view and is displayed on the
screen. When the user navigates to a new view and the previous view is no longer visible, both the
controller and the view are destroyed (removed from memory). A custom controller differs in that it is
instantiated as soon as it is required and remains in memory until explicitly destroyed by the IC WebClient
application. It has a lifetime as long as the application is running and this makes it ideal to hold common
data for the application, such as the confirmed business partner or current transaction. A custom controller
normally works with multiple views and view controllers. There is a one to many relationship between
custom controllers and views/view controllers.

1.2.1.3 Contexts and Context Nodes

Contexts and context nodes are the mechanism that links the data entered or displayed on a view to the
model. This linking is referred to as binding. Each data field in a view is bound to a context and context
node.
Data Binding of Context Nodes


Context nodes and contexts are both implemented as ABAP classes. You can find the context nodes quite
easily by looking at the views Page Attributes tab. Here you see some attributes that are assigned to
classes with names that have the suffix CN01, CN02 and so on. Note that not all view attributes are
context nodes. There may be other attributes defined for the view that are used as part of the layout. If
you look at the HTMLB coding within a view, you find an HTMLB input tag. You see the value attribute is
assigned to something that looks like //ContextNode/Attribute. The first part after the // refers to one of the
views context nodes, which is seen on the Page Attributes tab, and the last part after the single / refers to
Layout Controller
Business Object
Layer (BOL)
Advanced
Programming
Interface (API)
Context
Interaction
Layer (IL)
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 11

a context node attribute. A context node can have one or more attributes so there may be a context node
for address and this may provide attributes like street, city, or postal code.

Each context node is part of a context. The context is found by looking at the view controller attribute
TYPED_CONTEXT. Here you find a reference to an ABAP class which implements the context. A context
manages the instantiation of all of its context nodes. This occurs each time a view controller and thus a
view is called. However, as mentioned earlier, when the view is no longer visible it is removed from
memory. This also removes the context and context nodes. This is not desirable as each time a user
navigates from a view all the data is lost. To overcome this we use the custom controllers. Each custom
controller is also linked to a context. Again, this is seen in the class attribute TYPED_CONTEXT on the
custom controller ABAP class. Since the custom controllers have a lifetime that lasts for the application
runtime, the data is preserved.

1.2.1.4 Events

Some user interface elements like buttons can create events, which are processed by the view controller
class. The processing of these events takes place in the method DO_HANDLE_EVENT. If you add your
own button to a view, you need to react to the button press event for your button in this method.

The above described BSP events should not be confused with IC WebClient application events. These
are events that can be triggered and handled by the IC WebClient alerts. These events are described in
the online help documentation. Further documentation on BSP programming can be found in the Web
Application Server documentation, including a tutorial for beginners.
1.2.2 Interaction Center (IC) WebClient BSP Applications
1.2.2.1 Overview

The Interaction Center (IC) WebClient consists of two BSP applications at runtime and three BSP
applications at design time. The three BSP applications of interest are:

CRM_IC (central application)
CRM_IC_RT_REP (runtime repository)
CRM_IC_DT_REP (design time repository)

BSP application CRM_IC is the actual application and runtime repository CRM_IC_RT_REP contains
information about the composition of the application components (view sets, view areas, views) and
information about the navigation, which is determined at runtime. This data is stored in an XML format.
Design time repository CRM_IC_DT_REP includes all data that is not needed at runtime in an XML
format. The runtime and design time repositories are separated for performance reasons.
BSP Application Structure
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 12



1.2.2.2 Design Time Repository

Within a view, or also on a page with process logic, additional views or complete view sets can be called
and displayed. A view set can combine several view areas. A view area consists of a view set or a view.
Several views can be assigned to a view area, but only one view can be shown at the time. The first view
of the list is the default view. This view can be substituted by alternative views at runtime.
In this way, any complex combinations can be nested. The composition of view sets at runtime is taken
from the runtime repository. The resulting view appears in the Web browser.
View Set, View Area, and View

View Set Sample Definition
<ViewSet id="BuPaIdentifyCustomer">
<ViewArea id="businessPartner" views="BuPaSearch BuPaDetail BuPaCreate BuPaSearchB2B
BuPaDetailB2B BuPaContactPersonCreate"/>
<ViewArea id="product" views="BuPaIbaseSearch BuPaIbaseDetail Empty"/>
<ViewArea id="select" views="BuPaEmptySelect BuPaSelectCustomer BuPaSelectIbase
BuPaSelectContactPerson BuPaSelectCPforCustomer"/>
View set
View area
View
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 13

</ViewSet>

This sample is taken from BuPaViewSet.xml. To access this, choose Transaction SE80 and select BSP
Application CRM_IC_DT_REP Pages Fragments. The view set BuPaIdentifyCustomer (Identify
Account) consists of three view areas. The first view area hosts several views, for example, a view to
search for business partners (BuPaSearch), one to create business partners (BuPaCreate), or one to
create a contact person (BuPaContactPersonCreate). Since the view to search for business partners is
the first defined in the view definition, it is the default view.
Flow Modeling (Composition and Navigation)
The general view set of IC WebClient consists of four components. The two top components show the
current business partner, alerts, toolbar, and so on. The component on the left is used for navigation. The
fourth component is the workspace, in which other view sets are displayed, for example, the view set
BuPaIdentifyCustomer, as described above, can be displayed inside the workspace component.
Depending on the application, different views can be displayed within its view areas at runtime. The
workspace can also include a different view set at runtime, for example, an interaction record view set as
defined in IRecViewSets.xml.

The system can substitute views for other views or view sets at runtime. A view can only be used once
within a view set. A view should only appear once in the final view assembly that appears. A view should
not appear in more than one place at a time. However, in the tutorial section of this document, you will find
more details about a workaround to bypass this limitation.

1.2.2.3 Runtime Repository

After the system generates all controllers and views, the runtime architecture that appears below is
created. The main part is central BSP application CRM_IC, which uses different ABAP controller classes
and context classes. Additionally, the view set hierarchy and all navigational links are stored in runtime
repository CRMC_IC_RT_REP. Customizing settings control the general IC WebClient behavior.
Runtime Architecture
SE80 Development objects
ABAP Class Library
BSP Application CRM_IC
BSP View
BSP View
BSP View
BSP Controller
BSP Controller
BSP Controller
ABAP Controller Class
ABAP Controller Class ABAP Controller
Class
Navigation Area
Customizing
IC Runtime Repository
View Set Hierarchy
Navigational Links
Context classes
Context classes
Context classes


To start IC WebClient, the central application has to be executed. The initial BSP, a view or a page with
flow logic, is generated as HTML, sent to the client via HTTP, and displayed in the browser.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 14

Delta handling mechanisms have been implemented to allow for running the application flicker free. In
case you need to run the application without this feature, you can call it via a page with flow logic called
default_no_dh.htm .

The nesting of all single views is described in the section describing the page setup.

For more information about BSP applications, see the SAP Help Portal (http://help.sap.com) SAP R/3
Enterprise Release ABAP Workbench (BC-DWB) BC ABAP Workbench: Tools Web Application
Builder for BSPs Introduction Structure of a BSP Application.
(http://help.sap.com/saphelp_470/helpdata/en/d1/802cfc454211d189710000e8322d00/frameset.htm).

BSP Runtime Framework
BSP
Framework
Application
CL_BSP_WD_VIEW_CONTROLLER
(from CRM_BSP_...
CL_BSP_WD_REP_VIEW
(from CRM_BSP_...
CL_BSP_WD_VIEW_CONTR_EMPTY
(from CRM_BSP_...
CL_BSP_WD_CUSTOM_CONTROLLER
(from CRM_BSP_...
CL_BSP_WD_REPOSITORY
(from CRM_BSP_...
FRIENDS_REL
+REPOSITORY
FRIENDS_REL
CL_BSP_WD_VIEW_MANAGER
(from CRM_BSP_...
CL_BSP_WD_CONTROLLER
(from CRM_BSP_...
CL_BSP_WD_CONTEXT
(from CRM_BSP_...
CL_BSP_WD_CONTEXT_NODE
(from CRM_BSP_WD)
+parent
+mapSource
CL_BSP_CONTROLLER
(from SBSP_RUNTI...
CL_BSP_MODEL
(from SBSP_RUNTI... ...
CL_BSP_CONTROLLER2
(from SBSP_RUNTI...
+OWNER
CL_<BSP_APPL>_<VIEW>
<<generated>>
CL_<BSP_APPL>_<VIEW>_IMPL
<<implementation>>
CL_<BSP_APPL>_>CONTROLLER>
<<generated>>
CL_<BSP_APPL>_<CONTROLLER>_IMPL
<<generated>>
CL_<BSP_APPL>_<VIEW/CONTROLLER>_CTXT
<<generated>>
CL_<BSP_APPL>_<VIEW/CONTROLLER>_CN<nn>
<<generated>>
0..n 11 0..n


The figure above illustrates the runtime architecture with all corresponding classes.
The gray bar at the top describes the BSP part. These are classes that offer basic functions to control
BSPs. The blue bar in the middle shows framework classes. These classes control views or custom
controllers, describing the context and its corresponding context nodes, and so on. The orange bar at the
bottom describes the application. These are generated classes, which inherit the appropriate capabilities
from the framework classes.

The names of the classes consist of the central application name (CRM_IC) and the corresponding view
names. For the view controller class and custom controller class, an additional implementation class is
created, to ensure that existing coding (such as programmed event handler) is not overwritten at new
generation. These classes are named with the suffix _IMPL.

1.2.3 Navigation

Navigation among single views takes place via navigational links. These are stored in the runtime
repository and are evaluated at runtime. A navigational link consists of an explicit identifier, a source view,
an outbound plug, target views and their inbound plugs.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 15

Navigation Entry Sample in the Runtime Repository

<NavigationalLink name="SoBasketEvPastOrders">
<Source viewRef="SoBasket" outboundPlugRef="outboundPlug"/>
<Targets>
<Target viewRef="SoHist" inboundPlugRef="inboundPlug"/>
</Targets>
</NavigationalLink>

Navigation Flow

Event
(such as clicking a button)
DO_HANDLE_EVENT
Outbound Plug
OP_SOBASKETEVPASTORDERS
Inbound Plug
IP_INBOUNDPLUG
Display View


The navigation call is implemented as a method of the view controller class of the view that the user
leaves. The user leaves the view via a corresponding outbound plug. This is also a method of the view
controller class, which could include instructions to be executed before leaving the view.
Outbound Plug Method

METHOD op_sobasketevpastorders .
view_manager->navigate(
source_rep_view = rep_view
outbound_plug = 'SoBasketEvPastOrders' ).
ENDMETHOD.


Inbound Plug Method
METHOD ip_inboundplug .
...
ENDMETHOD.


A view is called by an inbound plug, which is a method of the view controller class of the target view.
Again it is possible to include instructions, which are executed before displaying the view. User interface
(UI) elements such as buttons can trigger events, which are processed by a view controller class. For
more information, see the Alerts section.

At this point, the underlying
navigation is executed
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 16


1.3 Additional Information
1.3.1 Debugging Remarks

While developing, the application often has to be debugged. This is not always trivial, especially when it
comes to the debugging of object instances where it is difficult to retrieve the necessary data because of
the debugger.

The debugger reports an addressing problem when you double-clicked an instance of an object with the
message Invalid System Rudi. Normally not all the attributes of an instance are equally important. Those
of major importance are listed in the figure above. Problem is fixed!

If you want to analyze the entity collection (attribute entity_list of the class CL_CRM_BOL_BO_COL and
CL_CRM_ENTITY_COL respectively) of a collection wrapper instance, you will encounter the described
addressing problems of the debugger. As a workaround, you can directly address the desired attribute.
The object instance of the collection wrapper which cant be addressed by the debugger is extended with
the attribute. By adding the -entity_list to the object instance the addressing problem of the debugger can
be avoided.

A second example describes the access to individual data of an entity. The data is stored in the container
object (CL_CRM_GENIL_CONTAINER_OBJECT) and accessed by attribute data_ref. By appending the
desired attribute, the addressing problem of the debugger is bypassed again.

In order to debug, HTTP debugging must be enabled with Internet Protocol (IP) matching for the
respective user.
http://help.sap.com/saphelp_webas620/helpdata/DE/17/00ab3b72d5df3be10000000a11402f/content.htm)

- Development Workbench (Transaction SE80):

Tools->setting, Popup user specific settings, Tab ABAP Editor, sub tab HTTP-Debugging,
activate global for your user, or
Tools -> Breakpoints->For HTTP-user (de-)activate.

In order to debug the JavaScripts on HTML-pages, the JavaScript Debugger has to be installed in the
Internet Explorer.
Use the following link to find it:
http://msdn.microsoft.com/downloads/default.asp?URL=/downloads/sample.asp?url=/MSDN-
FILES/027/001/731/msdncompositedoc.xml


1.3.2 Inheritance of Classes and Class Hierarchies

Some parts of the BSP inherit from different ABAP classes:

View controller CL_BSP_WD_VIEW_CONTROLLER
Custom controller CL_BSP_WD_CUSTOM_CONTROLLER
Context node CL_BSP_WD_CONTEXT
Value node, model node CL_BSP_WD_CONTEXT_NODE
Model node with table view CL_BSP_WD_CONTEXT_NODE_TV
Tree base context nodes CL_BSP_WD_CONTEXT_NODE_TREE
Tree nodes CL_BSP_WD_TREE_NODE_PROXY

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 17

Class Hierarchy of Views or Custom Controllers

CL_BSP_CONTROLLER Controller basis class

CL_BSP_CONTROLLER2 Business Server Page (BSP) component

CL_BSP_WD_CONTROLLER Basis class for WD controller


CL_BSP_WD_VIEW_CONTROLLER CL_BSP_WD_CUSTOM_CONTROLLER
Basis class for WD view controller Basis class for WD custom controller

Class Hierarchy of Value Nodes or Model Nodes with Table Views

CL_BSP_MODEL Business Server Page (BSP): model basis class

CL_BSP_WD_CONTEXT_NODE Context

CL_BSP_WD_CONTEXT_NODE_TV Context node for binding to table views

The lifetime of a custom controller starts as soon as a view with a context node bound to this custom
controller is displayed. When the system calls a view, an instance of the view controller is first created.
This instantiates the context, which creates the instances of the single context nodes.
1.3.3 Relevant Methods Overview
Creation and Deletion of Custom Controllers

GET_CONTROLLER and
CREATE_CONTROLLER
Business Server Page (BSP) base methods to get
or create a controller instance. In our framework,
you must use the GET_CUSTOM_CONTROLLER
method instead.
GET_CUSTOM_CONTROLLER Call this method to obtain the instance of a specific
custom controller.
DELETE_CONTROLLER BSP base method to delete a controller instance. In
our framework, you must use the
DELETE_CUSTOM_CONTROLLER method
instead.
DELETE_CUSTOM_CONTROLLER

Call this method to delete the instance of a specific
custom controller.

Creation and Deletion of View Controllers

WD_VIEW_INITIALIZE This method is called to initialize a view on the framework
side. Don't redefine this method. Use the controller
replacement in the RF profile customizing or, if some
dynamics is necessary during runtime, the
DO_REPLACE_INITIAL_VIEW method to adapt the view area
content to your needs. Don't call this method yourself.
BIND_VIEW Binds a view to a view area of a view set. Don't redefine or
call this method yourself.
DO_REPLACE_INITIAL_VIEW This method can be redefined in the implementation class to
override the view which is displayed as default in a view area.
The default is taken from the runtime repository and can be
replaced dynamically by implementing this method. This is
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 18

useful for a customizing-based initial view or if the initial view
is dependent on the context content. Be aware that the
replacing view has to be defined as content for the same view
area of the same view set!

Initialization and Cleanup of Contexts

WD_CREATE_CONTEXT

The method is called once when a custom controller is
instantiated or, for view controllers, each time the view
becomes visible. The purpose is to create and initialize the
context from a framework perspective. You should not
redefine that method, but rather use DO_INIT_CONTEXT
which is exactly made for that purpose. If you already have
redefined the method (as the DO_INIT_CONTEXT is relatively
new), the IC workbench wizards will fail on this views.
DO_INIT_CONTEXT

This method is called once when a custom controller is
instantiated or, for view controllers, each time the view
becomes visible to initialize the view controller context
according to the application's needs. This method is called by
WD_CUSTOM_CONTROLLER_INIT or
WD_VIEW_INITIALIZE after all the framework initialization is
done. You should redefine it in your controller implementation
class.
DO_VIEW_INIT_ON_ACTIVATION This method is called each time a view becomes visible to do
some not context related initialization of the controller. It is
called from WD_VIEW_INITIALZE right after
DO_INIT_CONTEXT.
WD_DESTROY

This method is called to destroy the context of a controller.
For view controllers, this happens each time the view
becomes invisible. It is used within the framework and can't
be redefined. It is also called when a custom controller
instance is deleted.
DO_CLEANUP_CONTEXT This method is called to clean up the context of a controller.
For view controllers, this happens each time the view
becomes invisible. It is called by WD_DESTROY before the
framework destroys the controller's context to allow a
controller to cleanup its content internally. It should be
redefined in the implementation class.
WD_DESTROY_CONTEXT

This method is called to destroy the context of a controller.
For view controllers, this happens each time the view
becomes invisible. It is used within the framework and can't
be redefined. It is called by WD_DESTROY after
DO_CLEANUP_CONTEXT.

Request Processing (Each Roundtrip)

DISPATCH_INPUT

This is called by the viewmanager only to dispatch the input to
all the active view controllers. Don't call this method or
redefine it.
DO_HANDLE_DATA

This is called by DISPATCH_INPUT to process the input data
of the controller of the incoming request. The default
implementation calls the FILL_MODEL_DATA method which
distributes the input to all the context nodes (models in the
sense of BSP) which are part of the controller's context. It can
be redefined to implement a specific logic to process incoming
data. In general it is not recommended to redefine this
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 19

method!
DO_HANDLE_EVENT

Is generated in your generated specific controller class to
handle the events, for example, button pressed, and to
dispatch to the modeled event handlers. It might be necessary
to be redefined according to your controller specific needs, for
example, to dispatch additional events..
DO_REQUEST

Implemented in the view controller base class to create and
display the view (layout class). It should not be redefined.
Internally calls the methods DO_PREPARE_OUTPUT and
SET_MODELS.
DO_PREPARE_OUTPUT This method is called on each round trip before the context
data is set to the view. You may redefine this method to
additional data manipulations right before the data is
displayed.
SET_MODELS

This method binds the context nodes to the view layout
instance's page attributes for rendering. Method
implementation is generated in the specific controller
generated class. Can be redefined in the implementation to
set additional page attributes if necessary.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 20

2 Tutorial: Advanced Customizing
In this section, you learn about making extended use of standard customizing tools:
Section Configuring the Transaction Launcher focuses on the navigation bar and transaction
launcher
Section Interactive Scripting: Architecture and Configuration is dedicated to interactive scripting
Section Alert Service (Alert Modeler) explains the alert modeler
All offer wizards or editors as tools to use on a project. The following chapters go beyond standard use of
these tools and explain how more complex requirements are accomplished.

2.1 Configuring the Transaction Launcher

You can use the transaction launcher and the transaction launcher profile, which is part of the IC
WebClient profile, to start SAP GUI for HTML transactions via the Internet Transaction Server (ITS) from
both Enterprise R/3, SAP CRM, IS-U, People-Centric User Interface (UI) transactions from SAP CRM, IS-
U front-office processes form IS-U and URL based transactions from external applications or SAP
Systems. Agents have access to launch transactions from the IC WebClient navigation bar.

For more information, see the SAP Help Portal (http://help.sap.com/) mySAP Business Suite SAP
Customer Relationship Management <relevant release and language> Getting Started with SAP
CRM Getting Started with the Interaction Center Interaction Center WebClient Transaction
Launcher.

2.1.1 System Connection Basic Settings

In order to launch transactions, the IC WebClient needs to know which system to call. This call is based
on logical systems and a number of mappings.
Transaction
Launcher
Item 1
Mapped
Log System
(MLS)
ID
Class
Item 2
...
Log System
Definition (BD54)
Mapping method
calls (BD97)
RFC Destin.
(SM59)
Assign log sys to
client (SCC4)
done in target
system
done in CRM IC
system
must
match
Navigation Bar
Setup
Handler
class
Mapping of MLS to
Log System
(CRMS_IC_CROSS_SYS)
Extend method
PREPARE_DATA_FLOW
Redefine
PROCESS_RETURN
.


Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 21

2.1.1.1 Defining and Maintaining the Logical System

IMG: Customer Relationship Management CRM Middleware and Related Components
Communication Setup Setup Logical System Define Logical System.
Transaction: BD54

The distribution of data between systems requires each system within a network to have a logical system
ID.





2.1.1.2 Defining the Remote Function Call (RFC) Destination

IMG: Customer Relationship Management CRM Middleware and Related Components
Communication Setup Define RFC Destinations.
Transaction: SM59 Create.

RFC is the method of choice to connect to SAP R/3 and SAP CRM systems.
1. Use Transaction SM59 to create your RFC destinations.
2. Choose a name for the RFC connection and choose a connection type.
3. Use R/3 connection for SAP R/3 and SAP CRM systems.
4. Choose Enter.
5. Depending on the connection type, maintain additional fields.

For more information, see IMG activity documentation.




Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 22

It is important that the RFC destination allows access without requiring a logon screen. During the
execution of IC WebClient, it is not possible to display the SAP GUI based logon, therefore no
connection is possible.

2.1.1.3 Connecting the RFC Destination to the Logical System as a Standard BAPI Destination

IMG: SAP Web Application Server SAP Web Application Server Application Link Enabling (ALE)
Sending and Receiving Systems Systems in Network Synchronous Processing Determine RFC
Destinations for Method Calls.
Transaction: BD97

RFC destinations are assigned to logical systems using a tree graphic that can display all the logical
systems of the whole system. The RFC destinations assigned to each logical system can be displayed.

For more information, see IMG activity documentation.






These settings are not transported in the change and transport system. You must make the
settings in each system.


2.1.1.4 Assigning Logical Systems to the Client

IMG: Customer Relationship Management CRM Middleware and Related Components
Communication Setup Setup Logical Systems Assign Logical Systems to Client.
Transaction: SCC4






These settings cannot be transported. When a new system is being set up, these settings must be
made after the system installation is completed.

For more information, see IMG activity documentation.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 23


2.1.1.5 Defining Logical Systems for the Transaction Launcher

SAP Menu: Interaction Center Interaction Center WebClient Administration System Parameters
Define Transaction Launcher Logical Systems and URLs.
Transaction: CRMS_IC_CROSS_SYS



For more information, choose HelpApplication Help or see the SAP Help Portal (http://help.sap.com/)
mySAP Business Suite SAP Customer Relationship Management <relevant release and language>
Getting Started with SAP CRM Getting Started with the Interaction Center Interaction Center
WebClient Transaction Launcher Defining Transaction Launcher Logical Systems and URLs.

2.1.2 7 Steps to Include a New Launch Transaction
Some of the following steps differ depending on if the transaction is based on People-Centric UI, BOR
methods, IS-U Front Office processes, or URLs.

For People-Centric UI based transactions, the BOL is used to create the respective object in the
background before accessing it in edit mode in the UI. In order to do this, the mapping to the underlying
BOR objects has to be set up. In addition, there is no common definition for input parameters, so there
might be additional effort required to provide parameters to the underlying BOR objects.

For URL based transactions, you also have to define the URL by specifying its target, texts, and
parameters. For more information, see IMG activity Define URLs and Parameters, transaction
CRMC_IC_LTX_URLS).

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 24

7 Steps to include a new transaction
1
2
6
7
BOR based PCUI/BOL based
Transaction Launcher
Wizard
OPTIONAL: Edit Transaction Laucher Profile XML (e.g. to copy, delete, etc.)
Enhance BOL/BOR Mapping XML
if necessary
Input parameters in
PREPARE_DATA_FLOW
OPTIONAL: Handle return parameters in
PROCESS_RETURN
OPTIONAL: Wrap objects, define object linking in Activity Clipboard Profile XML
Assign to Agent Profile
Define in Navigation Bar Profile
3
3b
4
5


These steps are used in the following example of adding a complaint transaction in People-Centric UI and
a quotation in SAP R/3.

2.1.2.1 Step 1: Add an Entry to the Navigation Bar Profile

IMG: Customer Relationship Management Interaction Center WebClient Navigation Bar Define
Navigation Bar Profiles (Wizard).

First you decide where the transaction should be included in the navigation bar. You include it in the
navigation bar profile.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 25



The resulting navigation bar profile looks like this:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 26


2.1.2.2 Step 2: Enhance BOL/BOR Mapping XML if necessary (People-Centric UI only)

The launching of a People-Centric UI transaction is a two step process. First, the new object is created in
the background, then it is presented to the agent in edit mode.

The BOL entity factory is used to facilitate the creation of a new object. As the BOL layer is agnostic to the
BOR objects, these have to be mapped to each other. For the create action, the right BOL type, for
example, BTOrder, for one order based objects, has to be determined for a certain BOR type, for
example, BUS2000120, a complaint. For a successive launch of the transaction from the activity
clipboard, the BOR object has to be determined from the BOL layer, as the clipboard is based on BOL.
This is a more complex transformation which is done using the KEYSOURCEMAPPERCLASS class. In
order for this to work correctly, for each BOL type there should be only one mapper class, for example, for
BTOrder it is CL_CRM_IC_MAP_BTORDER_TO_BOR.

In our example, the mapping for the complaint is already present in the mapping XML. To verify this, we
look at the mapping XML by calling transaction CRMC_XMLEDITOR. We enter MI in the Component ID
field, leave the MF empty and choose Enter. In the resulting screen, choose ICBOLTOBORMAPPING as
the Profile Name. You should see something like this:



In case the mapping is not yet available, add an item by copying from an example and adjusting the
parameters. For BTOrder based types you should use the existing mapper class.

If you have a new type of BOL object you would have to implement a new mapping class which must
implement the interface IF_CRM_IC_COL_BOR_MAPPER and its method CONVERT_BOL_TO_BOR.
2.1.2.3 Step 3: Maintain the Transaction Launcher Wizard
IMG: Customer Relationship Management Interaction Center WebClient Transaction Launcher
Configure Transaction Launcher (Wizard).

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 27

The transaction launcher wizard offers a comfortable way to set up the most common settings for a new
transaction. It automatically creates the entries in the transaction launcher profile as well as creates the
handler class with the respective methods.


When you enter the wizard to edit a transaction, only three of those methods will be overwritten,
all other changes will remain untouched. If you made changes to the BOR layer, you might need
to delete the transaction and create it from scratch to make sure these changes are reflected in
the generated methods.

For more information, see the IMG activity documentation.

2.1.2.4 Example: Creating a SAP R/3 Quotation Transaction

We start the wizard and after specifying the necessary parameters, for example, providing the name of the
handler class you want the wizard to create, see the following:



After choosing the CREATE method from the quotation BOR object, the next screen lets us select the
parameters to pass:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 28



In our example, the parameters are Transaction Code and Sales Document Type. You can also use
parameters which can be mapped against object keys from the BDC context. To map against those,
choose the F4 help for the value.

2.1.2.5 Example: Creating a People-Centric UI Complaint Transaction

When selecting People-Centric UI Transaction as the Transaction Launcher Type, you see the following:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 29





After specifying all parameters and going through the next steps, the wizard creates the class for you. The
following example is the class for complaints:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 30




Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 31



2.1.2.6 Step 3a: Edit Transaction Launcher XML (Optional)
The wizard only creates transactions and the classes for you. If you want to copy profiles or part of
profiles, delete items from a profile, and so on, you can use the edit transaction in Customizing.

2.1.2.7 Step 4: Pass Input Parameters in PREPARE_DATA_FLOW (Optional, Typically only
People-Centric UI)
When starting a transaction, or creating an object in case of People-Centric UI, you might want to pass in
parameters from either the BDC context or some other custom source. In the case of SAP R/3
transactions, you can typically set this up using the wizard, but for People-Centric UI you will often need to
do it manually.

The transfer of additional parameters, for example, the business partner ID, is explained in the following,
using complaints as an example.

To modify the class created in the wizard:

1. Use transaction SE24 to change the class.
2. Make the following addition in the method
IF_CRM_IC_ACTION_HANDLER~PREPARE_DATA_FLOW:

method IF_CRM_IC_ACTION_HANDLER~PREPARE_DATA_FLOW .

data: __bdc type ref to cl_crm_ic_cucobdc_impl,
__source type string,
__line type string.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 32

********** Begin of parameter declaration ***********

data: entity type ref to cl_crm_bol_entity,
pt type crmt_name_value_pair_tab,
p type crmt_name_value_pair.

********** End of parameter declaration ***********

__bdc ?=
gv_view_controller->get_custom_controller( 'CuCoBDC' ). "#EC NOTEXT


p-name = 'PROCESS_TYPE'. "#EC NOTEXT
p-value = 'CRMC'. "#EC NOTEXT
append p to pt.

me->gv_entity = me->create_entity( iv_bortype = gv_bortype
it_params = pt ).

***begin of manual extension *****
data: adm_h type ref to cl_crm_bol_entity,
partners type ref to cl_crm_bol_entity,
partner type ref to cl_crm_bol_entity,
partner_no type string,
core type ref to cl_crm_bol_core.

if me->gv_entity is bound.
core = cl_crm_bol_core=>get_instance( ).
try.
adm_h = me->gv_entity->get_related_entity( 'BTOrderHeader' ). "#EC NOTEXT
if not adm_h is bound.
* When creating BTOrder, the header is already created, but ...
adm_h = me->gv_entity->create_related_entity( 'BTOrderHeader' ).
"#EC NOTEXT
endif.
try.
partner_no = __bdc->get_xpath_property_as_string(
'//currentCustomer/BP_Number' ).
catch: cx_crm_bdc_no_data, cx_crm_bdc_xpath_error.
endtry.
if not partner_no is initial.
partners = adm_h->get_related_entity( 'BTHeaderPartnerSet' ).
if not partners is bound.
partners = adm_h->create_related_entity( 'BTHeaderPartnerSet' ).
endif.

partner = partners->create_related_entity( 'BTPartnerAll' ).
partner->set_property( iv_attr_name = 'PARTNER_FCT'
iv_value = '00000001').

partner->set_property( iv_attr_name = 'MAINPARTNER'
iv_value = 'X' ).

partner->set_property( iv_attr_name = 'PARTNER_NO'
iv_value = partner_no ).
endif.

catch: cx_crm_genil_model_error, cx_crm_genil_duplicate_rel.
*Error handling
endtry.

core->modify( ).
endif.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 33

***End of manual extension *********
me->persist_entity( me->gv_entity ).

if me->gv_entity is bound.
me->gv_data_flow_complete =
me->add_bor_data_to_url( iv_entity = me->gv_entity
iv_bortype = gv_bortype ).
else.
me->gv_data_flow_complete = abap_false.
endif.

endmethod.


The method create_entity opens a new transaction, if required, and creates the entity instance with the
help of the BOL entity factory. The BOL type is determined by the BOR type. For this, the mapping
defined in the XML profile ICBOLTOBORMAPPING is required.

The method persist_entity triggers save and commit and starts a new transaction. This is necessary
because People-Centric UI applications run in a different session and only the BOR key and type can be
transferred.

If you add additional data to the entity instance, this must be done between the two methods.
In the figure above, the additions have been made between begin of manual extension and end of manual
extension.

For the opportunity and lead, examples in the system are implemented and delivered in the default
transaction launcher profile:

Classes:
CL_CRM_IC_ABOXSAMPLE_OPPT_PRO
CL_CRM_IC_ABOXSAMPLE_LEAD_PRO



Do not regenerate these classes (using the wizard) or manual extensions will be lost.

2.1.2.8 Step 5: Handle Return Parameters in PROCESS_RETURN (Optional)
Only the key of the processed BOR object and the value of the default attribute are returned by the BOR-
based transaction launcher. However, it is possible to transfer the complete BOR container. This is made
possible by modifying the generated transaction launcher class.

Necessary changes:

1. Redefine method IS_RETURN_CONTAINER_REQUESTED to return true.
2. Redefine the method PROCESS_RETURN. Add code to receive and process the container.
3. The utility class CL_CRM_IC_ACTION_BOR_UTIL makes the method
GET_PROCESSED_CONTAINER available, which draws the BOR container from an HTTP
call/request.

URL based launch transactions have no generated support for data return. All that is generated are
statements to retrieve the data from the request, but nothing else.

The following example is based on a URL transaction that starts a simple BSP page doing nothing other
than returning a one order GUID to IC WebClient.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 34



The customizing for the URL defines a return parameter with name crm_guid.



The wizard generates the following coding for method PROCESS_RETURN:

method IF_CRM_IC_ACTION_HANDLER~PROCESS_RETURN .


data: lv_value type string,
lv_name type string.

* Create return data flow instance
super->if_crm_ic_action_handler~process_return( iv_request ).
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 35



* Process return parameters


concatenate me->gv_view_controller->component_id '_'
'crm_guid'
into lv_name.

lv_value = iv_request->if_http_entity~get_form_field( lv_name ).

endmethod.

The defined return parameter is retrieved from the request, but nothing happens with that information.
Apply the following changes to create an instance of an one order entity and add the entity to the activity
clipboard.

method if_crm_ic_action_handler~process_return .


data: lv_value type string,
lv_name type string.

* Create return data flow instance
super->if_crm_ic_action_handler~process_return( iv_request ).


* Process return parameters

concatenate me->gv_view_controller->component_id '_'
'crm_guid'
into lv_name.

lv_value = iv_request->if_http_entity~get_form_field( lv_name ).


********** START OF CUSTOM CODE **********


data: lv_entity type ref to cl_crm_bol_entity,
lv_core type ref to cl_crm_bol_core,
lv_class type seoclsname,
lv_bol_type type crmt_ext_obj_name,
lv_guid type crmt_genil_object_guid,
ls_bor type borident.

data: bdc type ref to cl_crm_ic_cucobdc_impl.


bdc ?= gv_view_controller->get_custom_controller( 'CuCoBDC' )."#EC
NOTEXT
if bdc is bound.

lv_guid = lv_value.
lv_core = cl_crm_bol_core=>get_instance( ).
try.
lv_entity = lv_core->get_root_entity( iv_object_name =
'BTOrder'
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 36

iv_object_guid = lv_guid
).

bdc->activities->if_bol_bo_col~add( lv_entity ).

catch cx_crm_genil_model_error.
clear lv_entity.
endtry.

endif.

********** END OF CUSTOM CODE **********


endmethod.


Sample BSP application and page for data return:

The page layout contains a form that will be submitted back to IC WebClient. It contains an input field for
the GUID of the one order to be added to the activity clipboard:



The page attributes COMPONENT_ID, GUID and ICRETURNADDRESS are filled by the launch
transaction.



The Auto flag must be selected.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 37



The OnRequest event handler constructs the return URL and adds the parameters needed to link the
returned data with the launch transaction that started the process.



The following slide describes how data can be returned from an URL based transaction.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 38




1. At runtime, parameters defined to return data are added as hidden input fields to the
ABoxExecution view. Return data is limited to those fields.
2. Determined by the inbound plug, the source for the iframe is set. In case parameters are
transferred via the URL, they have been added. If there should be a form/submit, then the iframe
source is set to page GenericLTXExecutionURL.htm. This page requests the form target and the
body from the handler.
a. In addition to transaction specific data, a GUID and the COMPONENT_ID of
ABoxExecution.htm are passed. The GUID identifies the transaction handler instance.
The COMPONENT_ID is needed to build the name of the button that has to be clicked in
order to trigger a round trip.
b. The launch transaction handler also adds parameter ICRETURNADDRESS which
contains the URL for GenericLTXResult.htm.
c. To prevent confusion between the client where the URL points to and the client to which
data should be returned, parameter ICRETURNCLIENT is used instead of sap-client to
transmit the client in which IC WebClient is running. It is the responsibility of the targeted
application to send the client information back via parameter sap-client. This of course
only applies if IC WebClient does not run in the default client.
3. Assemble return data, including GUID and COMPONENT_ID, send it to GenericLTXResult.htm.
4. GenericLTXResult.htm takes the received parameters and tries to fill them into the hidden form
fields created.
5. Execute a click on button ReturnFromBOR in ABoxExecution to trigger a round trip and
navigation to the interaction record (if not changed by the handler). This in turn triggers the
destruction of ABoxExecution and the execution of the handlers process_return method.

It is the task of the called application to return data via a form/submit to page GenericLTXReturn.htm.


Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 39

2.1.2.9 Step 6: Adjust Interaction with Activity Clipboard (Optional)


If the BOL/BOR object combination is already customized, you dont have to use this step.

The activity clipboard can display all entities that are contained in the activity collection of the BDC. The
activity clipboard Customizing determines which objects are displayed.

Each object that is to be displayed and linked to must be defined in the XML-based Customizing. The
Customizing profile has three main sections:


<profile>
<objects>

</objects>
<sources>

</sources>
<wrappers>

</wrappers>
</profile>

The section <objects> describes for each object which link should be used, how the object should be
displayed once selected, how the object should be linked during the event InteractionAfterEnd, as well as
how it is restored when a historic interaction record is called.

In our example, the entry for the complaint in the activity clipboard appears as follows:



Two new attributes to the object tag for the CRM 4.0 Add-On for Service Industries:
determinationClass
compareValue

They are used to differentiate entries which would otherwise appear to be of the same object type, for
example, same id and same wrappedObjectType. Classes that are specified under determinationClass
must implement interface IF_CRM_IC_AC_DETERMINATION. To determine which customizing entry
belongs to which entity, the activity clipboard executes method
IF_CRM_IC_AC_DETERMINATION~DETERMINE_COMPARE_VALUE and compares its return value to
the value specified in compareValue. If the object id, the wrappedObjectType, and the compareValue
match, then the corresponding Customizing entry is used for the processed entity.
2.1.2.10 BOR-Based Objects

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 40

BOR objects require special processing before they can be displayed in the activity clipboard. Their object
ID is always ICBORWrapper, the attribute wrappedObjectType contains the BOR type. A generic view
was created to display all BOR objects. (These objects must possess a display method.)
To use the view, the navigational link attribute must be IRecGoToIRecBORViewer.

2.1.2.11 People Centric-UI Application Based Objects

Objects that do not have their own view in IC WebClient can be displayed in the People-Centric UI
application. For this purpose, a generic view was created. To use the view, the navigational link attribute
must be IRecGoToIRecPCAViewer.

Object Linking

The definition of object linking is optional. If it is not defined, the object is not linked and is not reloaded
after a historic interaction record is called. As the activity collection can only contain BOL objects and the
BO links only work with BOR objects, a mapping must be performed.

Tag/Attribute Description
Id BOL object type
AttributeWithWrappedTypeXPath
Specifies which attributes of the BOL object
contain the data required to differentiate the
individual wrapped objects. The attribute could
again be defined by an XPath using 1:1
relations.
AttributeWithWrappedDescriptionXPath Specifies the attribute that is displayed in the
description column.

For the complicated mapping requirements, a mapping class must be defined that implements the
interface IF_CRM_IC_BOL_BOR_MAPPER. The following describes a mapping class. You can display
the complete list of mapping classes for the interface by using the Where Used List.

Mapping of BOR Objects

BOR objects must be wrapped in a special BOL object so that they can be included in the activities
collection of the BDC. As soon as the BO link is created, the BOR information from the BOL Wrapper
must be delivered. A similar functionality must be called when a historic interaction record is called.
Class : CL_CRM_MAP_WRAPPER_BOL2BOR2BOL

Wrappers

Wrappers are vehicles that enable objects to be correctly displayed and processed in the activity
clipboard. These objects are, for example, BOR objects that contain no other information, or one order
objects that require a special connection, as they all have the same type but different content.

<wrappers>
<wrapper id="ICBORWrapper"
attributeWithWrappedTypeXPath="//OBJTYPE"
attributeWithWrappedDescriptionXPath="//ATTR_VALUE"/>

<wrapper id="BTUsageKind"
attributeWithWrappedTypeXPath="//OBJECT_TYPE"
attributeWithWrappedDescriptionXPath="//OBJECT_TYPE_TXT_S"/>

<wrapper id="BTOrder"
attributeWithWrappedTypeXPath="//BTOrderHeader/OBJECT_TYPE"
attributeWithWrappedDescriptionXPath="//BTOrderHeader/DESCRIPTION"/>
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 41

</wrappers>

If an object ID is not defined as a wrapper, the attribute wrappedObjectType is ignored.

For BOR objects, which attributes are delivered by the transaction launcher and which are displayed in the
description column is determined within the wrapper. (Only one attribute per object is supported.)

2.1.2.12 Step 7: Assign the Transaction Launcher Profile to the IC WebClient Profile
IMG: Customer Relationship Management Interaction Center WebClient Define IC WebClient
Profiles.

The last necessary step is to assign the transaction launcher profile to the IC WebClient profile.

2.1.3 How to Add New Current Objects to the BDC (Modification)
Current objects are one of the data sources that can be used when generating launch transactions with
the wizard. If you have an object which is reused in a lot of launch transactions, you might consider
updating the XML for the BDC controller. This is a modification and requires some effort in implementing
the required classes. In most cases, it might be easier to include the required data in the input parameters
(in PREPARE_DATA_FLOW).

The BDC is defined as a custom controller and requires the following modifications to add new current
objects:

1. Update the XML definition in BDCController.xml.

<Controller id="CuCoBDC" type="CUSTOM">
<Context>
<ModelNode id="currentCustomer" type="BuilHeader"/>
<ModelNode id="currentContact" type="BuilHeader"/>
<ModelNode id="currentInteractionRecord" type="BTOrder"/>
<ModelNode id="currentOneOrder" type="BTOrder"/>
<ModelNode id="currentIBase" type="IBComponent"/>
<ModelNode id="currentFollowUp" type="BTOrder"/>
<ModelNode id="currentVehicle" type="Product"/>
<ModelNode id="currentProduct" type="Product"/>
</Context>
</Controller>

Each ModelNode definition must start with current. Some generic logic of the BDC is based on
that requirement.

2. Create a new context node.

Copy one of the existing nodes, for example, CL_CRM_IC_CUCOBDC_CN00 into
CL_CRM_IC_CUCOBDC_CNxx. Observe the naming convention.

3. Add the new context node as attribute to CL_CRM_IC_CUCOBDC_CTXT.
4. Update the constructor of CL_CRM_IC_CUCOBDC_CTXT to include the new object.
Example:


* create cntext node
model = owner->create_model(
class_name = 'CL_CRM_IC_CUCOBDC_CN00'
model_id = 'currentCustomer' ).
currentCustomer ?= model.
CLEAR model.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 42



5. Add code to fill the new current object.
Example (uses the currentCustomer object):


DATA: bdc TYPE REF TO cl_crm_ic_cucobdc_impl,
bp_entity TYPE REF TO if_bol_bo_property_access,
col TYPE REF TO cl_crm_bol_entity_col.


bdc ?= get_custom_controller( 'CuCoBDC' ).

if bdc is bound.
create object col.
col->if_bol_bo_col~add( bp_entity ).

bdc->typed_context->currentCustomer->set_collection( col ).


2.2 Interactive Scripting: Architecture and Configuration



While reading this section, we recommend having the Interaction Center (IC) WebClient running
and a CRM session open in transaction SE80 (CRM_IC BSP application). In addition, another
session for transaction SE80 for ABAP classes, to make sense of the references to class names,
views, and so on.

The configuration changes described in here offer additional options to what is possible using only the
interactive script editor. They are not required to provide basic scripting functionality.

2.2.1 Interactive Scripting Runtime Architecture
The interactive scripting runtime framework is based on the model view controller architecture of the IC
WebClient. It is implemented in BSPs and runs in the SAP Web Application Server (Web AS). The logic
for processing a script resides in the ABAP code behind the BSP pages.

2.2.1.1 Interactive Scripting Processor Interface

The IF_CRM_IC_SCRIPT_PROCESSOR interface lets you add script control capabilities by using
templates, actions, and dynamic content.

For example, you can call GO_NEXT_NODE method of the IF_CRM_IC_SCRIPT_PROCESSOR
interface to advance the script to the next node, or START_SCRIPT method to programmatically start a
new script and so on.

Sample Code: EH_NEXT method of the controller class CL_CRM_IC_SCRIPTURLV_A_IMPL

method eh_next .
data: processor type ref to if_crm_ic_script_processor.
processor ?= get_custom_controller( 'CuCoScriptProcessor' ).
processor->go_next_node( ).
endmethod.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 43

2.2.1.2 Interactive Scripting Data Context

Interactive scripting runtime maintains a data context for the running script. The data context is maintained
in class CL_CRM_IC_SCRIPT_CONTEXT. You can access it to program a new template or a new action.

Data contexts are divided into three categories:

Bound data
This data is bound to business object attributes and is referred in an XPath style.
Unbound data
This data corresponds to fields that are defined in a survey but do not have a direct correspondent
in the business object attributes.
Actions result data
Data that is merged in context as a result of an action execution.

Sample Code: Accessing the Script Context from an Action

data: lt_unbound type crmt_ic_script_tab.
data: script_controller type ref to cl_crm_ic_script_controller.
data: processor type ref to if_crm_ic_script_processor.

script_controller = processor->get_script_controller( ).
lt_unbound = script_controller->script_context->unbound_context.

For more information on actions, see Actions.
2.2.2 Creating New Actions

You must use the interactive script editor to create the definition for a new action. You must also create or
reuse an ABAP implementation class.

The action is a background method that can be inserted as a node in the script. Technical users create
the actual implementation for the action, in form of an ABAP class.

Part of the standard delivery is the Business Partner Modify action. This action updates the ABAP BOL.

2.2.2.1 Step 1: Creating New Actions Definition

We recommend creating actions using the interactive script editor. For more information, see the SAP
Help Portal (http://help.sap.com/) mySAP Business Suite SAP Customer Relationship Management
<relevant release and language> Getting Started with SAP CRM Getting Started with the
Interaction Center Interaction Center WebClient Interactive Scripting Interactive Script Editor
Creating Actions.

It is also possible to create the metadata for the actions directly in the XML repository using the XML
editor for component ID SA.

2.2.2.2 Step 2: Creating Implementation Classes


2.2.2.2.1 Creating ABAP Handler Classes

To illustrate how you can ABAP class methods from scripting, we use the retrieval of business partner
status as an example. You can display business partner status (gold, silver customer, and so on) in a
scripting view as follows:
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 44


1. Create a new script, Script1, in the interactive scripting editor.
For more information about using the script editor, see the SAP Help Portal (http://help.sap.com/)
mySAP Business Suite SAP Customer Relationship Management <relevant release and
language> Getting Started with SAP CRM Getting Started with the Interaction Center
Interaction Center WebClient Interactive Scripting.
2. Create two questions: WELCOME1 and BPSTATUS.
In question BPSTATUS, we want to display the result of the ABAP method call.
3. Drag&Drop the output parameters for the Business Partner Status action into the question text of
BPSTATUS as shown in the figure below:



4. In the script editor, select the script you are designing.
5. Drag&Drop questions WELCOME1 and BPSTATUS into the script.
6. Drag&Drop the Business Partner Status action into the script as shown in the figure below:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 45



LONG and SHORT Output Parameters



7. Link WELCOME1 to the Business Partner Status action.
8. Link the Business Partner Status action to BPSTATUS.
9. Save the script.
10. Maintain a status for the business partner that you plan to use to test the script (transaction BP).
11. Run the IC WebClient.
12. Execute the script.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 46

The status that you assigned to the business partner in transaction BP appears in BPSTATUS
instead of the placeholders.

2.2.3 Creating New Templates

In order to create a new template you need to define it in the XML repository, create a new ABAP class,
and potentially create a new view or view set.

The template is mainly composed of an ABAP implementation class and a view or view set that will be
used to navigate to. The default view set contains four views. Different templates can actually share the
same view or view set. In this case, the UI looks the same, but the background processing may be
different. This is the case with the dialog template and the marketing attributes template.

The user sees no difference when a node type Dialog is displayed or a node type
Marketing Attributes is displayed (assuming that we render the radio button control in both cases, for
example), but in the background, the marketing attributes template performs some more specialized
operations. In fact, the marketing attributes implementation class inherits from the dialog implementation
class.

For more information about using templates in the interactive script editor, see the SAP Help Portal
(http://help.sap.com/) mySAP Business Suite SAP Customer Relationship Management <relevant
release and language> Getting Started with SAP CRM Getting Started with the Interaction Center
Interaction Center WebClient Interactive Scripting Interactive Script Editor Templates.

2.2.3.1 Step 1: Defining New Templates

In this example we follow the creation and usage of the Survey template. The Survey template is part of
the default delivery. In a similar way you can create your own template.

1. Run CRM transaction CRMC_XMLEDITOR and choose component ID ST.
2. You can:
Select an existing profile.
If you select the DEFAULT profile, any changes you make to profile DEFAULT will be
overwritten when SAP delivers more out-of-the-box actions.
Enter a name.
If you enter a name, the system creates a new profile with that name.
3. Enter the necessary tags and values in the XML.
See below for a sample XML file and a table containing descriptions of the attributes used.

Sample Code: Template Definition

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 47



Description of Template Attributes

ID Unique identifier for the template
NavigationalLink Navigational link in the Interaction Center that indicates which view
set will be displayed when arriving at a node associated with this
template.
Color The color for nodes that are associated with this template
(ScriptEditor)
AttributeShownOnNode Is the attribute value that is shown on the node in the interactive
script editor.
For more information about the interactive script editor, see the
SAP Help Portal (http://help.sap.com/) mySAP Business Suite
SAP Customer Relationship Management <relevant release
and language> Getting Started with SAP CRM Getting
Started with the Interaction Center Interaction Center WebClient
Interactive Scripting.
ImplClass Name of the ABAP class that will implement the process before
node (PBN) and process after node (PAN) logic.
Description Language description for the template
TemplateParameterDefinition Defines a parameter for the template so that the script editor will
allow the user collect the value of such parameter when creating a
script.
For more information about the interactive script editor, see the
SAP Help Portal (http://help.sap.com/) mySAP Business Suite
SAP Customer Relationship Management <relevant release
and language> Getting Started with SAP CRM Getting
Started with the Interaction Center Interaction Center WebClient
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 48

Interactive Scripting.
Key Unique key for the parameter being defined, so that it can be
accessible by that name in the PBN or PAN logic.
PossibleValueProvider Defines the Java method that is responsible for providing possible
values for the parameter. At this point only
com.sap.ic.dtime.ise.api.ValueProviderRFC is possible because
the class is included in the JAR file containing the interactive script
editor. However, you can use parameter PVPParameter
Key="FunctionModuleName" to call a particular function module to
get the possible values. See function module
CRM_IC_SCRIPT_API_GET_SRVYIDS for interface requirements
(import, export, and tables parameters.
PVPParameter Parameter for the PossibleValueProvider. In the example given in
the description of PossibleValueProvider above, the
PVPParameter with key FunctionModuleName and value
CRM_IC_SCRIPT_API_GET_SRVYAPL is used to call function
module CRM_IC_SCRIPT_API_GET_SRVYAPL, which returns
the possible values for that template parameter.
ValueRestrictor Restricts the value selection of a particular parameter. In the
example above, parameter definition with key surveyId" uses as a
value restrictor parameter definition with key applicationId so that
when calling function module
CRM_IC_SCRIPT_API_GET_SRVYIDS, it restricts the returned
possible values to only those where the application ID is equal to
the one selected in the script editor. In other words, users first
select an application ID in the script editor, and when they get a list
for possible values for a survey ID, this list will be limited to those
matching the application ID they selected. For more information
about how this selection is made, see the implementation of
function module CRM_IC_SCRIPT_API_GET_SRVYIDS.

The process before node (PBN) method is invoked by the interactive scripting framework before the node
is rendered, meaning before the BSP view is rendered.

In this method, we can perform some initialization. For example in case of the Lead template, the URL to
call the lead survey is initialized.

The process after node (PAN) method is invoked by the interactive scripting framework after the node is
processed. For example, in the case of the default dialog template, this means collecting the data from
that node and putting it in the scripting context.

For a chat template, the PAN is the same as in dialog; only the PBN is different. For this reason, the chat
template inherits from the dialog template.

Sample Code: Chat Template Code Fragment

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 49



2.2.3.2 Step 3: Implementing Views and View Sets To Be Used with the Template

The process of creating a new view or view set to be used by a template in conjunction with interactive
scripting is the same as creating views or view sets for any other purposes. For more information on
creating, copying, and changing views or view sets, see section Working with Views and View Sets.

For example, if you create a new view called MyNewView to replace the dialog view, you have to insert it
in the view set definition for view area scriptDialogArea:

Sample Code: ScriptViewSet.xml

<ViewSet id="ScriptVset_A">
<ViewArea id="scriptControlArea_A" views="ScriptConV_A"/>
<ViewArea id="scriptDialogArea_A" views="ScriptDlgV_A ScriptUrlV_A
ScriptLeadV_A ScriptMapV_A MyNewView"/>
<ViewArea id="scriptOverviewArea_A" views="ScriptOverV_A ScriptOeV_A"/>
<ViewArea id="scriptNavArea_A" views="ScriptNavV_A"/>
</ViewSet>

You also have to define a navigational link called MyNewNavLink that leads to your view. For more
information, see Working with Views and View Sets.

<NavigationalLink name="ScriptGoToLead">
<Source viewRef="contextAreaView" outboundPlugRef="default"/>
<Targets>
<Target viewRef="ScriptLeadView" inboundPlugRef="default"/>
</Targets>
</NavigationalLink>
<NavigationalLink name="ScriptGoToDialog">
<Source viewRef="contextAreaView" outboundPlugRef="default"/>
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 50

<Targets>
<Target viewRef="ScriptView" inboundPlugRef="default"/>
</Targets>
</NavigationalLink>
<NavigationalLink name="MyNewNavLink">
<Source viewRef="contextAreaView" outboundPlugRef="default"/>
<Targets>
<Target viewRef="MyNewView" inboundPlugRef="default"/>
</Targets>
</NavigationalLink>

It is possible to reuse the views and navigational links. In the case of our example, the survey template
shares the same view with the URL template because they are very similar. They only differ in the ABAP
class implementation. The navigational link for the survey template is the same as for the URL template
ScriptGoToUrl_A.

View of Navigational Link ScriptGoToUrl_A in the ABAP Workbench



2.2.3.3 Step 4: Launching the Interactive Script Editor
The new template appears in the repository under templates and is ready to be used in designing
scripts.
2.2.4 Creating New Dynamic Content

The need for dynamic content emerges when the data that is presented at runtime in a script is not fully
known at design time.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 51

To create a dynamic content provider for runtime, you need to define the dynamic content in the XML
repository and to create a new ABAP implementation class.

2.2.4.1 Step 1: Defining New Dynamic Content

1. Run CRM transaction CRMC_XMLEDITOR and choose component ID DC.
2. You can:
Select an existing profile.
If you select the DEFAULT profile, any changes you make to profile DEFAULT will be
overwritten when SAP delivers more out-of-the-box actions.
Enter a name.
If you enter a name, the system creates a new profile with that name.
3. Enter the necessary tags and values in the XML.
See below for a sample XML file and a table containing descriptions of the attributes used.

<?xml version="1.0" encoding="UTF-8"?>
<DynamicContentRepository>
<DynamicContentDefinition DynamicContentClass="CL_CRM_IC_SCRIPT_DYN_MA"
Id="MarketingAttribute" Type="answer-snippet">
<Description Language="en">Marketing Attribute</Description>
<DCParameterDefinition ParameterId="MarketingAttributeSetId"
SequenceNo="01">
<Description Language="en">Marketing Attribute Set ID</Description>
<PossibleValueProvider
ProviderClass="com.sap.ic.dtime.ise.api.ValueProviderRFC">
<PVPParameter Key="FunctionModuleName"
Value="CRM_IC_SCRIPT_API_GET_MASETS"/>
</PossibleValueProvider>
</DCParameterDefinition>
<DCParameterDefinition ParameterId="MarketingAttributeName"
SequenceNo="02">
<Description Language="en">Marketing Attribute Name</Description>
<PossibleValueProvider
ProviderClass="com.sap.ic.dtime.ise.api.ValueProviderRFC">
<PVPParameter Key="FunctionModuleName"
Value="CRM_IC_SCRIPT_API_GET_MKTATR"/>
<ValueRestrictor ParameterId="MarketingAttributeSetId"/>
</PossibleValueProvider>
</DCParameterDefinition>
</DynamicContentDefinition>
</DynamicContentRepository>

Description of Dynamic Content Attributes

DynamicContentDefinition Defines a new entry in the dynamic content
repository.
Id A unique identifier.
DynamicContentClass Defines the class that will generate the
dynamic content.
Type At the moment we only support answer
snippets. In the future, we will support generic
html.
Description A language-dependent description for the
dynamic content.
DCParameterDefinition Defines a parameter for the dynamic content.
In the example above, the dynamic content
generates input fields for collecting marketing
attributes. The parameters for this dynamic
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 52

content entry is Marketing Attribute set name,
and Marketing attribute name.
PossibleValueProvider See the description in the template attributes
XML repository section above.

2.2.4.2 Step 2: Creating ABAP Implementation Class for Dynamic Content

The ABAP implementation class must implement the following interfaces
IF_CRM_IC_SCRIPT_DYNCON
IF_CRM_IC_SCRIPT_PRO

The IN_PARAMS table of GET_DYNAMIC_CONTENT method in
IF_CRM_IC_SCRIPT_DYNCON contains the design time action input parameters as key/value
pairs.
The processor object type IF_CRM_IC_SCRIPT_PROCESSOR is published via
IF_CRM_IC_SCRIPT_PRO so the action can use it to access the script context.
The return string is an XML snippet representing the dynamic answer.

When the framework traverses the current form (XML data model compatible with a survey) and
determines that an answer is dynamic, it loads the corresponding ABAP implementation and executes
GET_DYNAMIC_CONTENT method that provides the missing piece of XML (the string return of the
method). The framework then inserts that XML snippet in the current form.

Sample Code from Maintain/Create Marketing Attributes



2.2.4.3 Step 3: Using New Dynamic Content

1. Launch the script editor and create a new script.
2. Create a new question, Q1.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 53

3. Drag&Drop a dynamic answer into the text of the question.
In this case, add Marketing Attribute to your question.
4. Choose Dynamic Content Parameters and enter the attribute set and the attribute that you want to be
displayed.
The attributes and attribute sets that appear as input help have already been set up in the SAP CRM
system. For more information, see:
Marketing Attributes
Transaction CRMD_PROF_CHAR
Marketing Attribute Sets
Transaction CRMD_PROF_TEMPL

Interactive Script Editor Market Attribute Sets and Market Attributes Entry


5. Drag&Drop Q1 into the script design area.
6. Select the question and choose Node Properties.
7. Set the template type for the question to Organization Marketing Attributes as shown in the following
figure:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 54



8. Launch the IC WebClient and run the script.
Marketing attributes assigned to the organization appear in the question.

2.2.4.4 Launching Scripts and Background Processing Based on Events

By attaching an event name, a class, and a script name to a script profile in Customizing, it is possible to
react in custom way to IC WebClient events.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 55



The class delivered CL_CRM_IC_SCRIPT_LAUNCH subscribes to the event defined and when this event
is raised it launches the script specified by Script Id.

The class should implement at least the IF_CRM_IC_EVENT_SCRIPT interface in order to be instantiated
by the scripting runtime framework. By implementing this interface it also appears in the F4 help for the
Event Class Name field.

The class delivered CL_CRM_IC_SCRIPT_LAUNCH also implements IF_CRM_IC_EVENT_LISTENER
as it listens for IC WebClient events. In the example above, the event specified is BPConfirmed.

Additional processing can be performed by this class prior to launching a script, for example. Always
launching a script is not mandatory. There are two additional optional parameters in Customizing that are
transferred to the instantiated class.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 56



2.3 Alert Service (Alert Modeler)

The alert service (alert modeler) is an application component of the IC application which alerts the agent
of specific business-relevant situations, for example a service contract expiring in the next 4 weeks or a
cross-selling opportunity.

The alerts area near the top of the IC WebClient screen is where the alerts are rendered. It is always
visible for users, regardless of where they have navigated within the application.

Alerts can be navigable. For example, if an alert appears informing the agent it is time to end the
interaction with the customer, the agent can select the alert and navigate to the interaction record. You
can set the destination of this navigation in Customizing.

Alerts Area of the IC WebClient Screen


.
A key aspect of this service is the setup: which alerts should be displayed in which situation for which kind
of agent group. You specify these settings in Customizing. There is no coding necessary to specify a
certain behavior of this service.

For more information about how agents use alerts, see the SAP Help Portal (http://help.sap.com/)
mySAP Business Suite SAP Customer Relationship Management <relevant release and language>
Getting Started with SAP CRM Getting Started with the Interaction Center Interaction Center
WebClient Alerts and Messages.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 57


In addition to the Customizing options, you can enhance the alert service capability in two ways by:
Creating new events
Implementing custom alert classes
2.3.1 Architecture
With the SAP CRM 4.0 Add-On for Service Industries release, it is possible to install a Java configuration
or a non-Java configuration of IC WebClient. In the non-Java configuration of IC WebClient, alert service
is implemented in ABAP. In this case, alert service uses SAM (Simplified ABAP Messaging) to send alert
messages from the CRM Server to the browser. The same functionality is available in the non-Java
configuration as in Java configuration.
2.3.2 Customizing
IMG: Customer Relationship Management Interaction Center WebClient Alerts.

You could modify the SAP delivered alerts to suit your needs or add new alerts using either the alert
wizard or by modifying the XML file directly . For more information, see the IMG activity documentation.

The Customizing of the alert service is an XML document that describes all relevant properties of an alert,
which are detailed in the following figure:


<alert id="chatPosting">
<desc>Makes aware of posted chat message</desc>
<class>com.sap.ic.service.alert.ChatPostingAlert</class>
<abapclass>CL_CRM_IC_ALERT_CHATPOSTING</abapclass>
<triggeringEvents>
<triggeringEvent>ChatPostingNotification</triggeringEvent>
</triggeringEvents>
<terminatingEvents>
<terminatingEvent>ChatPostingClear</terminatingEvent>
</terminatingEvents>
<inputParams/>
<placeholders>
<placeholder id="chatTextComplete" property="false"/>
<placeholder id="chatTextTruncated" property="false"/>
</placeholders>
<message>
<messageText>[chatTextTruncated]</messageText>
<navigationalLink>AlertToChat</navigationalLink>
<messageTooltip>[chatTextComplete]</messageTooltip>
</message>
</alert>

Description
Java class that
renders the alert
ABAP class that
renders the alert
Triggering events
Terminating Events
Input parameters
Text blocks that can be
included in the message text
and will be replaced at
runtime.
Message to be displayed
Navigation destination Tooltip for the alert message

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 58

The <class> tag defines the Java class that implements this alert. The implementation class encapsulates
all logic required to determine if and how an alert is rendered. This class is used only if you are running
the Java configuration of IC WebClient.
The <abapclass> tag defines the ABAP class that implements this alert. The functionality is the same as
the corresponding Java class. This class is used if you are running the non-Java configuration of IC
WebClient.
The Java and ABAP alert classes can be fairly simple, such as just replacing certain placeholders, or
more complex, such as evaluating sophisticated rules to determine whether an alert is to be displayed.
However, all alert classes implement a common interface. You can use the generic alert class or create a
new one. For more information, see section Creating New Alert Classes.

The <event> tag defines the triggering event for an alert. If this event is raised by the application logic, the
execution of the implementing alert class is invoked.

The <inputParams> tag declares parameters that can be passed to the alert execution. For example, a
reminder alert could indicate to the user that a certain amount of time has elapsed and that it is time to
wrap up the contact. In this case, the number of seconds after which a reminder should appear would be
an input parameter.

The <usedProperties> tag declares localized text blocks, which will be provided by the alert class and can
be merged into the text message to be defined in the <message> tag.

The <placeholder> tag declares placeholders, which the alert class will substitute with actual values at
runtime. They can be also merged into the text message to be defined in the <message> tag.

The <message> tag defines the format and content of the message to be displayed. In the current
implementation, this message is specified as HTML code that will be sent via a messaging service to the
browser, and will be rendered in the browser by a JavaScript code snippet using DHTML. Other formats,
such as a specialized XML format, could be considered as well. Attributes of a message may include the
ability to navigate including a navigation destination, tool tip, or free-form parameters, which can be
evaluated in a custom event handler or any native HTML attribute that is valid for an HTML <a> anchor
tag.

2.3.3 Creating New Events
If you need customized events ,for example if you only want to raise an event under certain
circumstances, you can create a new event, which you can then use to send the respective alert.

In the following example, we want to alert the agent if a confirmed business partner has a certain
characteristic, such as gold customer classification.

2.3.3.1 Step 1: Write an Event Class that Implements the Interface
IF_CRM_IC_EVENT_LISTENER and IF_CRM_IC_EVENT_CUSTOM
In the constructor of this class, you:
Get a reference to event service
Subscribe to the BPConfirmed event

A sample event class is CL_CRM_IC_EVENT_SAMPLE. You could make a copy of this sample class and
modify the copy to add your business logic.

View of Sample Constructor in the ABAP Workbench
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 59



In the handle-event method of the interface, write your business logic to check for whatever you need for
the business partner and raise a new event.

Sample Code
method IF_CRM_IC_EVENT_LISTENER~HANDLE_EVENT .
* reference to classifier class
data: classifier type ref to CL_CRM_IC_SCRIPT_ACT_BPSTATUS.
data: partner_no type string.
data: intab type CRMT_IC_SCRIPT_TAB.
data: outtab type CRMT_IC_SCRIPT_TAB.
data: tab_entry type CRMT_IC_SCRIPT_KEY_VALUE.

class cl_crm_ic_services definition load.

* instantiate classifier object
create object classifier.
* get no of confirmed business partner
tab_entry-value_p = get_partner( ).
* add leading 0s
concatenate '0000' tab_entry-value_p into tab_entry-value_p.
* set up input parameter for classification
tab_entry-key_p = '//currentCustomer/BP_NUMBER'.
append tab_entry to intab.
* perform classification
CALL METHOD classifier->if_crm_ic_script_act_handler~execute
EXPORTING
in_tab = intab
IMPORTING
OUT_TAB = outtab.
* read result
read table outtab index 1 into tab_entry.
if sy-subrc = 0.
data: new_event type ref to cl_crm_ic_event.
* create event object
create object new_event.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 60

new_event->set_name( 'BPClassified' ).
* set event parameter
call method new_event->add_param
exporting name = 'class' value = tab_entry-value_p.
* add long text as second event parameter
read table outtab index 2 into tab_entry.
call method new_event->add_param
exporting name = 'long' value = tab_entry-value_p.
* raise event
event_service->raise( new_event ).
endif.
endmethod.

2.3.3.2 Step 2: Create Event Converter Class if You Have Event Parameters That Are Used in the
Alert
The event converter class converts event parameters in ABAP to Java format. A sample parameter
converter class is CL_CRM_IC_EVCNV_BPCONFIRM.

This step is necessary only if you are running the Java configuration of IC WebClient.
2.3.3.3 Step 3: Add This New Event and the Event Converter Class (if Any) in the IMG activity
Define Event Handling Profiles
2.3.3.4 Step 4: Add the New Event BPClassified to the Event Customization table
IMG: Customer Relationship Management Interaction Center WebClient Customer-Specific System
Modifications Alerts Define Events.

Enter the event name BPClassified and the event class name.

2.3.3.5 Step 5: Create an Alert for this Event in IMG Activity Define Alerts and Alert Profiles

For the non-Java configuration you could use the generic alert class CL_CRM_IC_ALERT_GENERIC. For
the Java configuration, the corresponding Java class is GenericAlert. For more information, see section
Creating New Alert Classes.

2.3.4 Creating New Alert Classes
In the non-Java configuration, the alert class specified with the <abapclass> tag determines the behavior
of the alert. An alert class implements the interface IF_CRM_IC_ALERT.

During initialization of the alert modeler component, an instance of the given alert classes is instantiated
for each alert in the current alert profile. Whenever a triggering event of an alert is raised, the alert
modeler component then calls the execute method of this alert. An instance of class
CL_CRM_IC_ALERT_RETURN is returned, which determines if and how the alert will be rendered on the
user interface (UI).

SAP delivers class CL_CRM_IC_ALERT_GENERIC, which can be used for any alert that does not require
specific parameters or placeholders. The event parameters of the triggering event are made available as
alert placeholders under the names param1, param2, and so on.


2.4 E-Mail Response Management (ERMS) Enhancements
2.4.1 Adding Additional Business Partner Attributes to the ERMS Attribute List
Adding attributes from the following BAPI structures is very easy as these are already read in the
CONVERT_BP method of the Business Partner Fact Gathering:
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 61

BAPIBUS1006_central
BAPIBUS1006_central_person
BAPIBUS1006_central_organ
BAPIBUS1006_central_group



EXAMPLE: Including the Nationality of the Business Partners Central Person



1. Note the name of the attribute in the BAPI structure (NATIONALITYISO) and go to Customizing
activity Customer Relationship Management E-Mail Response Management System Define
Repository (Attributes folder).
2. Copy the entry of BP_COUNTRY into ZBP_NATIONCOOKBK and adjust the XPath accordingly.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 62



3. Save your entries. The new attribute is now available for Rule Modeling.

2.4.2 Implementing New Fact Gathering Services and New Attributes
IMG: Customer Relationship Management E-Mail Response Management System Service Manager
Define Services (transaction CRMC_ERMS_SM_SRV).

In this Customizing activity, you can define new ERMS Services.

EXAMPLE: Defining a New Version of the Service for Business Partner Information



1. Create a copy of the FG_BP service.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 63



Just like the FG_BP Service, this one will not have any properties defined under the Properties folder.
2. Implement the new service class by copying the original class CL_CRM_ERMS_ADD2FB_BP into
ZCL_CRM_ERMS_ADD2FB_BPCOOKBOOK.
You can see all ERMS services if you look for all classes implementing the interface
IF_CRM_ERMS_SERVICE.
3. In the new class, change the copied class accordingly to access the industries the business partner
belongs to.

method IF_CRM_ERMS_SERVICE~EXECUTE .
data: doc_id TYPE sofolenti1-doc_id.
DATA: in_param TYPE o2paravalu_table.
DATA: out_param TYPE o2paravalu_table.
DATA: param_entry TYPE o2paravalu.
DATA: value TYPE string.
DATA: in_paramx TYPE crmt_ic_paravalx.
DATA: out_paramx TYPE crmt_ic_paravalx.
DATA: param_entryx TYPE crmt_ic_paravalu_xstr.
data: object_data type SOFOLENTI1.
data: container type swconttab.
data: mt_container type swconttab.
data: senderaddress type soxna-fullname.
data: webformsender type soxna-fullname. " webform sender
data: comm_type type tsac-comm_type.
data: ermssuprt type swc_object.
data: bp_object type swc_object.
data: partner_no TYPE BAPIBUS1006_HEAD-BPARTNER.

CLASS cl_crm_erms_converter DEFINITION LOAD.
CLASS cl_crm_erms_service_manager DEFINITION LOAD.

doc_id = service_manager->get_email_id( ).

container = service_manager->get_wi_container( ).
swc_get_element container 'SenderAddress' senderaddress.
swc_get_element container 'CommType' comm_type.
swc_get_element container 'ERMSSUPPORT' ermssuprt.
if senderaddress = 'LUECKHOFFH' or senderaddress is initial.
comm_type = 'INT'.
senderaddress = 'h.lueckhoff@sap.com'.
endif.
* call ERMSSUPRT method FindPartnerByAd

***** web form sender

webformsender = service_manager->factbase->get_by_xpath(
'/parts/webforms/sender/text()' ).
if webformsender <> ''.
senderaddress = webformsender.
endif.

*****
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 64

swc_set_element mt_container 'Address' senderaddress.
swc_set_element mt_container 'CommType' comm_type.
swc_call_method ermssuprt 'FindPartnerByAddr' mt_container.
swc_get_element mt_container 'BusinessPartner' bp_object.
swc_get_object_key bp_object partner_no.
service_manager->set_bp_number( partner_no ).

*** COOKBOOK Change:
*** In case of a contact BP get all companies associated with contact

data: partners TYPE table of BAPIBUS1006_HEAD-BPARTNER.

if service_manager->factbase->get_by_xpath(
'/parts/BUPA/CENTRALDATAORGANIZATIN/NAME1/text()' ) is initial.

data relationships type table of BAPIBUS1006_RELATIONS.
data current_partner type BAPIBUS1006_RELATIONS.

call function 'BAPI_BUPA_RELATIONSHIPS_GET'
exporting
businesspartner = partner_no
tables
relationships = relationships.
LOOP AT relationships INTO current_partner
WHERE RELATIONSHIPCATEGORY = 'BUR001'
and PARTNER1 = partner_no.
collect current_partner-partner2 into partners.
ENDLOOP.
LOOP AT relationships INTO current_partner
WHERE RELATIONSHIPCATEGORY = 'BUR001'
and PARTNER2 = partner_no.
collect current_partner-partner1 into partners.
ENDLOOP.

else.
append partner_no to partners.
endif.

LOOP AT partners INTO partner_no.

data: industrysectordetail type table of BAPIBUS1006_INDUSTRYSECTOR.

call function 'BAPI_INDUSTRYSECTORDETAILS_GET'
exporting
businesspartner = partner_no
tables
industrysectordetail = industrysectordetail.

data: industrysectordetail_string type string.

call transformation id
source industrysectordetail = industrysectordetail
result xml industrysectordetail_string.
call method cl_crm_erms_converter=>strip_xml
exporting
in_xml = industrysectordetail_string
split1 = '<asx:values>'
split2 = '</asx:values>'
receiving
result = industrysectordetail_string.

data: xml_chunk type string.

CONCATENATE
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 65

'<ZCOOKBOOK>'
'<Industry>'
industrysectordetail_string
'</Industry>'
'</ZCOOKBOOK>' INTO xml_chunk. "#EC NOTEXT



service_manager->factbase->add_snippet( xml_chunk ).

endloop.

endmethod.


4. Define the ZCOOKBOOK part of the fact base XML.
5. Define the attribute with the XPath
/parts/ZCOOKBOOK/Industry/INDUSTRYSECTORDETAIL/BAPIBUS1006_INDUSTRYSECTOR/IND
USTRYSECTOR/text().



6. Use the rule modeler to define rules using this new attribute.

2.4.3 Implementing Input Support for Industry Sector
IMG: Customer Relationship Management E-Mail Response Management System Define
Repository (Input Support for Conditions Folder).

In this Customizing activity, you can provide value help for this new attribute by configuring the input
support.

For the condition Attribute and Operator, the system looks for a corresponding entry in the following order.
If an entry is found, it will be used and no further lookup will happen.
1. With the attribute and the operator of the condition line
2. With an initial attribute and the operator of the condition line
3. With the attribute of the condition line and an initial operator

If no input support entry is found, the system will generate an entry field without any value help.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 66



Implement the corresponding class for the value help by copying from CL_CRM_ERMS_FIS_COUNTRY.
After activating you will see the values in the rule modeler.



The field input support (FIS) class provides specific extensions to the behavior of the input support that
would be difficult to capture in Customizing. It needs to implement interface IF_CRM_ERMS_RULE_FIS.

In particular, the following methods adhere to the semantics as follows:

GET_VALUEHELP_TAB
This method must be implemented for dropdown list boxes (DDLB) and input fields with simple value
help. It has to return a table with the values that are available for the field, either for selection (DDLB)
or value help.
BEFORE_VALUE_OUTPUT
This method is optional. It has two purposes:
o Allows the mapping of the value field from an internal format to an external format.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 67

o Provides an optional description for the value, which will be shown in the description field.
This is especially useful in case that the value field content itself is not particularly self-
descriptive.
In general this method does not need to be implemented for a DDLB. If the field is shown as a DDLB,
then the mapping of the value field from internal to external format is not necessary, since the value
itself wont be shown, only the corresponding description as returned by the method
GET_VALUEHELP_TAB.
AFTER_VALUE_INPUT
This method is optional. It has two purposes:
o Allows the mapping of the value field from an external to an internal format. This should
reverse any mapping done in method BEFORE_VALUE_OUTPUT.
o Provides a check, if the input is valid or not (parameter E_VALUE_IS_INVALID). If the
input isnt valid the rule modeler will show an error message.
In general this method does not need to be implemented for DDLBs. In particular it should never
return E_VALUE_IS_INVALID = X for DDLBs. Rather any invalid value should not be allowed for
selection in the method GET_VALUE_HELP_TAB.
Method OIC_GET_F4_PREASSIGN_FIELDS
This method is only relevant for fields with complex value help. It allows the pre-assignment of search
fields to an OIC. Those of the fields OIC_PREASSIGN_FIELD_1 to OIC_PREASSIGN_FIELD_8 that
the application uses have to be mapped to the actual fieldname of the OIC in the blueprint table
Customizing (Transaction CRMC_BLUEPRINT) under F4 Help Field Assignment for Search
Preassignment for field group ERM_RULE_VALUE_FIELDS.
Method OIC_RECEIVE_F4_RETURN_FIELDS
This method is only relevant for fields with complex value help. It is necessary, if the OIC returns its
value in multiple fields that have to be mapped into one field although it is recommended to use it
even with one return field.
o If the OIC returns one field and that key can be used as returned, then the blueprint table
Customizing (Transaction CRMC_BLUEPRINT) under F4 Help Field Assignment for
Transferring Values for field group ERM_RULE_VALUE_FIELDS can be configured to
map the result field directly to field VALUE_F4OIC. In that case this method is not
needed.
o If the OIC returns one or more fields, then the blueprint table Customizing (Transaction
CRMC_BLUEPRINT) under F4 Help Field Assignment for Transferring Values for field
group ERM_RULE_VALUE_FIELDS needs to map to the fields OIC_RET_FIELD_1 to
OIC_RET_FIELD_8. In that case this method is needed, since those fields are provided to
this method, which should build the proper content for the value field.

2.4.3.1 Adding OIC Input Support for a New Attribute

Assuming you already have written the OIC, the procedure is as follows:
1. Create a new BOR object that corresponds to the OIC or find an existing one. Enter this BOR
object name in field Object Type in Customizing.
2. Access the blueprint table Customizing (Transaction CRMC_BLUEPRINT).
3. Under Navigation (URL Generation) Define Object Type for Navigation, create a CRM object
for your BOR object, or find an existing CRM object.
4. Determine which method you are going to use for your CRM object from Navigation (URL
Generation) Define Method for Navigation. If you created a new CRM object, method
DEFAULT is usually okay. For an existing object, method VALUEHELP (so it exists for that object)
would be a more proper choice. Your BOR object might have to implement that method, at least
the shell for it.
5. Under Navigation (URL Generation) Method for Object Type, create an entry for your CRM
object and the method you picked, if it isnt already there.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 68

6. Under Navigation (URL Generation) Assign Object Method to Role, create an entry for role
SAP_PCC_ERMS_ADMIN and your CRM object and method. Use implementation type BSP
External Service and specify the People-Centric UI application name of the OIC in field
Application.


This step is client-dependent, so you have to also do this in the default Customizing client, in
order for this entry to be transported downstream, for example to customers.
7. If you need to pre-assign field values for the OIC, define the mappings under F4 Help Field
Assignment for Search Preassignment for field group ERM_RULE_VALUE_FIELDS. Your source
fields are fields OIC_PREASSIGN_FIELD_1 to OIC_PREASSIGN_FIELD_8. In this case you
need to implement a FIS class and implement the method OIC_GET_F4_PREASSIGN_FIELDS
to those fields.
8. Under F4 Help Field Assignment for Transferring Values, define the mapping to receive the
result field(s) of the search for field group ERM_RULE_VALUE_FIELDS. Your target fields are
VALUE_F4OIC and OIC_RET_FIELD_1 to OIC_RET_FIELD_8. If you use the latter fields, you
need to implement a FIS class and implement the method OIC_RECEIVE_F4_RETURN_FIELDS
to build the key from the fields OIC_RET_FIELD_1 to OIC_RET_FIELD_8.

2.4.4 Example: Implementing New Action Handler

We want to implement a new action handler for sending out notifications, for example to a mobile phone,
about an incoming e-mail. For example, you might want to send a notification to the account executive if
the e-mail contains the words contract cancellation.

1. Create the new service by copying from AH_AUTO_ACK in Customizing activity Customer
Relationship Management E-Mail Response Management System Service Manager Define
Services (Transaction CRMC_ERMS_SM_SRV).



For the properties, keep Process Type and Template GUID.



These parameter properties can be set using Customizing activity Customer Relationship Management
E-Mail Response Management System Service Manager Define Service Manager Profiles
(Transaction CRMC_ERMS_SM_PROF).
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 69



2. Add the following action and parameters in Customizing activity Customer Relationship Management
E-Mail Response Management System Define Repository (Actions Folder).





3. Change the implementation of the class that is copied from CL_CRM_ERMS_AH_AUTO_ACKNOW.

method IF_CRM_ERMS_SERVICE~EXECUTE .
DATA: action_entry TYPE o2paravalu.
DATA: action_entry2 TYPE o2paravalu.
DATA: lv_length TYPE sy-index.
DATA: idx TYPE i.
DATA: bp_number TYPE bapibus1006_head-bpartner.
DATA: lv_bp_number TYPE bu_partner.
DATA: lv_form TYPE tdsfname.
DATA: log_handle TYPE balloghndl.
DATA: error TYPE c.
DATA: param TYPE crmt_erms_rule_action_param.
DATA: result_action_tab TYPE crmt_erms_rule_actions.
DATA: raction TYPE crmt_erms_rule_action.
DATA: addr TYPE string.
DATA: lv_original_body TYPE string.
DATA: _addr TYPE ad_smtpadr.
DATA: conid TYPE crmt_erms_connection_id.
DATA: lv_top_scoring_category TYPE string.
DATA: lv_sender_id TYPE crmt_im_e_id.
* email reply address
DATA: lv_reply TYPE crmt_im_e_reply_add.
DATA: lv_send_addrnr TYPE ad_addrnum.
DATA: lv_send_persnum TYPE ad_persnum.
DATA: lv_send_addr_type TYPE bu_adrkind.
DATA: ev_error TYPE c.
DATA: lv_xpath TYPE string.
DATA: lv_schema TYPE string.

DATA:
lv_cat_guid type crm_erms_cat_guid,
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 70

lv_langu type lang,
lv_langu_iso(2),
lv_sender_address type bapiadsmtp-e_mail,
** cookbook:
lv_recipient type bapiadsmtp-e_mail,
lv_recipient_address type bapiadsmtp-e_mail,
lv_reply_address type crmt_im_e_reply_add,
lv_create_int_record.

DATA:
lv_subject TYPE so_obj_des,
lv_et_mail_body type soli_tab,
lv_soli_tab_line type soli,
lv_et_attachments type crmt_ic_mail_attachments,
lv_et_pictures type crmd_im_pictures,
lv_et_mail_parts type crmt_im_parts,
lv_mail_part type crmt_im_part,
lv_ev_log_handle type balloghndl,
lv_ev_error type c,
lt_it_f4struc_alv TYPE TABLE OF crm_im_f4_alv,
lt_it_fixed_value_fields TYPE TABLE OF fieldinfo,
lv_iv_log_handle type balloghndl,
lv_iv_texttype type crmt_texttype,
lv_iv_send_immediately type c,
lv_iv_activity_guid type bbp_guid_32,
lv_iv_mess_coll type c,
lv_iv_io_guid type crmt_im_guid,
lc_ev_document type ref to cl_document_bcs,
lc_ev_send_request type ref to cl_bcs,
lv_is_item_ds type crmd_im_ml_item_ds,
lv_iv_error_counter type i,
lv_error type c,
lv_cs_crmmail type crmmail.
DATA: LV_SHORTTEXT TYPE STRING.

*-- Interaction record related
DATA: lt_activity TYPE cmst_bapibus20001_object_id_t.
DATA: ls_activity TYPE BAPIBUS20001_OBJECT_ID.
DATA: lt_return TYPE bapiret2_t.
DATA: lv_email_id TYPE string.
DATA: lv_out_email_id TYPE string.
DATA: lv_bci_key TYPE soodk.
DATA: lv_bcs_key TYPE os_guid.
DATA: lv_activity TYPE BORIDENT.
DATA: lv_sapoffdoc TYPE BORIDENT.
DATA: lv_process_type TYPE CRMT_PROCESS_TYPE.
DATA: lv_template_guid TYPE CRMT_OBJECT_GUID.


DATA: lv_out_email_docno TYPE SO_OBJ_NO,
lv_out_email_doctp TYPE SO_OBJ_TP,
lv_out_email_docyr TYPE SO_OBJ_YR.
DATA: lv_description TYPE crmt_process_description.
DATA: lt_partner TYPE bup_partner_guid_t.
DATA: ls_partner TYPE bupa_partner_guid.
DATA lv_converted_body TYPE string.


*-- Get auto-response action parameters
result_action_tab = service_manager->actions->get_actions( ).
** cookbook
LOOP AT result_action_tab INTO raction WHERE name = 'ZNOTIFY'.
LOOP AT raction-parameters INTO param.
IF param-name = 'FORM'.
lv_form = param-value.
ENDIF.
IF param-name = 'SENDER_ID'.
lv_sender_id = param-value.
ENDIF.
IF param-name = 'CREATE_INT_FLAG'.
lv_create_int_record = param-value.
ENDIF.
** cookbook enhancement
IF param-name = 'RECIPIENT'.
lv_recipient = param-value.
ENDIF.

ENDLOOP.
ENDLOOP.


*-- Get Business partner number
bp_number = service_manager->get_bp_number( ).
lv_bp_number = bp_number.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 71


*-- Get original sender.
lv_recipient_address = service_manager->factbase->get_by_xpath( '/parts/SENDER_ADDRESS/text()' ).

*-- Check language from content analysis

lv_langu_iso = service_manager->factbase->get_by_xpath( '/parts/contentanalysis/part/classification/language/text()'
).

*-- If content analysis fails, then try from BP data.
IF lv_langu_iso IS INITIAL.
lv_langu_iso = service_manager->factbase->get_by_xpath( '/parts/BUPA/ADDRESS/LANGUISO/text()' ).
ENDIF.
IF NOT lv_langu_iso IS INITIAL.
CALL FUNCTION 'CONVERSION_EXIT_ISOLA_INPUT'
EXPORTING
INPUT = lv_langu_iso
IMPORTING
OUTPUT = lv_langu
EXCEPTIONS
UNKNOWN_LANGUAGE = 1
OTHERS = 2.
ENDIF.
*-- If everything else fails, then try system language
IF lv_langu IS INITIAL.
lv_langu = sy-langu.
ENDIF.

*-- Compose Mail
CALL FUNCTION 'CRM_ERMS_MAIL_COMPOSE'
EXPORTING
FORM_ID = lv_form
CAT_GUID = lv_cat_guid
LANGUAGE = lv_langu
BUSINESS_PARTNER = lv_bp_number
IMPORTING
ET_MAIL_BODY = lv_et_mail_body
ET_ATTACHMENTS = lv_et_attachments
ET_PICTURES = lv_et_pictures
ET_MAIL_PARTS = lv_et_mail_parts
EV_LOG_HANDLE = lv_ev_log_handle
EV_ERROR = lv_ev_error
SUBJECT = lv_subject
EXCEPTIONS
FORM_NOT_FOUND = 1
OTHERS = 2.

LOOP AT lv_et_mail_parts INTO lv_mail_part WHERE texttype = '1'.
lv_iv_texttype = '1'.
ENDLOOP.

* -> read sender addresses
CALL FUNCTION 'CRM_IM_GET_ADDRESS'
EXPORTING
iv_mail_id = lv_sender_id
CHANGING
ev_mail_address = lv_sender_address
ev_reply_address = lv_reply_address
ev_persnum = lv_send_persnum
ev_addrnum = lv_send_addrnr
ev_addrtype = lv_send_addr_type
ev_error = ev_error.

IF NOT ev_error IS INITIAL.
* RAISE CX_CRM_ERMS_SERVICE_FAILED.
EXIT.
ENDIF.


*-- Send email
CALL FUNCTION 'CRM_ERMS_MAIL_SEND'
EXPORTING
EV_PARTNER = lv_bp_number
** cookbook
IV_RECIPIENT = lv_recipient
IV_SENDER = lv_sender_address
IV_REPLY = lv_reply_address
IV_LOG_HANDLE = lv_ev_log_handle
IV_LANGUAGE = lv_langu
IV_TEXTTYPE = lv_iv_texttype
IV_SUBJECT = lv_subject
IV_SEND_IMMEDIATELY = 'X'
* IV_ACTIVITY_GUID =
* IV_MESS_COLL = ' '
* IV_IO_GUID =
IT_ATTACHMENTS = lv_et_attachments
IMPORTING
EV_DOCUMENT = lc_ev_document
EV_SEND_REQUEST = lc_ev_send_request
TABLES
IT_MAIL_BODY = lv_et_mail_body
* IT_TEXTS =
IT_MAIL_PARTS = lv_et_mail_parts
IT_PICTURES = lv_et_pictures
CHANGING
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 72

IS_ITEM_DS = lv_is_item_ds
IV_ERROR_COUNTER = lv_iv_error_counter
LV_ERROR = lv_error
CS_CRMMAIL = lv_cs_crmmail
EXCEPTIONS
SENDER_EQUAL_RECIPIENT = 1.

if sy-subrc = 0.
conid = service_manager->get_email_id( ).

CALL FUNCTION 'CRM_ERMS_RPT_EVENT_HANDLER'
EXPORTING
** cookbook
EVENT_ID = 'ZNO'
CONNECTION_ID = conid
FROM_ICWC = ' '
* EXT_ADDRESS =
* INT_ADDRESS =
* FIRST_ORG_UNIT = ''
* SECOND_ORG_UNIT = ''
* FIRST_AGENT = ''
* SECOND_AGENT = ''
* EMAIL_TIMESTAMP =
.
ELSE.
LV_SHORTTEXT = 'Acknowledgement can not be sent because sender and recipient are the same.'(001).
RAISE EXCEPTION TYPE CX_CRM_ERMS_SERVICE_FAILED
EXPORTING
* TEXTID =
* PREVIOUS =
* SERVICE =
SHORTTEXT = LV_SHORTTEXT
.


endif.


*-- Create interaction record if indicated, and if there is a BP.
IF lv_create_int_record EQ 'X' AND NOT lv_bp_number IS INITIAL.
ls_partner-partner = bp_number.
APPEND ls_partner TO lt_partner.
* -- Get BCI object id
lv_email_id = service_manager->get_email_id( ).
lv_bci_key-objtp = lv_email_id+17(3).
lv_bci_key-objyr = lv_email_id+20(2).
lv_bci_key-objno = lv_email_id+22(12).

* -- Convert BCI to BCS For incoming e-mail
CALL METHOD cl_crm_email_utility=>get_bcs_obj_from_bci_key
EXPORTING
IS_BCI_KEY = lv_bci_key
IMPORTING
EV_BCS_KEY = lv_bcs_key
* EV_DOCUMENT_BCS =
* EV_SEND_REQUEST_BCS =
* EV_BCS =
.

** cookbook
lv_process_type = service_manager->get_service_property( 'ZPROCESS_TYPE' )."#EC NOTEXT
lv_template_guid = service_manager->get_service_property( 'ZTEMPLATE_GUID' )."#EC NOTEXT

* -- Create the interaction record.
CALL METHOD cl_crm_email_utility=>create_activity
EXPORTING
IV_PROCESS_TYPE = lv_process_type
IV_TEMPLATE_GUID = lv_template_guid
IV_DESCRIPTION = lv_description
IT_LINK_PARTNER = lt_partner
IV_SEND_REQUEST_ID = lv_bcs_key
IMPORTING
ET_RETURN = lt_return
ET_ACTIVITIES = lt_activity.


LOOP AT lt_activity INTO ls_activity.
lv_activity-objkey = ls_activity-guid.
lv_activity-objtype = 'BUS2000126'.
lv_sapoffdoc-objkey = lv_email_id.
lv_sapoffdoc-objtype = 'SOFM'.

*-- Link incoming e-mail
CALL FUNCTION 'BINARY_RELATION_CREATE'
EXPORTING
OBJ_ROLEA = LV_ACTIVITY
OBJ_ROLEB = LV_SAPOFFDOC
RELATIONTYPE = 'INTO'
* FIRE_EVENTS = 'X'
* IMPORTING
* BINREL =
* TABLES
* BINREL_ATTRIB =
EXCEPTIONS
NO_MODEL = 1
INTERNAL_ERROR = 2
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 73

UNKNOWN = 3
OTHERS = 4
.
commit work.
IF SY-SUBRC <> 0.
* MESSAGE ID SY-MSGID TYPE SY-MSGTY NUMBER SY-MSGNO
* WITH SY-MSGV1 SY-MSGV2 SY-MSGV3 SY-MSGV4.
ENDIF.
ENDLOOP.
ENDIF.
endmethod.


Input support for action parameters is implemented like the support for conditions.

4. To include the notification in the reporting, enhance Customizing activity Customer Relationship
Management E-Mail Response Management System Reporting Define Events to match the
call of the reporting event handler CRM_ERMS_RPT_EVENT_HANDLER in the action class
implementation.


Leave the status column empty as we do not want to introduce a new status for this event.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 74

3 Tutorial: Working with Views and View Sets
This chapter explains how to work with views and view sets. You will learn how to enhance existing views
with input fields, dropdown list boxes, and buttons, and how to create your own views and view sets.
Fundamentals of the architecture, the Model View Controller (MVC) programming model, controllers, and
the business object layer (BOL) will be explained in sufficient depth in order for you to be able to answer
most customer requirements. We recommend reading this section in its entirety since the knowledge and
examples of several sections build on those in previous sections.

SAP CRM 4.0 Add-On for Service Industries Update
New with the SAP CRM 4.0 Add-On for Service Industries is the introduction of the wizards in the IC
WebClient workbench (Transaction BSP_WD_WORKBENCH). Wizards are available to:
Copy a view to another BSP application
(Prerequisite for using the other wizards)
Create a new view
Create a new context node
Create a new attribute within an existing context node
The wizards will automatically create subclasses so that changes can be performed without modifying the
system. This only works in systems set to customer mode and not in systems running in SAP mode where
the original classes would be modified.
3.1 Preparation
Before you can start changing a view layout or altering the application, you must first do some preparation
work, which is detailed in this section.

The core Interaction Center (IC) WebClient application is contained in Business Server Page (BSP)
application CRM_IC in package CRM_IC_APPL. Direct changes in views or controllers of this BSP
application would be modifications which can be avoided quite easily.

For this purpose, we need to create a new BSP application in the customer namespace and assign it to a
customer package, if you want to transport your developments. The remainder of this chapter assumes
you are working in package Z_CONS_COOK which contains BSP application Z_CRM_IC. Create these
objects as follows:
1. In the object navigator (transaction SE80), and choose Package from the dropdown list box.
2. Enter Z_CONS_COOK in the input field and choose Enter.
You can specify further information about the new package in the dialog box that appears, which
is illustrated in the following figure:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 75

Creating Package Z_CONS_COOK


3. Create BSP application Z_CRM_IC within this package by right-clicking on the package name and
creating the BSP application as shown in the following two figures:
Creating BSP Applications (1)


Creating BSP Applications (2)


It is always a good idea to change the property of the BSP application to Stateful.
3.2 Working with Views
3.2.1 Replacing One Input Field with Another Input Field
The example for this section will be the account identification view set. This view set is a good example
because requirements for identifying and maintaining business partners are so numerous that you will
most likely implement changes in this area frequently.

The goal is to replace the two Function fields on the More Fields view with the contact persons date and
place of birth.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 76

Standard View More Fields (Contact Person)


The end result will look like the following figure. Note that there is a calendar as input help for the Date of
Birth field.

Goal: New Fields Date of Birth and Birthplace


3.2.1.1 Step 1: Copy Standard Views and Controllers

1. Copy the corresponding BSP view and controller.
In this case, we copy the view BuPaMoreContactView.htm and the controller
BuPaMoreContactView.do into our application Z_CRM_IC. Be sure not to confuse it with
BuPaEMoreContactView.

Views should always be copied using the IC
WebClient workbench
(BSP_WD_WORKBENCH).
2. Enter application CRM_IC and can leave the
Runtime profile blank for now.
3. Open the node for views and find the view
BuPaMoreContactView.
4. Right-click on the view, choose copy, and
when asked for the Target BSP Application,
enter Z_CRM_IC.
Do not change the name of the target view in
this example!
This will copy the view consisting of the view
layout *.htm and the controller definition *.do
to the target BSP Application.
5. Go back in/restart the IC WebClient
workbench to select the target application
Z_CRM_IC which will show you your newly
copied view.
This also gives you comfortable navigation
to all objects contained in the view.

You can see that the controller, context, and
context node classes are still the original ones.

When you now navigate to the view layout BuPaMoreContactView.htm you see the layout is active.
However make a syntax check (Crtl+F2) and you will encounter a syntax error telling you that one or
several include files are not available in the BSP application Z_CRM_IC. This is because the relative
location of the view has been changed by the copying process. To remedy this, change the view layout as
shown in the following figure:

Code Changes for Views

Please note that these changes are particular for the chosen example. You may not encounter this type of
inconsistency each time you copy a view and try to activate it. Alternatively, you could copy the includes
into Z_CRM_IC.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 78

3.2.1.2 Step 2: Customize IC WebClient Profile

After copying the objects into the customer namespace, we need to have the IC WebClient use this new
view:
1. Choose Implementation Guide (IMG) activity Customer Relationship Management - Interaction
Center WebClient Customer-Specific System Modifications Define IC WebClient Runtime
Framework Profiles.
2. Enter profile name Z_COOKBOOK in the input field and choose Execute (F8).
A message appears stating that the entry does not exist and asks if you want to create the object.
3. Choose Yes.
An XML editor appears.
4. Enter the following XML code (can be partially copied from the DEFAULT profile):
Sample Code
<?xml version="1.0"?>
<RuntimeFrameworkSettings>
<RuntimeRepositorySource type="BSP">
<BspApplication>CRM_IC_RT_REP</BspApplication>
<PageName>CRM_IC.xml</PageName>
</RuntimeRepositorySource>
<WorkareaDefinition>
<ViewSet>workViewSet</ViewSet>
<ViewArea>workViewSetArea</ViewArea>
</WorkareaDefinition>
<ControllerReplacements>
<ControllerReplacement>
<ReplacedController>BuPaMoreContactView</ReplacedController>
<ReplacingController>Z_CRM_IC/BuPaMoreContactView</ReplacingController>
</ControllerReplacement>
</ControllerReplacements>
<InteractionLayerApplication>ALL</InteractionLayerApplication>
</RuntimeFrameworkSettings>

The tags tell the system to replace the standard view with the view as it is defined in our BSP
application. You can validate the XML by clicking on the validate button. A browser window opens with
the result of the validation (for this you have to have MSXML.DLL Version 4.0 installed).

5. Create an IC WebClient profile by copying the default profile DEFAULT to Z_COOKBOOK as
follows:
i) Choose IMG activity Customer Relationship Management Interaction Center WebClient
Define IC WebClient Profiles.
ii) Enter Z_COOKBOOK for the framework profile name
iii) Save your entries.

Assign the IC WebClient profile to your users or business partners position in organizational
management and restart the IC WebClient (application CRM_IC).


3.2.1.3 Step 3: Replace Input Fields

In the previous steps, you have completed the necessary preparation work: we have our own view in the
customer namespace, it is assigned to our IC WebClient profile, and we can now start changing the view
without modifying the SAP standard.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 79

If we look into the source code of the view and compare the grid positions with the browser display, we
find that the following code fragment is responsible for the three input fields we want to replace:

Code Fragment for Function Fields


Note: Now we need to find the replacement fields among the page attributes: Date of Birth and Birthplace.
In our case, this is the page attribute ContactPerson. The first way is to use standard forward navigation.
If you navigate (by double-clicking) to the class definition of this page attribute, which can be found on tab
Page Attributes, you will notice the following methods:
SET_BIRTHDATE / GET_BIRTHDATE
SET_BIRTHPLACE / GET_BIRTHPLACE
The second, easier way is to use the tree in the IC workbench. We already know from previous sections
that all page attributes in the view layout correspond to context nodes. Now we open node view controller
in the IC workbench navigation tree and follow it down via context, context node to the context node
CONTACTPERSON and open folder Attributes there. Now we see all available attributes on this context
node, especially the attributes BIRTHDATE and BIRTHPLACE.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 80



Double-clicking the node for the implementation class for context node CONTACTPERSON leads you to
the same class as the standard forward navigation CL_CRM_IC_BUPAMORECONTACT_CN04. You will
find the GET_*, GET_M_*, and SET_* methods for the attributes in the class overview.

These methods were generated from XML files in the Design Time Repository (for more information, see
section Creating the View Definition for Design Time Repository) and can be used for HTMLB tags like in
this example of context nodes. The notation for their usage is:

//Page Attribute/Property

Hence, in this case:

//ContactPerson/Birthdate
//ContactPerson/Birthplace

Consequently, we replace the highlighted code in the figure above with the following:

<crmic:gridLayoutCell columnIndex="1" rowIndex="9" colSpan="3"><crmic:label
design = "label"
id = "Birthdate"
for = "//ContactPerson/Birthdate" /></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="4" rowIndex="9"
colSpan=2><crmic:inputField
id = "Birthdate"
showHelp = "TRUE"
width = "100%"
maxlength = "10"
type = "DATE"
value = "//ContactPerson/Birthdate"
/></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="1" rowIndex="10" colSpan="3"><crmic:label
design = "label"
for = "//ContactPerson/Birthplace"/></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="4" rowIndex="10"
colSpan="5"><crmic:inputField
id = "Birthplace"
maxlength = "40"
width = "100%"
value = "//ContactPerson/Birthplace"
/></crmic:gridLayoutCell>

Note the formatting. This is necessary in order to avoid misaligned grid cells. The input help of a calendar-
type input field is provided by the following tags:
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 81


type = "DATE"
showHelp = "TRUE"

Now activate your changes and test the IC WebClient (application CRM_IC).
For a quick check of only the layout you can also use the preview functionality of the IC workbench. It is
available via context menu (right mouse button) on the view layout. You may need to wait a few seconds
until the preview appears.


3.2.2 Replacing Input Fields with Dropdown Boxes
Building on the results of section Replacing One Input Field with Another Input Field, we now want to
replace field Department and the corresponding description field with a dropdown box. Following the
description in this section, you will also learn how dropdown boxes work in general and therefore also be
able to program a (new) dropdown box on any view.

Dropdown boxes are very useful in places where space is limited and where value help options (leading to
popup windows) are not recommended.

The desired result in our example looks like this:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 82

Goal: Dropdown Box for Department Field


3.2.2.1 Step 1: Replace View Controllers

Dropdown boxes work with keys and descriptions, which makes them very handy. The result is an easily
comprehensible list of text values to choose from, and at the same time, internally a technical value is
used that can be directly stored in a database table, for example.

In our case, the controller is BuPaMoreContactView.do in BSP application Z_CRM_IC. The implementing
class in the standard is CL_CRM_IC_BUPAMORECONTACT_IMPL.

1. For the value table of the dropdown box we need a new context node. Start the IC WebClient
workbench for BSP application Z_CRM_IC. Navigate to the context of view
BuPaMoreContactView, expand it and right click on the context nodes folder. Choose Create from
the context menu.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 83

2. Insert a name for the new context node and mark it for use with dropdown box.
3. Skip the wizard step for linking to a custom controller. This is only necessary if the values for the
dropdown box should be shared with other view via a custom controller.
4. Skip through the next page of the wizard and complete the creation. The wizard automatically
creates the necessary subclasses for the view controller and context implementation class and
adjust the controller definition and the view layout accordingly. The wizard automatically builds
names for the subclasses. The naming convention is implemented in BAdI BSP_WD_APPL_WB
method GET_CUST_CLASSNAME_PROPOSAL. The default implementation replaces the first
letter with a Z. If a class with the proposed name already exists the wizard asks the user for an
alternative name. All of this only works if you created the copy of the view using the wizard.
3.2.2.2 Step 2: Determine Key and Description Table for Dropdown Boxes

The wizard automatically created a context node DEPARTMENT which is of predefined class type
CL_BSP_WD_CONTEXT_NODE_DDLB. This class offers method SET_VALUE_TABLE for setting the
value table for the dropdown box. The table is of predefined type BSP_WD_DROPDOWN_TABLE. In
assumption the value table will not change as long the view is display we have to set it only once in the
DO_INIT_CONTEXT method of the controller class.

Since the tree in the IC workbench is not automatically refreshed, restart the Workbench and load the
BSP application again. When we now open the view BuPaMoreContactView we see the new controller
implementation class, ZL_CRM_IC_BUPAMORECONTACT_IMPL. By double-clicking, navigate to the
class editor. Redefine method DO_INIT_CONTEXT and implement the method as follows:

method DO_INIT_CONTEXT .

call method SUPER->DO_INIT_CONTEXT.

* initial creation of table for dropdown values
data: LT_VALUES type BSP_WD_DROPDOWN_TABLE,
LS_VALUE type BSP_WD_DROPDOWN_LINE,
LT_DB_VALUES type table of TB911.
field-symbols: <LINE> type TB911.

* get values from DB table
select ABTNR BEZ20 from TB911 into table LT_DB_VALUES
where SPRAS = SY-LANGU.
* fill DDLB value table
loop at LT_DB_VALUES assigning <LINE>.
LS_VALUE-KEY = <LINE>-ABTNR.
LS_VALUE-VALUE = <LINE>-BEZ20.
append LS_VALUE to LT_VALUES.
endloop.
* allow empty selection
append initial line to LT_VALUES.

* sort by text value
sort LT_VALUES by VALUE.


ZTYPED_CONTEXT->DEPARTMENT->SET_VALUE_TABLE( LT_VALUES ).

endmethod.



Since we cannot change the attribute TYPED_CONTEXT, referring to the context, in the controller
class the wizard adds an additional attribute ZTYPED_CONTEXT to the derived controller class.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 84

This additional attribute has the exact type of the also derived context class. Therefore, it is
possible to directly access the additional context nodes.

If the value table for the dropdown box should change on roundtrips, put the implementation in
method DO_PREPARE_OUTPUT instead of DO_INIT_CONTEXT.
3.2.2.3 Step 3: Replace Input Fields with Dropdown Boxes

The dropdown box works by specifying the key/description table, the field names of the key column,
and the description column of this table.

For our example, the following changes are needed. They appear in the code right below the new
birthdate and birthplace fields described in section Replacing One Input Field with Another Input Field.

Layout Changes for Dropdown Boxes


Activate your changes and test the WebClient (application CRM_IC).
3.2.3 Adding Buttons to Views
A requirement you may be confronted with frequently is adding buttons to views. This section explains this
procedure by building on the work done in section Replacing Input Fields with Dropdown Boxes.

In this section, we demonstrate how to place a button labeled Goto Account on our view. Its purpose is the
same as the Account link near the top of the view. The result should look like the following figure:
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 85


Goal: New Button Goto Account

3.2.3.1 Step 1: Create Buttons on Views

The button should be added to the right of the Cancel button.
1. Add the following HTMLB code (add the bold text):
<crmic:gridLayoutCell columnIndex="1" rowIndex="3" colSpan="2"
horizontalAlignment="LEFT"
><crmic:button id = "Done"
onClick = "done" design="EMPHASIZED"
priority = "1"
text = "<%= otr(crm_ic_appl/Done) %>"
/>&nbsp;<crmic:button id = "Clear"
onClick = "cancel"
text = "<%= otr(crm_ic_appl/Cancel) %>"
/>&nbsp;<crmic:button id = "GotoAccount"
onClick = "GotoAccount"
text = "<%= otr(z_cons_cook/GotoAccount) %>"
/></crmic:gridLayoutCell>

2. Activate the view.

3.2.3.2 Step 2: Maintain Texts in the Online Text Repository (OTR)
The Online Text Repository (OTR) stores texts centrally and delivers services for processing and
managing these texts. At runtime, these texts are replaced by the text defined for the logon language.
Frequently occurring texts can be used in all packages. Each text should only be defined once per
package.
Syntax in HTMLB: <%=otr(Package/OTR-Name)%>
or: <%=page->otr_trim( 'Package/OTR-Name' )%>
(With OTR_TRIM, the text is generated without spaces at the beginning and end of the expression. This is
important when the text is to be displayed as a link, for example.)

In this context, Package means the component for which development work is done, while OTR Name is
the keyword for the OTR text.

In our example, we maintain OTR text GotoAccount in package Z_CONS_COOK as follows:
1. Display the view in the Web application builder (SE80), and choose Goto Online Text
Repository Browser.
2. In the dialog box that appears, choose Create.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 86

3. Enter the necessary information in the corresponding fields, as shown in the following figure, and
save your entry.

Maintain OTR Texts Using the OTR Editor

3.2.3.3 Step 3: Program Event Handlers

If you test your view now by choosing New, you will notice that a server roundtrip happens, but nothing
else. The reason for this is that the controller class is not yet handling the event. The way we defined the
button, the event raised is GotoAccount (see tag onClick). HTMLB events are handled by the method
do_handle_event in the view controller class. In order to incorporate a handler for our event, we need to
redefine this method:
1. Call up class ZL_CRM_IC_BUPAMORECONTACT_IMPL in transaction SE80.
2. Expand the object list tree along Methods Inherited Methods.
3. Find the method do_handle_event, preceded by a yellow triangle. Right-click this method and
choose Redefine.
4. Insert the following code into the event handler method:
METHOD do_handle_event .

CALL METHOD super->do_handle_event
EXPORTING
event = event
htmlb_event = htmlb_event
htmlb_event_ex = htmlb_event_ex
global_messages = global_messages
RECEIVING
global_event = global_event.

CASE htmlb_event->server_event.
WHEN 'GotoAccount'.
eh_oncustomerview( ).
ENDCASE.

ENDMETHOD.

The method eh_oncustomerview performs the navigation to the Account view. Note that we are calling the
super method before we examine our own events. Its best to always make sure that the event names are
unique within a view. Across the whole application, though, the same event name can be used multiple
times.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 87

3.3 Using Different Fields from the Business Object Layer (BOL) in Views
In section Replace Input Fields, we saw a simple example of displaying a field in a view which exists in the
context node. How do you proceed if the field does not exist in the context node? In other words, what do
you do if there are no GET_MYFIELD and SET_MYFIELD methods?

It depends. The following rules of thumb may help:
1. If you want to add only a few fields you can use a wizard to add the necessary methods to the
context node.
2. If you need to extend the standard database tables, use the Easy Enhancement Workbench.
Depending on the implementation of the BOL entities they get automatically extended or not. You
can use transaction GENIL_MODEL_BROWSER to verify this or call up the BOL model directly
from the IC workbench. Unfortunately it might also happen that the additional fields are directly
available in the BOL model but they get no value. In this case you will have to adjust the
implementation of the responsible GenIL component.
3. If you add entire objects but the standard view is still a good starting point, you might first add
additional context nodes with the corresponding wizard and then add attributes to them using the
other wizard.
4. If no standard view suits your needs, because you want to display only customer fields or the
reuse of an existing view would only be little, you can create a complete new view with the
corresponding wizard.

In this section we demonstrate how to add the Function field to the contact person details. The result
should look like this:

Goal: Valid Through Field in Contact Person Details


Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 88

3.3.1 Identifying Business Object Layer (BOL) Objects
The entire model of the CRM business transaction object in the business object layer (BOL) can be found
by
Using the IC WebClient workbench
To do this, open the BOL Model Browser container and make sure you select a runtime
framework when starting the workbench
Choosing BOL Model in the toolbar



There are ABAP statements to create objects and to navigate within the object model to related objects.
For more information, see section Creating View Controller Classes. The root object for the CRM business
transaction is BuilHeader. In the relationship BuilContactPersonRel, you find the DATE_FROM field
we want to add to our view.
3.3.2 Identifying and Changing Context Nodes
The view we need to change for our example is BuPaMoreContactView which we already copied into our
BSP application Z_CRM_IC by using the wizard.

Identifying the correct context node is a matter of experience. Since SAP views are generated from XML
files, the page attributes that represent the context nodes, which in turn bind to the BOL object model,
usually have the same or nearly the same names as their corresponding BOL entity.

In general, you can lookup the relation between context nodes in method CONNECT_NODES of the
context class. There the dependencies between nodes were built up. A dependency is build by registering
the event handler ON_NEW_FOCUS of the dependant node to the NEW_FOCUS event of its parent. In
order to find out how this relation is mapped to the BOL model, it is sufficient to have a look in the
registered event handler.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 89


1. Use the wizard to create the new field.
2. Start BSP_WD_WORKBENCH with BSP application Z_CRM_IC and navigate to the
BuPaMoreContactView view.
3. Call up the attributes for context node CONTACTRELATION, right click on Attributes, and choose
Create from the context menu.



4. Enter the necessary information for the new field into the wizard as follows and create the
attribute.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 90



This automatically creates necessary subclasses and the following methods in the implementation class of
the context node:



3.3.3 Changing View Layouts
1. Similar to the example in section Replacing Input Fields with Dropdown Boxes, change the view
layout as follows:

[...]
<crmic:gridLayoutCell columnIndex="4" rowIndex="14" colSpan="5"><crmic:inputField
id = "VIP"
disabled = "TRUE"
width = "100%"
value = "//ContactRelation/Vip" /></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="1" rowIndex="15" colSpan="3"><crmic:label
design = "label"
for = "//ContactRelation/Comments" /></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="4" rowIndex="15" colSpan="5"><crmic:inputField
id = "Comments"
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 91

width = "100%"
maxlength = "40"
value = "//ContactRelation/Comments"
/></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="1" rowIndex="16" colSpan="3">
<crmic:label design = "label"
for = "//ContactRelation/DateTo" /></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="4" rowIndex="16" colSpan="4">
<crmic:inputField
id = "DateTo"
maxlength = "10"
type = "DATE"
disabled = "<%=ContactRelation->GET_I_DATETO( )%>"
value = "//ContactRelation/DateTo" />
</crmic:gridLayoutCell>
</crmic:gridLayout>
</crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="3" rowIndex="2">
<crmic:gridLayout cellSpacing = "1"
columnSize = "8"
rowSize = "3"
height = "100%"
width = "100%"
widthPredefine = "TRUE">
<crmic:gridLayoutCell columnIndex="1" rowIndex="1" colSpan="8"><%@ include
file="../CRM_IC/BuPaMoreTelephoneInclude.htm" %></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="1" rowIndex="2" colSpan="8"><%@ include
file="../CRM_IC/BuPaMoreFaxInclude.htm" %></crmic:gridLayoutCell>
<crmic:gridLayoutCell columnIndex="1" rowIndex="3" colSpan="8"><%@ include
file="../CRM_IC/BuPaMoreEmailInclude.htm" %></crmic:gridLayoutCell>
</crmic:gridLayout></crmic:gridLayoutCell>
[...]

2. Change the page attribute for ContactRelation to reflect the new class.
This makes sure the GET_I_DATETO( ) method, which is responsible for dynamically enabling or
disabling the field can be found.



3. Activate the view layout and test your changes.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 92

3.4 Working with Customer-Specific View Sets
This section describes how to create your own view set and view using the wizard.

Even if you do not plan to create your own view set, this section contains a lot of information that is also
useful in different areas. You will learn the basics of the IC WebClient framework, allowing you to create
your own navigational links for instance, and you will get a better feeling for the architecture and most
important view controller methods.

The example for this section is a very simple view for the follow-up activity. The result is whenever you
click the link of a follow up activity from the activity clipboard, the system leads you to our very simple
Activity view on which you can maintain the description and the status.

Simple Activity View


3.4.1 Creating the View Set and Controllers
The following steps are necessary to create your view set:
1. Use the wizard to create a new view set SimpleActivitySet.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 93


2. Skip through all following steps in the wizard.
3. Redefine the method if_bsp_wd_history_state_descr~get_state_description in the
generated class ZL_Z_CRM_IC_SIMPLEACTIVIT_IMPL as follows:
METHOD if_bsp_wd_history_state_descr~get_state_description .

description = text-001. " 'Simple Activity'

ENDMETHOD.
This method is called by the framework whenever the quick navigation dropdown box is refreshed.
It returns the text to be displayed, in our case, Simple Activity. Double-click on text-001 in order
to create the program text.
4. Add the following code to the layout of the view set:
<%@page language="abap"%>
<%@ extension name="htmlb" prefix="htmlb"%>
<%@ extension name="xhtmlb" prefix="xhtmlb"%>
<%@ extension name="crm_bsp_ic" prefix="crmic"%>
<%@ extension name="bsp" prefix="bsp"%>
<crmic:gridLayout cellPadding="0" cellSpacing="2" columnSize="1" rowSize="1"
width="100%" height="100%">
<crmic:gridLayoutCell columnIndex="1" rowIndex="1" width="100%" height="34%">
<bsp:call comp_id="<%=controller->GET_VIEWAREA_CONTENT_ID( 'SimpAct' )%>"
url="<%=controller->GET_VIEWAREA_CONTENT_URL( 'SimpAct' )%>"/>
</crmic:gridLayoutCell>
</crmic:gridLayout>

This HTMLB code simply creates a grid layout with one cell. Within the cell, we call the view by its
ID (SimpAct). The ID is later on defined in the framework (cf. section 3.4.3.2).

This design has some overhead in our case, but it shows in general how more complex view sets
are to be designed. For example, see the view set definition of the interaction record,
IRecViewSet.htm, in the BSP application CRM_IC.
5. Activate all your objects.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 94

3.4.2 Creating the View and Controllers

The following steps are necessary to create your view:
1. Start the IC WebClient workbench and right-click on the View Root node to create a new view.
2. In the wizard, enter the following data:




Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 95



We do not define value nodes here. Value nodes are context nodes which are not bound to the
BOL model but implemented in the context classes.



Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 96




Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 97



3. After this step, restart the IC WebClient workbench and see your new view in the hierarchy:



Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 98

The following methods will all be created/implemented in the controller implementation class
ZL_Z_CRM_IC_SIMPLEACTIVI_IMPL. The additional controller base class should never be changed!

1. Define the inbound plug. This will be the method that is called by the framework whenever we
navigate to our view set. For more information on the link definition, see section 3.4.3.3.

Sample Code: Inbound Plug


In general, there are two way of passing parameters:
Via the business data context (BDC), which is represented by a custom controller.
At this custom controller you find the method SET_NAVIGATION_DATA and
GET_NAVIGATION_DATA to pass a context entity.
Binding to custom controller context nodes which leads to data sharing between views.
In our example we bind BTORDER, the root context node of our new view, to the
context node CURRENTINTERACTION of the BDC (custom controller CuCoBDC).
When our view is created the data of CURRENTINTERACTION is automatically set to
the node BTORDER and the data for the dependant nodes is automatically derived.
2. You can define a dropdown list box for the status as described in section 3.3.
3. The wizard automatically creates two methods that are responsible for the data transfer between
the model/controller and the view:
set_models
Sends data to the view. It is comparable to the PBO modules of traditional ABAP screen
programming.
do_handle_data
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 99

Retrieves data from the HTTP request fields. It is comparable to the PAI modules of an
ABAP screen.

3.4.3 Adjusting IC WebClient Framework
After having defined the views, controllers, and classes, we need to assign them to the runtime profile of
IC WebClient.

The first time you do this, there are some preparations needed which are explained in the following
section. After the preparation, the view and view set specific work for our example is explained.
3.4.3.1 Preparation

In order to prepare the IC WebClient framework for custom-built view sets, we need to create a new
runtime profile BSP application in the customer namespace. This BSP application will contain one page,
called CRM_IC.xml. It will contain the definition of all view sets and all navigational links by including the
corresponding files that actually contain the definitions. We build all this according to standard structures,
though it doesnt necessarily have to be this way.

To make things a bit simpler, we do not split up the repository into runtime and design time. All changes
we make are only relevant for the runtime repository.

Perform the following steps:
1. Create the BSP application Z_CRM_IC_RT_REP in the package Z_CONS_COOK.
2. Copy the file CRM_IC.xml from the BSP application CRM_IC_RT_REP to Z_CRM_IC_RT_REP.
3. Adjust the contents of this file according to the changes shown in bold in the following sample
code:
<?xml version="1.0"?>
<WebDynProDefinitions>
<Application id="CRM_IC">
<ViewSets>
<%@include file="../Z_CRM_IC_RT_REP/CRM_IC_All_Viewsets.xml" %>
</ViewSets>
<NavigationalLinks>
<%@include file="../Z_CRM_IC_RT_REP/CRM_IC_All_NavLinks.xml" %>
</NavigationalLinks>
</Application>
</WebDynProDefinitions>

Hence, CRM_IC.xml includes two more XML files which can be found in BSP application
Z_CRM_IC_RT_REP.
4. Create BSP application Z_CRM_IC_RT_REP in package Z_CONS_COOK.
5. Copy page fragment CRM_IC_All_Viewsets.xml of BSP application CRM_IC_DT_REP to
Z_CRM_IC_RT_REP and replace the file contents with the following lines:
<%@ include file="MainViewSet.xml" %>
<%@ include file="../CRM_IC_DT_REP/BuPaViewSet.xml" %>
<%@ include file="../CRM_IC_DT_REP/CRM_IC_All_Viewsets_wo_BUPA_and_Main.xml"
%>

This definition still works with all standard view sets, but replaces the MainViewSet.xml with our
own definition, since it is now loaded from Z_CRM_IC_RT_REP.
6. Copy page fragment MainViewSet.xml from BSP application CRM_IC_DT_REP to
Z_CRM_IC_RT_REP.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 100

7. Copy page fragment CRM_IC_All_NavLinks.xml of BSP application CRM_IC_DT_REP to
Z_CRM_IC_RT_REP and replace the file contents with the following line:

<%@ include file="../CRM_IC_DT_REP/CRM_IC_All_NavLinks.xml" %>

This definition makes sure that standard navigational links still work and that we are able to add
our own link definitions later on.
8. Activate all objects.
9. Customize the IC WebClient runtime framework profile in such a way that the new source file is
used, as shown in the following sample code:
<?xml version="1.0"?>
<RuntimeFrameworkSettings>
<RuntimeRepositorySource type="BSP">
<BspApplication>Z_CRM_IC_RT_REP</BspApplication>
<PageName>CRM_IC.xml</PageName>
</RuntimeRepositorySource>
<WorkareaDefinition>
<ViewSet>workViewSet</ViewSet>
<ViewArea>workViewSetArea</ViewArea>
</WorkareaDefinition>
<ControllerReplacements>
<ControllerReplacement>
<ReplacedController>BuPaMoreContactView</ReplacedController>
<ReplacingController>Z_CRM_IC/BuPaMoreContactView</ReplacingController>
</ControllerReplacement>
<ControllerReplacement>
<ReplacedController>IRecReason</ReplacedController>
<ReplacingController>Z_CRM_IC/IRecReason</ReplacingController>
</ControllerReplacement>
</ControllerReplacements>
<InteractionLayerApplication>ALL</InteractionLayerApplication>
</RuntimeFrameworkSettings>
3.4.3.2 Creating View Definitions for Design Time Repositories

Every new view set must be defined in the runtime repository.
1. Create page fragment SimpleActivitySet.xml in BSP application Z_CRM_IC_RT_REP and maintain it
as shown in the following sample code:
<ViewSet id="Z_CRM_IC/SimpleActivitySet">
<ViewArea id="SimpAct" views="Z_CRM_IC/SimpleActivity"/>
</ViewSet>



The view area ID (SimpAct) is the name of the literal used in the bsp:call tag. For more
information, see section 3.4.1.
2. Include this file in the framework. Place the following line into page CRM_IC_All_Viewsets.xml in
BSP application Z_CRM_IC_RT_REP:

<%@ include file="SimpleActivitySet.xml" %>

3. Activate your objects.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 101

3.4.3.3 Creating Navigational Link Definitions for Design Time Repositories

In order to provide a navigational link for the activity clipboard, we need to define this link.
1. Create page fragment SimpleActivityNavLinks.xml in BSP application Z_CRM_IC_RT_REP and
maintain it as shown in the following sample code:
<NavigationalLink name="SimpleActivity">
<Source viewRef="IRecActivitiesClipboard" outboundPlugRef="default"/>
<Targets>
<Target viewRef="Z_CRM_IC/SimpleActivity"
inboundPlugRef="inboundplugid"/>
</Targets>
</NavigationalLink>

The name of the link is SimpleActivity. We will refer to it in the activity clipboard Customizing. For
more information, see section 3.4.3.5. The link can be activated on the view
IRecActivitiesClipboard and it navigates to the view SimpleActivity in BSP application
Z_CRM_IC. When the target view is activated, method ip_inboundplugid of the view controller
class is called.



The framework adds the prefix ip_ automatically for this method.

2. Similar to the view definition, include the navigational link into the runtime repository. Add the
following line to the file CRM_IC_All_NavLinks.xml in BSP application Z_CRM_IC_RT_REP:
<%@ include file="SimpleActivityNavLinks.xml" %>

3. Activate your objects.

3.4.3.4 Placing View Sets into Controller Hierarchies

After the view set and the navigational link are defined, we finally add our new view to the possible views
for the work area. We need to adjust the file MainViewSet.xml in BSP application Z_CRM_IC_RT_REP. Add
the reference to our view set and activate the file as shown in the following sample code:
<ViewSet id="ICAPPMainViewSet">
<ViewArea id="navigationArea" views="navigationViewSet"/>
<ViewArea id="workArea" views="workViewSet"/>
<ViewArea id="contextArea" views="contextAreaView"/>
<ViewArea id="breadCrumbsArea" views="BreadCrumbsView"/>
<ViewArea id="globalSearchArea" views="HistoryView"/>
<ViewArea id="helpArea" views="Help"/>
<ViewArea id="statusArea" views="StatusView"/>
<ViewArea id="errorArea" views="ErrorViewSet"/>
</ViewSet>

<ViewSet id="navigationViewSet">
<ViewArea id="navigationViewSetArea" views="NavBarView"/>
</ViewSet>
<ViewSet id="workViewSet">
<ViewArea id="workViewSetArea"
views="<%@include file='../CRM_IC_DT_REP/StdWorkareaOccupation.xml' %>
Z_CRM_IC/SimpleActivitySet"/>
</ViewSet>
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 102

3.4.3.5 Verifying the Runtime Repository

After making all necessary changes in the new runtime repository, we will validate it to make sure all
changes are right. There are two possibilities to start the validation:
Start the XML validation in the IC workbench
Start the validation as BSP application CRM_IC_CHECK

As a precondition for the XML validation, you have to have the library MSXML4.0 or higher installed on the
front end PC. You can download it for free from the Microsoft homepage.
3.4.3.6 Customizing Activity Clipboard

In order to make the activity clipboard call our new view set, we need to change its customizing.
1. Create a profile called Z_COOKBOOK as a copy of the DEFAULT profile.
2. Assign this profile to IC WebClient profile Z_COOKBOOK.
3. Incorporate the changes in bold in the following sample code into the activity clipboard profile:

<object id="BTOrder" wrappedObjectType="BUS2000126"
navigationalLink="SimpleActivity">
<columns>
<activity text="$(CRM_IC_APPL_UI_BDC/FOLLOWUP)">
</activity>
<description attributeXPath="//BTOrderHeader/DESCRIPTION">
</description>
<moreinfo attributeXPath="//BTOrderHeader/OBJECT_ID">
</moreinfo>
</columns>
<objectLinking>
<borForLinking id="BUS2000126"/>
<bolAttributeForBorKey id="CRM_GUID"/>
<keyMapperClass id="CL_CRM_IC_MAP_BOR2BOL_SIMPLE"/>
</objectLinking>
</object>



The specified link name is the one defined in the runtime profile. For more information, see section
3.4.3.3. It is called whenever the user clicks the link to a CRM transaction of category BUS2000126
(business activity).

4. Activate your changes and test the IC WebClient (application CRM_IC).
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 103

Glossary

Term Definition
BOL Business object layer
BOL browser Utility to navigate within BOL
BSP Business Server Page
collection wrapper Encapsulates a BOL collection in order to
allow sharing them between context nodes
(binding). There are special version that also
extend the collections, e.g. with value
attributes.
Context The context defines the local (non persistent)
data that can be used by the view as well as
by the program implementing the controller.
The context of a view can in turn map to the
context associated with other controllers (for
example, custom controllers).
context node A class which provides the functions for the
context such as GET- and SET-methods for
the attributes of the context. Context nodes
might build a hierarchy with predefined
dependencies. All business data of a view is
stored in context nodes.
Controller A mediator between the user interface and the
business logic.
Controllers implement the event handlers and
validators that react to events. They handle
events triggered by the user on the user
interface in event handlers, propagate actions
into the business logic, and make sure that the
necessary data is collected for presentation on
the next user interface sent to the user as a
response.

controller class Class which provides the methods of the
controller
custom controller A controller that can be defined by application
development and used to share common data
over several views. Custom controllers are
defined for purposes that cannot be assigned
to view controllers. Custom controllers use
their context to communicate with their
surroundings. They are used for manipulating
data, or connecting to the back end. In
difference to view controllers the life time of
custom controllers is controlled by the
application.

Delta handling Behavior during change of data
GENIL Generic interaction layer
IC WebClient Interaction Center WebClient
IL Interaction layer
inbound plug An inbound plug defines an entry point for an
arbitrary number of navigation links. It is
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 104

represented as an event handler method on
the view controller class. The event handler
should contain application-specific coding that
needs to be processed in order to display or
update the content of the view.

J2EE Java 2 Enterprise Edition
JCo Java Connector
MVC Model View Controller
NavBar Navigation bar
OTR text Text elements which are displayed depending
on the language. These texts are stored and
maintained in the online text repository (OTR).
outbound plug Defines the events that a particular view may
raise in order to signal to its surroundings that
a change in the view composition must occur.
RFC Remote function call
view A view occupies a rectangular area of the
visualization estate of an application. The
most obvious aspect of a view is its layout. A
view can be built from user interface elements
such as buttons or input fields.
view area A view area is a part of a view set where a
view is displayed.
view set A view set consists of a certain number of
view areas, their views, and the corresponding
navigation links.
VM Virtual machine
Web AS Web Application Server

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 105

4 Appendix A: Business Object Layer (BOL) Programming
4.1 Business Object Layer

4.1.1 Abstract
This document describes the runtime programming interface of the Business Object Layer (BOL). After
you read through the material in this document, you will be able to write an application that uses BOL and
is to read and modify data. Your application may range from a simple Dynpro application to a Business
Server Page (BSP) application.

4.1.2 Introduction

After the customizable objects of for the Business Object Layer (BOL), namely business objects and query
services, are modeled and implemented you can use them at runtime. If you are a framework developer
you may prefer the generic BOL access. Alternatively, as an application developer you may access
specific business objects to implement specific application functionality.
In the next section we discuss both generic and specific approaches. Programs written according to this
BOL Application Programming Interface (API) are isolated from any changes in the underlying
implementation.

4.1.3 Overview

The Business Object Layer (BOL) Application Programming Interface (API) consists of interface classes,
which you can work with. The following figure shows the important classes and interfaces.
The lifetime of these objects is in general the whole session. However the BOL API provides the
possibility to free used business objects.

Overview of BOL API classes
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 106

Core
Query Service
IF Transaction Context
IF Entity Col Entity
BPSearch
BP
0..1
1..1
0..n
1..1
1..1
1..1
Object Model


4.1.4 Application Programming Interface

4.1.4.1 Writing an Application

For writing a Business Object Layer (BOL) application you have at least to perform the following steps.

4.1.4.2 Setting up a BOL Instance

You create an instance of BOL by calling a static method of the core class. The following code line
demonstrates this:

DATA: lr_core TYPE cl_crm_bol_core.
lr_core = cl_crm_bol_core=>get_instance( ).
lr_core->start_up( MY_APPLICATION ).

Since the core class follows the singleton design pattern you can just have one instance of it. The startup
method takes the name auf the component set you want to start as input parameter and starts the BOL.
From now on you can use all services of the BOL.

4.1.4.3 Issue Queries
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 107


Before you can work with entities you have to now them. So in general you would start your application
with the search for one or more entities. We will call this fire a query. A query service object will do this
and returns a collection of entities that match the search criteria given.
As you can see, a query is the starting point for all data access in the application. In the following sections
we will discuss how to interact with the BOL generically in a generic application or using typed generated
classes in a specific application.

4.1.4.4 Generic Application

In a generic application, such as a BOL browser, you can enumerate the available query services in the
system using the BOL object model service. Pick one of them (e.g. via user interaction), set the query
parameters and fire a query.

DATA: lv_obj_model TYPE REF TO if_genil_obj_model.
lv_obj_model = cl_crm_genil_model_service=>get_runtime_model( ).
DATA: lt_query_names TYPE crmt_ext_obj_name_tab.
CALL METHOD lv_obj_model->get_object_list
EXPORTING
iv_object_kind = if_genil_obj_model=>query_object
IMPORTING
ev_object_list = lt_query_names.

With the above coding segment you receive a table with the names of all available query services. We can
now instantiate one of them, set parameters and fire the query.

DATA: lv_query_name TYPE crmt_ext_obj_name.
READ TABLE lt_query_names INDEX 1 INTO lv_query_name.

DATA: lv_query TYPE cl_crm_bol_query_service.
lv_query = cl_crm_bol_query_service=>get_instance( lv_query_name ).

lv_query->set_property( iv_attr_name = City
iv_value = Walldorf ).
DATA: lv_result TYPE REF TO if_bol_entity_col.
lv_result = lv_query->get_query_result( ).

lv_city = lv_query->get_property( City ).

The last coding example shows how to get a runtime instance of a query service via the get_instance()
factory method. Then the query parameters are set and the query is fired to retrieve a result list of entities.
As you can also see from the example it is also possible to retrieve already set query parameters from the
query service.

4.1.4.5 Specific Application

With a typed query service the example from the last section will look like this:

DATA: lv_bpsearch TYPE zcl_bol_bpsearch.
lv_bpsearch ?= cl_crm_bol_query_service=>get_instance( BPSearch ).
lv_bpsearch->set_city( Walldorf ).
DATA: lv_result TYPE REF TO if_bol_entity_col.
lv_result = lv_bpsearch->get_query_result( ).

As you can see the only difference is a special set method for the search parameter.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 108


4.1.4.6 Working with Entities

After you get a list of entities from the query, you can start using them in your application such as
displaying then on a user interface, modifying them etc.

4.1.4.7 Generic Application

Here we work with generic interface methods, which are the same for each entity.

DATA:lv_iterator TYPE REF TO if_bol_entity_col_iterator.
lv_iterator = lv_result->get_iterator.
DATA: lv_entity TYPE cl_crm_bol_entity.
lv_entity = lv_iterator->get_first( ).
IF lv_entity IS BOUND.
DATA: lv_firstname TYPE string,
lv_lastname TYPE string.
lv_firstname = lv_entity->get_property_as_string( FirstName ).
lv_lastname = lv_entity->get_property_as_string( LastName ).
* get a 1:1 related entity
DATA: lv_def_addr TYPE cl_crm_bol_entity.
lv_def_addr = lv_entity->get_related_entity( DefaultAddress ).
* get a list of 1:N related entities
DATA: lv_addresses TYPE if_bol_entity_col.
lv_addresses = lv_entity->get_related_entities( Addresses ).
ENDIF.

This coding example shows how to access entities in the query result and how to read attributes from an
entity.
The last view lines show than how to navigate from an entity to a related entity. In conjunction with the
object model service you can use this technique to generically navigate through all relations defined in the
model.

4.1.4.8 Specific Application

In the following example we will se how to access data from typed entity classes and to navigate with
them. However typed entity classes are not available in general but they may be generated from model
data.

DATA: lv_bp TYPE REF TO zcl_bol_businesspartner.
lv_bp ?= lv_iterator->get_first( ).
IF lv_bp IS BOUND.
lv_bp->get_firstname( ).
lv_bp->get_lastname( ).
DATA: lv_def_addr TYPE zcl_bol_defaultaddress.
lv_def_addr = lv_bp->get_defaultaddress( ).
DATA: lv_addresses TYPE if_bol_entity_col.
lv_addresses = lv_bp->get_addresses( ).
ENDIF.

As you can see from the example you have to cast the element of the result collection to the desired type.

4.1.4.9 Transactions

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 109

One of the most important aspects of BOL programming is to know how to modify data. You can create,
modify, and delete entities in accordance to the BOL transaction model. The current transaction model
supports several kinds of transaction contexts. The basis form is the global transaction context, which
holds all modified objects. The second version is the fine granular transaction context, which exists for
each root object instance. In between is the third version: the custom transaction context. In this section
we only use the global context. For the other version please refer to section 4.1.6.6.

4.1.4.10 Creating Entities

The following code example shows how to create a root entity together with to related entities using the
generic BOL interface.

* 1.create the transaction context
DATA: lv_transaction TYPE REF TO if_bol_transaction_context.
lv_transaction = lv_core->begin_transaction( ).

* 2. build create parameters
DATA: lt_params TYPE crmt_name_value_pair_tab,
ls_params TYPE crmt_name_value_pair.
ls_params-name = PROCESS_TYPE.
ls_param-value = TA.
APPEND ls_params TO lt_params.

* 3. get a factory for BTOrder business object
DATA: lv_factory TYPE REF TO cl_crm_bol_entity_factory.
lv_factory = lv_core->get_entity_factory( BTOrder ).

* 4. create a BTOrder
DATA: lv_order TYPE REF TO cl_crm_bol_entity.
lv_order = lv_factory->create( lt_params ).

* 5. create child objects
DATA: lv_adm_h TYPE cl_crm_bol_entity,
lv_act_h TYPE cl_crm_bol_entity.
lv_adm_h = lv_order->create_related_entity( BTOrderHeader ).
lv_act_h = lv_adm_h->create_related_entity( BTHeaderActivityExt ).

* 6. submit created child objects
lv_core->modify( ).

* 7. save and commit your changes
lv_transaction->save( ).
lv_transaction->commit( ).

It is important to distinguish between the creation of root objects via a factory and the creation of
dependent or child objects with method create_related_entity( ). The first one triggers directly a call of the
underlying API, the second one not. So in the second case it is necessary to trigger the API call explicitly
via calling the modify( ) method. Without this call the created child objects will not get saved.

4.1.4.11 Locking Entities

Before an entity can be modified it must be locked. The current locking granularity of the BOL are the root
object instances. So the lock request for an entity is always delegated to the corresponding root instance.
In general you should lock an entity before you are going to modify it. However, the set methods of the
entity check that the entity is lock and, if not, try to do this. The setter only modifies properties in case the
entity is locked.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 110

The following code fragment shows how to lock an entity.

DATA: lv_success TYPE crmt_boolean.
lv_success = lv_entity->lock( ).

In case the lock was set the return value lv_success is true ( abap_true )

4.1.4.12 Modifying Entity Properties

Now we want to modify properties of entities. This is simply done by using the set methods of the entity. If
you have not start a transaction before modifying properties it will be created automatically.
The following code fragment shows how to modify a property of BTAdminH using the generic interface.

* 1. lock and modify a property
lv_adm_h = lv_order->get_related_entity( BTOrderHeader ).
IF lv_adm_h->lock( ) = if_genil_Boolean=>true.
lv_adm_h->set_property( iv_attr_name = DESCRIPTION
iv_value = Change description ).
ENDIF.

* 2. send all changes to BO layer
lv_core->modify( ).

* 3. get the implicitly created transaction
lv_transaction = lv_core->get_transaction( ).

* 4. save and commit your changes
lv_transaction->save( ).
lv_transaction->commit( ).

In step 1 we modify properties of entities and in step 2 we communicate all modifications to the
Application Programming Interface (API) layer. In step 3 we get access to the automatically created global
transaction context. Finally we save and commit the changes in step 4.

4.1.4.13 Deleting Entities

Like in case of creation we have again to distinguish between the deletion of root objects and the deletion
of dependant or child objects.
For root object instances the call of the delete( ) method is directly sent to the API where the complete
aggregation hierarchy is deleted. The deletion is written to the database only on commit. So you have to
use the transaction context to commit the changes.

DATA: lv_tcontext TYPE if_bol_transaction_context.
lv_order->delete( ).
lv_tcontext = lv_core->get_transaction( ).
lv_tcontext->save( ).
lv_tcontext->commit( ).

As you can see from the example you should always call the save( ) method before the commit( ) in order
to persist all changes logged in the transaction. This is necessary because the transaction ends after the
commit( ) and the context is deleted.
In case of a child object the deletion is not automatically sent to the API. You have to trigger this explicitly
by calling the modify( ) method of the core.

DATA: lv_tcontext TYPE if_bol_transaction_context.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 111

lv_adm_h->delete( ).
lv_core->modify( ).
lv_tcontext = lv_core->get_transaction( ).
lv_tcontext->save( ).
lv_tcontext->commit( ).


4.1.5 Execution of Entity Methods

4.1.5.1 Generic Application

Except working with entity properties it is also possible to call special modeled methods on an entity to
execute business functionality. So far these methods can have an arbitrary set of import parameters and
may return an entity collection of result objects.
The following coding example shows the usage.

DATA: lv_items TYPE REF TO cl_crm_bil_entity.
lv_items->execute( iv_method_name = RenumberItems ).
DATA: lv_adminh TYPE REF TO cl_crm_bil_entity,
ls_param TYPE crmt_name_value_pair,
lt_param TYPE crmt_name_value_pair_tab,
lv_result TYPE REF TO if_bol_entity_col.

ls_param-name = PROCESS_TYPE.
ls_param-value = TSRV.
append ls_param to lt_param.
lv_result = lv_adminh->execute( iv_method_name = createFollowUp
it_param = lt_param ).

4.1.6 Advanced BOL Programming

In the current implementation the Business Object Layer (BOL) recognizes two kinds of business objects
(Bos): entities and query services. In order to unify the property access for the two BO kinds some
generalizations where introduced.

4.1.6.1 Generic BO Access

For a generic BO access you can refer to the interface IF_BOL_ BO_PROPERTY_ACCESS.
Generalization of Business Object Layer (BOL) business objects (BOs)
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 112

interface
IF_BOL_BO_PROPERTY_ACCESS
CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY


You can cast query services as well as entities to a generic property access interface, which provides
generic getters and setters for BO properties.

4.1.6.2 Generic Business Object (BO) Collections

In line with the generic BO property access the BOL offers also the possibility to use a generic collection,
which can consist of query services and/or entities. This BO collection offers the same interface methods
as the more specific entity collection.

Generalization of the Collections
CL_CRM_BOL_BO_COL
CL_CRM_BOL_ENTITY_COL
IF_BOL_BO_COL
IF_BOL_ENTITY_COL


The difference is that the generic BO collection handles instances of the interface
IF_BOL_BO_PROPERTY_ACCESS where the entity collection handles entities only.

4.1.6.3 Local and Global Iterations on Collections

The generic BO collection as well as the entity collection supports a global iteration on the collection and a
local iteration using an separate iterator object.
Each collection has a well-defined focus object. Initially the first object has the focus. Any global iteration
operation will move the focus. Each focus change will be published by the event FOCUS_CHANGED of
the collection.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 113

If you want to iterate on the collection without moving the focus you can use local iteration. To do so you
request an iterator object from the collection and use this to iterate.

4.1.6.4 Searching on Collections

The general BO collection as well as the entity collection provide the method find() for searching a given
BO in the collection. If the BO is found it is returned and also the focus is set to this collection entry.
The method takes three parameters, were only one is used for the search. You can search by index, BO
instance, or with object name and ID. The parameters are taken in the given sequence. This means if you
provide an index and a BO instance only the index is used.
The local iterator interface of general BO and entity collection supports also the search by a single
property of the objects in the collection. This is provided by the method find_by_property(). The first
object, where the property has the given value, is returned. Neither the global nor the local collection
pointer is influenced by this operation.

4.1.6.5 Sorting Collections

General BO and entity collections can be sorted with the sort() method. Via this method the collection it
self is sorted and will stay in the resulting sort order. It is not possible to undo the sorting.
There is one mandatory parameter for the method, which is IV_ATTR_NAME the name of the property for
which the collection should be sorted. Per default the method sorts ascending. Using the parameter
IV_SORT_ORDER you can influence this behavior.
The sorting itself is alphabetical based on the string representation of the property. Since this may lead to
wrong results (e.g. for dates) it is possible to control the sorting by providing an instance of
IF_BOL_COL_SORTING. During the sort process the method IS_A_GREATER_B() is then called every
time to values must be compared. So with a certain implementation of this method you can influence the
sort order for your needs.

4.1.6.6 Fine Granular Transaction Handling

As already mentioned, a transaction context exists for each root object instance. This transaction context
can be access via calling method get_transaction() on an entity instance. The save() method of this
transaction context saves only the belonging root object instance and its aggregation hierarchy. However,
the commit() is global and if some implementation is not clean in transaction handling additional,
unwanted data may be saved!
There is also no monitoring of dependencies between root objects so far. It might be, that a newly created
root object refers to another newly generated object. If the first one is saved but the second one not, the
database is in an inconsistent state.
Since such dependencies are not automatically tracked so far it is up to the application to handle them.
For this reason the third kind of transaction contexts, the custom transaction contexts
CL_CRM_BOL_CUSTOM_TX_CTXT, is offered. The intension is to build a custom transaction out of any
number of single object transactions to handle them as one transaction. The following coding lines give a
little example:

* 1.create custom tx context
DATA: my_tx_context TYPE REF TO cl_crm_bol_custom_tx_context.
create object my_tx_context.

* 2. add some single object transactions
DATA: lv_entity1 TYPE REF TO cl_crm_bol_entity,
lv_entity2 TYPE REF TO cl_crm_bol_entity,
lv_tx_ctxt TYPE REF TO if_bol_transaction_context.

lv_tx_ctxt = lv_entity1->get_transaction( ).
my_tx_context->add_tx_context( lv_tx_ctxt ).
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 114

lv_tx_ctxt = lv_entity2->get_transaction( ).
my_tx_context->add_tx_context( lv_tx_ctxt ).

* 3. save and commit both single object transactions together
my_tx_context->save( ).
my_tx_context->commit( ).

Since transaction contexts can be requested/created at any time it is also possible to get the information,
if data was changed, and therefore and save is necessary, or not. This information is provided by the
method CHECK_SAVE_NEEDED().

4.1.6.7 Entity Property Modifiers / Input Readiness

BOL entities feature also a special modifier for each property. This modifier flag is a further description of
the property. It focuses mainly on input readiness and visibility on UI level. In general the generic BO
access method IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY() evaluates this
information and returns ABAP_TRUE in case the property is changeable or mandatory. In all other cases
it returns ABAP_FALSE.

The modifier for all properties of query services is changeable. For entities the following modifiers can
appear:
Read only
Changeable
Not defined
Hidden
Mandatory
Technical

All these modifiers are defined as public constants of the interface IF_GENIL_OBJ_ATTR_PROPERTIES.
If the exact modifier is requested, and not just read-only yes or no, the method
GET_PROPERTY_MODIFIER() of the entity can be used.

4.1.6.8 Excluding Entities from the Central Modify (Zombification)

Normally all changed objects, and created or deleted dependent objects are sent to the underlying APIs
with one central call of the BOL core modify() method. Depending on the application this call may appear
automatically at certain sync points. So it may happen, that entities were sent, which are not ready for
sending and therefore cause errors. In such cases it makes sense to exclude such entities from sending.
Entities are excluded from sending by the following reasons:
a dependent entities was newly created, but no properties were set
an entity was sent with modify(), but the changes were not accepted by the underlying API
and it was not changed since
an entity was explicitly deactivated

The current status of an entity can be check with the method is_send_active() on the entity instance. An
explicit change of the state is possible with the methods activate_sending() and deactivate_sending(). The
deactivation effects also aggregated children recursively.

4.1.7 Business Error Handling

In the current version only a message protocol is available. There is one message protocol/container per
root object instance and the message container manager handles them all. Additionally one global
message container exists were all non-business object (BO) instance-related messages should go to.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 115

Message Handling Model
CL_CRM_BOL_CORE
CL_CRM_GENIL_MESS_CONT_MANAGER
1
1
IF_GENIL_MESSAGE_CONTAINER
1
*


The message container manager can be reached via the core. The following coding example shows how
to get access to a particular message container.

DATA: lv_mcm TYPE REF TO cl_crm_genil_mess_cont_manager.
lv_mcm = lv_core->get_message_cont_manager( ).
DATA: lv_object_name TYPE crmt_ext_obj_name,
Lv_object_id TYPE crmt_gnil_object_id.
lv_object_name = lv_order->get_name( ).
lv_object_id = lv_order->get_key( ).
DATA: lv_mc TYPE REF TO if_genil_message_container.
lv_mc = lv_mcm->get_message_cont( iv_object_name = lv_object_name
Iv_object_id = lv_object_id ).

The message container interface provides two methods. Both take the message type as parameter, which
means that it is possible to filter for errors, warning, and so on. Possible values for the message type are
defined as constants at the interface.
The method get_number_of_messages( ) returns only the number of messages of the specified type. This
may be used to give the user a hint that messages exist. The method get_messages( ) returns than the
messages.

DATA: lv_error TYPE int4,
lt_messages TYPE crmt_genil_message_tab.
lv_error = lv_mc->get_number_of_messages( lv_mc->mt_error ).
IF lv_error <> 0.
lt_messages = lv_mc->get_messages( lv_mc->mt_error ).
ENDIF.

4.1.8 Buffering Issues

It is very important to know that the Business Object Layer (BOL) always operates on its own entity buffer.
That means:
Every entity found by a query is buffered
Every entity read via navigation over an relation is buffered
Also each modification of entities, and creation or deletion of dependent entities effects only the buffer.
The buffer is then synchronized with the modify() method.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 116

Besides the various automatisms for buffer synchronizations also some explicit sync may be necessary.
The following sections explain the possibilities.

4.1.8.1 Entity Properties

The entity method reread() should be used to synchronize the buffer state of the properties and property
modifiers of a single entity. Since this method calls the underlying Application Programming Interface
(API) directly, it should be used very carefully to prevent performance problems.

4.1.8.2 Entity Relations

The relationship between entities is also subject of buffering. But unlike buffered entities the relations
cannot get invalid and synchronized automatically. This may cause inconsistencies in some cases.
In general we distinguish between cacheable relations and those, which are not subject to buffering.
For the cacheable relations a mode can be specified for navigation. Therefore the navigation methods
get_related_entity() and get_related_entities() take an optional parameter iv_mode, which may be set to
one of the following constants:
NORMAL: This is the default and means: Take relation from buffer and read it from the underlying API, if
the buffer is empty.
BUFFER_ONLY: This takes the relation only from the buffer.
BYPASSING_BUFFER: This reads the relation from the underlying API ignoring the buffer.
These constants are defined in the class CL_CRM_BOL_ENTITY.
Non-cacheable relations are read with each navigation from the underlying API, ignoring the given mode.
Being non-cacheable is an unchangeable model property of a relation.

4.1.8.3 Preloading Views

The last two sections explained how to synchronize a single entity or relation. If a larger set of entities with
relation should be synchronized this methods are simply to ineffective. For that reason it is possible to
preload a well-defined part of the object model with a given start entity or set of entities.
Before this option can be used this model part must be defined and named. Within the context of the BOL
we call this defined model part a view.
Views are associated to BOL applications and this assignment is done in the maintenance view
CRMV_GIL_APPVIEW. Once the view was defined there its structure can be declared within maintenance
view CRMV_VIEWREG. Both can be found in the customizing (transaction SPRO).
Each view has a unique view root, which is either a root object or access object.
Now the method prefetch_view() can be called on the BOL core. It takes the view name and a collection of
entities as input. The model part defined by the view is read for each entity in the collection and stored in
the buffer. Of course the entities in the collection must match the view root.

4.1.8.4 Locking with Synchronization

After setting a lock it may be advantageous to synchronize the BOL buffer for the locked entity with the
current database state. This may be necessary because of:
The entity have been changed by someone else since the last read, or
the last lock attempt failed, because the entity was already locked. Because of the failure the entity was
set to read-only mode. Now we try it again and the property modifiers have to be refreshed.
Therefore the lock() method takes an optional parameter iv_reread. Per default it is set to ABAP_FALSE.
If it is set to ABAP_TRUE the full aggregation hierarchy of the locked root entity is invalidated in the buffer
and synchronized on the next access.

4.1.8.5 BOL Reset

Since the BOL buffer and the message services only collect information the amount of data constantly
grows with time. Therefore a mechanism is necessary to get rid of all this buffered/collected data.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 117

Currently the only possibility is the BOL core reset. This method clears all known buffers and all
messages. After the method was called it may also be advantageous to call the Advanced Business
Application Programming (ABAP) garbage collector explicitly to finally remove all the freed objects.
After the BOL reset all entity instances are useless. Further operations on them will probably cause short
dumps!

4.1.9 Interface Classes

4.1.9.1 Core

This is the most important class of the Business Object Layer (BOL) Application Programming Interface
(API). It can only exist one instance of it within one session and it cannot get lost or deleted.
The BOL Core is the central service provider for API classes and it communicates with the underlying
business object (BO) implementation.
It is possible to use the Core services directly, but it is strongly recommended to use the more comfortable
API classes.

4.1.9.2 Query Service

This is the generic query service and also the factory for specific query services. Each instance
corresponds to a distinct query object. It stores query parameters but does not aggregate the query result.

4.1.9.3 Entity

Generic representation for Business objects in the BOL and base class for all specific BOL BO
implementations. Each instance is a unique representation for a BO instance. Entities are centrally
managed and cached.

4.1.9.4 Entity Collection

Collection or list of generic entities. An entity collection provides local iterators to navigate on the list
without any influence as well as a global navigation with global a focus. It is possible to add and remove
entities to an entity collection. All entities in the collection are referenced and were not owned by the
collection.

4.1.9.5 Transaction Context

The transaction context is represented by the interface IF_BOL_TRANSACTION_CONTEXT. Depending
on the actual instance of the interface the scope of the represented transaction is a single root object
instance, all so far modified root object instances, or any explicitly built subset in between.
The BOL Core aggregates the global transaction context, which includes all modified root objects. The
global transaction context logs all modifications automatically
The single object transaction contexts can be accessed via the entities it belongs to.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 118

4.2 Architecture Details

This section contains a more detailed view on some aspects of the architectiure, with a focus on the
access to the Business Object Layer (BOL).
The figures below show the connection between the classes involved and their main attributes.

4.2.1 Entities
Entities
CL_CRM_BOL_ENTITY_MANAGER
entity_tab
CL_CRM_BOL_ENTITY
my_manager_entry
parent
0..n
1
CL_CRM_GENIL_CONTAINER_OBJECT
data_ref
1
1
#container_proxy
1
1
0..n
1


All entities are managed by the entity manager. By this mechanism the uniqueness of an entity is
ensured.
Each entity holds a reference to its manager entry. The manager entry includes values like the invalid
flag and the delta flag. Holding these values in the entity_tab of the entity manager enables table
operations on all entities.
An entity is only a wrapper for a container object belonging to a data container. This object is referred
as a container proxy and holds the attributes, properties, and relations of an entity.

4.2.2 Collections
Collections

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 119

CL_CRM_ENTITY_COL
entity_list
CL_CRM_BOL_ENTITY
0..n
1
0..n
1
CL_CRM_BOL_QUERY_SERVICE
IF_BOL_BO_COL
<<Interface>>
CL_CRM_BOL_BO_COL
entity_list
IF_BOL_BO_PROPERTY_ACCESS
<<Interface>>
0..n
1
0..n
1


A collection can either be an entity collection or a more general business object (BO) collection. In the
Interaction Center (IC), we only use the general BO collection.
A BO collection can hold entities and query services.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 120

4.2.3 Context Nodes
Context Node
CL_BSP_WD_CONTEXT_NODE
get_collection_wrapper()
set_collection_wrapper()
set_collection()
clear_collection()
CL_BSP_WD_COLLECTION_WRAPPER
set_collection()
clear_collection()
<<event>> new_focus()
1
1..n
1
1..n
IF_BOL_BO_COL
<<Interface>>
1
1
1
1
-collection_wrapper
-collection
IF_BOL_BO_COL
<<Interface>>


Each context node has a collection wrapper. These wrappers can also be shared among context
nodes.
The collection wrapper wraps the business object (BO) collection. This collection can be set and
cleared but not directly accessed.
The collection wrapper also implements the BO collection interface to provide indirect access to the
wrapped collection.
The FOCUS_CHANGED event of the collection is published by the wrapper as NEW_FOCUS event.


Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 121

4.2.4 Controller Context
Controller Context Nodes
CL_BSP_WD_CONTROLLER
CL_BSP_WD_CONTEXT
1
1
+typed_context
1
+owner
1
CL_BSP_WD_CONTEXT_NODE
1..n
1
+<name>
1..n
1


Each controller (view or custom) owns a context which holds a set of context nodes.
The context is created within the WD_CREATE_CONTEXT() method of the controller. In the
constructor of the context all context nodes are created. Within the WD_INIT_CONTEXT() method
context nodes may be explicitly initialized.
Neither context nor context nodes are expected to be shared between controllers.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 122

4.2.5 Data Binding
Data Binding
CL_BSP_WD_CONTEXT
<VIEW>
CL_BSP_WD_CONTROLLER
m_models
1
1
+typed_context
1
+owner
1
1
1
+view
1
+controller
1
CL_BSP_WD_CONTEXT_NODE
1..n
1
+<name>
1..n
1
1..n
1
+<name>
1..n
1
0..n 1 0..n 1


The view is created an owned by the controller.
Context nodes can be set as page attributes to a view (done in the SET_MODELS() method). These
page attributes are used for data binding in order to show model attributes on the view/page.
The context nodes belonging to a controller are also kept in the table m_models at the controller. This
information is used for data binding in the DO_HANDLE_DATA() method.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 123

4.2.6 Mixed Context Nodes
Mixed Context Nodes
CL_BSP_WD_COLLECTION_WRAPPER
IF_BOL_BO_COL
<<Interface>>
CL_CRM_BOL_BO_COL
CL_BSP_WD_2COLLECTION_WRAPPER
1
1
1
#collection
1
LCL_UNIFIER_MANAGER
(from CL_BSP_WD_2COLLECTION_WRAPPER)
1 1 1 1
IF_BOL_BO_PROPERTY_ACCESS
<<Interface>>
0..n
1
0..n
1
IF_BOL_BO_PROPERTY_ACCESS
<<Interface>>
1
1..n
1
1..n
LCL_NODE_UNIFIER
(from CL_BSP_WD_2COLLECTION_WRAPPER)
1
1
1
-model_node
1
IF_BOL_BO_PROPERTY_ACCESS
<<Interface>>
1
1
-value_node
1
1
IF_BOL_BO_EXT_PROPERTY_ACCESS
<<Interface>>
CL_BSP_WD_VALUE_NODE


Mixed nodes are implemented by the two collection wrapper which is a specialization of the collection
wrapper.
Via the node unifier a corresponding value node assigned to each model node. The assignment takes
place at the first access to value attributes of a mixed node.
The assignment is unique. This is ensured by the unifier manager.
The access to a mixed node is provided by the node unifier which then dispatches the request to
either the model node or the value node part.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 124

5 Appendix B: Additional Information and Further Examples
5.1 Extending Existing Views

In this section we show how to extend existing views with additional components (Buttons, Formatting,
etc.).

5.1.1 Output Formatting
Currency and quantity fields

In order to format the output depending on the decimals as well as on the language, a conversion of the
values in the Currency/Quantity fields in the DDIC is necessary. As an example we show the
GET_LISTPRICE-Method, which gets the price as well as the currency of the current entity and processes
it via the conversion method for display. Thus, the amount of the decimal places depends on the system
and not on the method.

method GET_LISTPRICE .
DATA:
current TYPE REF TO if_bol_bo_property_access,
dref TYPE REF TO data,
* CRMT_BASKET_CONVERT is a structure for currency and quantity fields
convert TYPE CRMT_BASKET_CONVERT,
convertref TYPE REF TO data,
coll TYPE REF TO if_bol_entity_col,
entity TYPE REF TO cl_crm_bol_entity,
entity2 TYPE REF TO cl_crm_bol_entity.

FIELD-SYMBOLS:
<l_data> type DATA.

value = convert-value. "#EC NOTEXT
IF iterator IS BOUND.
current = iterator->get_current( ).
ELSE.
current = collection_wrapper->get_current( ).
ENDIF.
IF current IS NOT BOUND.
RETURN.
ENDIF.

TRY.
entity ?= current.
entity2 ?= current.
* read currency
coll = entity2->get_related_entities(
iv_relation_name = 'BTItemPricingSet' ). "#EC NOTEXT
current = coll->get_current( ).
IF current IS BOUND.
call method current->GET_PROPERTY_AS_VALUE
EXPORTING
iv_attr_name = 'CURRENCY'
IMPORTING
ev_result = convert-currency.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 125

ENDIF.
* read price
coll = entity->get_related_entities(
iv_relation_name = 'BTItemPricingExt' ). "#EC NOTEXT
current = coll->get_current( ).
IF current IS BOUND.
call method current->GET_PROPERTY_AS_VALUE
EXPORTING
iv_attr_name = 'NET_PRICE'
IMPORTING
ev_result = convert-value.
ELSE.
* default value 0 if no price
convert-value = 0.
ENDIF.
CATCH cx_root.
RETURN.
ENDTRY.
value = convert-value.

GET REFERENCE OF convert-value INTO convertref.
TRY.
value = if_bsp_model_util~convert_to_string( data_ref = convertref
attribute_path = attribute_path ).
CATCH cx_bsp_conv_illegal_ref.
CATCH cx_root.
ENDTRY.

endmethod.
Date field GET-Method

In the following example we demonstrate the straightforward formatting of the date/time-field
(GET_CUSTDATE-Method in CL_CRM_IC_SOBASKET_CN04). The timezone is taken into account with
the CONVERT-Function. The variable dref contains the value that has to be converted.

DATA: lv_date(8) TYPE C,
lv_time(6) TYPE C.

FIELD-SYMBOLS: <ts> TYPE ANY.

ASSIGN dref->* TO <ts>.

* Convert to timezone to fields lv_date and lv_time
CONVERT TIME STAMP <ts> TIME ZONE SY-ZONLO
INTO DATE lv_date TIME lv_time.

* Reconvert without timezone to timestamp
CONVERT DATE lv_date TIME lv_time
INTO TIME STAMP <ts> TIME ZONE ' '.

value = if_bsp_model_util~convert_to_string( data_ref = dref
attribute_path = attribute_path ).

* This method only uses first 10 characters
DATA:
cdate(10) TYPE C.

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 126

cdate = value.
value = cdate.

The date is composed by the first ten digits. The next digits contain the time, which we do not want to be
displayed in this example.
Date field SET-Method

This example matches the example above for the SET-method. The time zone is taken into account by
the CONVERT-Function. This example is taken from the SET_DATE-Method of the class
CL_CRM_IC_SERVTECHREQ_CN04.

...
CALL METHOD if_bsp_model_util~convert_from_string
EXPORTING
data_ref = copy
value = value.

DATA: lv_date(8) TYPE C,
lv_time(6) TYPE C.

* Convert to timezone to fields lv_date and lv_time
CONVERT TIME STAMP <nval> TIME ZONE ' '
INTO DATE lv_date TIME lv_time.

* Reconvert without timezone to timestamp
CONVERT DATE lv_date TIME lv_time
INTO TIME STAMP <nval> TIME ZONE SY-ZONLO.
...

The field symbol <nval> contains the value that has to be saved.


5.1.2 Tables (TableViews, Iterators)

The tables on our views can be devided into two categories:
the standard tables, which display or change text only
tables, which present additional functionality in the different cells. Input fields with date
functionality, F4 help or dropdown list boxes, checkboxes etc. are examples for this type of
tables.
The iterator of a table takes care that rendering and display of the content of an individual cell of a table is
performed in the desired way. Within the iterator a socalled BEE is generated, which replaces the original
field (that was generated by the TableView-Element) and by this means extends the functionality of a cell
without restrictions. This can be used for color change, dropdown list boxes or other functions.

The iterator consists of four methods:

- CONSTRUCTOR (Initialistion of variables can be implemented here, but it is not necessary for our
example)
- GET_COLUMN_DEFINITIONS (is not necessary if the columns of the table are defined in the
table View-Tag)
- RENDER_ROW_START (not necessary)
- RENDER_CELL_START (Cell-Rendering, this method is passed once per cell; it is located where
the buildup of the table takes place)
Insertion of an iterator into a TableView-Object

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 127

For this view there is a special iterator class (CL_CRM_IC_SOBASKET_IT). It has the interface
IF_HTMLB_TABLEVIEW_ITERATOR and therefor three methods:
GET_COLUMN_DEFINITIONS (called once for the tableview),
RENDER_ROW_START (called for each row) and
RENDER_CELL_START (called for each cell).

Furthermore we need a new attribute (GR_ITERATOR) for the local iterator.

Step1: Fill the local iterator.

METHOD if_htmlb_tableview_iterator~get_column_definitions .
DATA: wrapper TYPE REF TO cl_bsp_wd_collection_wrapper.

* get the wrapper of the context node
wrapper = gr_context_node->get_collection_wrapper( ).

* Fill the local itarator
gr_iterator = wrapper->get_iterator( ).
ENDMETHOD.

Step 2: Position on the correct index.

METHOD if_htmlb_tableview_iterator~render_row_start .

* Position on correct index
gr_iterator->get_by_index( iv_index = p_row_index ).

ENDMETHOD.

Step 3: Get the values with the local iterators and use the replacement bee.

METHOD if_htmlb_tableview_iterator~render_cell_start .

CASE p_column_index.

* Example for a link field
WHEN 1.

DATA: col1_lnk TYPE REF TO cl_htmlb_link.
CREATE OBJECT col1_lnk.
col1_lnk->id = p_cell_id.
col1_lnk->tooltip = text-002.
col1_lnk->onclick = 'ItemDetail'.
col1_lnk->text = gr_context_node->get_item(
attribute_path = ''
iterator = gr_iterator ).
col1_lnk->reference = p_row_index.

p_replacement_bee = col1_lnk.

* Example for an amount field
WHEN 2.

DATA: col2 TYPE REF TO cl_htmlb_inputfield.
CREATE OBJECT col2.
col2->width = '100%'.
col2->id = p_cell_id.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 128

col2->value = gr_context_node->get_product(
attribute_path = ''
iterator = gr_iterator ).
col2->reference = p_row_index.

p_replacement_bee = col2.

ENDCASE.

ENDMETHOD.

Step 4: Furthermore we have to introduce the Iterator to the tableView-Tag:

<htmlb:tableView design = "STANDARD"
id = "Basket"
onNavigate = "navigate"
table = "//AdminI/Table"
visibleFirstRow = "1"
visibleRowCount = "6"
selectionMode = "MULTILINEEDIT"
onRowSelection = "onRowSelection"
fillUpEmptyRows = "TRUE"
width = "100%"
iterator = "<%= controller->iterator %>">
Selection/Deselection of rows in TableView-Objects

Rows can be selected/deselected in TableView-Objects via CheckBoxes in the first column of the table.
After the deletion of one or more rows it is recommended to cancel the selection of the lines. Otherwise,
the selection will point to the wrong rows. In order to accomplish the deletion, we use the
CHECK_TABLEVIEW_ROW-Method of the CL_HTMLB_MANAGER. Therefore we need the ID of the
TableView-Element, which we obtain by passing the P_TABLEVIEW_ID from the Iterator.

Example: CL_CRM_IC_BASKET_IT

1. We add the new attribute GV_TABLEVIEW_ID of type String (this attribute identifies the HTML-
element of the page).

2. We add the following line to the method GET_COLUMN_DEFINITIONS:

gv_tableview_id = p_tableview_id.

3. Call of CHECK_TABLEVIEW_ROW in the ADD/DELETE-Method (Insertion and deletion of a line):

CALL METHOD CL_HTMLB_MANAGER=>CHECK_TABLEVIEW_ROW
EXPORTING
MODE = 'SINGLESELECT'
ROW = row_number_you_have_to_set_like_in_example_below
REQUEST = request
ID = iterator->gv_tableview_id
CHECK = 'X'
KEY = '' .
Automatically adjusting TableView-Display

We also want the the TableView-Element to react as follows:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 129

1. when adding a new element the new elements should be shown as the last visible line and not
being invisible by adding it to one of the following pages
2. after adding the element, we dont want to jump to the first page of the view after the selection of a
line

For this reason we have to make the attribute visibleFirstRow variable:

<htmlb:tableView design = "STANDARD"
id = "Basket"
onNavigate = "navigate"
table = "//AdminI/Table"
visibleFirstRow = "<%= lv_visibleFirstRow %>"
visibleRowCount = "6"
selectionMode = "MULTILINEEDIT"
onRowSelection = "onRowSelection"
fillUpEmptyRows = "TRUE"
width = "100%"
iterator = "<%= controller->iterator %>">

Furthermore we need a new attribute gv_added_line of Type INT4 in the Iterator set it in the method
EH_ONADDNEWITEM of the class CL_CRM_IC_SOBASKET_IMPL (which is the place where a new
entity is created for the context node):

* get new size of collection and set gv_added_line to size
iterator->gv_added_line = lv_wrapper->size( ).

Finally we put the following coding at the beginning of our BSP-page (see also BSP-page SoBasket.htm in
the BSP application CRM_IC) in order to set the variable lv_visibleFirstRow. The number 5 represents the
number of displayed lines in the attribute visibleRowCount minus 1:

...
DATA: lv_visibleFirstRow TYPE INT4.

IF controller->iterator->gv_added_line > 5.
lv_visibleFirstRow = controller->iterator->gv_added_line - 5.
controller->iterator->gv_added_line = 0.
ELSE.
lv_visibleFirstRow = 0.
ENDIF.
...

5.1.3 Checkboxes and Radio Buttons
Checkboxes

A simple example for the use of checkboxes is the following:

<% DATA checked1 TYPE STRING,
checked2 TYPE STRING,
checked3 TYPE STRING.
* In this example we set the values forchecked manually
checked1 = "TRUE".
checked2 = "FALSE".
checked3 = "TRUE". %>
...
<htmlb:checkbox
id="CB1"
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 130

text="Value 1"
checked="<%= checked1 %>"
key="X"
keyNotChecked=""/>
<htmlb:checkbox
id="CB2"
text="Value 2"
checked="<%= checked2 %>"
key="X"
keyNotChecked=""/>
<htmlb:checkbox
id="CB3"
text="Value 3"
checked="<%= checked3 %>"
key="X"
keyNotChecked=""/>

In case the page is a page with flow logic or a page fragment, the field can be further processed in the
method OnInputProcessing in the loop.

In case the checkbox-fields are bound against a context-node, the values (X or ) are transferred to the
fields of the context-node via the corresponding SET-methods. If necessary, additional convertions have
to be implemented.
Checkboxes in TableViews

Unfortunately checkboxes cant be added without problems into the table views of our examples, since we
use context nodes (i.e. instanciated ABAP classes) rather than simple ABAP tables. In the case of tables
we get the reference to the content to be rendered in the RENDER_CELL_START-Method in the variable
P_ROW_DATA_REF. In the case of context nodes the reference is also present, however without
content. To return this content we have to read the contents of the context node before the rendering. We
dont need all columns, but only the content of the checkbox-column. We add the necessary lines of
coding to the GET_COLUMN_DEFINITIONS-Method (which we get from the class
CL_CRM_IC_SOBASKET_IT):

* get entries (necessary for "checked")
DATA: wrapper TYPE REF TO cl_bsp_wd_collection_wrapper,
current TYPE REF TO if_bol_bo_property_access,
old_cur TYPE REF TO if_bol_bo_property_access,
BEGIN OF line,
checked TYPE STRING,
END OF line.

wrapper = gr_context_node->get_collection_wrapper( ).

* remember focus
old_cur = wrapper->get_current( ).

current = wrapper->get_first( ).
CLEAR gt_checked.
WHILE current IS NOT INITIAL.
line-checked = gr_context_node->get_quote( '' ).
APPEND line TO gt_checked.
current = wrapper->get_next( ).
ENDWHILE.
IF current IS NOT INITIAL.
line-checked = gr_context_node->get_quote( '' ).
APPEND line TO gt_checked.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 131

ENDIF.

* set to old focus
wrapper->find( iv_bo = old_cur ).

GT_CHECKED is a private attribute of the class of the type TT_CHECKED
(defined as local type):

TYPES:
BEGIN OF st_checked,
checked TYPE string,
END OF st_checked,

tt_checked TYPE TABLE OF st_checked.

During the rendering in the method RENDER_CELL_START, the table content is read out through the
following coding:
...
* Column 11
WHEN 11.
DATA: col11 TYPE REF TO CL_HTMLB_CHECKBOX,
onClientClickStr TYPE STRING,
BEGIN OF line,
checked TYPE STRING,
END OF line.

CREATE OBJECT col11.
col11->id = p_cell_id.
col11->key = 'TRUE'.
col11->keyNotChecked = 'FALSE'.
READ TABLE gt_checked INDEX p_row_index INTO line.
col11->checked = line-checked.
p_replacement_bee = col11.
Radio buttons

Radio buttons are not yet used in the existing scenarios. The following short example demonstrates the
functionality. A radio button is always embedded in a radio button group. The selection, which is declared
as an attribute of the radio button group, represents the ID of the selected radio button.

<% DATA selection TYPE STRING.
* As an example we select radioButton RB2
selection = "RB2". %>
...
<htmlb:radioButtonGroup
id="RBGroup1"
selection="<%= selection %>">
<htmlb:radioButton
id="RB1"
text="Value 1"/>
<htmlb:radioButton
id="RB2"
text="Value 2"/>
<htmlb:radioButton
id="RB3"
text="Value 3"/>
</htmlb:radioButtonGroup>

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 132

5.1.4 Button Linking to Websites

Example:

A click on the button should lead to the display of an archived document on a different webpage.

The button is enriched with additional JavaScript code within the onClientClick-event:

<htmlb:button id = "Show"
text = "Show Invoice"
tooltip = "Show Invoice"
onClientClick =
"window.open('<%= Invoices->GET_GENEBPP_INVOICE( '' ) %>'
,'Invoice','resizable=yes,height=850,width=700,dependent=yes,status=1');"
design = "small"
width = "100" />

5.1.5 Links
simple links

Links in views always consist of two parts:

- the link

<htmlb:link id="SoHPFuncShip"
onClick="shipTo"
text="<%=page->otr_trim( 'crm_ic_appl/ShipTo' )%>"/>

(The method page->otr_trim(...) parses the unnecessary blanks in front of and behind the text (see also
OTR-texts)

- and the corresponding method, which is accessed through the DO_HANDLE_EVENT-method of
the implementation class

method EH_ONSHIPTO .
CALL METHOD OP_SOHPFUNCBILLEVSHIPTO.
endmethod.

There the outbound-plug which navigates to a different view, is accessed via the link:

method OP_SOHPFUNCBILLEVSHIPTO .
view_manager->navigate(
SOURCE_REP_VIEW = rep_view
OUTBOUND_PLUG = 'SoHPFuncBillEvShipTo' ).
endmethod.
Links in tables

Several possibilities exist to use links within tables. In case we dont need an iterator, we can create the
link in the tableView-tag as follows:

<htmlb:tableViewColumn columnName = "link"
title = "URL"
type = "user">
<htmlb:link id = "link"
onClick = "click"
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 133

onClientClick = "clientClick"
target = "$link$"
text = "$link$"
tooltip = "here is a tooltip" />
</htmlb:tableViewColumn>

In case we want to render the link with the iterator RENDER_CELL_START-method, we can use two
different classes:

CL_HTMLB_LINK oder CL_HTMLB_TABLE_LINK

The CL_HTMLB_LINK-class has the disadvantage, that the table cells are displayed without lower and no
left border in case the cells do not contain any values.

It is therefore better to use the CL_HTMLB_TABLE_LINK-class for tables. In the following you find an
example (RENDER_CELL_START-Method in CL_CRM_IC_SOBASKET_IT):
...
WHEN 3.
DATA: col3_lnk TYPE REF TO CL_HTMLB_TABLE_LINK.
CREATE OBJECT col3_lnk.
col3_lnk->id = p_cell_id.
col3_lnk->tooltip = text-001.
col3_lnk->onClick = 'ProductDetail'.
col3_lnk->text = gr_context_node->get_productdesc(
attribute_path = ''
iterator = gr_iterator ).
col3_lnk->reference = p_row_index.
p_replacement_bee = col3_lnk.
...


5.1.6 Dynamic View Replacement
It is possible to replace the view at runtime which is initially displayed in a view area when the view set
gets instanciated. To do this follow these steps:

- You have to redefine the method DO_REPLACE_INITIAL_VIEW of the view controller of the view
set which owns the view area of the content which you want to replace.
- This method gets called for each view area of the view set with the view area name as importing
parameter and returns a string containing the name of the view that you want to display there.
- Return an empty string when you don't want to replace the proposed view area content. This is
also the default implementation.
- The view set context is already initialized at the point in time when your method is being called.
I.e., if you want to display the view (which is originally based on the context) it is important to bind
or initialize the view set context accordingly. This way you can access the required data (As you
usually don't need any data in a view set, it's important to notice that a view set is also a view and
can have a context definition!)
- Be aware that the view name that you return is part of the XML and that also the view is defined
within the view area of the same view set where you want to place it.

5.1.7 Reusing Views

Reuse of views across view sets is not part of the Web Dynpro concept and also not available in our
framework. However, a workaround (not Web Dynpro compliant) without reimplementation of the whole
view is possible. You have to use an "alias" view/controller for it:
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 134


- In the XML define a view with a different name (=alias). You don't have to redefine in the XML the
controller, context and layouts for that view.
- Use this "alias" in the view set section as well as in the navigational links section of the XML.
- In the system, only create the BSP controller (manually) and put in as implementation class the
ABAP class that is used for the BSP controller of the original view. This will make the system
reuse the complete view controller/ view layout implementation of the original view.

5.2 Error Handling / Messages Display in the ErrorViewSet

To display messages in the ErrorViewSet the singleton class CL_BSP_WD_MESSAGE_SERVICE is
used. An instance is created with the method GET_INSTANCE( ). With the method ADD_MESSAGE( )
new messages can be displayed.

Example:

DATA: lv_msgsrv TYPE REF TO CL_BSP_WD_MESSAGE_SERVICE.

lv_msgsrv = CL_BSP_WD_MESSAGE_SERVICE => GET_INSTANCE( ).
lv_msgsrv-> ADD_MESSAGE ( iv_msg_type = 'I'
iv_msg_id = 'CRM_IC_APPL_UI_BPID'
iv_msg_number = '000' ).


5.3 User Interface Design Extras
5.3.1 Integrating Stylesheets

In order to use the stylesheets of the 2000-designs, the following lines have to be included on the
root.htm. It is the uppermost HTML-page of our layout:

<%
try.
call method _m_runtime->('IF_BSP_RUNTIME~SET_EXTERNAL_THEME_ROOT')
exporting path = '/sap/bc/bsp/sap/crm_ic/styles'. "#EC NOTEXT
catch cx_root.
endtry.
%>
5.3.2 Special Cases in the Tray Layout (New Look & Feel)

The layout for trays described here replaces the previous look & feel. The icons at the right side of the
layout have been removed, because they are not needed in the IC-WebClient.

<%@extension name="CRM_BSP_IC" prefix="crmic" %>
<crmic:tray
id="SoBasket"
title="<%=OTR(crm_ic_appl/Basket)%> <%=AdminH->GET_OBJECT_ID( 'Object_Id' )%>"
height="366"
width="840">
<crmic:trayBody>

</crmic:trayBody>
</crmic:tray>
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 135


In this example a tile (View) of a height of 366 pixels and a width of 840 pixels has been created.

5.3.3 Tableviews and Overflow Container

If we use a table of a fixed size which contains a wide column (e.g. description) we should use an
overflow-container.

Example: SolSResult.htm (BSP Application CRM_IC)

<%@extension name="CRM_BSP_IC" prefix="crmic" %>

<crmic:overflowContainer mode="SCROLL" height="280" width="405">
<htmlb:tableView id="KnowledgeDoc" selectionMode="MULTISELECT" design="ALTERNATING"
fillUpEmptyRows="true"
table="<%=<FS_RESULT> %>" navigationMode ="BYPAGE" onRowSelection="select"
visibleFirstRow="1" visibleRowCount="10" width="100%">
<htmlb:tableViewColumns>
<htmlb:tableViewColumn columnName="Select" title = " " type = "user" width="10%">
<htmlb:checkbox id="$kbid$" onClientClick="checked('$kbid$')" />
</htmlb:tableViewColumn>
<htmlb:tableViewColumn columnName="Description" wrapping="TRUE"
title="<%=OTR(crm_ic_appl/sols_description)%>" type = "user" width="70%">
<htmlb:link id = "$kbid$"
text = "$description$"
reference = "$kbname$=$kbid$=$description$"
onClick = "detail"
tooltip = "<%=OTR(crm_ic_appl/sols_detail_tooltip)%>" />
</htmlb:tableViewColumn>
<htmlb:tableViewColumn columnName="Kbname" title="<%=OTR(crm_ic_appl/sols_type)%>"
width="10%" onCellClick="select"/>
<htmlb:tableViewColumn columnName="Rank" title="<%=OTR(crm_ic_appl/sols_rank)%>"
width="10%" onCellClick="select"/>
</htmlb:tableViewColumns>
</htmlb:tableView>
</crmic:overflowContainer>

Furthermore the attribute wrapping="TRUE" can be set, to wrap a long line. The attributes height="280"
and width="405" in the overflowContainer-tag, specify the maximum size of the surrounding table.

5.3.4 F4 Help

5.3.4.1 F4 Help Overview

When calling the F4 help by the JavaScript function 'ShowF4KeyAndValueHelp', a new window opens and
the controller 'f4_help.do' is called. The function needs the following parameters:

KeyInputField - object name of the key data field for the search criteria
InputField - object name of the display field for the long text
HelpId - search help-ID

The input fields are processed in the ViewController of the page and the value help table is filled.
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 136

The controller 'f4_help.do' uses the controller class 'CL_CRM_BSP_F4_HELP' (This is the controller
'f4_help2.do' for the extended help, which is called via the JavaScript function 'ShowF4KeyAndValueHelp';
It uses the controller class 'CL_CRM_IC_F4_HELP').
For each OnClick-event a method is defined in the controller class. With extended help for example, the
method EH_ONCLEAR is used for the deletion of the input values, EH_ONCLOSE for the closure of the
help-window, EH_ONSHOW for the creation of the hit-list, and EH_ONSELECT is used for the selection
of a value.

5.3.4.2 Implementing F4 Help

The F4- or search-help can be implemented by using the following coding:

<htmlb:gridLayoutCell width="200" rowIndex="6" colSpan="1" columnIndex = "2">
<htmlb:gridLayout cellPadding="2" columnSize="1" rowSize="1">
<htmlb:gridLayoutCell
columnIndex="1"
rowIndex="1"
verticalAlignment="BOTTOM">
<htmlb:inputField
id="WithLang"
maxlength="2"
size="2"
value="//Text/TdSpras"
showHelp="TRUE"
onValueHelp="ShowF4Help(<%= _m_page_context->m_page_id %>_WithLang,'T002-SPRAS')" />
</htmlb:gridLayoutCell>
</htmlb:gridLayout>
</htmlb:gridLayoutCell>

In case of very large table columns, the help-icon is shifted to the right. This problem is avoided by using
the additional gridLayout. With the attribute verticalAlignment you can furthermore avoid the error that
displays the cell two pixels higher than the other fields of the row.
The function ShowF4Help() is found in the file showF4Help.js

5.3.4.3 Implementing Date Field F4 Help

<htmlb:gridLayoutCell width="200" rowIndex="6" colSpan="1" columnIndex = "2">
<htmlb:gridLayout cellPadding="2" columnSize="1" rowSize="1">
<htmlb:gridLayoutCell columnIndex="1" rowIndex="1">
<htmlb:inputField id = "MalfunctionStartDate"
alignment = "left"
width = "200"
maxlength = "30"
size = "30"
value = "//BTAdminH/MalfunctionStart"
showHelp="TRUE"
type="DATE" />
</htmlb:gridLayoutCell>
</htmlb:gridLayout>
</htmlb:gridLayoutCell>

The additional gridLayout fixes the problem of the right-shift of the help-icon for very wide columns (see
above).

5.3.4.4 Implementing F4 Help with a Second Field for Description
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 137


<htmlb:gridLayoutCell columnIndex="2" rowIndex="7">
<htmlb:gridLayout cellPadding="2" columnSize="2" rowSize="1">
<htmlb:gridLayoutCell columnIndex="1" rowIndex="1">
<htmlb:inputField id = "Country"
showHelp = "TRUE"
size = "3"
onValueHelp = "ShowF4KeyHelp(<%= _m_page_context->m_page_id %>_Country, <%=
_m_page_context->m_page_id %>_CountryName,'ADRC-COUNTRY')"
value = "//SearchCustomer/Country" />
</htmlb:gridLayoutCell>
<htmlb:gridLayoutCell columnIndex="2" rowIndex="1">
<htmlb:inputField id = "CountryName"
size = "25"
disabled = "TRUE" />
</htmlb:gridLayoutCell>
</htmlb:gridLayout>
</htmlb:gridLayoutCell>

5.3.5 Tips and Tricks
5.3.5.1 Aligning Buttons Correctly

<htmlb:gridLayoutCell columnIndex = "2"
horizontalAlignment = "RIGHT"
rowIndex = "12" >
<htmlb:gridLayout cellPadding="2" columnSize="3" rowSize="1">
<htmlb:gridLayoutCell columnIndex="1" rowIndex="1"><htmlb:button id = "New"
onClick = "new"
text = "<%= otr(crm_ic_appl/bupacreate) %>" /><htmlb:gridLayoutCell columnIndex="2"
rowIndex="1"><htmlb:button id = "Reset"
onClick = "reset"
text = "<%= otr(crm_ic_appl/bupareset) %>" /><htmlb:gridLayoutCell columnIndex="3"
rowIndex="1"><htmlb:button id = "Search"
onClick = "search"
text = "<%= otr(crm_ic_appl/bupasearch) %>"
/></htmlb:gridLayout></htmlb:gridLayoutCell>

NO tags are allowed between the HTML-Tags htmlb:gridLayoutCell and htmlb:button. Otherwise the
buttons will be shifted upward or downward.

5.3.5.2 Pretty Printer Warning

After the alignment of a BSP- or HTML-page, you should avoid to prettify the layout with the Pretty
Printer. Especially after the alignment of buttons and tables, the pretty printer is very likely to mess up the
whole layout.
The HTML-page might look chaotic, but just with HTML this is not always avoidable.

This means: ATTENTION when using the Pretty Printer!

5.3.5.3 Using Search Help Icons Instead of Buttons

In case the search help is branching to other views, it is necessary to use a search help icon rather than a
button. The onClick-event of the original buttons can be included into the coding of the page in the
following way:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 138

<htmlb:gridLayoutCell
colSpan="1"
columnIndex="2"
rowIndex="1"
width="70%"
horizontalAlignment="LEFT"
verticalAlignment="MIDDLE"><htmlb:image
id = "Search"
onClick = "search"
src = "styles/HTMLB/inputfield/helpF4.gif"
tooltip = "<%= otr(crm_ic_appl/bupasearch) %>" /></htmlb:gridLayoutCell>

5.3.6 View Sizes

The views have a standardized size. The 2x3-Layout should be kept by any means. Of course it is
possible to combine the different parts of the screen in various ways.

5.3.6.1 Layout

The layout of the page is fixed and not dynamic. The core (where the dynamic content is displayed),
contains the following parameters:

183+183+185 = 555 high (because the border of a tile is one pixel wide)
and 420+420 = 840 wide (no border there!):


5.3.6.2 ViewSet Layouts Dimensions and Pixel Problems

In case we need exact values for the size of a tile in the ViewSet, the cellPadding and cellSpacing has
to be set in the ViewSet.

Example: SoCurrent.htm

<htmlb:gridLayout cellPadding="0" cellSpacing="0" columnSize="2" rowSize="2">
<htmlb:gridLayoutCell colSpan="2" columnIndex="1" rowIndex="1">
...
</htmlb:gridLayoutCell>
</htmlb:gridLayout>
Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 139


The size of the parameter width is NOT necessary her, because it is defined within the view (as in
SoBasket.htm).
The NavBar has exactly the size of 555 pixels. NB: the content has a maximum height of 551 pixels,
which means that we should set the height of the tiles of our ViewSet to e.g., 183 / 183 / 185 pixel (as in
IRecViewSet.htm, or IRecFollowUp.htm, IRecHistory.htm and IRecActivitiesClipboard.htm) or 279 / 272
pixel (as in SoCurrent.htm, or SoBasket.htm, SoItemSoldTo.htm and SoHeader.htm) or 551 pixel (as in
TODOMyWorklist.htm).


5.4 Page Setup What is Where?

At the start of the application the profile determination page is called first (profile_determ.htm). It contains
just as the contextAreaPage.htm the Branding of the page (Logo). After selecting the profile, the
default.htm is loaded, which contains the following files:

default.htm
- Main.htm
o ICDomainRelaxing.htm (defines the domain of the actual document example: the
hostname pwdf0666.wdf.sap-ag.de is changed to the domain sap-ag.de)
o contextAreaPage.htm
(contains images/branding/SPICE_brand_image.gif and images/branding/SAP_logo.gif)
crm_ic_contextarea.js (contextArea-functions)
crm_ic_scratchpad_contextarea.js (scratchpad-functions)
WorkspaceBar.js (functions for the WorkspaceBar)
crm_ic_contextareanew.css or crm_ic_contextarea.css (Style sheet for the
contextArea)
WorkspaceBar.css (Stylesheet for the WorkspaceBar)
WorkspaceBarPage.htm (Button bar for the general functions)
o default_delta.do or default.do
ICAPPMainViewSet.htm
ErrorViewSet.htm (errorArea)
(Error display, it is possible to switch from one line to several lines)
ErrorViewSingleLine.htm
o ErrorViewList.htm
Help.htm (helpArea) (searchhelp)
HistoryView.htm (historyArea)
NavBarView.htm (navigationArea)
(workArea) (this is the changable content)
contextAreaView.htm(contextArea) (invisible Context-fields)
o MessageBar.htm (contains Java-Applet for the messages display)
o appletPage.htm (contains Java-Applet for the message receipt)

The files are nested depending on the level of indentation:

Consultants Cookbook for Interaction Center (IC) WebClient SAP CRM 4.0 Add-On for Service Industries Page 140



The figure above shows the build up of a page on the screen. The appletPage.htm and
contextAreaView.htm are not displayed.
FAQs

5.5 Transaction Codes
BSP_WD_WORKBENCH
SOTR_EDIT Edits OTR-Texts
SE63 Translate OTR Texts
GENIL_BOL_BROWSER Browser for the Business Object Layer
GENIL_MODEL_BROWSER Model Browser
CRMC_IC_TLBPROF Maintains MCM-Toolbars
CRMC_XMLEDITOR Editor for XML-files