-
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 1
Creating Custom GenIL/BOL Model
for Z-tables Bound by
Relationships
Applies to:
SAP CRM 6.0. For more information, visit the Customer
Relationship Management homepage.
Summary
A walkthrough, explaining the steps for creating a custom
GenIL/BOL model for handling your Z-tables bound by
relationships.
Author: Arun Prakash Karuppanan
Company: Accenture
Created on: 24 February 2010
Author Bio
Arun Prakash Karuppanan is an application developer in SAP-CRM.
He is currently employed with Accenture Services Private Ltd.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 2
Table of Contents
Introduction
.........................................................................................................................................................
3
Creating the sample Model
.................................................................................................................................
3
Identifying Tables Needed:
.............................................................................................................................
3
Identifying relationships and cardinality:
.........................................................................................................
3
Create tables:
..................................................................................................................................................
5 Check table relationships:
............................................................................................................................................
5
Identifying BOL business objects:
...................................................................................................................
5
Implementing the GenIL class:
.......................................................................................................................
6
Making our Model known to the system
..........................................................................................................
9
Handling Non-Root objects in model
............................................................................................................
10
Related Content
................................................................................................................................................
11
Disclaimer and Liability Notice
..........................................................................................................................
12
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 3
Introduction
SAP has provided many "Models" to take care of all requirements
under various business scenarios. For example, Sales, Marketing,
Campaign etc., This is what you see under "Model" in the runtime
repository of the BSP component. You probably know that each of the
Model has its own implementation class aka GenIL handler class.
This information can be found in the IMG path "customer
relationship management->crm cross-application
components->generic interaction layer/object layer->basic
settings".
Now, you might have come across some requirements that require
you to take care of some custom tables. You might have to develop
user interfaces, write the table maintenance logic etc. You might
also have to use the table data in some standard application
screens. In case of single tables without relationships, you might
get off easily. In fact, there is a WIKI entry showing you how to
create a model for simple objects (Wiki Entry). But how about a set
of tables bound by relationships?
In BSP development, a crude approach in this scenario is to use
value nodes and call the maintenance logic directly in the
getter-setter/event handlers directly. Reuse and enhancements are a
pain. Want to do it the better way? When it comes to taking care of
business data while allowing the end user to play around with the
interface, you have to worry about data consistency and integrity,
application performance, reusability of your code etc.,
Performance(buffering) is crucial when you deal with tables with
huge amount of transaction data. SAP knows its business and the
architecture is a tried and tested one. Why not leverage on their
expertise? You might have seen how wizards in the component
workbench and BOL programming make developing user interfaces easy
when using Model Nodes. Do you want the same convenience and
reusability? The solution is to create your own Model.
Creating the sample Model
Creating a Model require you to understand some relational
database concepts. Once we get through that, we will look at how to
create the implementation class. For this walkthrough, I'm not
going to create a model from scratch. I will provide you with a
walkthrough based on the simplest model implementation sample
available in the package 'CRM_GENIL_SAMPLE'.
Identifying Tables Needed:
In this model we have a header object "Order". Each Order can
have a single "Partner" entry and multiple "Item" entries. Each
Item has exactly one "Shipping Data" entry. So, we need four
database tables.
ZORDER for storing Orders.
ZPARTNER for storing Order Partners.
ZITEM for storing Order Items.
ZSHIPMENT for storing Item shipment data.
Identifying relationships and cardinality:
Relationships can be of three types:
A - Association - An association is simply any sort of
relationship between two tables.
B - Composition - This is a strong association. Meaning, Part A
uses part B in it, and Part A getting destroyed means that part B
is also destroyed.
C - Aggregation - This is a weak "has a" relationship. Meaning,
Part A uses part B in it, but Part A getting destroyed does not
necessarily mean that part B should be destroyed.
Cardinality can be of four types. I'm sure this needs no
explanation.
A - 0..1
B - 0..n
C - 1
D - 1..n
Now, identify the relationships between these tables.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 4
ZORDER has a relationship with ZPARTNER. According to our
business rule, an entry in table ZORDER can have zero to multiple
entries in table ZPARTNER referring to it through a foreign key.
But each entry in table ZPARTNER must refer to one entry in table
ZORDER and only one. Let's give this relationship a name
"OrderPartnerRel". So the relation ship cardinality is
ZORDER----------------------->ZPARTNER 1 OrderPartnerRel 0..n
This is an aggregating relationship as the primary key of the
ZPARTNER table is not part of any foreign
key relationship with ZORDER table.
The exact same rule applies for the relationship between the
tables ZORDER and ZITEM. Let's name the relationship
"OrderItemRel"
ZORDER------------------>ZITEM 1 OrderItemRel 0..n This is an
aggregating relationship as the primary key of the ZITEM table is
not part of any foreign key
relationship with ZORDER table. You will see more of this below,
when creating tables.
ZITEM has a relationship with ZSHIPMENT. By our business rules,
each item line must have exactly one shipment line. Each shipment
line must refer to an item line and not more than one. Let's give
the relationship a name "OrderItemShipmentData". So, the
cardinality is as follows.
ZITEM----------------------->ZSHIPMENT 1 OrderItemShipmentRel
1 This is a composite relationship as the primary key of the
ZHIPMENT table is supplied by ZITEM. You will see
more of this below, when creating tables.
Apart from these relationships, our ZPARTNER table has a
relationship with the standard master table but000. Each line in
ZPARTNER table must refer to an entry in but000 table and not more
than one. Let's name this relationship "BusinessPartnerRel". The
cardinality is as follows.
ZPARTNER----------------------->BUT000 1 BusinessPartnerRel 1
This is an association relationship as the operations on ZPARTNER
table does not have any effect on the
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 5
Create tables:
Now that we have identified the relationships, we can proceed
creating the tables with required fields and check table relations
as follows.
The necessary fields are available in the structures shown
below. Do not directly append these structures to the table.
Rather, create the same fields as found in the structure.
Otherwise, you will face difficulties specifying primary keys and
foreign key relationships. Once you have created the tables, create
structures for accessing entity data in BOL at runtime
(CL_CRM_BOL_ENTITY->CONTAINER_PROXY->DATA_REF). During
runtime in the BOL layer, not all fields of the table are required
for manipulation. Thus, the table fields and the fields available
at runtime in BOL layer might be different. If this bothers you,
you may use the same type in BOL also. In the SAP sample, the
runtime structure types are different for some objects. For those
tables, whose structure differs from the BOL runtime field
structure, I have specified the type in ABAP syntax.
Table Table Structure Type BOL structure type
ZORDER CRMT_GENIL_ORDER_ATTR CRMT_GENIL_ORDER_ATTR
ZITEM types: begin of GTYPE_ITEM,
HEADER_GUID type CRMT_GENIL_OBJECT_GUID. include type
CRMT_GENIL_ITEM_ATTR as ATTR.
types: end of GTYPE_ITEM,
CRMT_GENIL_ORDER_ATTR
ZPARTNER types: begin of GTYPE_PARTNER,
HEADER_GUID type CRMT_GENIL_OBJECT_GUID. include type
CRMT_GENIL_PARTNER_ATTR as ATTR.
types: end of GTYPE_PARTNER,
CRMT_GENIL_PARTNER_ATTR
ZSHIPMENT CRMT_GENIL_SHIPMENT_ATTR CRMT_GENIL_SHIPMENT_ATTR
Check table relationships:
ZITEM-HEADER_GUID ----> ZORDER-GUID
ZPARTNER-HEADER_GUID ----> ZORDER-GUID
ZSHIPMENT-GUID ----> ZITEM-GUID
ZPARTNER-NUMBER ----> BUT000-PARTNER
Identifying BOL business objects:
Now it's time to identify the BOL objects for our model. A BOL
object may refer to a table line or query object or view object or
query result object etc., The different kinds of business objects
are specified below.
A Root Object
B Access Object
C Dependent Object
D Search Object
E Search Result Object
F View Object
G Dynamic Search Object
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 6
Root Object: This is a special access object, that is at the top
of the hierarchy. See access object below. Access Object: This is
an object that can be accessed independently, without requiring
information from other objects. It
has an ID that can be used to determine both the attributes of
the access object itself and those of its dependent objects.
Dependent Object: A dependent object is a special type of
business object, whose attributes cannot be determined solely from
the ID of this business object, but instead, only or together with
the ID of the superior access object.
Search Object: These are query objects. Search Result Object:
These are query results. The returned results may also directly
correspond to root/access
entities Dynamic Search Object: Advanced query Objects
In our model, we have the following business objects.
Order -> Root object
OrderItem ->Access object. Now, ideally, we would think that
OrderItem is a dependent object. But, remember that the shipment
line refers to the item line and not the order line. So, OrderItem
must exist as an access object for the sake of shipment data.
OrderItemShipmentData ->Dependent object. It depends on
OrderItem object for meaningful existence.
OrderPartner ->Dependent object. It depends on Order object
for meaningful existence.
OrderQuery ->Search Object
OrderItemQuery ->Search Object
AdvOrderHquery ->Dynamic Search Object
AdvOrderQuery ->Dynamic Search Objects
Important Note: While giving names to your BOL objects, make
sure that unlike in this example, you use the Z or your customer
name space. This is to ensure that no conflict arises with standard
BOL objects when various component sets are loaded in the user
environment. Check out the Model SAMPLE in transaction
GENIL_MODEL_BROWSER.
Implementing the GenIL class:
Now, it's time to implement the GenIL class. This class should
inherit the interfaces IF_GENIL_APPL_INTLAY and IF_GENIL_APPL_MODEL
or directly inherit from the class CL_CRM_GENIL_ABSTR_COMPONENT.
It's time you opened the class CL_CRM_GENIL_SAMPLE_COMP" in class
viewer. We will look at how the implementation has been done. For
sake of readability and maintainability, separate classes have been
created for handling each of the objects. Theres one other reason
which you will see at the end of this document. A base API class
which manages the BOL buffer and does all the base API
functions.
"CL_CRM_GENIL_SAMPLE_COMP" -> Main GenIL handler class
"CL_GENIL_SAMPLE_ORDER" -> Contains methods for manipulating
Order object "CL_GENIL_SAMPLE_ITEM" -> Contains methods for
manipulating item object "CL_GENIL_SAMPLE_PARTNER" -> Contains
methods for manipulating partner object "CL_GENIL_SAMPLE_SHIPMENT"
-> Contains methods for manipulating Shipment object
"CL_CRM_GENIL_SAMPLE_API" -> Methods for low level API
Except for the main GenIL class, you may find that all the other
classes have only static methods and attributes. This is a must for
the API class as it holds the BOL buffers (look at the attributes
of this class), that must persist throughout the session. Theres
also the coding convenience, the methods can be called directly
using the "=>" operator.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 7
BOL buffers(attributes) in the API class
HEADER_TAB ---> Buffer for "Order" entity ITEM_TAB --->
Buffer for "OrderItem" entity SHIPMENT_TAB--> Buffer for
"OrderItemShipmentData" entity PARTNER_TAB---> Buffer for
"Orderpartner" entity One important note is that in this sample
model, no database tables are used. Look at the attributes of the
class
CL_CRM_GENIL_SAMPLE_API. All the attributes that end with _DB
serve to simulate database tables. For demo purposes, initial
values for these are filled using the method "DATA_BUILD", called
in the CONSTRUCTOR method. These initial entries are for simulating
database entries. So, whatever operations have been done on the
buffer tables(*_DB), should be done on database tables instead.
HEADER_TAB_DB ------> ZORDER ITEM_TAB_DB---------> ZITEM
SHIPMENT_TAB_DB-----> ZSHIPMENT PARTNER_TAB_DB------>
ZPARTNER
I will give a short explanation as to what each method does.
IF_GENIL_APPL_MODEL~GET_MODEL
Supplies information on relationship, cardinality between
objects.
IF_GENIL_APPL_MODEL~GET_OBJECT_PROPS
Supplies information on individual BOL objects.
Object_name Name of BOL object Object_Kind - Whether this is a
root object or access object, etc., Key_struct - Key fields of the
object Attr_struct - BOL attribute structure Create_struct -
Structure for creation of root objects Root_Object - The Header
object of the BOL object You can also specify methods linked to BOL
objects. These methods can be executed at runtime using
CL_CRM_BOL_ENTITY->EXECUTE or EXECUTE2 depending on the
parameters accepted by the method.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 8
IF_GENIL_APPL_MODEL~GET_DQUERY_ATTR_OPTIONS
- Supplies dynamic search operators for each search field
IF_GENIL_APPL_INTLAY~CHECK_OBJECTS_BEFORE_SAVE
- Gets called by IF_BOL_TRANSACTION_CONTEXT~CHECK_SAVE_POSSIBLE.
You can change the success flag in the returning data to prevent a
save.
IF_GENIL_APPL_INTLAY~CREATE_OBJECTS
-Called for creating root objects only.
cl_crm_bol_entity_factory->create( )
IF_GENIL_APPL_INTLAY~DELETE_OBJECTS
-Called for deletion of root objects only.
cl_crm_bol_entity->delete( )
IF_GENIL_APPL_INTLAY~EXECUTE_OBJECT_METHOD
-Handlers for the methods you specified in
'GET_OBJECT_PROPS'.
IF_GENIL_APPL_INTLAY~EXECUTE_OBJECT_METHOD2
-Handlers for the methods you specified in
'GET_OBJECT_PROPS'.
IF_GENIL_APPL_INTLAY~GET_DYNAMIC_QUERY_RESULT
-Process advanced search queries
IF_GENIL_APPL_INTLAY~GET_OBJECTS
-Read attribute values of root and access objects. Dependent
objects are read only if a relationship is requested via
cl_crm_bol_entity->get_related_entity( ).
IF_GENIL_APPL_INTLAY~GET_QUERY_RESULT
-Simple query processing
IF_GENIL_APPL_INTLAY~GET_ROOT_PATH
Returns Keys of the root object for the passed BOL objects
IF_GENIL_APPL_INTLAY~GET_TEXT
Supplies text information, usually for page titles(OTR),
etc.,
IF_GENIL_APPL_INTLAY~GET_VIEW
IF_GENIL_APPL_INTLAY~INIT_OBJECTS
-Reset BOL buffer for the root objects.
Called by IF_BOL_TRANSACTION_CONTEXT->REVERT()
IF_GENIL_APPL_INTLAY~LOCK_OBJECTS
-Database locks('ENQUEUE_*) for root objects.
IF_GENIL_APPL_INTLAY~MODIFY_OBJECTS
-Modify root object/relations.
Note: When you modify attribute values of a root object, it is
registered as a change in root object. When you
create/delete/modify a related object, this registers as a delta
change in that object and a change in root
object. Processing is required depending on what object has been
changed and what the delta change is.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 9
IF_GENIL_APPL_INTLAY~ON_AFTER_COMMIT
-Something to do after a database commit. Usually release
database locks...
IF_GENIL_APPL_INTLAY~ON_AFTER_ROLLBACK
-What to do in case of a roll back? Clear buffer entries related
to rolled back root object...
IF_GENIL_APPL_INTLAY~RESET
-Reset whole BOL buffer. Called during
CL_CRM_BOL_CORE->RESET( ).
IF_GENIL_APPL_INTLAY~SAVE_OBJECTS
-Save Root and dependent objects to database
Making our Model known to the system
Now, that we are done with the GenIL class implementation, we
must make it known in the IMG.
Launch transaction SPRO, go to IMG path "customer relationship
management->crm cross-application components->generic
interaction layer/object layer->basic settings". You have to
create a component first. Choose a name for your component in the Z
or customer name space. Specify name and implementation class here.
Since we are supplying model and object details in our
implementation class, you can leave those fields empty. Save your
entry. The screenshot highlights the sample Model.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 10
Next, create a Component Set. This corresponds to the Model
which you see in the runtime repository of a BSP component. A
component set is a place holder for components. You can include any
existing component into this component set. Again make sure that
this is in the Z or customer name space. Now, include the desired
components into the component set. Do test your models using the
transactions GENIL_MODEL_BROWSER and GENIL_BOL_BROWSER.
When you initialize a component set using
CL_CRM_BOL_CORE->STARTUP( ), all the components will be loaded
and be available in your environment
Handling Non-Root objects in model
When creating a model, we can have non-root objects that do not
have GUIDs(own or borrowed) as part of their key. For this kind of
Model, the object handler class for root object must implement the
interfaces IF_GENIL_SAMPLE_ABSTR and IF_GENIL_SAMPLE_ABSTR_ROOT or
inherit from the class CL_CRM_GENIL_SAMPLE_ABSTR_ROOT. The rest of
the object handler classes must implement the interface
IF_GENIL_SAMPLE_ABSTR or inherit from class
CL_CRM_GENIL_SAMPLE_ABSTR.
Look at the class CL_CRM_GENIL_SAMPLE_COMP_NEW and the other
relevant classes to see how the implementation has been done. If
you are wondering why the Create method for shipment data has been
left empty, this is the reason. Have fun modeling!
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 11
Related Content
Wiki - Creating Z-BOL for simple objects
BOL/GENIL architecture for CRM IC Web Client
Extending CRM core components to build enhanced IC Web Client
business applications
Extend BOL Model BT with custom table type relationship
For more information, visit the Customer Relationship Management
homepage.
-
Creating Custom GenIL/BOL Model for Z-tables Bound by
Relationships
SAP COMMUNITY NETWORK SDN - sdn.sap.com | BPX - bpx.sap.com |
BOC - boc.sap.com | UAC - uac.sap.com
2010 SAP AG 12
Disclaimer and Liability Notice
This document may discuss sample coding or other information
that does not include SAP official interfaces and therefore is not
supported by SAP. Changes made based on this information are not
supported and can be overwritten during an upgrade.
SAP will not be held liable for any damages caused by using or
misusing the information, code or methods suggested in this
document, and anyone using these methods does so at his/her own
risk.
SAP offers no guarantees and assumes no responsibility or
liability of any type with respect to the content of this technical
article or code sample, including any liability resulting from
incompatibility between the content within this document and the
materials and services offered by SAP. You agree that you will not
hold, or seek to hold, SAP responsible or liable with respect to
the content of this document.