Busi ness Obj ec t Layer (BOL)

Appl i c at i on Pr ogr ammi ng Gui de

SAP

CRM 2007
Target Audience
System administrators
Technology consultants
Document version: 1.0 J uly 2008
Copyright 2007 SAP AG. All rights reserved.
No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP AG.
The information contained herein may be changed without prior
notice.
Some software products marketed by SAP AG and its distributors
contain proprietary software components of other software vendors.
Microsoft, Windows, Outlook, and PowerPoint are registered
trademarks of Microsoft Corporation.
IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex,
MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries,
xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity,
Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and
PowerPC are trademarks or registered trademarks of IBM Corporation.
Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either
trademarks or registered trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
Oracle is a registered trademark of Oracle Corporation.
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the
Open Group.
Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame,
VideoFrame, and MultiWin are trademarks or registered trademarks of
Citrix Systems, Inc.
HTML, XML, XHTML and W3C are trademarks or registered
trademarks of W3C, World Wide Web Consortium, Massachusetts
Institute of Technology.
J ava is a registered trademark of Sun Microsystems, Inc.
J avaScript is a registered trademark of Sun Microsystems, Inc., used
under license for technology invented and implemented by Netscape.
MaxDB is a trademark of MySQL AB, Sweden.
SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and
other SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP AG
in Germany and in several other countries all over the world. All other
product and service names mentioned are the trademarks of their
respective companies. Data contained in this document serves
informational purposes only. National product specifications may
vary.
These materials are subject to change without notice. These materials
are provided by SAP AG and its affiliated companies ("SAP Group")
for informational purposes only, without representation or warranty of
any kind, and SAP Group shall not be liable for errors or omissions
with respect to the materials. The only warranties for SAP Group
products and services are those that are set forth in the express
warranty statements accompanying such products and services, if any.
Nothing herein should be construed as constituting an additional
warranty.
SAP Library document classification: PUBLIC
Disclaimer
Some components of this product are based on Java. Any
code change in these components may cause unpredictable
and severe malfunctions and is therefore expressively
prohibited, as is any decompilation of these components.
Any J ava Source Code delivered with this product is
only to be used by SAPs Support Services and may not be
modified or altered in any way.
Documentation in the SAP Service Marketplace
You can find this documentation at the following address:
ht t p: //ser vi c e.sap.c om/
SAP AG
Dietmar-Hopp-Allee 16
69190 Walldorf
Germany
T +49/18 05/34 34 24
F +49/18 05/34 34 20
www.sap.c om
Ter ms f or I nc l uded Open
Sourc e Sof t ware
This SAP software contains also the third party open
source software products listed below. Please note that for
these third party products the following special terms and
conditions shall apply.
1. This software was developed using ANTLR.
2. gSOAP
Part of the software embedded in this product is gSOAP
software. Portions created by gSOAP are Copyright
(C) 2001-2004 Robert A. van Engelen, Genivia inc. All
Rights Reserved.
THE SOFTWARE IN THIS PRODUCT WAS IN PART
PROVIDED BY GENIVIA INC AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE AUTHOR BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
3. SAP License Agreement for STLport
SAP License Agreement for STLPort between
SAP Aktiengesellschaft
Systems, Applications, Products in Data Processing
Neurottstrasse 16
69190 Walldorf, Germany
(hereinafter: SAP)
and
you
(hereinafter: Customer)
a) Subject Matter of the Agreement
A) SAP grants Customer a non-exclusive,
non-transferrable, royalty-free license to use
the STLport.org C++library (STLport) and its
documentation without fee.
B) By downloading, using, or copying STLport or
any portion thereof Customer agrees to abide
by the intellectual property laws, and to all of
the terms and conditions of this Agreement.
C) The Customer may distribute binaries compiled
with STLport (whether original or modified)
without any royalties or restrictions.
D) Customer shall maintain the following
copyright and permissions notices on STLport
sources and its documentation unchanged:
Copyright 2001 SAP AG
E) The Customer may distribute original or
modified STLport sources, provided that:
o The conditions indicated in the above
permissions notice are met;
o The following copyright notices are retained
when present, and conditions provided in
accompanying permission notices are met:
Copyright 1994 Hewlett-Packard
Company
Copyright 1996,97 Silicon Graphics
Computer Systems Inc.
Copyright 1997 Moscow Center for
SPARC Technology.
Copyright 1999,2000 Boris Fomitchev
Copyright 2001 SAP AG
Permission to use, copy, modify, distribute and
sell this software and its documentation for
any purposes is hereby granted without fee,
provided that the above copyright notice appear
in all copies and that both that copyright notice
and this permission notice appear in supporting
documentation. Hewlett-Packard Company
makes no representations about the suitability
of this software for any purpose. It is provided
as is without express or implied warranty.
Permission to use, copy, modify, distribute and
sell this software and its documentation for any
purpose is hereby granted without fee, provided
that the above copyright notice appear in all
copies and that both that copyright notice and
this permission notice appear in supporting
documentation. Silicon Graphics makes no
representations about the suitability of this
software for any purpose. It is provided as is
without express or implied warranty.
Permission to use, copy, modify, distribute and
sell this software and its documentation for
any purposes is hereby granted without fee,
provided that the above copyright notice appear
in all copies and that both that copyright notice
and this permission notice appear in supporting
documentation. Moscow Center for SPARC
makes no representations about the suitability
of this software for any purpose. It is provided
as is without express or implied warranty.
Boris Fomitchev makes no representations
about the suitability of this software for any
purpose. This material is provided "as is", with
absolutely no warranty expressed or implied.
Any use is at your own risk. Permission to
use or copy this software for any purpose is
hereby granted without fee, provided the above
notices are retained on all copies. Permission
to modify the code and to distribute modified
code is granted, provided the above notices
are retained, and a notice that the code was
modified is included with the above copyright
notice.
Permission to use, copy, modify, distribute
and sell this software and its documentation
for any purposes is hereby granted without
fee, provided that the above copyright notice
appear in all copies and that both that copyright
notice and this permission notice appear in
supporting documentation. SAP makes no
representations about the suitability of this
software for any purpose. It is provided with a
limited warranty and liability as set forth in the
License Agreement distributed with this copy.
SAP offers this liability and warranty obligations
only towards its customers and only referring
to its modifications.
b) Support and Maintenance
SAP does not provide software maintenance for the
STLport. Software maintenance of the STLport
therefore shall be not included.
All other services shall be charged according to the
rates for services quoted in the SAP List of Prices
and Conditions and shall be subject to a separate
contract.
c) Exclusion of warranty
As the STLport is transferred to the Customer on a
loan basis and free of charge, SAP cannot guarantee
that the STLport is error-free, without material
defects or suitable for a specific application under
third-party rights. Technical data, sales brochures,
advertising text and quality descriptions produced
by SAP do not indicate any assurance of particular
attributes.
d) Limited Liability
A) Irrespective of the legal reasons, SAP shall only
be liable for damage, including unauthorized
operation, if this (i) can be compensated under
the Product Liability Act or (ii) if caused due to
gross negligence or intent by SAP or (iii) if based
on the failure of a guaranteed attribute.
B) If SAP is liable for gross negligence or intent
caused by employees who are neither agents or
managerial employees of SAP, the total liability
for such damage and a maximum limit on the
scope of any such damage shall depend on
the extent to which its occurrence ought to
have anticipated by SAP when concluding the
contract, due to the circumstances known to
it at that point in time representing a typical
transfer of the software.
C) In the case of Art. 4.2 above, SAP shall not
be liable for indirect damage, consequential
damage caused by a defect or lost profit.
D) SAP and the Customer agree that the typical
foreseeable extent of damage shall under no
circumstances exceed EUR 5,000.
E) The Customer shall take adequate measures
for the protection of data and programs, in
particular by making backup copies at the
minimum intervals recommended by SAP. SAP
shall not be liable for the loss of data and its
recovery, notwithstanding the other limitations
of the present Art. 4 if this loss could have been
avoided by observing this obligation.
F) The exclusion or the limitation of claims in
accordance with the present Art. 4 includes
claims against employees or agents of SAP.
4. Adobe Document Services
Adobe, the Adobe logo, Acrobat, PostScript, and Reader
are either registered trademarks or trademarks of
Adobe Systems Incorporated in the United States and
/ or other countries. For information on Third Party
software delivered with Adobe document services and
Adobe LiveCycle Designer, see SAP Note 854621.
Typographi c Convent i ons
Type Style Descripti on
Example Text Words or characters quoted
from the screen. These include
field names, screen titles,
pushbuttons labels, menu
names, menu paths, and menu
options.
Cross-references to other
documentation
Example text Emphasized words or phrases
in body text, graphic titles, and
table titles
EXAMPLE TEXT Technical names of system
objects. These include report
names, program names,
transaction codes, table
names, and key concepts of a
programming language when
they are surrounded by body
text, for example, SELECT and
INCLUDE.
Exampl e t ext Output on the screen. This
includes file and directory
names and their paths,
messages, names of variables
and parameters, source text,
and names of installation,
upgrade and database tools.
Example text
Exact user entry. These are
words or characters that you
enter in the system exactly as
they appear in the
documentation.
<Example
text>
Variable user entry. Angle
brackets indicate that you
replace these words and
characters with appropriate
entries to make entries in the
system.
EXAMPLE TEXT Keys on the keyboard, for
example, F2 or ENTER.
I c ons
Icon Meaning
Caution
Example
Note
Recommendation
Syntax
Additional icons are used in SAP
Library documentation to help you
identify different types of information at
a glance. For more information, see
Help on Help General Information
Classes and Information Classes for
Business Information Warehouse on
the first page of any version of SAP
Library.
<July 2008> 7
Contents
1 Business Obj ect Layer .......................................................................8
1.1 Abstract ................................................................................................... 8
1.1.2 Introduction.............................................................................................................. 8
1.1.3 Overview.................................................................................................................. 8
1.1.4 Basic Features of the BOL API ............................................................................... 10
1.1.4.1 Setting up a BOL Instance................................................................................... 10
1.1.5 Advanced Features of the BOL API ........................................................................ 18
1.1.6 Interface Classes.................................................................................................... 29
1.1.7 Checkpoint Groups................................................................................................. 29
1.2 Architecture Details and Context ........................................................ 30
1.2.1 BOL Entities........................................................................................................... 30
1.2.2 Collections ............................................................................................................. 31
1.2.3 Context Nodes ....................................................................................................... 32
1.2.4 Controller Context.................................................................................................. 34
1.2.5 Data Binding.......................................................................................................... 35
1.2.6 Mixed and Value Nodes of the Controller Context................................................... 35
1 Business Obj ect Layer
8 <July 2008>
1 Business Object Layer
1.1 Abstract
This document describes the runtime programming interface of the business object layer
(BOL). After you have read this document, you can create, access, and modify business data
provided by the BOL, such as business partners, products, or Human Resources data. The
BOL may be used within all ABAP based applications (for example, simple reports, dynpro,
and business server page (BSP) applications).
1.1.2 Introduction
Using the BOL and its uniform application programming interface (API) to access business
data offers considerable advantages compared to the various APIs typically available for
business objects:
The object-oriented BOL API is simple, uniform, and easy to use.
The built-in buffer accelerates your applications.
You can isolate your programs from any interface changes in the underlying business
object-specific APIs.
Development of SAP Customer Relationship Management (SAP CRM) applications is
easy since the BOL has been designed to work hand-in-hand with the UI parts of the
CRM WebClient UI framework.
It is possible to enhance the BOL to cover business data not yet supported. After the
corresponding business objects and query services have been modeled and implemented,
you can use them at runtime.
1.1.3 Overview
The BOL API consists of various interfaces and classes that you can use to access business
data:
CL_CRM_BOL_QUERY_SERVICE
You use this class to select business objects.
CL_CRM_BOL_ENTITY
You use this class for implementing business objects.
IF_BOL_TRANSACTION_CONTEXT
You use this interface to control transaction behavior.
IF_BOL_BO_COL
You use this interface to provide collections to hold business objects.
The lifetime of these objects lasts the entire session. The BOL API, however, provides you
with the ability to free used business objects and their memory.
1 Business Obj ect Layer
<July 2008> 9
Important objects in the BOL Programmi ng ABAP and their corresponding interfaces
and classes:
Objects
Object Model
BOL Core
Enti ty Factory
Query Servi ce
Transaction
Context
Enti ty
Collection
for Busi ness
Objects
1
1
1
1..*
1
1..*
1..*
*
*
*
Interfaces and Classes
<<Interface>>
IF_GENIL_OBJ ECT_MODEL
<<Interface>>
IF_BOL_TRANSACTION_CONTEXT
CL_CRM_BOL_CORE
get_instance()
CL_CRM_BOL_ENTITY
CL_CRM_BOL_ENTITY_FACTORY
CL_CRM_BOL_QUERY_SERVICE
get_instance()
<<Interface>>
IF_BOL_BO_COL
1
1
1
1
0..n
0..n
0..n
1 Business Obj ect Layer
10 <July 2008>
1.1.4 Basic Features of the BOL API
When you use the BOL to work with business objects in an ABAP application, you typically
use code sequences similar to those indicated in the following sections.
1.1.4.1 Setting up a BOL Instance
You create an instance of the BOL by calling a static method of its core class:
Syntax
* St ar t BOL Cor e modul e
DATA: l v_bol _cor e TYPE REF TO cl _cr m_bol _cor e.
l v_bol _cor e = cl _cr m_bol _cor e=>get _i nst ance( ) .
l v_bol _cor e- >st ar t _up( MY_COMPONENT_SET ) .
The BOL core CL_CRM_BOL_CORE follows the singleton design pattern, so you can only
have one instance of it. The START_UP() method takes the name of the component set that
you want to start as input parameter and starts the BOL. Once this is completed, you can
load all services of the BOL and the component set.
The START_UP() method takes another optional parameter, I V_DI SPLAY_MODE_SUPPORT,
which is set to ABAP_FALSE by default. This means that the BOL follows the optimistic
locking approach, making all of the objects appear changeable in the user interface even
without a lock. The lock is automatically requested on the first attempt to make a change to
an object.
If the parameter I V_DI SPLAY_MODE_SUPPORT is set to ABAP_TRUE, the BOL follows the
strict locking approach where only locked objects appear as changeable. For more
information, see Display Mode Support [page 18].
1.1.4.2 Component Sets and Components of the Generic
Interacti on Layer
Each component set defines a set of Generic Interaction Layer (GenIL) components, each
providing specific business objects with dependent objects and related queries. GenIL
component sets and GenIL components are defined in Customizing for Customer
Relationship Management under CRM Cross-Application Components Generic Interaction
Layer/Object Layer Basic Settings.
Components of the GenIL are implemented using ABAP classes. To determine which
business objects, attributes, relations, dependent objects, queries, and further services are
provided by a component set, you can use the Model Browser (transaction
GENIL_MODEL_BROWSER).
To check which components are loaded and to load additional components, you can use the
following code:
Syntax
* Load addi t i onal component
DATA: l v_component _name t ype cr mt _component _name.
l v_component _name = ' ANOTHER_COMPONENT' .
l v_bol _cor e- >l oad_component ( l v_component _name ) .
1 Business Obj ect Layer
<July 2008> 11
* Get component s l oaded
DATA: l v_obj _model t ype r ef t o i f _geni l _obj _model ,
l v_obj _model _ t ype r ef t o cl _cr m_geni l _obj _model ,
l t _component s_l oaded t ype geni l _component _t ab.
l v_obj _model =
cl _cr m_geni l _model _ser vi ce=>get _r unt i me_model ( ) .
l v_obj _model _ ?= l v_obj _model .
l t _component s_l oaded = l v_obj _model _-
>get _component s_l oaded( ) .
1.1.4.3 Issue Queri es
Before you can work with business objects or entities, you need to locate them using a
search. You use a query service object to receive a collection of business objects that match
the search criteria given.
1.1.4.3.1 Regular Queries
In a generic application, such as the BOL browser, you may use the BOL Object Model
Service to determine the query services of the loaded component sets and components.
Select a query service, set the query parameters, and launch a query.
You can receive a table with the names of all available query services by entering the
following code:
Syntax
* Det er mi ne quer y ser vi ces avai l abl e
DATA: l v_obj _model TYPE REF TO i f _geni l _obj _model .
l v_obj _model =
cl _cr m_geni l _model _ser vi ce=>get _r unt i me_model ( ) .
DATA: l t _quer y_names TYPE cr mt _ext _obj _name_t ab.
CALL METHOD l v_obj _model - >get _obj ect _l i st
EXPORTI NG i v_obj ect _ki nd =
i f _geni l _obj _model =>quer y_obj ect
I MPORTI NG ev_obj ect _l i st = l t _quer y_names.
To get a runtime instance of the query service CL_CRM_BOL_QUERY_SERVICE, use the
GET_INSTANCE factory method. Use its SET_PROPERTY method to indicate the search
criteria and its GET_QUERY_RESULT method to launch your query to retrieve a result list of
entities (represented by IF_BOL_ENTITY_COL):
Syntax
* Sel ect a par t i cul ar quer y
DATA: l v_quer y_name TYPE cr mt _ext _obj _name.
READ TABLE l t _quer y_names I NDEX 1 I NTO l v_quer y_name.
* Cr eat e a quer y ser vi ce
DATA: l v_quer y TYPE REF TO cl _cr m_bol _quer y_ser vi ce.
1 Business Obj ect Layer
12 <July 2008>
l v_quer y = cl _cr m_bol _quer y_ser vi ce=>get _i nst ance( l v_quer y_name
) .
* Set a sear ch cr i t er i on
l v_quer y- >set _pr oper t y( i v_at t r _name = Ci t y
i v_val ue = Wal l dor f ) .
* Read a sear ch cr i t er i on
DATA: l v_ci t y t ype st r i ng.
l v_ci t y = l v_quer y- >get _pr oper t y_as_st r i ng( Ci t y ) .
* Execut e quer y and r ecei ve r esul t
DATA: l v_r esul t TYPE REF TO i f _bol _ent i t y_col .
l v_r esul t = l v_quer y- >get _quer y_r esul t ( ) .
If you already know the name of the query service to be used, there is no need to use the
model: you can directly access the query service by name.
As you can see in the above example, it is also possible to retrieve search criteria from the
query service.
You can perform queries and other methods of the BOL API using the BOL Browser
(transaction GENIL_BOL_BROWSER):
1. Select the desired component set, for example, SAMPLE.
2. Select the query object and enter the parameters before you select Find.
3. Double click an object ID displayed in the List Browser to see a particular object with its
attributes.
1.1.4.3.2 Advanced Queries
As of SAP CRM release 5.1, the CRM WebClient UI framework supports advanced queries,
with the following enhanced features:
In addition to the EQUAL operator, you can use arbitrary operators, such as
GREATER THAN, LESS THAN, CONTAINS, and IS EMPTY to define search criteria.
You can search for multiple values for one search criterion at the same time (logical
OR).
You can save and retrieve searches with predefined search criteria as templates
identified with an arbitrary name.
Syntax
* Get advanced quer y
DATA: l v_advanced_quer y TYPE REF TO cl _cr m_bol _dquer y_ser vi ce.
l v_advanced_quer y =
cl _cr m_bol _dquer y_ser vi ce=>get _i nst ance( ' AdvOr der Quer y' ) .
* Set gener al quer y par amet er f or maxi mumnumber of hi t s
DATA: l t _par ams t ype cr mt _name_val ue_pai r _t ab,
1 Business Obj ect Layer
<July 2008> 13
l s_par ams t ype cr mt _name_val ue_pai r .
l s_par ams- name = ' MAX_HI TS' . l s_par ams- val ue = ' 5' .
APPEND l s_par ams TO l t _par ams.
l v_advanced_quer y- >set _quer y_par amet er s( i t _par amet er s = l t _par ams
) .
* Add sel ect i on cr i t er i a: Or der number > 5
l v_advanced_quer y- >add_sel ect i on_par am( i v_at t r _name =
' ORDER_NUMBER'
i v_si gn = ' I '
i v_opt i on = ' GT' Gr eat er t han
i v_l ow = ' 5'
i v_hi gh = ' ' ) .
* Execut e t he quer y and r ecei ve r esul t
DATA: l v_r esul t t ype r ef t o i f _bol _ent i t y_col .
l v_r esul t = l v_advanced_quer y- >get _quer y_r esul t ( ) .
To display advanced queries in the CRM WebClient UI, easy-to-use tags have been
developed.
Query templates are used to store and retrieve saved searches with predefined search
criteria:
Syntax
* Save quer y as t empl at e
l v_advanced_quer y- >save_quer y_as_t empl at e( i v_quer y_i d = My
Quer y
i v_over wr i t e = abap_t r ue ) .
* Load quer y f r omt empl at e
l v_advanced_quer y- >l oad_quer y_t empl at e( i v_quer y_i d = My Quer y
) .
1.1.4.4 Working with Entities
After you receive a list of entities from the query, you can use them in your application by, for
example, displaying their attributes on the user interface, modifying them, or deleting them.
1.1.4.5 Access Properties and Rel ated Entities
The following code shows how to access entities of the query result and how to read their
properties. Note that the methods are the same for all types of business objects.
Syntax
* Use i t er at or t o access ent i t i es i n quer y r esul t
DATA: l v_i t er at or TYPE REF TO i f _bol _ent i t y_col _i t er at or .
1 Business Obj ect Layer
14 <July 2008>
l v_i t er at or = l v_r esul t - >get _i t er at or .
DATA: l v_ent i t y TYPE REF TO cl _cr m_bol _ent i t y.
l v_ent i t y = l v_i t er at or - >get _f i r st ( ) . Ent i t y i s busi ness par t ner
her e
WHI LE l v_ent i t y I S BOUND.
* Access at t r i but es of busi ness obj ect s sel ect ed
DATA: l v_f i r st name TYPE st r i ng,
l v_l ast name TYPE st r i ng.
l v_f i r st name = l v_ent i t y- >get _pr oper t y_as_st r i ng( Fi r st Name ) .
l v_l ast name = l v_ent i t y- >get _pr oper t y_as_st r i ng( Last Name ) .
* Get a 1: 1 r el at ed ent i t y
DATA: l v_def aul t _addr ess TYPE REF TO cl _cr m_bol _ent i t y.
l v_def aul t _addr ess = l v_ent i t y- >get _r el at ed_ent i t y(
Def aul t Addr ess ) .
* Get a l i st of 1: N r el at ed ent i t i es
DATA: l v_addr esses TYPE REF TO i f _bol _ent i t y_col .
l v_addr esses = l v_ent i t y- >get _r el at ed_ent i t i es( Addr esses ) .
*
l v_ent i t y = l v_i t er at or - >get _next ( ) .
ENDWHI LE.
The last section of code shows how to navigate from one entity to a related entity. Use the
BOL Object Model Service or the Model Browser to find out which relationships have been
defined in the model for a particular object type.
1.1.4.6 Transacti ons
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 with the BOL transaction model, which
supports several kinds of transaction contexts to handle entity operations consistently.
The global transaction context holds all modified root entities, whereas the fine granular
transaction context exists for each root object instance. The custom transaction context can
be used to handle special situations, where more than one (but not all) modified object forms
the transaction. This section discusses only the global context. For more information about
the fine granular transaction context, see Fine Granular Transaction Handling [page 24].
1.1.4.7 Creati ng Entiti es
The following code shows how to create a root entity with two related entities:
Syntax
* 1. Bui l d par amet er s t o cr eat e an ent i t y:
* her e an or der ent i t y wi t h t echni cal name BTOr der
1 Business Obj ect Layer
<July 2008> 15
DATA: l t _par ams TYPE cr mt _name_val ue_pai r _t ab,
l s_par ams TYPE cr mt _name_val ue_pai r .
l s_par ams- name = PROCESS_TYPE .
l s_par ams- val ue = TA .
APPEND l s_par ams TO l t _par ams.
* 2. Get f act or y f or busi ness obj ect
DATA: l v_or der _f act or y TYPE REF TO cl _cr m_bol _ent i t y_f act or y.
l v_or der _f act or y = l v_bol _cor e- >get _ent i t y_f act or y( BTOr der ) .
* 3. Cr eat e r oot ent i t y
DATA: l v_or der TYPE REF TO cl _cr m_bol _ent i t y.
l v_or der = l v_or der _f act or y- >cr eat e( l t _par ams ) .
* 4. Cr eat e chi l d obj ect s
DATA: l v_or der _header TYPE REF TO cl _cr m_bol _ent i t y,
l v_act i vi t y_header TYPE REF TO cl _cr m_bol _ent i t y.
l v_or der _header = l v_or der - >cr eat e_r el at ed_ent i t y( BTOr der Header
) .
l v_act i vi t y_header =
l v_or der _header - >cr eat e_r el at ed_ent i t y(
BTHeader Act i vi t yExt ) .
* 5. Submi t chi l d obj ect s cr eat ed
l v_bol _cor e- >modi f y( ) .
* 6. Save and commi t changes usi ng gl obal t r ansact i on cont ext
DATA: l v_t r ansact i on TYPE REF TO i f _bol _t r ansact i on_cont ext
l v_t r ansact i on = l v_bol _cor e- >get _t r ansact i on( ) .
l v_t r ansact i on- >save( ) .
l v_t r ansact i on- >commi t ( ) .
You can distinguish between the creation of root objects using the factory and the creation of
dependent or child objects using method CREATE_RELATED_ENTITY. The first case
directly triggers a call to the underlying API, whereas in the second case it does not. In the
second case, it is necessary to trigger the API call explicitly by calling the MODIFY method,
which sends the changes to the underlying GenIL. Without this call, the created child objects
are not saved.
1.1.4.8 Locki ng Entiti es
You should lock an entity before you are going to modify it, as the setter only modifies entity
properties when the entity is locked. The set-methods of the entity perform a check to see if
the entity is locked. If it is not, they try to lock it. This attempt can fail if another user is using
the entity.
1 Business Obj ect Layer
16 <July 2008>
The current locking granularity of the BOL is the root object instances, so the lock request for
an entity is always delegated to the corresponding root instance.
The following code shows how to lock an entity:
Syntax
* Lock BOL ent i t y
DATA: l v_success TYPE cr mt _bool ean.
l v_success = l v_ent i t y- >l ock( ) .
If the lock was set, the return value LV_SUCCESS is true (ABAP_TRUE or
IF_GENIL_BOOLEAN =>TRUE ).
1.1.4.9 Modifyi ng Entity Properties
You can modify entity properties using the set-methods of the entity. If you have not started a
transaction before modifying the properties, it is created automatically.
The following code shows how to modify the property of an order:
Syntax
* 1. Lock and modi f y a pr oper t y
* her e or der header ent i t y wi t h t echni cal name BTOr der Header
l v_or der _header = l v_or der - >get _r el at ed_ent i t y( BTOr der Header
) .
I F l v_or der _header - >l ock( ) = i f _geni l _bool ean=>t r ue.
l v_or der _header - >set _pr oper t y( i v_at t r _name = DESCRI PTI ON
i v_val ue = Changed
Descr i pt i on ) .
ENDI F.
* 2. send al l changes t o BO l ayer
l v_bol _cor e- >modi f y( ) .
* 3. get t he i mpl i ci t l y cr eat ed t r ansact i on
l v_t r ansact i on = l v_bol _cor e- >get _t r ansact i on( ) .
* 4. save and commi t your changes
l v_t r ansact i on- >save( ) .
l v_t r ansact i on- >commi t ( ) .
The given example works with or without display mode support, since the lock is explicitly set.
1.1.4.10 Deleting Entiti es
Similar to when you create entities, you must distinguish between the deletion of root objects
and the deletion of dependent or child objects.
1 Business Obj ect Layer
<July 2008> 17
For root object instances, the DELETE method call is sent directly to the API where the
complete aggregation hierarchy is deleted. The deletion is written to the database with an
internal COMMIT WORK.
Syntax
* Del et e r oot ent i t y
l v_or der - >del et e( ) .
In the 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 BOL core.
Syntax
* Del et e chi l d obj ect
l v_or der _header - >del et e( ) .
l v_bol _cor e- >modi f y( ) .
DATA: l v_t r ansact i on TYPE REF TO i f _bol _t r ansact i on_cont ext .
l v_t r ansact i on = l v_bol _cor e- >get _t r ansact i on( ) .
l v_t r ansact i on- >save( ) .
l v_t r ansact i on- >commi t ( ) .
Note: You must save and commit the transaction to confirm the deletion.
Immediately after CL_CRM_BOL_CORE->MODIFY has been executed, the entity is deleted
in the BOL buffer. This is published in the entity instance by creating a DELETED event. After
the deletion, any further access to the entity instance can lead to a CX_BOL_EXCEPTION
exception.
1.1.4.11 Executi on of Enti ty Methods
To perform special business functions, it is possible to call special methods on an entity that
have been modeled and implemented for a particular object type. These methods can have
an arbitrary set of import parameters and may return an entity collection of result objects.
The following code shows how to execute an entity method for special business functionality:
Syntax
* Execut e ent i t y met hod
DATA: l v_i t ems TYPE REF TO cl _cr m_bol _ent i t y.
l v_i t ems- >execut e( i v_met hod_name = Renumber I t ems ) .
* . . . wi t h i nput par amet er s and a l i st of BOL ent i t i es r et ur ned
DATA: l s_par am TYPE cr mt _name_val ue_pai r ,
l t _par am TYPE cr mt _name_val ue_pai r _t ab,
l v_r esul t TYPE REF TO i f _bol _ent i t y_col .
l s_par am- name = PROCESS_TYPE .
l s_par am- val ue = TSRV .
append l s_par amt o l t _par am.
TRY.
1 Business Obj ect Layer
18 <July 2008>
l v_r esul t = l v_or der _header - >execut e( i v_met hod_name =
cr eat eFol l owUp
i t _par am = l t _par am) .
* Er r or handl i ng
CATCH CX_CRM_BOL_METH_EXEC_FAI LED.
* An except i on i s r ecei ved i f met hod has i ndi cat ed an er r or
* and has not r et ur ned mor e t han one ent i t y.
. . .
ENDTRY.
1.1.5 Advanced Features of the BOL API
The following sections describe special features of the BOL API.
1.1.5.1 Di splay Mode Support
As of SAP CRM 5.0, the BOL optionally supports DISPLAY mode for entities, which is
activated by default if the BOL core has been started with the parameter
I V_DI SPLAY_MODE_SUPPORT = ABAP_TRUE.
In display mode, any attempt to change properties, or to create or delete dependent objects
is ignored and a call of method
IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY on the entity returns
ABAP_TRUE (X).
To change entity properties, it is necessary to switch the entity explicitly to CHANGE mode.
You can do this by calling method SWITCH_TO_CHANGE_MODE or method LOCK. If no
lock is obtained, the entity remains in display mode. The current state of an entity can be
checked with method IS_CHANGEABLE.
Syntax
* St ar t BOL cor e wi t h di spl ay mode suppor t
DATA: l v_bol _cor e TYPE REF TO cl _cr m_bol _cor e.
l v_bol _cor e = cl _cr m_bol _cor e=>get _i nst ance( ) .
l v_bol _cor e- >st ar t _up( i v_appl _name = MY_COMPONENT_SET
i v_di spl ay_mode_suppor t = ABAP_TRUE ) .
* Execut e quer y and access ent i t y
DATA: l v_ent i t y t ype r ef t o cl _cr m_bol _ent i t y.
l v_ent i t y = . . . - Ent i t y i s i n now di spl ay
mode
* Swi t ch t o change mode and change ent i t y
l v_ent i t y- >swi t ch_t o_change_mode( ) . Rer ead and l ock ent i t y
I F l v_ent i t y- >i s_changeabl e( ) = abap_t r ue.
l v_ent i t y- >set _pr oper t y_as_st r i ng( i v_at t r _name =
PROPERTY_NAME
1 Business Obj ect Layer
<July 2008> 19
i v_val ue = New Val ue ) .
ENDI F.
When an entity is locked, its properties are re-read to ensure that the most current data is
available.
1.1.5.2 Standard Interface to Access Properties of Business
Obj ects
To access the properties of BOL entities and query services, you must use their
IF_BOL_BO_PROPERTY_ACCESS interface methods.
<<interface>>
IF_BOL_BO_PROPERTY_ACCESS
CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY
The interface offers a standard means to work with BOL objects. Note that it is possible to
have an instance of IF_BOL_BO_PROPERTY_ACCESS for any BOL object.
Syntax
* Get sear ch cr i t er i on of BOL quer y
DATA: l v_quer y TYPE REF TO cl _cr m_bol _quer y_ser vi ce, l v_ci t y_t ype
st r i ng.
l v_quer y = cl _cr m_bol _quer y_ser vi ce=>get _i nst ance( QUERY_NAME ) .
l v_ci t y =
l v_quer y- >i f _bol _bo_pr oper t y_access~get _pr oper t y_as_st r i ng(
Ci t y ) .
Shor t f or musi ng al i as
l v_ci t y = l v_quer y- >get _pr oper t y_as_st r i ng( Ci t y ) .
* Set pr oper t y of BOL ent i t y
DATA: l v_ent i t y TYPE REF TO cl _cr m_bol _ent i t y
l v_ent i t y- >i f _bol _bo_pr oper t y_access~set _pr oper t y( i v_at t r _name =
CI TY
i v_val ue = Wal l dor f ) .
Shor t f or musi ng al i as
l v_ent i t y- >set _pr oper t y( i v_at t r _name = CI TY i v_val ue =
Wal l dor f ) .
1 Business Obj ect Layer
20 <July 2008>
* Cast t o pr oper t y_access i nt er f ace
DATA: l v_busi ness_obj ect TYPE REF TO i f _bol _bo_pr oper t y_access.
l v_busi ness_obj ect ?= l v_ent i t y.
In addition to generic getter and setter methods to read and modify business object
properties, the interface offers methods to receive the text for a key-code value.
Syntax
* Get key code
DATA: l v_per son TYPE REF TO cl _cr m_bol _ent i t y,
l v_sex t ype bu_sexi d. Def i nes val ues 1 = Femal e, 2 = Mal e
. . .
l v_sex = l v_per son- >get _pr oper t y( SEX ) . Key code
* Get pr oper t y t ext f or key code:
* - > Mal e or Femal e t r ansl at ed i n cur r ent l anguage
DATA: l v_sex_t ext t ype st r i ng.
l v_sex_t ext = l v_per son- >get _pr oper t y_t ext ( SEX ) .
The text is taken from the domain values if available or is determined by the underlying GenIL
component.
1.1.5.3 Collections to hold Busi ness Objects and BOL Entiti es
The BOL API offers two collections for application use:
CL_CRM_BOL_COL, which can be used to hold all instances implementing the
standard property access interface IF_BOL_BO_PROPERTY_ACCESS
CL_CRM_BOL_ENTITY_COL, which can hold regular BOL entities only
IF_BOL_BO_COL
IF_BOL_ENTITY_COL
CL_CRM_BOL_BO_COL
CL_CRM_BOL_ENTITY_COL
The collection interfaces offer a number of methods to work with collections, such as
INSERT, GET_FIRST, GET_NEXT, GET_CURRENT, SORT, CLEAR, MARK, and
UNMARK.
1.1.5.3.1 Local and Global Iterations
Both collection types support global iteration and local iteration. Each collection has a well-
defined focus object. Initially, the first object has the focus. Any global iteration moves the
focus, which is published by the event FOCUS_CHANGED of the collection.
1 Business Obj ect Layer
<July 2008> 21
If you want to iterate on the collection without moving the focus (and without triggering time-
consuming follow-up processes) you can use local iteration. To do so, request an iterator
object from the collection and use this to iterate.
Syntax
* Cr eat e col l ect i on
DATA: l v_col l ect i on TYPE REF TO cl _cr m_bol _bo_col l ect i on,
l v_pr oper t y_access TYPE REF TO i f _bol _bo_pr oper t y_access,
l v_quer y TYPE REF TO cl _cr m_bol _quer y_ser vi ce.
CREATE OBJ ECT l v_col l ect i on.
. . .
* Add i t emand make i t cur r ent
l v_col l ect i on- >i f _bol _bo_col ~i nser t ( i v_bo = l v_quer y
I v_i ndex = 1
I v_set _f ocus = ABAP_BOOL ) .
* Gl obal i t er at i on
l v_pr oper t y_access = l v_col l ect i on- >get _next ( ) . Gl obal i t er at i on
moves f ocus
* Local i t er at i on
DATA: l v_i t er at or TYPE REF TO i f _bol _bo_col _i t er at or .
l v_i t er at or = l v_col l ect i on- >get _i t er at or ( ) .
l v_pr oper t y_access = l v_i t er at or - >get _f i r st ( )
WHI LE l v_quer y_i s_bound.
l v_pr oper t y_access = l v_col l ect i on- >get _next ( ) . Local i t er at i on
does not
ENDWHI LE. move f ocus
1.1.5.3.2 Searching
The collections provide the method FIND to search for a given business object in the
collection. If the business object is found, it is returned and the focus is set to this collection
entry.
You can search by index, business object instance, or object name and ID, but only one of
these parameters is used for the search at a time. The parameters are taken in the given
sequence. For example, if you provide an index and an instance, only the index is used.
The local iterator interface supports the search for a single property. This is provided by the
method FIND_BY_PROPERTY. The first object, whose property has the given value, is
returned. Neither the global nor the local collection pointer is influenced by this operation.
Syntax
* Fi nd by pr oper t y
DATA: l v_per sons TYPE REF TO cl _cr m_bol _ent i t y_col l ect i on,
l v_mal e TYPE REF TO cl _cr m_bol _ent i t y,
l v_i t er at or TYPE REF TO i f _bol _bo_col _i t er at or .
1 Business Obj ect Layer
22 <July 2008>
l v_i t er at or = l v_per sons- >get _i t er at or ( ) .
l v_mal e = l v_i t er at or - >f i nd_by_pr oper t y( i v_at t r _name = SEX
i v_val ue = 2 ) .
* Set col l ect i on f ocus on t he ent i t y f ound
l v_per sons- >f i nd( i v_bo = l v_mal e ) .
1.1.5.3.3 Sorting
Collections can be sorted with the SORT method and stay in the resulting sort order.
Note
You can not undo the sorting process.
The mandatory parameter I V_ATTR_NAME specifies the property that the collection is sorted
for. If you do not specify I V_SORT_ORDER, the sort order defaults as ascending.
Syntax
* Sor t i ng
DATA: l v_per sons TYPE REF TO cl _cr m_bol _ent i t y_col l ect i on,
l v_mal e TYPE REF TO cl _cr m_bol _ent i t y,
l v_i t er at or TYPE REF TO i f _bol _bo_col _i t er at or .
l v_per sons- >sor t ( i v_at t r _name = SEX
i v_sor t _or der = I F_BOL_BO_COL=>SORT_DESCENDI NG ) .
The sorting is alphabetical and based on the string representation of the property. Since this
can lead to false results (for example, when working with 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 called whenever two values are compared. To modify the sort
order as needed, implement this method and provide the interface.
1.1.5.3.4 Multi Select Support
BOL collections support two different modes for entry selection:
Single Selection Mode
In this mode, it is only possible to select a single entry at a time. When a second
entry is selected, the previous one is de-selected.
Multi Selection Mode
In this mode, it is possible to select more than one entry at a time.
The current selection mode can be checked with the public collection attribute
IF_BOL_BO_COL~MULTI_SELECT and it can be set with method
IF_BOL_BO_COL~SET_MULTI_SELECT.
In single selection mode, the selected element is communicated with the following methods:
Method Result
IF_BOL_BO_COL~GET_CURRENT Returns the selected element
IF_BOL_BO_COL~GET_CURRENT_INDEX Returns the index of the selected element
IF_BOL_BO_COL~PUBLISH_CURRENT
IF_BOL_BO_COL~FOCUS_CHANGED
Publishes the selected element using the
event
1 Business Obj ect Layer
<July 2008> 23
The selected element is implicitly set with the following methods:
Method Result
IF_BOL_BO_COL~GET_NEXT Moves focus to the next element and
returns it
IF_BOL_BO_COL~GET_PREVIOUS Moves focus to the previous element and
returns it
Note
In single selection mode, the current or focus element is always defined, except
when the collection is empty. The methods of the interface
IF_BOL_BO_COL_MULTI_SEL are deactivated.
When multi selection mode has been activated, you may use the methods of the interface
IF_BOL_BO_COL_MULTI_SEL to mark and unmark entries, and to check which entries have
been marked (IF_BOL_BO_COL_MULTI_SEL~MARK, UNMARK, GET_MARKED).
In multi selection mode, the collection methods behave differently than in single selection
mode:
Method Result
IF_BOL_BO_COL~GET_CURRENT Returns the last selected element
IF_BOL_BO_COL~GET_CURRENT_INDEX Returns the index of the last selected
element
IF_BOL_BO_COL~PUBLISH_CURRENT Does nothing
IF_BOL_BO_COL~FIND Finds, eventually selects and returns an
element
IF_BOL_BO_COL~GET_NEXT Does nothing
IF_BOL_BO_COL~GET_PREVIOUS Does nothing
1.1.5.3.5 Auto Cleanup Mode
Auto cleanup mode for a collection ensures that deleted entities are automatically removed
from the collection. As a result, the (last) selected element changes automatically.
Entity removal is not always necessary and this feature can lead to serious problems with
memory, so by default it is inactive. To activate this function, call method
IF_BOL_BO_COL~ACTIVATE_AUTOCLEANUP. The current state of the collection is
indicated by the public attribute IF_BOL_BO_COL~AUTOCLEANUP, which is ABAP_TRUE if
active.
Caution
If auto cleanup mode is active, it is necessary to clear a collection (call method
IF_BOL_BO_COL~CLEAR) when it is no longer needed. The garbage collector
cannot delete the collection if it is referenced in the event handler table of its
entities. If you do not clear unneeded collections, the affected collections remain
in memory until the next BOL reset operation or session end. This can lead to
serious memory issues.
1.1.5.3.6 BOL Reset Survi val Mode
To free unused memory, the SAP CRM application periodically triggers a BOL reset that
deletes all BOL entities, and as a result clears all collections that have auto cleanup
activated.
1 Business Obj ect Layer
24 <July 2008>
Some collections need to protect their content, especially if they are essential for the further
operation of the application. You can use method
IF_BOL_BO_COL~SET_RESET_SURVIVAL_MODE to indicate that the root and access
entities are to be recreated after the BOL reset.
To receive notice at runtime of any collections that are not reset-compliant because they
contain dependent entities, you can activate the assertion group BOL_ASSERTS using
transaction SAAB (assertions, breakpoints and logpoints).
1.1.5.4 Fi ne Granular Transacti on Handli ng
A transaction context is established for each root object instance that you use. It can be
accessed using method GET_TRANSACTION on an entity instance. Its SAVE method saves
the underlying root object instance and its aggregation hierarchy. However the COMMIT is
global and if the implementation in transaction handling contains any unwanted data, this
unwanted data may be saved.
Note
There is no monitoring of dependencies between root objects. For example, you
have a newly created root object that refers to another newly generated object. If
the first object is saved but the second one is not, the database is in an
inconsistent state.
You can use the CL_CRM_BOL_CUSTOM_TX_CTXT transaction context to create a single
transaction that contains more than one root object transaction:
Syntax
* 1. Cr eat e cust omt x cont ext
DATA: my_t x_cont ext TYPE REF TO cl _cr m_bol _cust om_t x_cont ext .
CREATE OBJ ECT my_t x_cont ext .
* 2. Add some si ngl e obj ect t r ansact i ons
DATA: l v_ent i t y1 TYPE REF TO cl _cr m_bol _ent i t y,
l v_ent i t y2 TYPE REF TO cl _cr m_bol _ent i t y,
l v_t x_ct xt TYPE REF TO i f _bol _t r ansact i on_cont ext .
. . .
l v_t x_ct xt = l v_ent i t y1- >get _t r ansact i on( ) .
my_t x_cont ext - >add_t x_cont ext ( l v_t x_ct xt ) .
l v_t x_ct xt = l v_ent i t y2- >get _t r ansact i on( ) .
my_t x_cont ext - >add_t x_cont ext ( l v_t x_ct xt ) .
* 3. Save and commi t bot h si ngl e obj ect t r ansact i ons t oget her
my_t x_cont ext - >save( ) .
my_t x_cont ext - >commi t ( ) .
Transaction contexts can be requested at any time by using method
IF_BOL_TRANSACTION_CONTEXT~CHECK_SAVE_NEEDED. This allows you to see if
data has been changed or if a save is necessary.
1.1.5.5 Input Readi ness and Enti ty Property Modifi ers
1 Business Obj ect Layer
<July 2008> 25
To check if an entity property is read only, you can use method
IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY. It returns ABAP_TRUE
if the property is not changeable and not mandatory.
The property modifier is defined for each entity property and calculates input readiness. It
takes one of the following public constants defined in the interface
IF_GENIL_OBJ _ATTR_PROPERTIES:
READ_ONLY
CHANGEABLE
NOT DEFINED
HIDDEN
MANDATORY
TECHNICAL
To access the property modifier, use the entity method GET_PROPERTY_MODIFIER.
By default, it is possible to change properties of query services.
1.1.5.6 Excludi ng Entiti es from the Central Modify
New, changed, or deleted dependent objects are sent to the underlying APIs with one central
call of the BOL cores MODIFY method. Depending on the application, this call may appear
automatically at certain sync points. If entities are not ready to be sent, sending them can
cause errors. In this case, you can exclude such entities to prevent them from being sent.
An entity is excluded in the following cases:
A dependent entity was created but its properties were not set
An entity was sent with MODIFY, but the changes have not been accepted by the
underlying API
An entity was deactivated for sending
The current status of an entity can be checked with method IS_SEND_ACTIVE on the entity
instance. You can make an explicit change to the status with the methods
ACTIVATE_SENDING and DEACTIVATE_SENDING. If you deactivate sending, this also
affects any child objects.
1.1.5.7 Busi ness Error Handli ng
The BOL offers a message protocol to support communication of information messages,
warning messages, and error messages. Messages are collected in message containers,
which are handled by the message container manager. There is one message container for
each root object instance and a global one for all general messages.
1 Business Obj ect Layer
26 <July 2008>
Message Handling Model
CL_CRM_COL_CORE
CL_CRM_GENIL_MESS_CONT_MANAGER
IF_GENIL_MESSAGE_CONTAINER
1
1
1
*
The message container manager can be reached using the core. The following code shows
how to access a particular message container:
Syntax
* Access messages of a busi ness obj ect
* 1) Use t he message cont ai ner manager
DATA: l v_mcmTYPE REF TO cl _cr m_geni l _mess_cont _manager .
l v_mcm= l v_bol _cor e- >get _message_cont _manager ( ) .
* 2) . . . t o obt ai n t he message cont ai ner
DATA: l v_obj ect _name TYPE cr mt _ext _obj _name,
Lv_obj ect _i d TYPE cr mt _gni l _obj ect _i d.
l v_obj ect _name = l v_or der - >get _name( ) .
l v_obj ect _i d = l v_or der - >get _key( ) .
DATA: l v_mc TYPE REF TO i f _geni l _message_cont ai ner .
l v_mc = l v_mcm- >get _message_cont ( i v_obj ect _name = l v_obj ect _name
I v_obj ect _i d = l v_obj ect _i d ) .
The message container interface provides the method
IF_GENIL_MESSAGE_CONTAINER~GET_MESSAGES for access. Since it takes the
message type as parameter, it is possible to filter for errors, warnings, and information.
Possible values for the message types are defined as constants MT_ALL, MT_ERROR,
MT_WARNING, MT_INFO, and MT_SUCCESS in the IF_GENIL_MESSAGE_CONTAINER
interface.
1 Business Obj ect Layer
<July 2008> 27
The method GET_NUMBER_OF_MESSAGES returns the number of messages of the
specified type. This can be used to notify a user of new messages.
Syntax
* 3) Access messages
DATA: l v_number _of _er r or s TYPE i nt 4,
l t _er r or _messages TYPE cr mt _geni l _message_t ab.
l v_number _of _er r or s = l v_mc- >get _number _of _messages( l v_mc- >mt _er r or
) .
I F l v_number _of _er r or s <> 0.
l t _er r or _messages = l v_mc- >get _messages( l v_mc- >mt _er r or ) .
ENDI F.
1.1.5.8 Buffering Issues
The BOL operates on its own entity buffer, and so each of the following is buffered:
Every entity found by a query
Every entity read by navigation over a relationship
Each entity modification, as well as the creation or deletion of dependent entities
The underlying buffers of the GenIL components (for the various business object types) are
synchronized with BOL modifications when CL_CRM_BOL_CORE->MODIFY()is called. In
the SAP CRM application, this happens automatically with each round trip. The BOL buffer is
also informed automatically about data changes in the GenIL component.
In special situations, an explicit synchronization between the BOL buffer and GenIL
component is necessary. These situations are described in the sections below.
1.1.5.8.1 Entity Properties
The entity method CL_CRM_BOL_ENTITY->REREAD() can be used to synchronize the
buffer state of the properties and property modifiers of a single entity. Since this method calls
the underlying API directly, it should be used with caution to avoid performance problems.
1.1.5.8.2 Entity Relationships
The system also buffers the relationships between entities. Unlike with buffered properties,
this may make the relationships invalid and cannot be synchronized automatically. This may
cause inconsistencies in some cases.
You can distinguish between cacheable relations and those which are not subject to
buffering.
For the cacheable relations, you can apecify a mode for navigation. Therefore the navigation
methods GET_RELATED_ENTITY() and GET_RELATED_ENTITIES() take an optional
parameter I V_MODE, which may be set to one of the following constants (defined in class
CL_CRM_BOL_ENTITY) :
NORMAL
This is the default constant. It reads a relationship from the underlying API if the BOL
buffer is empty.
BUFFER_ONLY
1 Business Obj ect Layer
28 <July 2008>
This only reads the relationship from the BOL buffer.
BYPASSING_BUFFER
This only reads the relationship from the underlying API, ignoring the BOL buffer.
Non-cacheable relations are read from the underlying API for each navigation, ignoring the
given mode. Being non-cacheable is an unchangeable model property of a relationship
(IF_GENIL_OBJ _MODEL~RELATION_IS_CACHEABLE).
1.1.5.8.3 Preloading BOL Views
If you need to synchronize a larger set of entities with relationships, the above methods are
ineffective. You can load a well-defined part of the object model with a given start entity or set
of entities at one time. This model part must be defined as a BOL View in Customizing for
Customer Relationship Management under CRM Cross-Application Components Generic
Interaction Layer/Object Layer Define Views.
Select an existing view or create a new entry, and choose Maintain Views. Each BOL view is
assigned to a specific component set and has a unique view root, which is either a BOL root
object or access object. You also define the related object types and their relationships.
Once you have completed this customizing, the method PREFETCH_VIEW can be called on
the BOL core. It takes the view name and a collection of view root entities as input. The
model part defined by the view is read for each entity in the collection and stored in the
buffer.
1.1.5.8.4 Locking with Synchronization
After setting a lock it is sometimes necessary to synchronize the BOL buffer for the locked
entity with the current database state. Synchronization is necessary in the following cases:
If the entity has been changed by another user since the last read operation
If the last lock attempt failed because the entity was already locked
When a lock attempt fails, the entity is set to read-only mode and the property
modifiers must be refreshed.
Therefore the CL_CRM_BOL_ENTITY->LOCK method takes an optional parameter
I V_REREAD. The default setting is 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.
1.1.5.9 BOL Reset
The BOL buffer and the message services permanently collect information, but do not
release it. Therefore, the amount of data constantly grows over time. A mechanism is
necessary to remove this buffered or collected data.
To reset the BOL core, you can use the method CL_CRM_BOL_CORE->RESET(). This
method clears all known buffers and messages. After the method has run, you can call the
ABAP garbage collector to remove all of the freed objects.
In the SAP CRM application, a BOL reset is triggered automatically from the framework
whenever the user switches the work center with a click in the CRM WebClient UI Navigation
bar.
You can not use entity instances after the BOL reset. Further operations using them cause
runtime exceptions unless the entity is a root or access entity and contained in a collection
that has reset survival mode activated. For more information, see BOL Reset Survival Mode
[page 23].
1 Business Obj ect Layer
<July 2008> 29
1.1.6 Interface Cl asses
The following sections include a summary of important classes and interfaces of the Business
Object Layer (BOL).
1.1.6.1 BOL Core
CL_CRM_BOL_CORE is the most important class of the BOL Application Programming
Interface (API). There is only one instance of it within each session and it cannot be lost or
deleted. The BOL core is the central service provider for API classes and it communicates
with the underlying business object implementation. You can use the core services directly,
but it is strongly recommended to use the API classes, such as query services or entities.
1.1.6.2 Query Services
Generic query services are provided by the classes CL_CRM_BOL_QUERY_SERVICE and
CL_CRM_BOL_DQUERY_SERVICE. Each instance corresponds to a distinct query object. It
stores query parameters but does not aggregate the query result.
1.1.6.3 Entities
The class CL_CRM_BOL_ENTITY is a generic representation for business objects in the
BOL. Each instance is a unique representation for a specific business object. You can access
data using the IF_BOL_BO_PROPERTY_ACCESS interface. Entities are centrally managed
and cached.
1.1.6.4 Entity Collecti on
A collection or list of generic entities is represented by the interfaces IF_BOL_BO_COL and
IF_BOL_ENTITY_COL, and the underlying classes CL_CRM_BOL_BO_COL and
CL_CRM_BOL_ENTITY_COL (among others). An entity collection provides global
navigation, which changes the global focus. Using the local iterator does not change the
global focus. It is possible to add and remove entities that are referenced, but not owned by
the collection.
1.1.6.5 Transacti on 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 modified root object instances, or any explicitly built subsets
in between.
The BOL core aggregates the global transaction context, which includes all modified root
objects. The global transaction context logs all modifications automatically. A single object
transaction context can be accessed using the entity it belongs to.
1.1.7 Checkpoint Groups
To highlight important places for debugging and to introduce expensive consistency checks,
some checkpoint groups have been introduced. Checkpoint groups are activated with
transaction SAAB (assertions, breakpoints, and logpoints) in the development environment.
1.1.7.1 BOL Checkpoint Groups
The following BOL checkpoint groups are available:
BOL_ASSERTS
This checkpoint group includes expensive checks for inner consistency and for the
correct use of the display mode. If the checkpoint group is activated, any attempt to
1 Business Obj ect Layer
30 <July 2008>
change entities in display mode is detected. You can activate this checkpoint group
in development and test systems to get early notice of problems related to the BOL
usage.
BOL_MODIFY_WATCH
This checkpoint group defines important break points, which can be used to track the
data transport from the business object to the Generic Interaction Layer (GenIL), the
merge back of data returned into the BOL buffer, ID adjustments for new entities, and
buffer invalidation of changed entities.
BOL_COLL_AUTOCLEAN
This checkpoint group activates the auto cleanup mode for collections as default.
This may lead to memory problems, so it should only be used for testing purposes or
compatiblility purposes with framework versions SAP CRM 5.0 and older.
1.1.7.2 Rel ated Checkpoi nt Groups
For detailed investigations and debugging, it is required to break-in the GenIL, which gives
access to data persistency.
The following related checkpoint groups are available:
GENIL_DC_CHECKS
This checkpoint group activates consistency checks for the data containers.
GENIL_LOCK
This checkpoint group stops the ABAP debugger if an entity is to be locked.
GENIL_SAVE
This checkpoint group allows investigations of the save process.
GENIL_READ
This checkpoint group breaks-in the read method of the GenIL core
CL_CRM_GENERIC_IL_NEW. It allows detailed investigations of the communication
with the underlying GenIL component responsible for a specific business object.
GENIL_MODIFY
This checkpoint group breaks in the modify method of the GenIL core
1.2 Architecture Details and Context
This section presents further aspects of the business object layer (BOL) and its use by the
CRM WebClient UI framework. The Unified Modeling Language (UML) diagrams below show
the connection between the classes involved and their main attributes.
1.2.1 BOL Entities
BOL entities are managed by the BOL entity manager and use classes of the Generic
Interaction Layer (GenIL) to hold their data.
1 Business Obj ect Layer
<July 2008> 31
CL_CRM_BOL_ENTITY_MANAGER
entity_tab
CL_CRM_BOL_ENTITY
my_manager_entry
parent
CL_CRM_GENIL_CONTAINER_OBJ ECT
data_ref
1
1
1
0..n
#container_proxy
In the diagram above:
All entities are managed by the entity manager. It assures the uniqueness of entities
and buffer access.
Each entity holds a reference to its manager entry. The manager entry includes
values such as the invalid and delta flags. Holding these values in the ENTITY_TAB
of the entity manager enables efficient BOL table operations for all entities, for
example, CL_CRM_BOL_CORE->MODIFY().
An entity is a wrapper for a GenIL container object
CL_CRM_GENIL_CONTAINER_OBJ ECT belonging to a data container. This object
is referred to as CONTAINER_PROXY and holds the attributes, properties, and
relationships of the entity.
1.2.2 Collections
Various collections reference a set of BOL entities and offer convenient access to their
properties.
1 Business Obj ect Layer
32 <July 2008>
<<Interface>>
IF_BOL_BO_COL
CL_CRM_BOL_BO_COL
entity_list
CL_CRM_ENTITY_COL
entity_list
<<Interface>>
IF_BOL_BO_PROPERTY_ACCESS
CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY
1 1
0..n
0..n
In the diagram above:
A collection is represented by the IF_BOL_BO_COL interface and can either be an
entity collection CL_CRM_ENTITY_COL or the generalized business object collection
CL_CRM_BOL_BO_COL.
A business object collection can hold entities (for example, CL_CRM_BOL_ENTITY)
and query services (for example, CL_CRM_BOL_QUERY_SERVICE).
Access to properties of BOL objects is offered by the interface
IF_BOL_BO_PROPERTY_ACCESS with its standard access methods, such as
IF_BOL_BO_PROPERTY_ACCESS~GET_PROPERTY,
GET_PROPERTY_AS_STRING(), or SET_PROPERTY().
1.2.3 Context Nodes
Context nodes belong to the model part of the CRM WebClient UI framework, which supports
the model view controller pattern. The model holds business object data, therefore it is
related to the business object layer through collection wrappers (as shown in the following
diagram).
1 Business Obj ect Layer
<July 2008> 33
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()
<<Interface>>
IF_BOL_BO_COL
<<Interface>>
IF_BOL_BO_COL
1
1
1..n
-collection
-collection_wrapper
In the above diagram:
Each context node represented by an instance derived from class
CL_BSP_WD_CONTEXT_NODE has a collection wrapper. Wrappers implemented by
class CL_BSP_WD_COLLECTION_WRAPPER can be shared among different
context nodes.
The collection wrapper wraps a business object collection, IF_BOL_BO_COL, which
can be set (CL_BSP_WD_COLLECTION_WRAPPER->SET_COLLECTION) and
cleared (SET_COLLECTION) but not directly accessed.
The collection wrapper implements the business object collection interface to provide
indirect access to the wrapped collection.
The attributes of the current entity in the collection (wrapper) are displayed on the UI.
1 Business Obj ect Layer
34 <July 2008>
The IF_BOL_ENTITY_COL~FOCUS_CHANGED event of the collection is published
by the wrapper as a NEW_FOCUS event. This allows implementing dependencies
between model nodes, for example, when the user selects another order entity on the
screen and the list of order items displayed is adjusted accordingly.
A context node is calledModel Node if it holds BOL entities defined in a GenIL
component.
1.2.4 Controller Context
The model and its nodes can be accessed from the underlying controller.
CL_BSP_WD_CONTROLLER
CL_BSP_WD_CONTEXT
CL_BSP_WD_CONTEXT_NODE
1
1
1
1..n
+owner
+typed_context
+<name>
In the above diagram:
Each view, custom, or component controller owns a context that it inherits from
CL_BSP_WD_CONTEXT, which holds a set of context nodes derived from
CL_BSP_WD_CONTEXT_NODE.
You can create the context within the WD_CREATE_CONTEXT method of the
specific controller, which overrides the base class method provided by
CL_BSP_WD_CONTROLLER. In the construction of the context, all of its nodes are
created. By overriding the WD_INIT_CONTEXT method (also provided by
CL_BSP_WD_CONTROLLER) a specific controller can explicitly initialize its context
nodes.
1 Business Obj ect Layer
<July 2008> 35
Neither context nor context nodes are expected to be shared between controllers. The
underlying collections can be shared using the collection wrapper class by context
node binding.
1.2.5 Data Binding
The following graphic illustrates the relationship between the controller, the model, and the
view, which pulls business data from the models context nodes on the user interface of the
CRM WebClient UI Framework.
<VIEW>
CL_BSP_WD_CONTROLLER
m_models
CL_BSP_WD_CONTEXT_NODE
CL_BSP_WD_CONTEXT
1 1
1
1
1
1
1
1..n
1..n
0..n
+<name>
+<name>
+view
+controller
+owner
+typed_context
In the above diagram:
The view (derived from CL_BSP_PAGE) is created and owned by the controller.
Context nodes can be set as page attributes to a view (done in the controllers
implementation of the CL_BSP_WD_VIEW_CONTROLLER->SET_MODELS()
method). These page attributes are used for data binding to show model attributes on
the view or page.
The context nodes belonging to a controller are also kept in the controllers table
M_MODELS, inherited from base class CL_BSP_CONTROLLER2. This information is
used for data binding in the DO_HANDLE_DATA() method.
1.2.6 Mixed and Value Nodes of the Controller Context
A user interface view displays properties of BOL entities defined in the GenIL model. The
context node holding these entities is then called a model node.
1 Business Obj ect Layer
36 <July 2008>
Sometimes it is necessary to display further entity-related attributes that are not part of the
underlying GenIL model and that are calculated at runtime. This is possible using mixed node
elements, which contain a regular BOL entity plus a value part with application-defined
attributes. The corresponding context node is referred to as a mixed node.
A mixed node element (represented by class CL_BSP_WD_MIXED_NODE) consists
of a model part referencing a regular BOL entity and a value part holding additional
application-defined data.
CL_BSP_WD_MIXED_NODE implements the IF_BOL_BO_PROPERTY_ACCESS
interface and does not inherit from CL_BSP_WD_CONTEXT_NODE.
When creating the element you hand over the BOL entity reference and a structure
with application-defined data.
You use the IF_BOL_BO_PROPERTY_ACCESS interface to access the elements
properties. The mixed node automatically dispatches the request to either the model
or the value part.
You may also use
<IF_BSP_WD_EXT_PROPERTY_ACCESS>~GET_MODEL_NODE() to access the
underlying BOL entity.
Mixed node elements can be added to IF_BOL_BO_COL collections, which accept
objects implementing the IF_BOL_BO_PROPERTY_ACCESS interface.
It is easy to display mixed nodes on the UI, as context node binding proceeds as
normal.
To facilitate the application of mixed node elements, a specialization of the collection wrapper
CL_BSP WD_2COLLECTION_WRAPPER is available.
Assign CL_BSP_WD_2COLLECTION_WRAPPER to your mixed context node and
use its SET_VALUE_STRUCT method to declare the data structure with additional
application-defined attributes.
Add BOL entities to the nodes collection wrapper as usual. When its items are
accessed (for example, for UI display) a mixed node element with application-defined
attributes is automatically created and returned.
This technique saves memory because you only create the value part if it is needed.
The collection wrapper supports sorting by both model and value attributes.
CL_BSP WD_2COLLECTION_WRAPPER uses the built-in unifier manager, as shown in the
diagram below:
1 Business Obj ect Layer
<July 2008> 37
CL_BSP_WD_COLLECTION_WRAPPER
CL_BSP_WD_2COLLECTION_WRAPPER LCL_UNIFIER_MANAGER
(from CL_BSP_WD_2COLLECTION_WRAPPER)
<<Interface>>
IF_BOL_BO_COL
<<Interface>>
IF_BOL_BO_PROPERTY_ACCESS
<<Interface>>
IF_BOL_BO_EXT_PROPERTY_ACCESS
CL_BSP_WD_MIXED_NODE
<<Interface>>
IF_BOL_BO_PROPERTY_ACCESS
CL_BSP_WD_VALUE_NODE
CL_CRM_BOL_BO_COL
<<Interface>>
IF_BOL_BO_PROPERTY_ACCESS
1
1
1
1
1
1
1
1
1..n
0..n
#collection
-model_node -value_node
1 1
The CRM WebClient UI framework also supports value nodes, which contain value node
elements having an application-defined value part only.
A value node element is represented by class CL_BSP_WD_VALUE_NODE, which
accepts application-defined attributes in its constructor method.
You can use the IF_BOL_BO_PROPERTY_ACCESS interface to access its
attributes.
Value node elements can be added to IF_BOL_BO_COL collections.
Context node binding and the UI display work as normal.