Cookbook BOL App CRM2007

Target Audience 

System administrators administrators



Technology consultants

Document version: 1.0 – July 2008

Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20

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

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their

Some software products marketed by SAP AG and its distributors

respective logos are trademarks or registered trademarks of SAP AG

contain proprietary software components of other software vendors.

in Germany Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their

Microsoft, Windows, Outlook, and PowerPoint are registered

respective companies. Data contained in this document serves

trademarks of Microsoft Corporation.

informational purposes only. National product specifications may vary.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries,

These materials are subject to change without notice. These materials

xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, WebSphere, Netfinity,

are provided by SAP AG and its affiliated companies ("SAP Group")

Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and

for informational purposes only, without representation or warranty of

PowerPC are trademarks or registered trademarks of IBM Corporation.

any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either

products and services are those that are set forth in the express

trademarks or registered trademarks of Adobe Systems Incorporated in

warranty statements accompanying such products and services, if any.

the United States and/or other countries.

Nothing herein should be construed as constituting an additional warranty.

Oracle is a registered trademark of Oracle Corporation. SAP Library document classification: PUBLIC UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame,

Disclaimer

VideoFrame, and MultiWin are trademarks or registered trademarks of

Some components of this product are based on Java™. Any

Citrix Systems, Inc.

code change in these components may cause unpredictable and severe malfunctions and is therefore expressively expressively

HTML, XML, XHTML and W3C are trademarks or registered

prohibited, as is any decompilation of these components.

trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Any Java™ Source Code delivered with this product product is is only to be used by SAP’s Support Services and may not be

Java is a registered trademark of Sun Microsystems, Inc.

modified or altered in any way.

JavaScript is a registered trademark of Sun Microsystems, Inc., used

Documentation in the SAP Service Marketplace

under license for technology invented and implemented by Netscape.

You can find this documentation at the following address:

MaxDB is a trademark of MySQL AB, Sweden.

(hereinafter: Customer)

T e r m s f o r I n c l u d e d Op Op e n S o u r c e So So f t w a r e

a) Subject Matter of the Agreement

This SAP s oftware oftware contains also th e third party open

the STLport.org C++ library (STLport) and i ts

source software products listed below. Please note that for

documentation without fee.

these third party products the following special special terms and

B) By downloading, using, or copying STLport or

conditions shall apply.

any portion thereof Customer agrees to abide

1. This software was developed using ANTLR.

by the intellectual property laws, and to all of

2. gSOAP

the terms and conditions of this Agreement.

Part of the software embedded in this product is gSOAP

C) The Customer may distribute binaries compiled

software. Portions created by gSOAP are Copyright

with STLport (whether original or modified)

(C) 2001-2004 Robert A. van Engelen, Genivia inc. All

without any royalties or r estrictions.

Rights Reserved.

D) Customer shall maintain the following

THE SOFTWARE IN THIS PRODUCT WAS IN PART

copyright and permissions notices on STLport

PROVIDED BY GENIVIA INC AND ANY EXPRESS

sources and its documentation unchanged:

OR IMPLIED WARRANTIES, INCLUDING, BUT

Copyright 2001 SAP AG

NOT LIMITED TO, THE IMPLIED WARRANTIES

E) The Customer may distribute original or

OF MERCHANTABILITY AND FITNESS FOR A

modified STLport sources, provided that:

PARTICULAR PURPOSE ARE DISCLAIMED. IN

o The conditions indicated in the above

NO EVENT SHALL THE AUTHOR BE LIABLE

permissions notice are met;

FOR ANY DIRECT, INDIRECT, INCIDENTAL,

o The following copyright copyright notices are retained

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

when present, and conditions provided in

DAMAGES (INCLUDING, BUT NOT LIMITED TO,

accompanying permission notices are met:

PROCUREMENT OF SUBSTITUTE GOODS OR

Copyright 1994 Hewlett-Packard

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR

Company

BUSINESS INTERRUPTION) HOWEVER CAUSED

Copyright 1996,97 Silicon Graphics

AND ON ANY THEORY OF LIABILITY, WHETHER

Computer Systems Inc.

IN CONTRACT, STRICT LIABILITY, OR TORT

Copyright 1997 Moscow Center for

(INCLUDING NEGLIGENCE OR OTHERWISE)

SPARC Technology.

ARISING IN ANY WAY OUT OF THE USE OF THIS

Copyright 1999,2000 Boris Fomitchev

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY

Copyright 2001 SAP AG

OF SUCH DAMAGE.

Permission to use, copy, modify, distribute and

3. SAP License Agreement for STLport

sell this software and its documentation for

SAP License Agreement for STLPort between

any purposes is hereby granted without fee,

SAP Aktiengesellschaft

provided that the above copyright notice appear

Systems, Applications, Products Products in Data Processing

in all copies and that both that copyright notice

Neurottstrasse 16

and this permission notice appear in supporting

69190 Walldorf, Germany

documentation. Hewlett-Packard Company

(hereinafter: SAP)

makes no representations representations about the suitability

and

of this software for any purpose. It is provided

you

“as is” without express or implied warranty.

A) SAP grants Customer a non-exclusive, non-transferrable, royalty-free license to use


limited warranty and liability as set forth in the

sell this software and its documentation for any

License Agreement distributed with this copy.

purpose is hereby granted without fee, provided

SAP offers this liability and warranty obligations

that the above copyright notice appear in all

only towards its customers and only referring

copies and that both that copyright notice and

to its modifications. modifications.

this permission notice appear in supporting

b) Support and Maintenance

documentation. Silicon Graphics makes no

SAP does not provide software maintenance for the

representations representations about the suitability of this

STLport. Software maintenance of the STLport

software for any purpose. It is provided “as is”

therefore shall be not included.

without express or implied warranty.

All other services shall be charged according to the


rates for services quoted in the SAP List of Prices

sell this software and its documentation for

and Conditions and shall be subject to a separate

any purposes is hereby granted without fee,

contract.

provided that the above copyright notice appear

c) Exclusion of warranty

in all copies and that both that copyright copyright notice

As the STLport is transferred to the Customer on a

and this permission notice appear in supporting

loan basis and free of charge, SAP cannot guarantee

documentation. Moscow Center for SPARC

that the STLport is error-free, without material

makes no representations representations about the suitability

defects or suitable for a specific application under

of this software for any purpose. It is provided

third-party rights. Technical data, sales brochures,

“as is” without express or implied warranty.

advertising text and quality descriptions produced

Boris Fomitchev makes no representations

by SAP do not indicate any assurance of particular

about the suitability of this software for any

attributes.

purpose. This material is provided "as is", with

d) Limited Liability

absolutely no warranty expressed or implied.

A) Irrespective of the legal reasons, SAP shall only

Any use is at your own risk. Permission to

be liable for damage, including unauthorized

use or copy this software for any purpose is

operation, if this (i) can be compensated under

hereby granted without fee, provided the above

the Product Liability Act Act or (ii) i f caused due to

notices are retained on all copies. Permission Permission

gross negligence or intent by SAP or (iii) if based

to modify the code and to distribute modified

on the failure of a guaranteed guaranteed attribute.

code is granted, provided the above notices

B) If SAP is liable for gross negligence or intent

are retained, and a notice that the code was

caused by employees who are neither agents or

modified is included with the above copyright

managerial employees employees of SAP, the total l iability

notice.

for such damage and a maximum limit on the

Permission to use, copy, modify, distribute

scope of any such damage shall depend on

and sell this software and its d ocumentation ocumentation

the extent to which its occurrence occurrence ought to

for any purposes is hereby granted without

have anticipated by SAP when concluding the

fee, provided that the above copyright notice

contract, due to the circumstances known to

appear in all copies and that both that copyright

it at that point in time representing a typical

notice and this permission notice appear in

transfer of the software.

supporting documentation. SAP makes no

C) In the case of Art. 4.2 above, SAP shall not

representations representations about the suitability of this

be liable for indirect damage, consequential

software for any purpose. It is provided with a

damage caused by a defect or lost profit.

D) SAP and the Customer agree agree that the t ypical

F) The exclusion or the limitation of claims in

foreseeable extent of damage shall under no

accordance with the present Art. 4 includes

circumstances exceed EUR 5,000.

claims against employees or agents of SAP.

E) The Customer shall take adequate measures

4. Adobe Document Services

for the protection of data and programs, in

Adobe, the Adobe logo, Acrobat, PostScript, and Reader

particular by making backup copies at the

are either registered trademarks or t rademarks rademarks of

minimum intervals recommended by SAP. SAP

Adobe Systems Incorporated in the United States and

shall not be liable for the loss of data and its

/ or other countries. For information information on Third Party

recovery, recovery, notwithstanding notwithstanding the other limitations

software delivered with Adobe document services and

of the present Art. 4 if this loss could have been

Adobe LiveCycle Designer, see SAP Note 854621.

avoided by observing this obligation.

T y p o g r a p h i c Co Co n v e n t i o n s Type Style

Description

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.

Example text

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.

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.

Icons Icon

Meaning Caution Example Note Recommendation Syntax

Additional icons are used in SAP Library documentation to help you identify different types of information i nformation at a glance. For more information, see Help on Help  General Information Classes and Information Classes for Business Information Warehouse on Warehouse on the first page of any version of SAP Library .

Contents 1 Business Object Layer .................... ......................................... ........................................... .............................. ........8 1.1 Abstract...................................................................................................8 1.1.2 Introductio Introduction n ................................................................... ..................................................................................................... ........................................... .........8 1.1.3 Overview.......................................... Overview............................................................................ .................................................................... ...................................... ....8 1.1.4 Basic Features Features of the BOL API .................................................................. ............................................................................... .............10 10 1.1.4.1 1.1.4.1 Setting Setting up a BOL Instance Instance............................... ................................................................. .................................................... ..................10 10 1.1.5 Advanced Advanced Features Features of the BOL API ................................................................ ........................................................................ ........18 18 1.1.6 Interface Interface Class Classes.......................... es............................................................ .................................................................... ........................................ ......29 29 1.1.7 Che Checkpo ckpoint int Groups.................... Groups....................................................... ..................................................................... .......................................... ........29 29

1.2 Architecture Details and Context........................................................30 Context........................................................30 1.2.1 BOL Entities............................................................. Entities............................................................................................... .............................................. ............30 30 1.2.2 Collectio Collections ns ............................................................... ................................................................................................. .............................................. ............31 31 1.2.3 Con Context text Nod Nodes es .................................................................... ...................................................................................................... ...................................32 3 .2 1.2.4 Con Controll troller er Con Context text .................................................................... .................................................................................................. ..............................34 34 1.2.5 Data Binding Binding ................................................................. ................................................................................................... ......................................... .......35 35 1.2.6 Mixed and Value Nodes of the Controller Context...................................................35 Context................................................... 35

7

1 Business Object Layer

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 Introd Introduction uction Using the BOL and its uniform application programming interface (API) to access business data offers considerable advantages advantages compared to the t he 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 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.

8


Important objects in the BOL Programming ABAP and their corresponding interfaces and classes:

Objects 1..* Object Model

Transaction Context

1

1..*

1

1..* 1 *

BOL Core

Entity

1 * Entity Factory

Query Service

* Collection for Business Objects

Interfaces and Classes <> IF_GENIL_OBJECT_MODEL

1

<> IF_BOL_TRANSACTION_CONTEXT

0..n

1 CL_CRM_BOL_CORE

1

1 CL_CRM_BOL_ENTITY

get_instance()

0..n CL_CRM_BOL_ENTITY_FACTORY

0..n <> IF_BOL_BO_COL CL_CRM_BOL_QUERY_SERVICE get_instance()

9


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 * Start BOL Core module DATA: lv_bol_core TYPE REF TO cl_crm_bol_core. lv_bol_core = cl_crm_bol_core=>get_instance( ). lv_bol_core->start_up( ‘MY_COMPONENT_SET’ ).

The BOL core CL_CRM_BOL_ CL_CRM_BOL_CORE CORE follows the singleton singleton design pattern, 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 complete c ompleted, d, you can load all services of the BOL and the component set. The START_UP() method takes another optional parameter, IV_DISPLAY_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 IV_DISPLAY_MODE_SUPPORT is set to ABAP_TRUE , the BOL B OL follows the strict locking approach where only locked objects appear as changeable. For more information, see Display Mode Support [page Support [page 18] 18]..

1.1.4.2 Component Sets and Components of the Generic Interaction 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 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 Browser (transaction GENIL_MODEL_BROWSER). To check which components are loaded and to load additional components, you can use the following code: Syntax *

Load additional component DATA: lv_component_name type crmt_component_name. lv_component_name = 'ANOTHER_COMPONENT'. lv_bol_core->load_component( lv_component_name ).

10


*

Get components loaded DATA: lv_obj_model

type ref to if_genil_obj_model, if_genil_obj_ model,

lv_obj_model_ type ref to cl_crm_genil_obj_model, lt_components_loaded type genil_component_tab. lv_obj_model = cl_crm_genil_model_service=>get_runtime_model(

).

lv_obj_model_ ?= lv_obj_model. lt_components_loaded = lv_obj_model_>get_components_loaded >get_components_loaded( ( ).

1.1.4.3 Issue Queries 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 * Determine query services available DATA: lv_obj_model TYPE REF TO if_genil_obj_model. lv_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.

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 * Select a particular query DATA: lv_query_name TYPE crmt_ext_obj_name. READ TABLE lt_query_names INDEX 1 INTO lv_query_name.

* Create a query service DATA: lv_query TYPE REF TO cl_crm_bol_query_service.

11


lv_query = cl_crm_bol_query_service=>get_instance( lv_query_name ).

* Set a search criterion lv_query->set_property( iv_attr_name = ‘City’ iv_value

= ‘Walldorf’ ).

* Read a search criterion DATA: lv_city type string. lv_city = lv_query->get_property_as_string( ‘City’ ).

* Execute query and receive result DATA: lv_result TYPE REF TO if_bol_entity_col. lv_result = lv_query->get_query_res lv_query->get_query_result( ult( ).

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, example, SAMPLE. 2. Select the query query object and enter the parameters before you select Find . 3. Double click an object ID displayed in the List Browser to 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 t o 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 query DATA: lv_advanced_query TYPE REF TO cl_crm_bol_dquery_service. lv_advanced_query = cl_crm_bol_dquery_service=>get_instance( 'AdvOrderQuery' ).

* Set general query parameter for maximum number of hits DATA: lt_params type crmt_name_value_pair_tab,

12


ls_params type crmt_name_value_pair. ls_params-name = 'MAX_HITS' . ls_params-value = '5'. APPEND ls_params TO lt_params. lv_advanced_query->set_query_parameters( it_parameters = lt_params ).

* Add selection criteria: Ordernumber > 5 lv_advanced_query->add_selection_param( iv_attr_name = 'ORDER_NUMBER' iv_sign

= 'I'

iv_option

= 'GT'

iv_low

= '5'

iv_high

= '' ).

“Greater than

* Execute the query and receive result DATA: lv_result type ref to if_bol_entity_col. lv_result = lv_advanced_query->get_query_result( ).

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 query as template lv_advanced_query->save_query_as_template( iv_query_id = ‘My Query’ iv_overwrite = abap_true ).

* Load query from template lv_advanced_query->load_query_template( iv_query_id = ‘My Query’ ).

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 Related 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 iterator to access entities in query result DATA:lv_iterator TYPE REF TO if_bol_entity_col_iterator.

13


lv_iterator = lv_result->get_iterator. DATA: lv_entity TYPE REF TO cl_crm_bol_entity. lv_entity = lv_iterator->get_first( ). “Entity is business partner here WHILE lv_entity IS BOUND.

*

Access attributes of business objects selected 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_default_address TYPE REF TO cl_crm_bol_entity.

lv_default_address = lv_entity->get_related_entity( ‘DefaultAddress’ ).

*

Get a list of 1:N related entities DATA: lv_addresses TYPE REF TO if_bol_entity_col. lv_addresses = lv_entity->get_related_entities( ‘Addresses’ ).

* lv_entity = lv_iterator->get_next( ). ENDWHILE.

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 Transactions 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] 24]..

1.1.4.7 Creating Entities The following code shows how to create a root entity with two related entities: Syntax * 1. Build parameters to create an entity: *

14

here an order entity with technical name ‘BTOrder’


DATA: lt_params TYPE crmt_name_value_pair_tab, ls_params TYPE crmt_name_value_pair. ls_params-name = ‘PROCESS_TYPE’. ls_params-value ls_params-value = ‘TA’. APPEND ls_params TO lt_params.

* 2. Get factory for business object DATA: lv_order_factory TYPE REF TO cl_crm_bol_entity_factory. lv_order_factory = lv_bol_core->get_entity_factory( ‘BTOrder’ ).

* 3. Create root entity DATA: lv_order TYPE REF TO cl_crm_bol_entity. lv_order = lv_order_factory->create( lt_params ).

* 4. Create child objects DATA: lv_order_header TYPE REF TO cl_crm_bol_entity, lv_activity_header TYPE REF TO cl_crm_bol_entity. lv_order_header = lv_order->create_related_entity( ‘BTOrderHeader’ ). lv_activity_header = lv_order_header->create_related_entity( ‘BTHeaderActivityExt’ ‘BTHeaderActivityExt’ ).

* 5. Submit child objects created lv_bol_core->modify( ). * 6. Save and commit changes using global transaction context DATA: lv_transaction TYPE REF TO if_bol_transaction_context lv_transaction = lv_bol_core->get_transaction( ). lv_transaction->save( ). lv_transaction->commit( ).

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

15


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 entity DATA: lv_success TYPE crmt_boolean. lv_success = lv_entity->lock( ).

If the lock was was set, the return return value LV_SUCCESS LV_SUCCESS is true (ABAP_TRUE (ABAP_TRUE or IF_GENIL_BOOLEAN => TRUE ).

1.1.4.9 Modifying 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 modify a property *

here order header entity with technical name ‘BTOrderHead ‘BTOrderHeader’ er’

lv_order_header lv_order_head er ).

= lv_order->get_related_enti lv_order->get _related_entity( ty( ‘BTOrderHeader’ ‘BTOrderHeade r’

IF lv_order_header->lock( ) = if_genil_boolean=>true. lv_order_header->set_property( iv_attr_name = ‘DESCRIPTION’ iv_value

= ‘Changed

Description’ ). ENDIF.

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

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

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

The given example works with or without display mode support, since the lock is explicitly set.

1.1.4.10 Deleting Entities Similar to when you create entities, you must distinguish between the deletion of root objects and the deletion of dependent or child objects.

16


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 * Delete root entity lv_order->delete( lv_order->delete( ).

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 * Delete child object lv_order_header->delete( ). lv_bol_core->modify( ).

DATA: lv_transaction TYPE REF TO if_bol_transaction_context. lv_transaction = lv_bol_core->get_transaction( ). lv_transaction->save( lv_transaction->save( ). lv_transaction->commit( ).

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 Execution of Entity 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 * Execute entity method DATA: lv_items TYPE REF TO cl_crm_bol_entity. lv_items->execute( iv_method_name = ‘RenumberItems’ ). * ... with input parameters and a list of BOL entities returned DATA: ls_param lt_param

TYPE crmt_name_value_pair, crmt_name_va lue_pair, TYPE crmt_name_value_pair_tab, crmt_name_va lue_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. TRY.

17


lv_result = lv_order_header->execute( iv_method_name = ‘createFollowUp’ it_param

= lt_param ).

* Error handling CATCH CX_CRM_BOL_METH_EXEC_FAILED. *

An exception is received if method has indicated an error

*

and has not returned more than one entity. ... ENDTRY.

1.1.5 Advanced Features of the BOL API The following sections describe special features of the BOL API.

1.1.5.1 Display 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 IV_DISPLAY_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 * Start BOL core with display mode support DATA: lv_bol_core TYPE REF TO cl_crm_bol_core. lv_bol_core = cl_crm_bol_core=>get_instance( ). lv_bol_core->start_up( iv_appl_name = ‘MY_COMPONENT_SET’ iv_display_mode_support = ABAP_TRUE ).

* Execute query and access entity DATA: lv_entity type ref to cl_crm_bol_entity. lv_entity = ... mode

-“Entity is in now display

* Switch to change mode and change entity lv_entity->switch_to_chang lv_entity->sw itch_to_change_mode( e_mode( ).

“Reread and lock entity

IF lv_entity->is_changeable( lv_entity->is_changeable( ) = abap_true. lv_entity->set_property_as_string( iv_attr_name = ‘PROPERTY_NAME’

18


iv_value

= ‘New Value’ ).

ENDIF.

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 Objects To access the properties of BOL entities and query services, you must use their IF_BOL_BO_PROPERTY_ACCESS interface methods.

<> IF_BOL_BO_PROPERTY_ACCESS

CL_C CL _CRM RM_B _BOL OL_Q _QUE UERY RY_S _SE ERVIC RVICE E

CL_C CL _CRM RM_B _BOL OL_E _ENT NTIT ITY Y

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 search criterion of BOL query DATA: lv_query TYPE REF TO cl_crm_bol_query_service, lv_city_type string. lv_query = cl_crm_bol_query_service=>get_instance( ‘QUERY_NAME’ ). lv_city = lv_query->if_bol_bo_property_access~get_property_as_string( ‘City’ ). “Short form using alias lv_city = lv_query->get_property_as_string( ‘City’ ).

* Set property of BOL entity DATA: lv_entity TYPE REF TO cl_crm_bol_entity lv_entity->if_bol_bo_property_access~set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ). “Short form using alias lv_entity->set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ).

19


* Cast to property_access interface DATA: lv_business_object TYPE REF TO if_bol_bo_property_access. lv_business_object ?= lv_entity.

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: lv_person TYPE REF TO cl_crm_bol_entity, lv_sex type bu_sexid. “Defines values 1 = Female, 2 = Male ... lv_sex = lv_person->get_property( ‘SEX’ ). “Key code

* Get property text for key code: *

-> ‘Male’ or ‘Female’ translated in current language DATA: lv_sex_text type string. lv_sex_text = lv_person->get_property_text( ‘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 Business Objects and BOL Entities The BOL API offers two collections for application 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

CL_CRM_BOL_BO_COL

IF_BOL_ENTITY_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 welldefined focus object. Initially, the first object has the f ocus. ocus. Any global iteration moves the focus, which is published by the event FOCUS_CHANGED of the collection.

20


If you want to iterate on the collection without moving the focus (and without triggering timeconsuming follow-up processes) you can use local iteration. To do so, request an iterator object from the collection and use this to iterate. Syntax * Create collection DATA: lv_collection TYPE REF TO cl_crm_bol_bo_collection, lv_property_access TYPE REF TO if_bol_bo_property_access, lv_query TYPE REF TO cl_crm_bol_query_service. CREATE OBJECT lv_collection. ... * Add item and make it current lv_collection->if_bol_bo_c lv_collection ->if_bol_bo_col~insert( ol~insert( iv_bo Iv_index

= lv_query = 1

Iv_set_focus = ABAP_BOOL ). * Global iteration lv_property_access = lv_collection->get_next( ). “Global iteration “

moves focus

* Local iteration DATA: lv_iterator TYPE REF TO if_bol_bo_col_iterator. lv_iterator = lv_collection->get_iterator( ). lv_property_access = lv_iterator->get_first( ) WHILE lv_query_is_bound. lv_property_access = lv_collection->get_next(). “Local iteration does not ENDWHILE.

“

move focus

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 object is found, f ound, 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 * Find by property DATA: lv_persons lv_male

TYPE REF TO cl_crm_bol_entity_collecti cl_crm_bol_en tity_collection, on,

TYPE REF TO cl_crm_bol_entity, cl_crm_bol_en tity,

lv_iterator TYPE REF TO if_bol_bo_col_iterator.

21


lv_iterator lv_iterator = lv_persons->get_iterat lv_persons->get_iterator( or( ). lv_male = lv_iterator->find_by_property( iv_attr_name = ‘SEX’ iv_value

= 2

).

* Set collection focus on the entity found lv_persons->find( iv_bo = lv_male ).

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 IV_ATTR_NAME specifies the property that the collection is sorted for. If you do not specify IV_SORT_ORDER, the sort order defaults as ascending. Syntax * Sorting DATA: lv_persons lv_male

TYPE REF TO cl_crm_bol_entity_collecti cl_crm_bol_en tity_collection, on, TYPE REF TO cl_crm_bol_entity, cl_crm_bol_en tity,

lv_iterator TYPE REF TO if_bol_bo_col_iterator. lv_persons->sort( lv_persons->sort( iv_attr_name = ‘SEX’ iv_sort_order = IF_BOL_BO_COL=>SORT_DESCENDING ).

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_ IS_A_GREATER_B B is called whenever whenever two values are are compared. compared. To modify the sort 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 th the se selected el element

IF_BOL_BO_COL~GET_CURRENT_INDEX

Returns the index of the selected element

IF_BOL_BO_COL~PUBLISH_CURRENT

Publishes the selected element using the event

IF_BOL_BO_COL~FOCUS_CHANGED

22


The selected element is implicitly set with the following methods: Method

Result

IF_BOL_BO_COL~GET_NEXT

Moves focus to the next element 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 las last s se elected eleme men nt

IF_BOL_BO_COL~GET_CURRENT_INDEX

Returns the index of the last selected element

IF_ IF_BOL_ OL_BO_C O_COL~PU PUB BLISH ISH_CURREN ENT T

Does nothin thing g

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 i s inactive. To activate this function, f unction, 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 Survival 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.

23


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_R IF_BOL_BO_COL~SET_RESET_SURVI ESET_SURVIVAL_MODE VAL_MODE to indicate that 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 Fine Granular Transaction Handling 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. 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 ). 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( ).

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 Readiness and Entity Property Modifiers

24


To check if an entity property is read only, you can use method IF_BOL_BO_PROPERTY_ACC IF_BOL_BO_PROPERTY_ACCESS~IS_PR ESS~IS_PROPERTY_ OPERTY_READONL READONLY. Y. 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 Excluding Entities from the Central Modify New, changed, or deleted dependent objects are sent to the underlying APIs with one central call of the BOL core’s 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 Business Error Handling 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.

25


Message Handling Model

CL_CRM_COL_CORE 1 1 CL_CRM_GENIL_MESS_CONT_MANAGER 1 * IF_GENIL_MESSAGE_CONTAINER

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

* 1) Use the message container manager DATA: lv_mcm TYPE REF TO cl_crm_genil_mess_cont_manager. lv_mcm = lv_bol_core->get_messa lv_bol_core->get_message_cont_man ge_cont_manager( ager( ).

* 2) ... to obtain the message container DATA: lv_object_name TYPE crmt_ext_obj_name, Lv_object_id

TYPE crmt_gnil_object_id. crmt_gnil_obj ect_id.

lv_object_name = lv_order->get_name( ). lv_object_id

= lv_order->get_key( 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 lv_object_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.

26


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: lv_number_of_errors TYPE int4, lt_error_messages TYPE crmt_genil_message_tab. lv_number_of_errors = lv_mc->get_number_of_messages( lv_mc->mt_error ). IF lv_number_of_errors <> 0. lt_error_messages = lv_mc->get_messages( lv_mc->mt_error ). ENDIF.

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 GET_RELATED_ENTITY _ENTITY() () and GET_RELATED_E GET_RELATED_ENTITIES() NTITIES() take take an optional optional parameter IV_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

27


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 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 Synchron Synchronization ization 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 read-only mode and the property modifiers must be refreshed.

Therefore the CL_CRM_BOL_ENTITY->LOCK method takes an optional parameter IV_REREAD. The default setting is ABAP_FALSE. If it is set to ABAP_TRUE, 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].

28


1.1.6 Interface Classes 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 the IF_BOL_BO_PROP IF_BOL_BO_PROPERTY_ACC ERTY_ACCESS ESS interface. Entities Entities are centrally centrally managed managed and cached.

1.1.6.4 Entity Collection 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 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 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

29


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

30


CL_CRM_BOL_ENTITY_MANAGER entity_tab

1

0..n CL_CRM_BOL_ENTITY my_manager_entry parent 1

1

#container_proxy

CL_CRM_GENIL_CONTAINER_OBJECT data_ref

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

31


<> IF_BOL_BO_COL

CL_CRM_BOL_BO_COL entity_list

CL_CRM_ENTITY_COL entity_list

1

1

0..n <> IF_BOL_BO_PROPERTY_ACCESS

0..n CL_CRM_BOL_QUERY_SERVICE

CL_CRM_BOL_ENTITY

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

32


CL_BSP_WD_CONTEXT_NODE get_collection_wrapper() set_collection_wrapper() set_collection() clear_collection() 1..n

-collection_wrapper

1

CL_BSP_WD_COLLECTION_WRAPPER set_collection() clear_collection() <>new_focus() 1

-collection <> IF_BOL_BO_COL

<> IF_BOL_BO_COL

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.

33






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 called Model Node if Node if it holds BOL entities defined 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

+owner

1

+typed_context

1

CL_BSP_WD_CONTEXT

1

+

1..n

CL_BSP_WD_CONTEXT_NODE




34

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.




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 model’s context nodes on the user interface of the CRM WebClient UI Framework.

+view

1

1

+controller

1

+

CL_BSP_WD_CONTROLLER m_models

CL_BSP_WD_CONTEXT_NODE 1

0..n 1..n

+owner

1..n

+

1

1

CL_BSP_WD_CONTEXT

1

+typed_context


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 controller’s 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 controller’s 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.

35


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 element’s properties. The mixed node automatically dispatches the request to either the model or the value part. You may also use ~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 node’s 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:

36


CL_BSP_WD_COLLECTION_WRAPPER

LCL_UNIFIER_MANAGER

CL_BSP_WD_2COLLECTION_WRAPPER 1

1

(from CL_BSP_WD_2COLLECTION_WRAPPER)

1

1

#collection 1

0..n

<> IF_BOL_BO_COL


<> IF_BOL_BO_EXT_PROPERTY_ACCESS CL_CRM_BOL_BO_COL CL_BSP_WD_MIXED_NODE

1

1 1

1..n

-model_node


-value_node

1

<> IF_BOL_BO_PROPERTY_ACCESS 1

CL_BSP_WD_VALUE_NODE

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.

37

Cookbook BOL App CRM2007

Recommend Documents