Crm 7.0 Bol Guide

Business Object Layer (BOL)Application Programming Guide

WEBCUIF 7.0

Uwe Reimitz, Martin Wegmann

© SAP AG

Business Object Layer (BOL) Programming Guide Page 2

Table of Contents

1 ABSTRACT ............................................................................................................... 4

2 INTRODUCTION ...................................................................................................... 4

3 BOL VERSIONS........................................................................................................ 4

4 OVERVIEW .............................................................................................................. 4

5 BASIC FEATURES OF THE BOL APPLICATION PROGRAMMING INTERFACE 5

5.1 Setting up a BOL Instance .....................................................................................................................................5

5.2 Component Sets and Components of the Generic Interaction Layer .............................................................6

5.3 Issue Queries.............................................................................................................................................................85.3.1 Simple Queries ..................................................................................................................................................85.3.2 Dynamic Queries ............................................................................................................................................ 11

5.4 Read Access to Business Objects using Entities............................................................................................... 135.4.1 Access Attributes............................................................................................................................................ 135.4.2 Access to related Entities ............................................................................................................................... 135.4.3 Further operations on entities ........................................................................................................................ 14

5.5 Changing Business Objects using Entities ........................................................................................................ 145.5.1 Transaction contexts....................................................................................................................................... 145.5.2 Locking Entities.............................................................................................................................................. 155.5.3 Modifying Entity Attributes........................................................................................................................... 155.5.4 Creating Entities ............................................................................................................................................. 165.5.5 Deleting Entities ............................................................................................................................................. 175.5.6 Execution of Entity Methods ......................................................................................................................... 17

6 ADVANCED FEATURES OF THE BOL APPLICATION PROGRAMMINGINTERFACE ................................................................................................................. 19

6.1 Display mode support .......................................................................................................................................... 19

6.2 Standard Interface to Access Properties of Business Objects ....................................................................... 20

6.3 Working with Collections .................................................................................................................................... 216.3.1 Local and Global Iterations............................................................................................................................ 226.3.2 Searching......................................................................................................................................................... 236.3.3 Sorting............................................................................................................................................................. 236.3.4 Filtering ........................................................................................................................................................... 246.3.5 Changing the collection content .................................................................................................................... 256.3.6 Single and Multi Select Support.................................................................................................................... 256.3.7 Auto Cleanup Mode ....................................................................................................................................... 276.3.8 BOL Reset Survival Mode............................................................................................................................. 276.3.9 Specialized collections ................................................................................................................................... 28

6.3.9.1 Unique Type collections ............................................................................................................................ 286.3.9.2 Unique instance collections ....................................................................................................................... 28


6.4 Transaction Handling .......................................................................................................................................... 296.4.1 Transaction context kinds .............................................................................................................................. 296.4.2 Transaction cycle............................................................................................................................................ 296.4.3 Collective transactions and Change tracking................................................................................................ 306.4.4 Tracking transaction state .............................................................................................................................. 31

6.5 Advanced Entity features .................................................................................................................................... 316.5.1 Input Readiness and Entity Property Modifiers ........................................................................................... 316.5.2 Excluding Entities from the Central Modify ................................................................................................ 31

6.6 Business Error Handling ..................................................................................................................................... 32

6.7 Mass operations using the BOL core................................................................................................................. 33

6.8 Buffering Issues..................................................................................................................................................... 336.8.1 Entity Properties ............................................................................................................................................. 346.8.2 Entity Relations .............................................................................................................................................. 346.8.3 Preloading BOL Views .................................................................................................................................. 346.8.4 Locking with Synchronization....................................................................................................................... 366.8.5 Buffering of Query results ............................................................................................................................. 36

6.9 BOL Reset.............................................................................................................................................................. 36

7 INTERFACE CLASSES........................................................................................... 37

7.1 Core......................................................................................................................................................................... 37

7.2 Query Services....................................................................................................................................................... 37

7.3 Entity ...................................................................................................................................................................... 37

7.4 Collection................................................................................................................................................................ 37

7.5 Transaction Context............................................................................................................................................. 37

8 CHECKPOINT GROUPS ........................................................................................ 38

8.1 BOL checkpoint groups....................................................................................................................................... 38

8.2 Related checkpoint groups.................................................................................................................................. 38

9 INNER DETAILS AND DEBUGGING..................................................................... 39

9.1 BOL Entities .......................................................................................................................................................... 39

9.2 Collections.............................................................................................................................................................. 40


1 AbstractThis document describes the runtime programming interface of the Business Object Layer (abbreviated asBOL). After you have read this document, you as a developer are able to create access and modifybusiness data – like CRM Business Partner, CRM Product, HR data etc. - provided by the business objectlayer. The BOL may be used within all ABAP based applications – e.g. simple reports, dynpro- andbusiness server page (BSP) applications.

2 IntroductionThe usage of the busines object layer and its uniform application programming interface (API) to accessbusiness data offers considerable advantages compared to the usage of various native APIs historicallyavailable for business objects:

The object oriented BOL API is simple, uniform and easy to use The built-in buffer accelerates your applications Your programms are decoupled from any interface changes in the underlying business object

specific APIs Development of WEBCUIF applications is made easy, since the BOL has been designed to work

hand in hand with the UI parts of the frameworkIt is possible to enhance the business object layer to cover business data not yet supported: After thecorresponding business objects and query services have been modeled and implemented, you can usethem at runtime.

3 BOL VersionsThe following list shows the various versions of the Business Object Layer:

CRM 3.1 First version – never in productive useCRM 4.0 First version use in a productive systemCRMIS 4.0 Several improvements – introduction of separate display modeSAP_ABA 7.0 Relocation from CRM to ABA layer, first usage outside CRMCRMUIF 5.1 Introducion of dynamic searches; whole CRM with BOL supportCRMUIF 5.2 Stabization and performance improvementsCRMUIF 6.0 Major internal changes for better performance on high number of objectsWEBCUIF 7.0 Current version; Full Switch Framework support; Stable Core release

4 OverviewThe business object layer API consists of various interfaces and classes, you use to access businessdata. Most important are class CL_CRM_BOL_QUERY_SERVICE you use to select business objects, classCL_CRM_BOL_ENTITY representing entities as business object segments, the interfaceIF_BOL_TRANSACTION_CONTEXT to control transactional behavior, and IF_BOL_BO_COL providingaccess to collections holding entities.

The lifetime of these objects in general is the whole session. The BOL API, however, provides a possibilityto free used business objects and their memory.


Figure 1: Important objects, classes and interfaces of the BOL Programming API

Entities and related transactional contexts are centrally managed. This influeces their lifetime but ensuresalso instance uniqueness. Therefore it is sufficient to compare object instances for equality instead ofobject type and key.

5 Basic Features of the BOL Application ProgrammingInterface

When you use the business object layer to work with business objects in an ABAP application youtypically use code sequences similar to those indicated in the following chapters.

5.1 Setting up a BOL InstanceYou create an instance of the business object layer by calling the static factory method of its core class:

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

Figure 2: It needs a few lines to start the BOL with an initial component set

Since the BOL core CL_CRM_BOL_CORE follows the singleton design pattern you can just have oneinstance of it. The START_UP method takes the name of the GenIL component set you want to start asinput parameter and starts the BOL. From now on you can use all services of the BOL and the componentset loaded.


The START_UP method takes another optional parameter IV_DISPLAY_MODE_SUPPORT, which is set toABAP_FALSE by default. This means the BOL follows the optimistic locking approach, which makes allobjects appear changeable in the user interface even without a lock (entity method IS_CHANGEABLEalways return ABAP_TRUE). The lock is automatically requested on the first attempt to really make achange. The lock state of an entity could be check via method IS_LOCKED.

If the parameter IV_DISPLAY_MODE_SUPPORT is set to ABAP_TRUE the BOL follows the strict lockingapproach where only locked objects appear as changeable: See chapter 6.1 for further details.

5.2 Component Sets and Components of the Generic InteractionLayer

Each component set1 available is defined in view cluster CRMVC_GIL_APPDEF located in the SAPImplementation Guide and defines a set of so called GenIL2 components, each providing specific businessobjects like CRM Business Partner with dependent objects and related queries, CRM Product, CRMOrder, etc.

Figure 3: You’ll find BOL and GenIL Customizing in the SAP Implementation Guide

1 The expression ‘component set’ has replaced the former expression ’application’2 GenIL = Generic Interaction Layer


Figure 4: The GenIL component set SAMPLE consists of the GenIL components ‘BP’ and ‘SAMPLE’

Components of the Generic Interaction Layer (GenIL) are implemented ABAP classes. In order to find outwhich business objects and attributes, which relations, dependant objects, queries and further servicesare provided by a component or component set, you may use the so called Model Browser (transactionGENIL_MODEL_BROWSER).

Figure 5: The Model Browser (transaction GENIL_MODEL_BROWSER) shows the technical names of business objects:“BuilHeader” in the screenshot above indicates a CRM Business Partner object as provided by the component set“SAMPLE” here; “BuilAddress” and “BuilActivity” stand for its address and related activities


The following code snippet shows how to load additional components or component sets and how tocheck the components loaded so far:

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

* Load additional component set DATA: lv_component_set_name type crmt_genil_appl. lv_component_set_name = 'ANOTHER_COMPONENT_SET'. lv_bol_core->load_component_set( lv_component_set_name ).

* Get components loadedDATA: lv_obj_model TYPE REF TO 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( ).

Figure 6: It is easy to check which GenIL components are available at runtime. It is possible to load additional components

Note: Via this technique it is also possible to work fully without predefined component sets. Just start theBOL core with predefined component set EMPTY, which does not include any component. After this youmay load component by component via LOAD_COMPONENT method.

5.3 Issue QueriesBefore you can work with business objects or “entities” you have to find them. That’s why you usually startyour application with a search. You use a query service object to receive a collection of entities that matchthe search criteria given.

5.3.1 Simple Queries

In order to fire a query you need to instanciate the query service you want to use and provide it with thesearch criteria:

* Create a query service DATA: lv_query TYPE REF TO cl_crm_bol_query_service. lv_query = cl_crm_bol_query_service=>get_instance( ‘UIFSearchConnection’ ).

* Set a search criterion lv_query->set_property( iv_attr_name = ‘CARRID’ iv_value = ‘AA’ ).

* Read a search criterion DATA: lv_carrid TYPE string. lv_carrid = lv_query->get_property_as_string( ‘CARRID’ ).

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

Figure 7: Use the query service to fire a query

The last coding example shows how to do this: First get an instance of the generic query serviceCL_CRM_BOL_QUERY_SERVICE via the factory method GET_INSTANCE. Use its SET_PROPERTY


method to indicate the search criteria and its GET_QUERY_RESULT method to fire your query and toretrieve a result list of entities (represented by IF_BOL_ENTITY_COL).As you can also see from the example it is also possible to retrieve search criteria from the query service.

In a generic application, such as the BOL browser, you may use the BOL Object Model Service todetermine available query services of the component set and components loaded.

* Determine available query services DATA: lv_obj_model TYPE REF TO if_genil_obj_model, lt_query_names TYPE crmt_ext_obj_name_tab.

lv_obj_model = cl_crm_genil_model_service=>get_runtime_model( ). lv_obj_model->get_object_list( EXPORTING iv_object_kind = if_genil_obj_model=>query_object IMPORTING ev_object_list = lt_query_names ).

Figure 8: You may access the object model of the GenIL components loaded at runtime

You may try out a query and many other methods of the BOL API described below with the so called BOLBrowser (transaction GENIL_BOL_BROWSER) interactively.Start the BOL Browser with the component or component set providing the objects you are interested in,e.g. component set SAMPLE containing sample orders, the OrderQuery, etc. …

Figure 9: You have to specify an initial component set to be loaded when you start the BOL browser

Select the query and enter search criteria, before you launch the query:

Figure 10: Use the BOL browser to test your queries

Double click on an object ID displayed in the List Browser to see the particular object with its attributes:

Figure 11: The BOL browser is able to display entity properties


5.3.2 Dynamic Queries

With release CRMUIF 5.1 the BOL supports also so called Dynamic Queries, with enhanced features: Besides the “Equal” operator you may use arbitrary operators like “Greater than”, Less than”,

“Contains”, “Not Contains”, etc. to specify the search criteria Search multiple values for one search criterion at the same time (logical OR) Save and retrieve predefined Searches with preset search criteria as templates identified with an

arbitrary name

* Get advanced query DATA: lv_dyn_query TYPE REF TO cl_crm_bol_dquery_service. lv_dyn_query = cl_crm_bol_dquery_service=>get_instance( 'UIFAdvSearchFlight' ).

* Set general query parameter for maximum number of hits lv_dyn_query->set_property( iv_attr_name = 'MAX_HITS' iv_value = '5' ).

* Add selection criteria: Maximum Seats > 5 lv_dyn_query->add_selection_param( iv_attr_name = 'SEATSMAX' iv_sign = 'I' iv_option = 'GT' “Greater than iv_low = '100' iv_high = '' ).

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

Figure 12: An advanced query offers enhanced search capabilities

Because of the dynamic nature the selection parameters of a dynamic query are organized in a collection.You can access them via method GET_SELECTION_PARAMS, which returns directly the collection thedynamic query service it self operates on. You can iterate on this collection in order to check or change allselection parameters.Beside adding of selection parameters it is also possible to insert them. In a normal program this makesnot really sense. However you high directly display the parameter collection in a UI where you normallywant to group the criteria by the parameter name.

Dynamic queries allow also easy saving and restoring of queries as/from templates:

* Save query as templatelv_dyn_query->save_query_as_template( iv_query_id = ‘My Query’

iv_overwrite = abap_true ). ...* Load query from templatelv_dyn_query->load_query_template( iv_query_id = ‘My Query’ ).

...

Figure 13: Query templates are used to store and retrieve saved searches with predefined criteria


In order to display advanced queries in the Web UI special easy-to-use tags have been developed.

Figure 14: Example for an advanced query display in the CRM Web UI


5.4 Read Access to Business Objects using EntitiesAfter you get a list of entities from a query service, you can use them in your application: Display itsattributes on the user interface, modify, delete, etc.

5.4.1 Access Attributes

The following coding example shows how to access entities of the query result and how to read theirattributes. Note that the methods are the same for all kinds of business objects.

* Use iterator to access entities in query result

DATA:lv_iterator TYPE REF TO if_bol_entity_col_iterator. lv_iterator = lv_result->get_iterator( ).

DATA: lv_entity TYPE REF TO cl_crm_bol_entity. lv_entity = lv_iterator->get_first( ). “Entity is UIFFlight here

WHILE lv_entity IS BOUND.

* Access attributes of business objects selected DATA: lv_carrid TYPE ref to S_CARR_ID, lv_connid TYPE S_CONN_ID, lv_flightdate TYPE string. lv_carrid ?= lv_entity->get_property( ‘CARRID’ ). lv_entity->get_property_as_value( EXPORTING iv_attr_name = ‘CONNID’ IMPORTING ev_result = lv_connid ). lv_flightdate = lv_entity->get_property_as_string( ‘FLDATE’ ).

* Get all attributes of an entity DATA: ls_attributes TYPE CRMS_BOL_UIF_TRAVEL_FLIGHT_ATT. lv_entity->get_properties( IMPORTING es_attributes = ls_attributes ).

* lv_entity = lv_iterator->get_next( ).

ENDWHILE.

Figure 15: Access BOL entities contained in a BOL collection and access attributes.

You can access attributes in three different formats. Method GET_PROPERTY returns a pointer to theactual value were as method GET_PROPERTY_AS_VALUE provides the actual value as exportingparameter. Method GET_PROPERTY_AS_STRING returns the value converted into and string.Note: This conversion considers some display formatting rules but not all. So this resulting string is notintended for direct use in a business application UI!

The attribute access is covered by generic interface IF_BOL_BO_PROPERTY_ACCESS. This interface isprovided not only from entities but also from query services to allow a uniform attribute access, see alsosection 6.2.

5.4.2 Access to related Entities

The following coding example shows how to navigate from one entity to another. This navigation followsthe relations given in the object model.


* Get a list of 1:N related entities DATA: lv_bookings TYPE REF TO if_bol_entity_col. lv_bookings = lv_flight->get_related_entities( iv_relation_name = ‘FlightBookRel’ ). DATA: lv_booking TYPE REF TO cl_crm_bol_entity. lv_booking = lv_bookings->get_first( ).

* Get a 1:1 related entity DATA: lv_customer TYPE REF TO cl_crm_bol_entity. lv_customer = lv_booking->get_related_entity( ‘BookCustomerRel’ ).* Get back to the parent lv_entity = lv_booking->get_parent( ).

In general we distinguish between 1:N and 1:1 relations. Method GET_RELATED_ENTITIES works forboth relations and returns always a collection. For convenience method GET_RELATED_ENTITY returnsdirectly the related entity for 1:1 relations.In order to get back generic method GET_PARENT is provided. This method returns the parent object.Note: Since the parent needs not necessarily unique it would return the last used. Also the parent couldonly be returned for non-root objects. So if you follow an association to another root entity you cannotreturn via GET_PARENT!

Furthermore it is possible to get to the root oentity of a business object via method GET_ROOT.

5.4.3 Further operations on entities

Beside the access to attributes and the navigation an entity provides further functionalities: You can check the changeability with methods IS_CHANGEABLE and IS_LOCKED, see also

section 6.1. You may check if an entity instance is still valid, which means that it represents existing data, via

method ALIVE. You can directly access model data, like the entity name with GET_NAME or the type of the

attribute structure with GET_ATTR_STRUCT_NAME. You can check the properties of an attribute if it is changeable, hidden, mandatory … with method

GET_PROPERTY_MODIFIER, see section 6.5 for further details.

Further functions are described in the following sections.

5.5 Changing Business Objects using Entities

5.5.1 Transaction contextsOne of the most important aspects of BOL programming is to know how to modify data. You can create,modify, and delete entities in accordance to the BOL transaction model, which supports several kinds ofso called transactional contexts to handle entity operations consistently.

The global transaction context holds all modified root entities, whereas the single business object scopetransaction context exists for each root entity instance. The custom transaction context can be used tohandle special situations, where more than one but not all modified objects belong to a transaction. In thissection we only use the global context. For a discussion on the possible scopes of transaction contextsrefer to section 6.4.

The global transaction context exists always and is accessable via the BOL core instance. A single BOtransaction context (fine granular context) is created either on request, via method GET_TRANSACTION onan entity, or latest when the object gets locked.Each single BO transaction context has to be finished once it was created. This happens either by callingmethods SAVE and COMMIT or method REVERT on the context or via a higher order transaction context


(global or customer). Further the methods CHECK_SAVE_NEEDED and CHECK_SAVE_POSSIBLE allow tocheck before save if it is required and possible. Once the transaction was saved it has to be finished viaCOMMIT or ROLLBACK. There is no way back after a failed save! So always check before hand!

The end of a transactional context removes in general also the pending locks from the covert objects. Ifonly an intermediate save is required the COMMIT method allows keeping the locks via optional parameterIV_KEEP_LOCKS set to ABAP_TRUE.

The REVERT method always removes the lock. All changes, covered by the transaction will be rejectedand the object returns to the last saved state from the database. Normally this synchronization happensdirectly in the REVERT method. However, for performance reasons it might be better to do thissynchronization in a lazy mode. To do so the optional input parameter IV_SUPPRESS_BUFFER_SYNCneeds to be set to ABAP_TRUE.

For further details see also section 6.4.

5.5.2 Locking EntitiesIn the default optimistic lock mode, see 5.1, you should lock an entity before you are going to modify it.However, the set-methods of the entity check that the entity is locked and, if not, try to do this. The setteronly modifies properties in case the entity is locked. With display mode support switched on locking ismandatory.

The current locking granularity of the BOL are the root object instances. So the lock request for an entity isalways delegated to the corresponding root instance.

The following code fragment shows how to lock an entity.

* Lock BOL entity DATA: lv_success TYPE abap_bool. lv_success = lv_entity->lock( ).

Figure 16: Lock an entity

In case the lock was set the return value LV_SUCCESS is true ( ABAP_TRUE ). The current lock state of anentity could be checked via method IS_LOCKED. Latest with setting a lock successfully a transactioncontext is created for the corresponding root entity instance. The only way to unlock the entity now is tofinish this transaction context.

5.5.3 Modifying Entity Attributes

Now we want to modify properties of entities. This is simply done by using the set-methods of the entity. Ifyou have not started a transaction before modifying properties it will be created automatically.The following code fragment shows how to modify a property of a booking.

* 1. Lock an entity and modify a property* here booking entity with technical name ‘UIFBokking’

lv_booking = lv_flight->get_related_entity( ‘FlightBookingRel’ ). IF lv_booking->lock( ) = ABAP_TRUE. lv_booking->set_property( iv_attr_name = ‘SMOKER’ iv_value = ‘X’ ). ENDIF.

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


* 3. get the implicitly created global transaction DATA: lv_transaction TYPE REF TO if_bol_transaction_context. lv_transaction = lv_bol_core->get_transaction( ).

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

Figure 17: Modify properties of a related entity

In step 1 we modify properties of an entity and in step 2 we communicate all modifications done so far tothe Application Programming Interface (API) layer. In step 3 we get access to the automatically createdglobal transaction context. Finally we save and commit the changes in step 4.The given example works with or without display mode support, since the lock is explicitely set.Note: Independent of the lock state you can only modify changeable attributes. The actual changeabilityof an attribute could be checked with method IS_PROPERTY_READONLY.

5.5.4 Creating Entities

The following code example shows how to create a root entity together with two related entities.

* 1. Build parameters to create an entity:* here a flight entity with technical name ‘UIFFlight’ DATA: lt_params TYPE crmt_name_value_pair_tab, ls_params TYPE crmt_name_value_pair. ls_params-name = ‘CARRID’. ls_params-value = ‘AC’. APPEND ls_params TO lt_params.

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

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

* 4. Create child objects DATA: lv_booking TYPE REF TO cl_crm_bol_entity, lv_ticket TYPE REF TO cl_crm_bol_entity. lv_booking = lv_flight->create_related_entity( ‘FlightBookRel’ ). lv_booking->set_property( iv_attr_name = ‘CARRID’ iv_attr_value = ‘AC’ ). lv_ticket = lv_booking->create_related_entity( ‘BookTicketRel’ ). lv_ticket->set_property( iv_attr_name = ‘CARRID’ iv_attr_value = ‘AC’ ).

* 5. Submit child objects created lv_bol_core->modify( ).

* 6. Save and commit changes using single object transaction context DATA: lv_transaction TYPE REF TO if_bol_transaction_context lv_transaction = lv_flight->get_transaction( ). lv_transaction->save( ). lv_transaction->commit( ).

Figure 18: Create root and related entities


It is important to distinguish between the creation of root objects via the entity factory and the creation ofdependent or child objects with method CREATE_RELATED_ENTITY. The first one triggers directly a callof the underlying API, the second one in general not (depending on the model). So in the second case it isnecessary to trigger the API call explicitly via calling the MODIFY method of the BOL core, which sends thechanges to the underlying generic interaction layer. Without this call the created child objects will onlyexist in the BOL buffer and never get saved. This technique is used to collect fine granular changes and tobundle them before sending to the API to process and evaluate them together. For options to control whatis send by the MODIFY method see section 6.5.2.Note: For performance reasons a newly created entity has always sending deactivated, since in general itdoes not make sense to send empty objects. So in order to send it with MODIFY you need either to set atleast one attribute or activate the sending explicitely.

Even after sending an newly created entity to the API it is not yet persistent. This is only after finishing thetransaction the case. The persistence state of an entity could be checked via method IS_PERSISTENT.

5.5.5 Deleting Entities

Similar to entity creation we have to distinguish between the deletion of root objects and the deletion ofdependant or child objects.For root object instances the call of the DELETE method is directly sent to the API where the completeaggregation hierarchy is deleted. The deletion is written to the database with an internal COMMIT WORK.

* Delete root entity lv_flight->delete( ).

Figure 19: Delete root entity

In case of a child object the deletion is not automatically sent to the API. You have to trigger this explicitlyby calling the MODIFY method of the BOL core.

* Delete child object lv_booking->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->commit( ).

Figure 20: Delete related entity

As you can see from the example in this case you also have to save and commit the transaction in orderto persist the deletion.Immediately after the method CL_CRM_BOL_CORE->MODIFY has been executed and the underlying APIconfirmed the deletion the entity is deleted from the BOL buffer. This is published from the entity instanceby raising event DELETED. After the deletion any further access to the entity instance might lead to anexception CX_BOL_EXCEPTION.

5.5.6 Execution of Entity Methods

In order to perform special business functionality it is possible to call special methods on an entity, whichhave been modeled and implemented for a particular object type. Entities can have two kinds of methods.Both can have an arbitrary set of import parameters. Method EXECUTE may return an entity collection ofresult objects. With the CRMUIF 6.0 release method type EXECUTE2 was introduced. It returns anarbitrary DDIC type instead of a collection.


The following coding example shows the usage.

* 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 TYPE crmt_name_value_pair, lt_param TYPE crmt_name_value_pair_tab, lv_result TYPE REF TO if_bol_entity_col. ls_param-name = ‘PROCESS_TYPE’. ls_param-value = ‘TSRV’. append ls_param to lt_param. TRY. 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.

Figure 21: Execute an entity method to perform special business functionality

Note: Before an entity method is processed all pending changes in the BOL buffer are transferredautomatically to the API with an implicite MODIFY.

Entity methods may also include changes of a business object. These changes lead to automatic lockingand the creation of an associated transaction context.


6 Advanced Features of the BOL Application ProgrammingInterface

The following sections describe special features of the BOL API.

6.1 Display mode supportWith SAP_ABA 7.0 the Business Object Layer optionally supports the so called “Display Mode” forentities. It is turned on if the BOL core is started with the parameter IV_DISPLAY_MODE_SUPPORT =ABAP_TRUE.

In display mode a call of method IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY on anentity returns ABAP_TRUE for each property. Any attempt to change properties, to create or deletedependent objects is ignored. Such attempts can be monitored via checkpoint group BOL_ASSERTSunder subkey READ-ONLY VIOLATION.

In order to do changes it is necessary to switch the entity explicitly to “Change Mode” first: This is eitherdone by calling method SWITCH_TO_CHANGE_MODE or method LOCK. If no lock could be obtained theentity remains in display mode. The current state of an entity can be checked with methodIS_CHANGEABLE, which is with display mode support equal to method IS_LOCKED.

* 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 = ... “Entity is in now display mode

* Switch to change mode and change entity lv_entity->switch_to_change_mode( ). “Reread and lock entity IF lv_entity->is_changeable( ) = abap_true. lv_entity->set_property_as_string( iv_attr_name = ‘PROPERTY_NAME’ iv_value = ‘New Value’ ). ENDIF.

Figure 22: Usage of the BOL core’s change mode

When an entity is locked its properties are read anew to make the latest data available.


6.2 Standard Interface to Access Properties of Business ObjectsIn order to access properties of BOL entities and query services (among others) you make use of theirIF_BOL_BO_PROPERTY_ACCESS interface methods.

«interface»IF_BOL_BO_PROPERTY_ACCESS

CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY

Figure 23: The interface IF_BOL_BO_PROPERTY_ACCESS provides a standard means to access properties of BOL objects

The interface is implemented by entities, simple and dynamic query services, and parameters of dynamicqueries.The interface offers a standard means to work with BOL objects. Note that it is possible to cast many BOLobject to an instance of IF_BOL_BO_PROPERTY_ACCESS.

* Get search criterion of BOL query DATA: lv_query TYPE REF TO cl_crm_bol_query_service, lv_bo TYPE REF TO if_bol_bo_property_access, 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’ ).* up cast and generic access lv_bo ?= lv_query. lv_city = lv_bo->get_property_as_string( ‘City’ ).

* Set property of BOL entityDATA: 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’ ).* up cast and generic access lv_bo ?= lv_entity. lv_bo->set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ).

Figure 24: Usage of the IF_BOL_BO_PROPERTY_ACCESS interface


Besides generic getter and setter methods to read and modify business object properties the interfaceoffers methods to receive the text for a key-code value. This is available with release CRMUIF 5.1.

* Get key code DATA: lv_person TYPE REF TO cl_crm_bol_entity, lv_bo TYPE REF TO if_bol_bo_property_access, lv_sex TYPE REF TO bu_sexid. “Defines values 1 = Female, 2 = Malelv_bo ?= lv_person.

lv_sex = lv_bo->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_bo->get_property_text( ‘SEX’ ).

Figure 25: Access property texts of key codes

The text is taken from the domain values if available or has to be provided by the underlying GenILcomponent.

6.3 Working with CollectionsThe BOL API offers several collections for application use. CL_CRM_BOL_COL is the most generic oneand can be used to hold all instances implementing the the standard property access interfaceIF_BOL_BO_PROPERTY_ACCESS. It implements the standard collection interface IF_BOL_BO_COL.Especially for handling entities exists the spezialized version CL_CRM_BOL_ENTITY_COL implementingthe also specialized collection interface IF_BOL_ENTITY_COL.There exist several further specializations of these classes, which are the subject of section 6.3.9.

Figure 26: Collection types and their interfaces

The collection interfaces offer a bunch of methods to work with collections – e.g. GET_FIRST, GET_NEXT,GET_CURRENT, SORT, CLEAR, or ADD.

With release SAP_ABA 7.0 collections implement the additional interface IF_BOL_BO_COL_MULTI_SELfor multi selection support, see section 6.3.6 for details.

All collections provide events to track the collection state. The available events are:FOCUS_CHANGED: Raised, if the focus element in single selection mode changes.


BO_ADDED Raised, if a new object is added to the collection.BO_DELETED Raised, if a object is removed from the collection.

If possible the events provide also additional information about the object, which is subject of the event.

All collections provide further an auto cleanup mode. In this mode deleted entities will automaticallyremoved from the collection, see section 6.3.7 for details.

Furthermore collections provide a reset survival mode. In this mode the collection tries to restore allentities in the collection after a BOL reset, see section 6.3.8 for further details

6.3.1 Local and Global IterationsAll collection types support global and local iteration. In the default single selection mode each non-emptycollection has a well-defined focus object. Initially the first object has the focus. Any global iteration movesthe focus, which is published by the event FOCUS_CHANGED of the collection.

If you want to iterate on the collection without moving the focus (and without triggering time-consumingfollow-up processes) you have to use local iteration. To do so you request an iterator object from thecollection and use this to iterate.

* 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_col~insert( iv_bo = lv_query iv_index = 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_property_access is bound. lv_property_access = lv_iterator->get_next(). “Local iteration does not ENDWHILE. “ move focus

Figure 27: Collection types and their interfaces

There are two iterator interfaces. The standard interface IF_BOL_BO_COL_ITERATOR for general accessis provided by all collections. Collections of type CL_CRM_BOL_ENTITY_COL support further interfaceIF_BOL_ENTITY_COL_ITERATOR for more strict typed access.

Beside local iteration to avoid changes of the collection focus iterators provide also additional features likesearching by property (section 6.3.2) or filtering (section 6.3.4).

Iterators are unmanaged subobjects of a collection. Once you retrieve an iterator the collection will notremember it. It is also not possible to determine afterwards on which collection an iterator will operate.Without this option to access the creating collection directly, iterator method GET_COPY allows to get afurther iterator on the collection without knowing it.


6.3.2 Searching

The collections provide the method FIND to search a given business object in the collection. If found it isreturned and also the focus is set to this collection entry.

The method takes two parameters, where only one is used for the search at a time. You can search byindex or business object instance. The parameters are taken in the given sequence. This means if youprovide an index and an instance only the index is used.

The local iterator interfaces support the search for a single property. This is provided by the methodFIND_BY_PROPERTY. The first object, whose property has the given value, is returned. Neither the globalnor the local collection focus is influenced by this operation.

* Find by property DATA: lv_persons TYPE REF TO cl_crm_bol_entity_collection, lv_male TYPE REF TO cl_crm_bol_entity, lv_iterator TYPE REF TO if_bol_bo_col_iterator. lv_iterator = lv_persons->get_iterator( ). 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 ).

Figure 28: Find collection item by property and set focus

6.3.3 Sorting

Collections can be sorted with the SORT method. Via this method the collection itself is sorted and will stayin the resulting sort order. It is not possible to undo the sort operation.

The mandatory parameter IV_ATTR_NAME specifies the property the collection is to be sorted for. If youdo not specify IV_SORT_ORDER the sort order is ascending.

* Sorting by gender DATA: lv_persons TYPE REF TO cl_crm_bol_entity_collection. lv_persons->sort( iv_attr_name = ‘SEX’ iv_sort_order = IF_BOL_BO_COL=>SORT_DESCENDING ).

Figure 29: Collections can be sorted

Note: The sorting itself is alphanumerical based on the internal format of the attribute. This means alsothat conversion exits are not considered!Note: Text-type components are sorted according to the locale of the current text environment.

The optional parameter IV_STABLE = ABAP_TRUE is used to perform stable sorting, which means thatthe relative sequence of lines that does not change in the sort key remains unchanged in the sort. Withoutthis addition, the sequence is not retained and multiple sorting of a table using the same sort key results ina different sequence each time the table is sorted.

The optional parameter IV_USE_TEXT_RELATION = ABAP_TRUE allows you to sort using the textrelated to a key in case the attribute is just a key and the key-text relation is known. The text used in thesorting will be retrieved via GET_PROPERTY_TEXT. See also section 6.2.The following code sample shows the sorting of a collection of persons by the gender. Instead of the priorexample, where the gender key SEX (1 or 2) was used, now the gender text (‘Male’ or ‘Female’) is usedfor sorting.


* Sort collection containing UIFFlight entities lv_flights->sort( iv_attr_name = ‘SEX’ iv_use_text_relation = ABAP_TRUE ).

The optional parameter IV_PATH_2_SUBOBJECT allows you to sort the collection base on an attribute ofa related child object. The given relation or relations should be 1:1 relations. In case of a 1: N relation thefirst object will be taken.If more then one relation should be followed the relation need to be separated by a slash ‘/’. The attributename given with IV_ATTR_NAME must fit to the addressed target object. The following code sampleshows the sorting of a collection of flights by the name of the customers.

* Sort collection containing UIFFlight entities lv_flights->sort( iv_attr_name = ‘NAME’ iv_path_2_subobject = ‘FlightBookRel/BookCustomerRel’ ).

When building the sort table for each flight the relation FlighBookRel will be follow to UIFBooking and fromthere relation BookCustomerRel to UIFCustomer from which attribute NAME is taken. Since FlightBookRelis a 1: N relation only the first booking is considered.

If the desired sort order is not alphanumerical, or should base on not supported criteria, or simply on morethe one field, it is possible to control the sorting externally. To do so an instance ofIF_BOL_COL_SORTING can be provided. During the sort process its method IS_A_GREATER_B is calledwhenever two values are compared. Implement this method and provide the interface to influence the sortorder as needed.Normally the actual attribute values of the given attribute IV_ATTR_NAME are passed as IV_A and IV_B.In case pseudo attribute name IF_BOL_COL_SORTING=>CUSTOM is passed to whole entity instance ispassed instead. This is also supported in combination with parameter IV_PATH_2_SUBOBJECT. So thenavigation along a fixed path of relations does not need to be implemented in method IS_A_GREATER_B.

6.3.4 Filtering

Collections can be filtered using an iterator. As you can have any number of iterators for a collection it isalso possible to have any number of filters on it in parallel. A filter is only applied via the iterator(s). Thusthe collection it self is never changed by the filtering.The filter functionality is equal for both iterator types IF_BOL_BOL_COL_ITERATOR andIF_BOL_ENTITY_COL_ITERATOR. Therefore all examples will just concentrate on the standard iteratorIF_BOL_BOL_COL_ITERATOR.

In order to set a filter an iterator for the collection is required (see section 6.3.1). A filter could be set usingmethod IF_BOL_BOL_COL_ITERATOR~FILTER_BY_PROPERTY. You have to specify the name of theattribute and a value or value pattern as filter criteria. Optional you can chosse the filter mode.

* Filtering a collection of persons for females only DATA: lv_persons TYPE REF TO cl_crm_bol_bo_collection, lv_filter TYPE REF TO if_bol_bo_col_iterator. lv_filter = lv_persons->get_iterator( ). lv_filter->filter_by_property( iv_attr_name = ‘SEX’ iv_value = 1 ).

Figure 30: Collections can be filtered

The code sample above shows the filtering of a collection of persons by gender. The gender could befemale (attribute SEX = 1) or male (attribute SEX = 2). After setting the filter criteria the iterator will onlyoperate on objects matching the given criteria, in the example: persons being female. The attribute valuecan be given as pattern. The standard ABAP operator CP will be used for comparison.


All iterator methods will respect the filter. This applies especially to the iterator methods SIZE andGET_BY_INDEX, which behave now different to there counterparts directly on the collection. The presentsof a filter colud be checked via public attribute IF_BOL_BO_COL_ITERATOR~FILTER_ACTIVE.

In order to setup a more complex filter you can call method FILTER_BY_PROPERTY several times. Eachcall will refine the result according to the addition filter criteria.In the same order you build up the filter by adding criterias you can delete it again. MethodDELETE_FILTER removes per default only the last filter criteria. With optional parameter IV_ALL =ABAP_TRUE can can remove all filters at once.

Method ADAPT_FILTER allows you to adapt the filter criteria of your iterator the the once of a giveniterator. Thus in combination with iterator method GET_COPY it is also possible to store filter criteria in aniterator independent of a collection.

The default filter mode is IF_BOL_BO_COL_ITERATOR =>FILTER_MODE_CACHED. In this mode theiterator stores a filtered copy of the original collection. Thus operations on the filtered collection are asperformant as without filter. The downside of this approach is that the filter result might get invalid whenoriginal collection or the contained entities get changed. Consequently this mode should only be used inread-only case.The alternative filter mode is IF_BOL_BO_COL_ITERATOR =>FILTER_MODE_INTERACTIVE. Here theiterator stores only the filter criteria and operates still on the original collection. For each iterator operationthe filter is interactively applied vthe the original collection computing the result. Thus the operations getless performant, especially operations on the whole collection, such as GET_SIZE. However, the resultwill always be correct, reflecting all changes to the collection and there entities directly.

6.3.5 Changing the collection content

The content of a collection could be changed via the following single object operations:IF_BOL_BO_COL~ADD Append an object to the collection,IF_BOL_BO_COL~INSERT Insert an object into the collection at a given position, andIF_BOL_BO_COL~REMOVE Remove an object from the collection. All occurrences of theobject will be removed.

The addition and removal of objects to/from the collection can be monitored via the collection eventsBO_ADDED and BO_DELETED. The added/removed object will be published by the event.

Additionally the following mass operations are supported:IF_BOL_BO_COL~ADD_COLLECTION Appends the content of a given collection to thecollection,IF_BOL_BO_COL~CLEAR Removes all objects from the collection.

As for the single object operations the addition and removal of objects to/from the collection can bemonitored via the collection events BO_ADDED and BO_DELETED. The added/removed objects will not bepublished by the event.

All operation might change the focus object of the collection, see section 6.3.6 for details.

Note: When adding object to the collection the sort order is not automatically preserved. Also filters mightget outdated, see also section 6.3.4

6.3.6 Single and Multi Select Support

BOL collections support two different modes for entry selection: In the so called Single Selection Mode it is possible to select a single entry at a time: As soon as

another entry is selected, the previous one looses focus. In the Multi Selection Mode it is possible to mark more than one entry at a time


The current selection mode can be checked with the public collection attributeIF_BOL_BO_COL~MULTI_SELECT, which could be ABAP_TRUE or ABAP_FALSE, and it can be set withmethod IF_BOL_BO_COL~SET_MULTI_SELECT.

In single selection mode the selected element is accessed with the methodsIF_BOL_BO_COL~GET_CURRENT returns the selected elementIF_BOL_BO_COL~GET_CURRENT_INDEX returns the index of the selected elementIF_BOL_BO_COL~PUBLISH_CURRENT publishs the selected element via eventIF_BOL_BO_COL~FOCUS_CHANGED

and it is implicitly set with

IF_BOL_BO_COL~FIND moves focus either to given index or objectIF_BOL_BO_COL~GET_NEXT moves focus to the next element and returns itIF_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 the collection isempty. The methods of the interface IF_BOL_BO_COL_MULTI_SEL are switched off.

When multi selection mode has been switched on, you may use the methods of the interfaceIF_BOL_BO_COL_MULTI_SEL to mark and unmark entries and to check, which entries have beenmarked (IF_BOL_BO_COL_MULTI_SEL~MARK, UNMARK, GET_MARKED).

In multi selection mode the collection methods mentioned above behave different:

IF_BOL_BO_COL~GET_CURRENT returns the last selected elementIF_BOL_BO_COL~GET_CURRENT_INDEX returns the index of the last selected elementIF_BOL_BO_COL~PUBLISH_CURRENT does nothingIF_BOL_BO_COL~FIND finds, eventually selects and returns an elementIF_BOL_BO_COL~GET_NEXT does nothingIF_BOL_BO_COL~GET_PREVIOUS does nothing

Also changes to the collection may change the the focus. Method IF_BOL_BO_COL~ADD changes thefocus in case the collection was empty before. In all other cases it can change the focus if optionalparameter IV_SET_FOCUS is given as ABAP_TRUE. The same applies for methodIF_BOL_BO_COL~INSERT.

Method IF_BOL_BO_COL~CLEAR will change the focus to nothing.

Note: Special attention should be payed to the focus handling of method IF_BOL_BO_COL~REMOVE. Incase the removed object(s) has/have not the focus it remains unchanged. In case the focus object isremoved, the focus is moved to the next in the collection (in fact the index of the focus object remainsunchanged). Only in case it was the last in the collection (and the collection is not empty), the focusmoves to the previous object.The following code sample demonstrates a possible coding mistake based on this behaviour and itscorrect solution:

* Example: Remove all flights from Air Canada (AC) from the collection DATA: lv_flights TYPE REF TO if_bol_entity_collection, Lv_flight TYPE REF TO cl_crm_bol_entity.

* Wrong code lv_flight = lv_flights-> get_first( ) WHILE lv_flight is bound. IF lv_flight->get_property_as_string( ‘CARRID’ ) = ‘AC’.


lv_flights->remove( iv_entity = lv_flight ). ENDIF. lv_flight = lv_flights->get_next( ). ENDWHILE.* Correct code lv_flight = lv_flights-> get_first( ) WHILE lv_flight is bound. IF lv_flight->get_property_as_string( ‘CARRID’ ) = ‘AC’. lv_flights->remove( iv_entity = lv_flight ). lv_flight = lv_flights->get_current( ). ELSE. lv_flight = lv_flights->get_next( ). ENDIF. ENDWHILE.

Because of the global iteration the REMOVE always effects the current focus element. So when theremoval happens the next object gets the focus automatically. Thus an unconditional call of GET_NEXTwould left out some objects from the check.

6.3.7 Auto Cleanup Mode

Auto clean up mode for a collection ensures that deleted entities are automatically removed from thecollection. As a consequence the (last) selected element may change automatically in this case.

Since the automatic removal of deleted entities is not always necessary and this feature might lead toserious memory consumption issues (due to the creation of lifetime dependencies), it is not active bydefault. Calling method IF_BOL_BO_COL~ACTIVATE_AUTOCLEANUP activates this function. The currentstate of the collection is indicated by the public attribute IF_BOL_BO_COL~AUTOCLEANUP, which isABAP_TRUE if auto cleanup is active.

Note: If auto cleanup mode is switched on, it is necessary to clear a collection (call of methodIF_BOL_BO_COL~CLEAR) when it is not needed any more: Otherwise the garbage collector could notdelete the collection since it is referenced in the event handler table of its entities; the affected collectionwould remain in memory probably until the next BOL reset operation or session end. This might lead toserious memory consumption issues!

6.3.8 BOL Reset Survival Mode

In order to release unused memory the application from time may trigger a BOL reset, which destroys allBOL entitites and as a consequence clears all collections with auto cleanup activated. Furthermore thereset is propagated to the underlying GenIL components in order to cleanup their buffers.

Although this is OK for most collections at certain times, some may have to protect their content,especially if it is essential for the further progress of the application. You can use methodIF_BOL_BO_COL~SET_RESET_SURVIVAL_MODE to indicate that the root and access entities in thecollection should be kept and recreated afterwards.

Note: The use of the reset survival mode limits the effect of the BOL reset and could lead to considerableruntimes of the reset. To reduce this negative impact the recreation is delayed from release WEBCUIF 7.0onwards.

As already stated above, the recreation after reset is limited to root and access entities. Thus the contentof the collection could be checked for reset complaintness when turning on the reset survival mode. Toavoid negative runtime impacts of this safety check it needs to be activated via checkpoint groupBOL_ASSERTS using transaction SAAB (Assertions and Breakpoints). In case you just log assertviolations they will get collected under subkey COLLECTION_NOT_RESET_COMPLIANT.


6.3.9 Specialized collections

Beside the simple specialization CL_CRM_BOL_ENTITY_COL, which focuses only on strikter typed accessto entities, exist further specialized collections providing also additional functionalities.

6.3.9.1 Unique Type collectionsThe further specialized entity collection CL_CRM_BOL_ENTITY_COL_UT limits the content of the collectionto a single entity type. The desired type is given to the constructor of the collection and all methods addingobjects to the collection will respect it. Violations will lead to exception CX_BOL_EXCEPTION.Note: Method ADD_COLLECTION is not supported by this collection type.

Static method CL_CRM_BOL_ENTITY_COL_UT=>CONVERT allows you to convert an existing collection toa unique type collection preserving its content and state. If the conversion is not possible it will result inexception CX_BOL_EXCEPTION.

Since the type of all entities in the collection is equal the collections can offer mass operations on itscontent. So far only navigation is supported. Method GET_RELATED_ENTIES will return a collection ofrelated entities for a given relation. The collection will be build out of all resulting collections of methodGET_RELATED_ENTIES on each entity in the collection.

* Get all children of all entities of a collection – standard implementation DATA: lv_collection TYPE REF TO cl_crm_bol_entity_col, lv_iterator TYPE REF TO if_bol_entity_col_iterator, lv_entity TYPE_REF TO cl_crm_bol_entity, lv_children TYPE Ref TO if_bol_entity_col, lv_result TYPE REF TO cl_crm_bol_enity_col.. CREATE OBJECT lv_result. lv_iterator = lv_collection-> get_iterator( ). lv_entity = lv_iterator->get_first( ). while lv_entity is bound. lv_children ?= lv_entity->get_related_entities( iv_relation_name = ‘MyRelation’). lv_result->add_collection( lv_children ). Endwhile.

* Get all children of all entities of a collection – using unique type coll DATA: lv_ut_collection TYPE REF TO cl_crm_bol_entity_col_ut.

lv_ut_collection = .cl_crm_bol_entity_col_ut=>convert( lv_collection ). lv_result = lv_ut_collection->get_related_entities( iv_relation_name = ‘MyRelation’ ).

The collection method supports all features of the entity method. Furthermore optional parameterIV_MARKED_ONLY allows restricting the set of parent entities to the marked entities in multiselectionmode; in single selection mode only the focus object would be taken.

6.3.9.2 Unique instance collectionsThe specializations CL_CRM_BOL_UNIQUE_BO_COL and CL_CRM_BOL_UNIQUE_ENTITY_COL areprovided to make it easy to control that each BO or entitiy instance is only stored once in a collection. Thismakes it easy to collect objects in a collection without the risk of duplicates.All methods adding objects to the collection check the uniqueness and will ignored objects already part ofthe collection.


6.4 Transaction Handling

6.4.1 Transaction context kinds

Transactions are handled via transaction contexts represented by interfaceIF_BOL_TRANSACTION_CONTEXT. There are three different scopes of transaction contexts:

The Global Transaction Context covering all changes. It could be retrieved via the BOL coremethod GET_TRANSACTION. The global transaction context is managed by the BOL core anddoes not change in the whole session.

The Single Business Object Transaction Context covering the changes of a single business objectinstance. It could be easily retrieved via method GET_TRANSACTION of any entity belonging tothis BO. Alternatively you can retrieve transpaction contexts per root entity instance from theglobal transaction context via method GET_TX_CONTEXT. Single BO transaction contexts aremanaged by the global transaction manager. The instance associated with a root entity is uniquefor a transaction cycle. Once the transaction has finished a new transaction context is associatedwith the root entioty and the prior one becomes usesless.

The custom transaction context for any scope inbetween the two above. A custom transactioncontext is an instance of class CL_CRM_BOL_CUSTOM_TX_CTXT, which needs to be instanciatedas needed. Then any transaction context could be added to it, including other custom transactioncontexts. Custom transaction contexts are not centrally managed.

The methods of the transaction contexts act always on its whole content.

BOL transactions handle all database updates synchronously.

6.4.2 Transaction cycle

As mentioned in section 6.4.1 the creation and lifetime of the three transaction context kinds are different.However, the general life cycle is equal.A transaction starts latest with locking the first object. The lock event is publish by the BOL core and thetransaction manager createst a single BO transaction context for the locked BO. This instance is stored inthe transaction manager. In case there is already an, beforehand created, transaction context for this BOit is used. The setting of the lock is published by this single BO transaction context via event LOCK_SET.

Now it is possible the change the BO. All changes made via the BOL API are collected in the BOL buffer.Only with calling the MODIFY method of the BOL core will communicate the changes to the underlyingbusiness logic. If any change is expepted there it is publish from the BOL core to the transaction managerand remembered in the associated single BO transaction context. This could be repeated many times.Existence of changes that need to be saved can be checked via method CHECK_SAVE_NEEDED.Note: Pending Changes in the BOL buffer are not recognized by this method!

In order to close the transaction cycle you can save or reset the changes. Before saving you can call thebusiness logic for further consistence check via method CHECK_SAVE_POSSIBLE. The actual save of thedata is initiated with calling method SAVE. This method will return a success indicator. In the success casethe transaction is closed by calling method COMMIT. In the unlikely case of an error during save it needs tobe finished with method ROLLBACK. But this case should be avoided by processing all necessary checksbeforehand in CHECK_SAVE_POSSIBLE.When calling COMMIT you can specify that you want to keep the lock via optional parameterIV_KEEP_LOCK = ABAP_TRUE. Actually the lock is released in any case, but the BOL tries to lock theobject immediately again.Note: The BOL COMMIT always forces a synchronous database update!

In case you deside to reset all changes you have to call the method REVERT. This will reset the bufferstate and release the lock. Per default the buffer is directly synchronized with the latest save state from


the database. If you don’t need the direct synchronization you can delay it by setting optional parameterIV_SUPPRESS_BUFFER_SYNC = ABAP_TRUE.Note: In the lazy mode it might happen that you access an already deleted entity, which will lead to anexception! To be save you might check the entity state before hand via method ALIVE or you programsecurely with a TRY. CATCH CX_BOL_EXCEPTION. ENTRY. construct.After this cycle a single BO transaction context becomes obsolete and could not be used any further. Acustom tranaction context can be used for a further cycle, and the global transaction context starts a newcycle anyway.

6.4.3 Collective transactions and Change tracking

There is no monitoring of dependencies between root objects so far. It might be that a newly created rootobject refers to another newly generated object. If the first one is saved but the second one not, thedatabase is in an inconsistent state. Since such dependencies are not automatically tracked, it is up to theapplication to handle them.

Custom transaction contexts are offered for collecting single BO transactions which belong logicallytogether. Use it to build one transaction context consisting of more than one single BO transactions. Thefollowing coding lines give a little example:

* 1. Create custom tx context DATA: my_tx_context TYPE REF TO cl_crm_bol_custom_tx_context. CREATE OBJECT my_tx_context.

* 2. Add some single BO 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 BO transactions together my_tx_context->save( ). my_tx_context->commit( ).

Figure 31: The custom transaction context can be used to form transactions consisting of more than one root object

With method ADD_TX_CONTEXT you can add other transaction contexts to your custom context. This ispossible for any transaction context, thus not only single BO transactions contexts but aolso other customtransaxtion context may added.

Beside this explite adding of transaction contexts it is also possible to monitor changes for a certain timeperiode and to collect all associated transaction contexts. This collecting mode is switched on via methodSTART_RECORDING and with STOP_RECORDING switched off again.

In case a transaction context contained in the custom transaction context is finished independently it isautomaitally removed form the custom transaction context. Therefore it is not necessary to remove itexplicitely via method REMOVE_TX_CONTEXT. Because of this feature a custom transaction context will beempty after it has finished or the global transaction has been finished.


6.4.4 Tracking transaction state

In order to track the state of a certain transaction context several event are offered:LOCK_SET Raised only by single BO transaction context when the associatedbusiness object was locked.TX_FINISHED Raised by any transaction context when the transaction cycle hasfinished either via COMMIT or REVERT. In case of single BO transaction contexts the eventparameter INSTANCE holds the name and key of the associated root entity. With releaseWEBCUIF 7.0 event parameter LOCKS_KEPT publishes the locking state of the BO after the endof the transaction.AFTER_TX_FINISHED Raised by single BO transaction contexts after TX_FINISHED event. Atthis time the raising context is already removed from the global transaction manager. Thus theevent could be used for retrieving a followup transaction context.

6.5 Advanced Entity features

6.5.1 Input Readiness and Entity Property Modifiers

In order to check if an entity attribute is read only, you may use entity methodIF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY: It returns ABAP_TRUE in case theproperty is not changeable and not mandatory.

Input readiness is determined from the so called Property Modifier, which is defined for each entityproperty and which may take one of the following public constants defined in the interfaceIF_GENIL_OBJ_ATTR_PROPERTIES:

READ_ONLYCHANGEABLENOT DEFINEDHIDDENMANDATORYTECHNICAL

Use the entity method GET_PROPERTY_MODIFIER for access.

By default it is always possible to change attributes of query services.

6.5.2 Excluding Entities from the Central Modify

Normally all changed as well as created or deleted dependent objects are sent to the underlying APIs withone central call of the BOL core method MODIFY. Depending on the application this call may appearautomatically at certain ‘sync points’. So it may happen, that entities are sent, which are not ready forsending and therefore cause errors. In such cases it makes sense to exclude such entities from sending.

Entities are automatically excluded from sending for the following reasons: A dependent entity was newly created, but its attributes are still initial. An entity was sent with MODIFY, but the changes have not been accepted by the underlying

API and it has not been changed since. See also section 6.6. An entity was explicitly deactivated for sending.

The current status of an entity can be checked with method IS_SEND_ACTIVE on the entity instance. Anexplicit change of the state is possible with the methods ACTIVATE_SENDING andDEACTIVATE_SENDING. The activation can also be propagated to aggregated children recursively viasetting optional parameter IV_PROPAGATE_2_DEPENDENT. Beside the default value NO_PROPAGATIONthe values PROPAGATE_2_ALL and PROPAGATE_2_INACTIVE_ONLY are possible. In the latter case the


recursion stops at child objects were sending is already activated. Thus deactivated sub-children might bepreserved.

6.6 Business Error HandlingThe business object layer offers a message protocol to support communication of information-, warning-and error messages. Messages are collected in so called ‘message containers’, which are handled by themessage container manager: There is one message container for each access object instance and aglobal one for all general messages without object relation.

Message Handling Model

CL_CRM_BOL_CORE

CL_CRM_GENIL_MESS_CONT_MANAGER

1

1

IF_GENIL_MESSAGE_CONTAINER

1

*

Figure 32: The message container manager handles all message containers

The message container manager can be reached via the BOL core. The following coding example showshow to get access to a particular message container:

* Access messages of a business object

* Get message container manager DATA: lv_mcm TYPE REF TO cl_crm_genil_mess_cont_manager. lv_mcm = lv_bol_core->get_message_cont_manager( ).

* ... to obtain the global message container DATA: lv_mc TYPE REF TO if_genil_message_container. lv_mc = lv_mcm->get_global_message_cont( ).

* ... to obtain the object related message container DATA: lv_object_name TYPE crmt_ext_obj_name, lv_object_id TYPE crmt_gnil_object_id. lv_object_name = lv_order->get_name( ). lv_object_id = lv_order->get_key( ). DATA: lv_mc TYPE REF TO if_genil_message_container. lv_mc = lv_mcm->get_message_cont( iv_object_name = lv_object_name iv_object_id = lv_object_id ).

* or directly lv_mc = lv_bol_core->get_global_message_cont( ). lv_mc = lv_order->get_message_container( ).

Figure 33: Access the message container for a particular entity


The message container interface IF_GENIL_MESSAGE_CONTAINER provides the methodGET_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 constantsMT_ALL/MT_ERROR/MT_WARNING/MT_INFO/MT_SUCCESS in the message container interface.

Method GET_NUMBER_OF_MESSAGES returns the number of messages of the specified type. This may beused to give the user a hint that messages exist.* 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.

Figure 34: Check message count and retrieve messages from a message container

As already mentioned in section 6.5.2, changes might be rejected by the underlying business logic in caseof errors. In this case the BOL will automatically switch off the sending to prevend the repeated sending oferrors. The effected entities remain in buffer state modified, valid, and sending deactivated. Thus the userinput, even if wrong, is preserved.In this situation the application should present the error messages to the user and allow the correction ofthe input. A further change of attributes will automatically activate sending again for the entity.

6.7 Mass operations using the BOL coreMany operation of the entity API could also be called via the BOL core instance. The difference in manycases is the possible amount of objects to execute the operation on. Logically entity methods operatealways on the entity instance they are called on. Contrary the corresponding BOL core method takes ingeneral a collection of entities as input.The following operations are supported as mass operation on a collection of entities:

DELETE_ROOT_ENTITIES Delete a given set of root entities, see also section 5.5.5. EXECUTE_ENTITY_METHOD Execute an entity method on a given set of enities, see

also section 5.5.6. EXECUTE_ENTITY_METHOD2 Execute an entity method type 2 on a given set of enities,

see also section 5.5.6.

Beside this multi object enabled operations the BOL core supports all major operation provided by theentities directly. So it is in general possible to program mainly against the bOL core. However, using theentities is more convenient.

6.8 Buffering IssuesIt is very important to keep in mind that the business object layer operates on its own entity buffer. Thatmeans:

Every entity found by a query, Every entity read via navigation following a relation, and Each entity modification as well as the creation or deletion of dependent entities is buffered.

The underlying buffers of the GenIL components (for the various business object types) aresynchronized with BOL modifications, when CL_CRM_BOL_CORE->MODIFY() is called. In theCRM UIF application this happens automatically with each roundtrip. Vice versa the BOL buffer isusually informed automatically about data changes in the GenIL component.

So only in exceptional situations an explicit synchronization between BOL buffer and GenIL component isnecessary. The following sections explain the possibilities


6.8.1 Entity Properties

The entity method CL_CRM_BOL_ENTITY->REREAD may be used to synchronize the buffer state of theattributes and property modifiers of a single entity. Since this method calls the underlying applicationprogramming interface directly, it should be used very carefully to avoid performance problems.In case the entity is in state created the method does nothing. In case the entity is in state modified theattributes are not changed to preserve the changes.Note: As a result of the synchronization the BOL may detect the deletion of an entity which will result inexception CX_BOL_EXCEPTION.

The BOL may deside to turn a REREAD call into a GET_RELATED_ENTITIES call for buffer updateefficiency reasons. This happens only if the parent relation of the entity is an invalid 1:N relation and thereare less than 20 objects in the current relation.

6.8.2 Entity Relations

The relationship between entities is also subject of buffering. Like buffered properties the relations maybecome invalid and get synchronized automatically on the next access. Even empty relations arebuffered.In general we distinguish between cacheable relations and those, which are not subject to buffering. Thelatter is a property of the underlying object model.

For the cacheable relations a mode can be specified for navigation. Therefore the navigation methodsGET_RELATED_ENTITY and GET_RELATED_ENTITIES take an optional parameter IV_MODE, which maybe set to one of the following constants (defined in class CL_CRM_BOL_ENTITY):

NORMAL - This is the default and means: Take relation from buffer and read it from the underlyingAPI, if the buffer is invalid.BUFFER_ONLY: This takes the relation only from the buffer.BYPASSING_BUFFER: This reads the relation from the underlying API ignoring the buffer.

Non-cacheable relations are always read from the underlying API, ignoring the given mode. Being non-cacheable is an unchangeable model property of a relation (IF_GENIL_OBJ_MODEL~RELATION_IS_CACHEABLE).

Note: For optimal system performance you should always use the default mode NORMAL. If there is realya synchronization issue, which could be solved with bypassing the buffer it points mostlikly to an error.Such errors should always be investigated. In some reason the underlying business logic does not allowbuffering. In this case it should be incorporated in the model. However, since this will be a global settingthis should be desided very careful!

6.8.3 Preloading BOL Views

The last two sections explained how to synchronize a single entity or relation. If a larger set of entities withrelations should be synchronized these methods are too inefficient

For that reason it is possible to load a well-defined part of the object model with a given start entity or setof entities at once. This model part has to be defined as a so called BOL View in the SAP implementationguide (View cluster GENIL_VIEWDEF).


Figure 35: BOL views are defined in the SAP implementation guide

Figure 36: Each BOL view is assigned to a specific BOL component set

Figure 37: Each BOL view has a unique view root, which is either a root object or access object: here BTOrder. The relatedobject types BTAdminH, BTTextH, … and their relations are specififed in a table.


Each BOL view is assigned to a specific component set and has a unique view root, which is either a BOLroot object or access object.Now the method PREFETCH_VIEW can be called on the BOL core: It takes the view name and a collectionof view root entities as input; the model part defined by the view is read for each entity in the collectionand stored in the buffer effectively.Beside the explicite fetch via the BOL core it is also possible to apply a view directly to a search result of aquery service. To do so you have to set the name of the view on the query service instance with methodSET_VIEW_NAME.

6.8.4 Locking with Synchronization

After setting a lock it is sometimes necessary to synchronize the BOL buffer for the locked entities with thecurrent database state for the following reasons:

The entity could have been changed by someone else since the last read operation, or The last lock attempt failed, because the entity was already locked. Due to the failure the entity

was set to read-only mode. Now we try it again and the property modifiers have to be refreshed.Therefore the CL_CRM_BOL_ENTITY->LOCK method takes an optional parameter IV_REREAD. Perdefault it is set to ABAP_FALSE. If it is set to ABAP_TRUE the full aggregation hierarchy of the locked rootentity is invalidated in the buffer and synchronized on the next access.Note: With display mode support, see section 6.1, this synchronization takes always place!

6.8.5 Buffering of Query results

Since queries might return a big amount of objects they may increase considerably to the memoryconsumption of the bOL buffer. Because the BOL reset is the only way to clear the BOL buffer it is not soeasy to control the memory consumption when frequent searches happen. On the other hand many queryservices return Query Result Object as aggregation of actual entities for performant result display.With release WEBCUIF this can be further leveraged by not adding them to the central BOL buffer. In factthis becomes the default for simple and dynamic query services. Adding the result to the central buffer hasto be enforced by setting optional parameter IV_ADD_QRESOBJ_2_BOL_BUFFER of methodGET_QUERY_RESULT to ABAP_TRUE.Without registration in the central buffer query result object instance live with result collection, thus theirlifetime is controlled by the application program. On the down side of this the object instances are notlonger unique.

6.9 BOL ResetSince the BOL buffer and the message services permanently collect but not release information theamount of data constantly grows with time. Therefore a mechanism is necessary to get rid of all thisbuffered/collected data.Currently the only possibility is the BOL core reset using method CL_CRM_BOL_CORE->RESET. Thismethod clears all known buffers and messages. After the method has run it may also be advantageous tocall the ABAP garbage collector explicitly to finally remove all the freed objects.

In the CRM UIF application a BOL reset is triggered automatically from the framework whenever the userswitches the workcenter with a click in the navigation bar.

After the BOL reset all entity instances are useless: Further operations on them will cause runtimeexceptions. This applies also for entities contained in collections, for which the Reset Survival Mode hasbeen turned on (see section 6.3.8). This mode does not preserve the actual entity instance, only therelated object is remembered and a new entity instance is created for it.In order to really keep the current entity instances you can provide an exception list when calling theRESET method. In a later release this may combined with the reset survival mode.

When the BOL reset procedure starts the BOL core raises event RESET_TRIGGERED and when the resethas finish event RESET_FINISHED. During the BOL reset most BOL API operation are not possible. Thestate could be checked via public attribute RESET_RUNNING of the BOL core instance.


During the BOL reset all entities get cleared from the buffer. This leads also to the raise of the DELETEDevent for these entities. However, during the reset procedure this must not interpreted as real deletion ofthe object!

Since the BOL reset triggers also the reset of the loaded GenIL components it might also be necessary onsession close in order to close connections to remote systems. On the other hand any restore of data afterthe reset would be a waste of time in this case. Therefore this can be prevented by setting optionalparameter IV_NO_RESTORE to ABAP_TRUE.

7 Interface ClassesFind below a summary of important classes and interfaces of the Business Object Layer (BOL).

7.1 CoreCL_CRM_BOL_CORE is the most important class of the BOL Application Programming Interface (API).There’s only one instance of it within one session and it cannot get lost or deleted. The BOL core is thecentral service provider for API classes and it communicates with the underlying business objectimplementation. It is possible to use the core services directly, but it is recommended to use the morecomfortable API classes – e.g. query service or entity.

7.2 Query ServicesGeneric query services are provided by the classes CL_CRM_BOL_QUERY_SERVICE andCL_CRM_BOL_DQUERY_SERVICE. Each instance corresponds to a distinct query object. It stores queryparameters but does not aggregate the query result.

7.3 EntityThe class CL_CRM_BOL_ENTITY is a generic representation for business object segments in the BOL.Each instance is a unique representation for a specifc part of a business object. Data access is done byhelp of the IF_BOL_BO_PROPERTY_ACCESS interface. Entities are centrally managed and cached.

7.4 CollectionA collection or list of generic objects represented by the interfaces IF_BOL_BO_COL andIF_BOL_ENTITY_COL and the underlying classes CL_CRM_BOL_BO_COL andCL_CRM_BOL_ENTITY_COL (among others). A collection provides global iteration, which changes theglobal focus; Usage of local iterators does not. It is possible to add and remove objects referenced but notowned by the collection.

7.5 Transaction ContextThe transaction context is represented by the interface IF_BOL_TRANSACTION_CONTEXT. Depending onthe actual instance of the interface the scope of the represented transaction is a single root objectinstance, all so far modified root object instances, or any explicitly built subset in between.The BOL core aggregates the global transaction context, which includes all modified root objects. Theglobal transaction context logs all modifications automatically. A single BO transaction context can beaccessed via the entity it belongs to.


8 Checkpoint groupsIn order to highlight important places for debugging and to introduce expensive consistency checks, somecheckpoint groups have been introduced. Checkpoint groups are activated with transaction SAAB(Assertions and Breakpoints) usually in the development environment.

8.1 BOL checkpoint groups The checkpoint group BOL_ASSERTS includes expensive checks for inner consistency and for the

correct usage of the display mode. If switched on, any attempt to change entities in display modeis detected. This checkpoint group should be switched on in development and test systems to getearly notice of problems related to the BOL usage.BOL_MODIFY_WATCH defines some important breakpoints, which can be used to track the datatransport from the business object to the generic interaction layer (GenIL), the merge back of datareturned into the BOL buffer, ID adjustments for new entities and buffer invalidation of changedentities.BOL_COLL_AUTOCLEAN activates the auto cleanup mode for all collections per default. Since thismay lead to memory consumption issues this switch should only be used for testing purposes orto be compatible with framework versions SAP_ABA 7.0 and older.

8.2 Related checkpoint groupsFor detailed investigations and debugging it is often required to break in the generic interaction layer(GenIL), which gives access to data persistency.

The checkpoint group GENIL_DC_CHECKS activates consistency checks for the data containers.GENIL_GENERAL_CHECKS turns on general checks in the GenIL layer.GENIL_MODEL_CHECKS activates consistency checks for the object models of the used GenILcomponentsGENIL_LOCK makes the ABAP debugger stop when an entity is to be locked.GENIL_SAVE allows investigations of the save process.GENIL_READ breaks in the read method of the GenIL core CL_CRM_GENERIC_IL_NEW andallows detailed investigations of the communication with the underlying GenIL componentresponsible for a specific Business Object.GENIL_MODIFY breaks in the modify method of the GenIL core.


9 Inner Details and DebuggingThis section presents further aspects of the business object layer (BOL). The UML diagrams below showthe connection between the classes involved and their main attributes.

9.1 BOL EntitiesBOL entities are managed by the BOL entity manager and use classes of the the Generic InteractionLayer (GenIL) to hold their data.

CL_CRM_BOL_ENTITY_MANAGERentity_tab

CL_CRM_BOL_ENTITYmy_manager_entryparent

0..n

1

CL_CRM_GENIL_CONTAINER_OBJECTdata_ref

1

1

#container_proxy1

1

0..n

1

All entities are managed by the entity manager: It assures the uniqueness of entities and buffersaccess.

Each entity holds a reference to its manager entry. The manager entry includes values like the invalidand delta flags. Holding these values in the ENTITY_TAB of the entity manager enables efficient BOLtable operations on all entities – e.g. CL_CRM_BOL_CORE->MODIFY.

An entity is a wrapper for a GenIL container object CL_CRM_GENIL_CONTAINER_OBJECT belongingto a data container. This object is referred as CONTAINER_PROXY and holds the attributes, properties,and relations of an entity.


9.2 CollectionsVarious collections reference a set of BOL entities and offer convenient access to their properties.

CL_CRM_ENTITY_COLentity_list

CL_CRM_BOL_ENTITY0..n

1

0..n

1

CL_CRM_BOL_QUERY_SERVICE

IF_BOL_BO_COL<<Interface>>

CL_CRM_BOL_BO_COLentity_list

IF_BOL_BO_PROPERTY_ACCESS<<Interface>>

0..n

1

0..n

1

A collection is represented by the IF_BOL_BO_COL interface and can either be an entity collectionCL_CRM_ENTITY_COL or the generalized business object collection CL_CRM_BOL_BO_COL.

A BO collection can hold entities (CL_CRM_BOL_ENTITY) and query services(CL_CRM_BOL_QUERY_SERVICE).

The access to properties of BOL objects is offered by the interface IF_BOL_BO_PROPERTY_ACCESSwith its standard access methods like IF_BOL_BO_PROPERTY_ACCESS~GET_PROPERTY,GET_PROPERTY_AS_STRING or SET_PROPERTY.

Documents

Crm 7.0 Bol Guide