Implementing an event detection mechanism

After you determine the business process to support (for example, sales quotes or sales orders), and determine the preferred event detection mechanism, implement the mechanism for your business process.

Note:
When implementing an event detection mechanism, it is a good idea to support all of the functionality for a business process in one mechanism. This limits the impact in the SAP application and makes event detection easier to manage.

The following sections describe the implementation process for the four event detection mechanisms implemented by the connector. Whenever applicable, an example is provided along with sample code.

Code enhancement

Code enhancement requires encapsulating a portion of ABAP code in a custom function module. The event detection code is written as a function module to ensure that the processing remains separate from the transaction. Any tables or variables used from the transaction need to be passed to the function module by value and not by reference.

To minimize the effects of locking a business object when retrieving an event, the function module typically executes in an update-task mode. To avoid inconsistencies, do not use update task if the function module is already being called within a process that is in an update -task mode.

To minimize the impact in the transaction, place the function module within another include program. Using an include program allows you to make changes to custom code rather than to SAP code.

The event detection code contains logic that identifies the object for the event. For example, the sales order transaction handles many types of orders, but only one order type is required. This logic is in the event detection code. The general strategy for placing this event detection code is to insert it just before the data is committed to the database. The function module containing the event detection code is typically created as a part of the function group for the business object.

To implement Code enhancement for event detection:

The following steps describe the process of creating an example SAP sales quote using the code enhancement event detection mechanism. The code that follows it is a result of this process.

  1. Upon investigation of the SAP sales quote transaction, transaction VA21 is found to support the desired sales quote creation business process.
  2. The sales quote number is determined to be the unique key. The Sales quote number is stored in table/field VBAK-VBELN.
    Note:
    Because this event uses a single unique key, the code example uses the OBJKEY parameter to pass the key's value. For an example of coding an event that uses a composite key, see Coding composite keys as name-value pairs.
  3. Transaction VA21 has a user exit in the transaction flow as part of the document save process (Form Userexit_save_document). At this point in the transaction, the quote number is available when the user exit is executed.
  4. The user exit belongs to other business processes, so additional coding is needed to differentiate a sales quote from other categories of documents. VBAK-VBTYP is available to determine the document category. A sales quote is saved in the SAP database with a document category of B.
  5. An include statement is added to the user exit that points to the include program.
  6. At this time, the include program and a function module need to be created.

/CWLD/ADD_TO_QUEUE: single key value example

The following code fragment illustrates the function call to the /CWLD/ADD_TO_QUEUE event trigger (using a single key value).

If VBAK-VBTYP = 'B'.
      C_OBJ_ORDER = 'SAP4_SalesQuote'.
         TMP_OBJKEY = XVBAK-VBELN.
    TMP_EVENT = 'Create'.
 
      CALL FUNCTION '/CWLD/ADD_TO_QUEUE'
            EXPORTING
                  OBJ_NAME                = C_OBJ_ORDER
                  OBJKEY                  = TMP_OBJKEY
                  EVENT                   = TMP_EVENT
                  GENERIC_RECTYPE = ''
            IMPORTING
                  RECTYPE                 = TMP_RECTYPE
            TABLES
                  EVENT_CONTAINER = TMP_EVENT_CONTAINER
            EXCEPTIONS
                  OTHERS                  = 1.
 
Endif.

/CWLD/ADD_TO_QUEUE_IN_FUTURE: single key value example

The following code fragment illustrates the function call to the /CWLD/ADD_TO_QUEUE_IN_FUTURE event trigger (single key value).

DATA: DATE_IN_FUTURE LIKE SY_DATUM.
 
DATE_IN_FUTURE = VBAK-VDATU.
 
If VBAK-VBTYP = 'B'.
      C_OBJ_ORDER = 'SAP4_SalesQuote'.
         TMP_OBJKEY = XVBAK-VBELN.
    TMP_EVENT = 'Create'.
 
      CALL FUNCTION '/CWLD/ADD_TO_QUEUE_IN_FUTURE'
            EXPORTING
                  OBJ_NAME               = C_OBJ_ORDER
                  OBJKEY                 = TMP_OBJKEY
                  EVENT                  = TMP_EVENT
                  VALID_DATE             = DATE_IN_FUTURE
            IMPORTING
                  RECTYPE                = TMP_RECTYPE
            TABLES
                  EVENT_CONTAINER        = TMP_EVENT_CONTAINER
            EXCEPTIONS
                  OTHERS                 = 1.
 
Endif.

Coding composite keys as name-value pairs

If an event's key is composed of multiple fields rather than a single key field, you can specify the name of each key attribute and its corresponding value. Because you specify the attribute's name, the attribute need not be marked as IsKey for the connector to populate it and use it for retrieval.

If you specify more than one name-value pair, the connector sets the value of multiple attributes in the business object it creates to retrieve the full object from the application. If you specify a single name-value pair, the connector sets the value of the specified attribute rather than the first attribute that is marked IsKey.

Because IDoc handlers do not use name-value pairs, it is important that you not specify name-value pairs when using /CWLD/IDOC_HANDLER. For more information, see IDoc handlers and the retrieve verbs.

The following steps describe the process of creating an example SAP sales quote that uses three fields in its composite key. The code that follows it is a result of this process.

  1. Create a local name_value_pairs internal table based on the structure (/CWLD/NAME_VALUE_PAIRS) delivered with the adapter. This structure has two columns: ATTR_NAME and ATTR_VALUE.
  2. Before calling the function module /CWLD/ADD_TO_QUEUE or /CWLD/ADD_TO_QUEUE_IN_FUTURE, write code that adds the names of the key attributes and their values to your internal table.
  3. Change the function module /CWLD/ADD_TO_QUEUE or /CWLD/ADD_TO_QUEUE_IN_FUTURE:
  4. The triggering function automatically formats each event key. The format uses the following syntax:
    attribute1=value1|Cx|attribute2=value2|Cx|[attributeN=valueN|Cx|]
    

    where:

    attribute
    The name of the key attribute (not case-sensitive)

    value
    The value of the key attribute (case-sensitive)

    |Cx|
    Terminator for each name-value pair (used even if only one name-value pair is specified)

The order in which you specify name-value pairs in your code need not match the order of the attributes in the business object. However, the event fails if you specify an attribute that does not exist in the business object.

The following code fragment specifies, at the time of triggering, the customer number, sales organization, and distribution channel in table KNVV as name-value pairs. Two lines are highlighted in the code for the function module /CWLD/ADD_TO_QUEUE:

DATA:  name_value_pairs LIKE /cwld/name_value_pairs OCCURS 5 with header line.
 
MOVE   'CustomerId' TO name_value_pairs-attr_name.
MOVE   knvv-kunnr TO name_value_pairs-attr_value.
APPEND name_value_pairs.
 
MOVE   'SalesOrg' TO name_value_pairs-attr_name.
MOVE   knvv-vkorg TO name_value_pairs-attr_value.
APPEND name_value_pairs.
 
MOVE   'DistributionChannel' TO name_value_pairs-attr_name.
MOVE   knvv-vtweg TO name_value_pairs-attr_value.
APPEND name_value_pairs.
If VBAK-VBTYP = 'B'.
      C_OBJ_ORDER = 'SAP4_SalesQuote'.
         TMP_OBJKEY = XVBAK-VBELN.
    TMP_EVENT = 'Create'.
 
      CALL FUNCTION '/CWLD/ADD_TO_QUEUE'
            EXPORTING
                  OBJ_NAME               = C_OBJ_ORDER
*                 OBJKEY                 = TMP_OBJKEY
                  EVENT                  = TMP_EVENT
                  GENERIC_RECTYPE = ''
            IMPORTING
                  RECTYPE                 = TMP_RECTYPE
            TABLES
                  NAME_VALUE_PAIRS = name_value_pairs
                  EVENT_CONTAINER = TMP_EVENT_CONTAINER
            EXCEPTIONS
                  OTHERS                  = 1.
 
Endif.

Batch program

To implement batch program as an event detection mechanism, you must write an ABAP program that evaluates database information. If the criteria in the ABAP program is fulfilled when the program executes, then an event is triggered.

To implement batch program for event detection:

The following steps describe the process of creating a batch program that detects events for all sales quotes created on today's date. The code that follows it is a result of this process.

  1. Create is determined to be the supported verb.
  2. The quote number is determined to be the unique key used to retrieve the events.
  3. The creation date (VBAK-ERDAT) and the document category (VBAK-VBTYP) need to be checked.

The following sample code supports the SAP sales quote as a batch program:

REPORT ZSALESORDERBATCH.
 
tables: vbak.
 
parameter: d_date like sy-datum default sy-datum.
 
data: tmp_key like /CWLD/LOG_HEADER-OBJ_KEY,
      tmp_event_container like swcont occurs 0.
 
" retrieve all sales quotes for today's date
" sales quotes have vbtyp = B
select * from vbak where erdat = d_date
                     and vbtyp = 'B'.
 
  tmp_key = vbak-vbeln.
 
  CALL FUNCTION '/CWLD/ADD_TO_QUEUE'
       EXPORTING
            OBJ_NAME        = 'SAP4_SalesQuote'
            OBJKEY          =  tmp_key
            EVENT           = 'Create'
            GENERIC_RECTYPE = ''
       IMPORTING
            RECTYPE         = r_rectype
       TABLES
            EVENT_CONTAINER = tmp_event_container.
 
  write: / vbak-vbeln.
endselect.

Business workflow

Business workflow is a set or sequence of logically related business operations. The processing logic within a workflow detects events. The business workflow event detection mechanism relies on the SAP Business Object Repository (BOR), which contains the directory of objects along with their related attributes, methods, and events.

To implement business workflow for event detection:

The following example of SAP sales quote can be used to implement an event trigger using business workflow:

  1. Search the BOR for the appropriate sales quote business object. A search can be done using the short description field and the string '*quot*'. BUS2031 (Customer Quotes) is one of the business objects returned.
  2. Upon further investigation of BUS2031, it is determined that the key field is CustomerQuotation.SalesDocument (VBAK-VBELN).
  3. A subtype for BUS2031 is created using the following entries:

    Object type--ZMYQUOTE

    Event--SAP4_SalesQuote

    Name--SAP4 Sales Quote

    Description--Example of an SAP 4 Sales Quote Subtype

    Program--ZMYSALESQUOTE

    Application--V

  4. The event detection mechanism is activated by adding an entry to the Event Linkage table (transaction SWE3). The create event is activated using the following entries:

    Object type--ZMYQUOTE

    Event--SAP4_SalesQuote

    Receiver FM--/CWLD/ADD_TO_QUEUE_DUMMY

    Receiver type FM--/CWLD/ADD_TO_QUEUE_WF

Note:
The Receiver and Receiver type function modules (FM) point to /CWLD/ADD_TO_QUEUE. The DUMMY function module is used only because sometimes the SAP application requires that both fields be populated. The WF function module translates the SAP standard interface to the one used by /CWLD/ADD_TO_QUEUE.

The business workflow event detection mechanism is created and active. It is set up to detect all SAP Customer Quotes that are created.

Change pointer

Change pointer uses change documents and is one of the more challenging event detection mechanisms to implement. SAP's Business Object Repository (BOR) is used as well as Application Link Enabled (ALE) technology. A change document always refers to a business document object having at least one database table assigned to it. If the data element in a table is marked as requiring a change document and the table is assigned to a business document object, then a change in value of the field defined by the data element generates a change document. The changes are captured in tables CDHDR and CDPOS and are used for event detection.

To implement change pointer for event detection:

The following example of an SAP sales quote can be used to implement an event trigger using change pointer:

  1. Update is determined to be the supported verb. Investigating the sales quote create transaction shows that the Create verb is not detected through this mechanism.
  2. When performing the checks of the business for sales quote:
  3. No evaluation of data elements was done for this example.
  4. The sales quote number is determined to be the unique key in CDHDR-OBJECTID.
  5. CDHDR-OBJECTCLAS has a value of VERKBELEG, which is the main differentiator. Only sales quotes should be picked up. The code checks the TCODE field in the header table, but a proper lookup should be done in the VBAK table.

The following sample code is added to /CWLD/EVENT_FROM_CHANGE_POINTR:

when 'VERKBELEG'.
   data: skey    like /cwld/log_header-obj_key,
      s_event like swetypecou-event,
      r_genrectype like swetypecou-rectype,
      r_rectype like swetypecou-rectype,
      t_event_container like  swcont occurs 1 with header line.
 
   " Quick check. Should check document category (VBTYP) in VBAK.
   check header-tcode = 'VA22'.
 
   " Event detection has started
   perform log_create using c_log_normal c_blank
                              c_event_from_change_pointer c_blank.
 
   " Set the primary key 
   skey = header-objectid.
 
   " Set the verb
   s_event = c_update_event.
 
   " Log adding the event to the queue
   perform log_update using c_information_log text-i44
                            'SAP4_SalesQuote' s_event skey.
 
      " Event detection has finished.
      perform log_update using c_finished_log c_blank
                               c_blank c_blank c_blank.
 
   call function '/CWLD/ADD_TO_QUEUE'
      exporting
            obj_name                  = 'SAP4_SalesQuote'
            objkey                    = skey
            event                     = s_event
            generic_rectype           = r_genrectype
      importing
            rectype                   = r_rectype
      tables
            event_container           = t_event_container
      exceptions
            others                     = 1.

Copyright IBM Corp. 1997, 2004