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 CRM’s 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.

Figure 1

Standard entry from the event handler table

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 let’s 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 I’ll 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.

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, let’s 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 function’s import parameters, which pass values from the calling program into the function module. For example, the system passes the order’s 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 won’t 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.

* set structure of old data for evaluation  
* verify that the preceding document is a sales contract
* get contract details
       call function 'CRM_ORDER_READ'
* check if contract cancelled by checking cancellation reason field
* check if contract is expired by check date type CONTEND

Now the system prevents users from creating a sales transaction as a follow-on 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 doesn’t 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 Add-In 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.

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, let’s 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.

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.