Professional Documents
Culture Documents
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
Figure 1
Standard entry from the event handler table
Event handler field
Function
Trans. Category
Execution Time
Priority
Sets the order in which the callback functions execute with all ot
executes before a 99 priority.
Object Name
Event
Attribute
Function
Perform Function for Doc. Controls whether or not the system executes the callback functi
Header
Do Not Process Function
if Event Errors Occur
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.
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
Assign a 99 priority to specify that the system should call it last if any
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
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
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.