Custom GenIL BOL for Z-Tables With Relationships

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.

https://www.sdn.sap.com/irj/sdn/bpx-crm

Creating Custom GenIL/BOL Model for Z-tables Bound by Relationships


© 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



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

http://wiki.sdn.sap.com/wiki/display/CRM/Create+a+Z+BOL+Object+Part+1




© 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



© 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



© 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. There‟s 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. There‟s also the coding convenience, the methods can be called directly using the "=>" operator.



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



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



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



© 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( „<model_name>‟ ), 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!



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


http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/6158

http://www.sdn.sap.com/irj/scn/weblogs?blog=/pub/wlg/6178

http://wiki.sdn.sap.com/wiki/display/CRM/Extend+BOL+Model+BT+with+custom+table+type+relationship

https://www.sdn.sap.com/irj/sdn/bpx-crm



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

Custom GenIL BOL for Z-Tables With Relationships

Documents

Transcript of Custom GenIL BOL for Z-Tables With Relationships