Can't Find a BAdI to Handle a Requirement?

Try
the Event Handler
SAPexperts/CRM
To streamline processes, ensure data integrity, and minimize errors in mySAP
CRM, many companies incorporate business rules into business transaction
processing. While SAP offers various ways to implement these business rules,
such as Business Add-Ins, they may not meet all of your requirements. In
these cases perhaps the event handler can do the trick.
Key Concept

The event handler is a table-driven framework incorporated into mySAP

CRM to control business transaction processing. It registers function modules
that the system executes at certain points in standard mySAP CRM code
processing. You can execute these function modules repeatedly, so they are
referred to as callback functions.
Object function entries represent an additional customizing step to assign a
function module to an object. Such entries serve as additional filtering on
which function modules should execute for which objects.
Imagine that during a mySAP CRM implementation, you are asked to
configure the system to prevent it from saving a sales order for a blocked
sold-to party or from creating orders for expired or cancelled contracts. After
some investigation through the IMG, you determine that no configuration
exists to meet these requirements, so you think about adding custom
development.
Business Add-Ins (BAdIs) can handle some requirements, but what can you do
in situations when they cannot? Fortunately one tool at your disposal is the
event handler. With the event handler, you set the system to execute
function modules at specified points during business transaction processing
for objects such as the header, items, partners, and dates. Before I go into
some practical examples of when to use the event handler, let me briefly
introduce you to it.

Event Handler Overview

Transaction CRMV_EVENT maintains customizing table

CRMC_EVENT_CALL, whose entries comprise the event handler functionality.
The event handler is part of mySAP CRMs framework for handling the
processing of business transactions. Note that the event handler is a system
table and as such, you should not modify SAP entries without explicit
instructions from SAP, such as an SAP note. However, to suit your needs, you
can add entries to table CRMC_EVENT_CALL to adjust the way the system
processes business transactions.
Figure 1 shows the standard SAP settings for the event handler. These
settings control when a callback function, such as
CRM_DATES_ORDERADM_H_EC, should execute. To get a better idea of
what each field does, refer to Table 1, which provides a brief overview of the
key event handler fields.
Note
The screenprints in this article are from mySAP CRM 4.0, but the process also
applies to mySAP CRM 2005.

Figure 1
Standard entry from the event handler table
Event handler field

Function

Trans. Category

Controls the relevant business object for the business transactio

If you need an entry for all transaction types, use BUS20001.

Execution Time

Defines the point during transaction processing that you want yo

Depending on your requirements, the callback function either ex
the system processes the header (execution time 030).

Priority

Sets the order in which the callback functions execute with all ot
executes before a 99 priority.

Object Name

Corresponds to the business object, such as PARTNER for partn

ORDERADM_H for header

Event

Defines for which event the callback function should execute. Ex

executes before you save the changes) and AFTER_CHANGE (i.

Attribute

Filters for objects to improve performance by limiting the numbe

dates, and statuses use attributes. If you want your callback fun
the Attribute field blank or enter <*>.

Function

The name of your callback function module. Beginning with myS

function in this screen, you first must assign it to an object funct

Perform Function for Doc. Controls whether or not the system executes the callback functi
Header
Do Not Process Function
if Event Errors Occur

Controls whether or not the system should execute your callbac

Call Callback

Controls how often the system calls the callback function and wh
function

Table
Overview of the fields in an event
1
handler entry
Note
Using the event handler requires ABAP knowledge. In some cases, this article
references processes that may require the assistance of your technical team.
Note
Because the object function was introduced in mySAP CRM 4.0, if you
upgrade from mySAP CRM 3.0 or 3.1 to mySAP CRM 4.0 or higher, you need
to assign the callback functions to corresponding object functions.

Determine the Event Handler Settings

Now that you know what each field represents, how do you determine the
event handler settings you need to achieve your desired results (in this case,
preventing the system from creating an order for an expired contract)? A
quick and dirty method is through trial and error register a dummy function
module and check if the system seems to call it at an appropriate time.
Depending on your requirements, this actually may be the quickest method.
However, a more thorough analysis involves performing a trace to see which
settings you need to prevent the system from creating orders for expired
contracts. The trace lets you see which events and attributes the system
sets, which execution times the system reaches, and which objects the
system calls when it creates an order.
To perform a trace, create two sessions. Run the trace in one session and run
the create order transaction in the other session. For this example, in the first
session right-click to access the context menu and follow menu path User
Profile>Own Data. In the Parameters tab, set the parameter value to X for
the parameter ID CRM_EVENT_TRACE.
In the second session, perform the normal transaction that you use to create
an order. Next, in the first session call transaction CRMD_EVENT_TRACE
with your user ID and execute to display your trace. Figure 2 shows a
sample trace output captured when the system created an order.

Figure 2
Sample trace output. Click here to view a larger version of this image.
Notice that the trace information relates to the fields in the event handler
table in Table 1. With this information, you can determine how to configure
the event handler to suit your needs. For example, lines 17 to 26 in Figure 2
relate to the object APPOINTMENT, which represents the dates configured in
the business transaction. Under the Event in Program column, you can see
the events the system raised during order creation. Notice that line 18 relates
to the date type ORDERPLANNED for the event AFTER_CREATE. This allows
you to insert additional logic that the system triggers after it determines the
date type ORDERPLANNED.
Now lets take a look at four examples of how you can use the event handler,
starting with an examination of a standard event handler entry. Then Ill go
through three custom examples for various objects and events. The first
custom example is more detailed examining the entry field by field to give
you a feel for each of the fields. The final two custom examples involve using
the event handler for other common objects and events. These examples are
for illustrative purposes only.
Tip!
When you are done with your trace, you should unset the user parameter
CRM_EVENT_TRACE to avoid consuming too much memory.

Example 1

Recall that I mentioned that the event handler is a system table and as a
result, SAP uses it to process standard business transactions. To illustrate this
further, lets take a look at a standard SAP entry (Figure 3). This entry
corresponds to Available-to-Promise (ATP) functionality that occurs when
mySAP CRM carries out ATP checks when you save an order (as denoted by
the BEFORE_SAVE event).

Figure 3
Standard SAP entry in the event handler
In Figure 3, you might expect the system to call function module
CRM_CONFIRM_DEL_ER_SCHEDLIN_EC when you save an order. By placing
a breakpoint in the callback function, you can see that, as expected, the
system calls the function module when you save the order (Figure 4).

Figure 4
Callback function CRM_CONFIRM_DEL_ER_SCHEDLIN_EC breakpoint
Figure 4 also shows the callback functions import parameters, which pass
values from the calling program into the function module. For example, the
system passes the orders header globally unique identifier (GUID) into the
callback function, as shown by the field name IV_HEADER_GUID in Figure 4.
This is an important parameter to receive into a callback function because
you either can call function module CRM_ORDER_READ to retrieve
additional transactional data or pass it into function module CRM_ORDER_
MAINTAIN to change the business transaction.

Example 2
Standard mySAP CRM allows you to create follow-on documents to cancelled
and expired contracts, which can create a set of invalid orders. With the
event handler, you can block this from happening with the following steps.
Step 1. Create a shell function module in transaction code SE37. Call
it Z_CHECK_CONTRACT_BEFORE_CREATE. This function module prevents
the system from creating a sales transaction as a follow-on document to an
expired or cancelled sales contract. Using standard ABAP procedures, derive
the import parameters from another function module registered in the event
handler. Then specify an exception that you plan to raise when the
appropriate conditions are met (e.g., ABORT) as shown in Figure 5.

Figure 5
Sample interface for callback function
Step 2. Assign your function module to the object function
ORDERADM_H. In transaction CRMV_EVENT, click on the Object
Function/Callback button in the Definitions tab (Figure 6). In the screen
that appears, assign the object function CRM_ORDERADM_H to the callback
function Z_CHECK_CONTRACT_BEFORE_CREATE. The system calls it using
the header of the transaction (Figure 7).

Figure 6
Click on the Object Function/Callback button in transaction CRMV_EVENT

Figure 7
Assign the object function CRM_ORDERADM_H
Step 3. Adjust the event handler settings. In this case, I wont bother
with a trace because the entries are intuitive. Configure the following, as
shown in Figure 8:
Enter BUS2000115 (Sales) for the Trans. Category to prevent the

system from creating a sales transaction

Enter 1 (Immediately) for the Execution Time

Assign a 99 priority to specify that the system should call it last if any

other entries exist

Enter ORDERADM_H for the Object Name, so the system performs the

evaluation at the header

Enter BEFORE_CREATE_WITH_REFERENCE for the Event, so that the

system calls the function when it tries to create a follow-on document (in
my example, a sales order)
Select the Perform Function for Doc.Header check box so that the

function executes for only the header of the transaction. This prevents
the system from executing the function when any errors occur.
Select Do Not Process Function If Event Error Occurs to stop the

callback function when the system encounters an error

Select Call to Header/Item, with Object, Event, Attr., Old/New

Data from the Call Callback drop-down menu. This enables the system
to include the old data (i.e., data from the contract).

Figure 8
Adjust event handler settings
Step 4. Perform a cursory function check. A standard ABAP process, this
verifies that the system calls your function when you attempt to create a
sales transaction as a follow-on document to a sales contract. Place a
breakpoint in your function. In another session, create a sales transaction as
a follow-on document to the sales contract. The system should hit your

breakpoint and, as a result, you can proceed with further development of

your callback function.
Step 5. Edit your callback function in transaction SE37. Complete the
development of the callback function through unit tests, a standard ABAP
process in which you run and test one component of the system. The logic for
the completed function is shown in Figure 9. For a sample code that shows
you the completed callback function, see the file Sample code 1 in the
Downloads section at the end of this article.
* set structure of old data for evaluation * verify that the preceding document is a sales contra
call function 'CRM_ORDER_READ' * check if contract cancelled by checking cancellation reason
is expired by check date type CONTEND
Figure 9
Now the system prevents users from creating a sales transaction as a followon document to an expired or cancelled sales contract.
Example 3
This example involves a more complicated setup that shows how you can
integrate the event handler into other development. Imagine that you have a
requirement whereby you need to check for a particular date at the item level
(i.e., for a particular item category) and raise an error message if that date is
not filled in. For example, this could be the date an employee contacted the
customer, which you use for KPI reporting.
Standard mySAP CRM incompleteness check functionality doesnt allow you
to check only specified date types within a date profile it checks only for all
date types. As a result, you once again turn to implementing custom
development to meet this requirement. Find and implement the BAdI for
general item processing of item data by following IMG menu path
CRM>Transactions>Basic Settings>Business Add-Ins>Business AddIn for General Item Processing of Item Data. With this BAdI (in the check
method) the system immediately raises an error message when someone
adds an item to the order.
However, when you set the appropriate date in the item, the BAdI is no longer
hit, so you cannot remove the error message you raised. Fortunately, you can
add an entry into the event handler to check for the mandatory date type
whenever someone changes a date. With this setting, if the system finds the
date type, it removes the error message. To do this, enter the settings shown
in Figure 10.

Figure 10
Sample event handler entry to check date types
The system executes function module Z_DATE_CHECKS immediately for
sales orders at the item level when someone changes a date. You can view
the callback functions logic and code in the Sample code 2 file in the
Downloads section at the end of this article.
Now your BAdI implementation immediately raises the appropriate error
message when you add an item. The event handler entry repeats the same
date check until the date is filled in, at which point it removes the error
message.

Example 4
Finally, lets look at a useful event handler setting that includes the object
name ORDER with the event BEFORE_SAVE (Figure 11). This entry allows

you to register a callback function to check an order before you save it. This
can include, for instance, the need to check the completeness of the order or
the validity of field entries in the order. As mentioned earlier, you can make
this functionality available by passing the header GUID of the business
transaction into function module CRM_ORDER_READ to read data from the
business transaction and then perform subsequent checks against the data.

Figure 11
Register a callback function to check an order before you save it
In this last example, say you want to prevent users from saving a sales order
if the Sold- To field has a particular flag set in its master data record. For
example, you could use the Customer Class field to represent this flag and
define a value of 01 to represent that the Sold- To field is blocked (Figure
12).

Figure 12
Set the Customer Class to 01
In this case, use the event handler entry shown in Figure 11. Function module
Z_CHECK_ORDER reads the partners in the order, selects the sold-to party in
the order, and then checks for the flag maintained in the Customer Class
field in Figure 12. If the flag exists, the system raises an exception to prevent
the user from saving the order. While this is only an example, the event
handler setup allows you to perform virtually any order checking as needed.
You can view the code and logic for this in the Sample code 3 file in the
Downloads section at the end of this article.
The event handler is a system table, so upgrades may overwrite your entries
in it. As a result, an upgrade task should be to examine the event handler and
recreate entries as needed.