Customizing the event mechanism for new business objects

If you create a new business object, you must determine what events will be generated for each action on the business object. When you have determined this, you must customize the event module configuration file so that the event module DLL can find events of that type. The name of the event module configuration file is event_code.txt, and it is located in $INFRANET$\sys\cm.

Infranet generates enough data for an event to enable the event module to identify what part of a storable class (in other words, what business object) has been invoked. When the event module gets an event, it gets an instance of a storable class containing information, such as the account, the user, and the calling program.

To differentiate an update from a delete or a create, the event module compares the original value and the updated one. To find out if a create or delete occurred, however, the event module must retrieve the storable class when the action is done at the root level, or it can look at the element ID for a child object. When a child is added, its element ID is positive and contains the position of this element in the array. If it is negative, it has been dropped.

Syntax of the event module configuration file

When modifying the event module configuration file, changes to the file must conform to the following syntax rules. This syntax must be strictly adhered to.

  1. Comment lines begin with two dashes.
  2. An event is described in one row. Parameters are delimited by the pipe character (|).
  3. A row follows this syntax:
    <event>|<Inf.action>|<array>|<key poid>|<constraints>|<BO.verb>|<priority>|<comment> 
     
    

    where:

    event Storable class name of the event
    Infranet action C (Create), U (Update), or D (Delete). This represents the action performed in Portal Infranet.
    array Portal Infranet code representing the array on which the action is done. The array is the Infranet element that must be retrieved from the event information.

    In Portal Infranet, each field has an associated number. For example, PIN_FLD_NAMEINFO is associated with the Infranet code 156. The list of fields and associated numbers can be found in the file $INFRANET$\Include\pin_flds.h.

    poid Portal Infranet code representing the field which is the key of the storable class created, updated, or deleted.
    constraints List of constraints necessary to determine exactly what happened. The constraint supports these keywords:
    • exists or not_exists: true or false specifying whether the object exists or not.
    • =, >, >=, <=, < : comparison operators for numerical types
    • equal, nequal, contains: comparison operators for string type.
    • & is used to separate constraints. The constraints are true only if all conditions separated by & are true.

    If you want to specify an or, use several lines. The first line in which the constraints are true is executed.

    BO.verb Name of the business object and verb corresponding to the action in Portal Infranet.
    priority Priority of the event
    comment Comment to insert in the event table

Example event module configuration file

The text below shows an example of an event_code.txt file. This example includes lines specifying events for the account storable class. Lines beginning with dashes are comments.

-- Account creation: PIN_FLD_STATUSES[0].PIN_FLD_STATUS[0] = 0 &
       PIN_FLD_SYS_DESCR = "Set Status (acct)": OK
 /event/customer/status |U |144  |40  |40 exists&55;5 equal "Set Status
       (acct)"&144:0-145;3 = 0 |Portal_Account.Create |1 |Account Creation
  
 -- Account Updated (status updated) : PIN_FLD_STATUSES[1].PIN_FLD_STATUS[0] =
       10100 or 10103 or 10102 & & PIN_FLD_SYS_DESCR = "Set Status (acct)" : OK
 /event/customer/status |U |144  |40  |40 exists&55;5 equal "Set Status (acct) 
       "&144:1-145;3 > 0 |Portal_Account.Update |1 |Status Updated
  
 -- Account Updated (new contact added):OK
 /event/customer/nameinfo |C |156 |40|40 exists|Portal_Account.Update|1|new contact 
  
 -- Account Updated (contact updated): OK
 /event/customer/nameinfo |U |156 |40 |40 exists&17;5 equal "Customer Mngmt. Event
       Log" |Portal_Account.Update |2 |contact_update
  
 -- Account Updated (contact deleted):OK
 /event/customer/nameinfo |D |156  |40  |40 exists&67;5 nequal "Automatic Account
       Creation"|Portal_Account.Update |2 |contact_delete
  
 -- Account Updated (billinfo updated) : two PIN_FLD_BILLINFO and
       PIN_FLD_BILLINFO[0].PIN_FLD_BILL_TYPE[0] <> 0 : OK
 /event/customer/billinfo |U |126  |40 |40 exists & 126:0-127;3 > 0
       Portal_Account.Update |2 |billinfo_update
 

Defining event configuration file entries

When an event occurs, Infranet generates an flist representing the event. The event facilities module examines the flist to identify the verb and the action that occurred.

For example, assume an flist representing an event is:

0     PIN_FLD_POID            POID [0] 0.0.0.1 /event/customer/nameinfo -1 0
 0     PIN_FLD_NAME             STR [0] "Customer Mngmt. Event Log"
 0     PIN_FLD_USERID          POID [0] 0.0.0.1 /service/admin_client 2 1
 0     PIN_FLD_SESSION_OBJ     POID [0] 0.0.0.1 /event/session 10366 0
 0     PIN_FLD_ACCOUNT_OBJ     POID [0] 0.0.0.1 /account 9406 32
 0     PIN_FLD_PROGRAM_NAME     STR [0] "Admin Manager"
 0     PIN_FLD_START_T       TSTAMP [0] (942104217) 11/08/99 15:36:57
 0     PIN_FLD_END_T         TSTAMP [0] (942104217) 11/08/99 15:36:57
 0     PIN_FLD_SYS_DESCR        STR [0] "Set Name Info"
 0     PIN_FLD_NAMEINFO       ARRAY [0] allocated 20, used 17
 1     PIN_FLD_SALUTATION       STR [0] ""
 1     PIN_FLD_LAST_NAME        STR [0] "Event Test1"
 1     PIN_FLD_LAST_CANON       STR [0] "event test1"
 1     PIN_FLD_FIRST_NAME       STR [0] "Event Test1"
 1     PIN_FLD_FIRST_CANON      STR [0] "event test1"
 1     PIN_FLD_MIDDLE_NAME      STR [0] ""
 1     PIN_FLD_MIDDLE_CANON     STR [0] ""
 1     PIN_FLD_TITLE            STR [0] "Event Test1  "
 1     PIN_FLD_COMPANY          STR [0] "Event Test1"
 1     PIN_FLD_ADDRESS          STR [0] "Event Test1"
 1     PIN_FLD_CITY             STR [0] "Event Test1"
 1     PIN_FLD_STATE            STR [0] "CA"
 1     PIN_FLD_ZIP              STR [0] "00000"
 1     PIN_FLD_COUNTRY          STR [0] "US"
 1     PIN_FLD_EMAIL_ADDR       STR [0] ""
 1     PIN_FLD_CONTACT_TYPE     STR [0] "Billing"
 1     PIN_FLD_ELEMENT_ID      UINT [0] 1
 0     PIN_FLD_NAMEINFO       ARRAY [1] allocated 20, used 19
 1     PIN_FLD_SALUTATION       STR [0] ""
 1     PIN_FLD_LAST_NAME        STR [0] "Event Test1"
 1     PIN_FLD_LAST_CANON       STR [0] "event test1"
 1     PIN_FLD_FIRST_NAME       STR [0] "Event Test1"
 1     PIN_FLD_FIRST_CANON      STR [0] "event test1"
 1     PIN_FLD_MIDDLE_NAME      STR [0] ""
 1     PIN_FLD_MIDDLE_CANON     STR [0] NULL str ptr
 1     PIN_FLD_TITLE            STR [0] "Event Test1"
 1     PIN_FLD_COMPANY          STR [0] "Event Test1"
 1     PIN_FLD_ADDRESS          STR [0] "Event Test1"
 1     PIN_FLD_CITY             STR [0] "Event Test1"
 1     PIN_FLD_STATE            STR [0] "CA"
 1     PIN_FLD_ZIP              STR [0] "00000"
 1     PIN_FLD_COUNTRY          STR [0] "US"
 1     PIN_FLD_EMAIL_ADDR       STR [0] ""
 1     PIN_FLD_CONTACT_TYPE     STR [0] "Billing"
 1     PIN_FLD_ELEMENT_ID      UINT [0] 1
 1     PIN_FLD_CANON_COUNTRY    STR [0] "US"
 1     PIN_FLD_CANON_COMPANY    STR [0] "event test1"
 0     PIN_FLD_ITEM_OBJ        POID [0] 0.0.0.1 /item 11454 0
 0     PIN_FLD_CURRENCY        UINT [0] 840
 

When adding a line to the event module file, you must specify the number associated with the field instead of the field name. For example, the field PIN_FLD_NAMEINFO, as shown in bold in the preceding flist, is represented by the code 156.

For a field that is deeper than the first level of the flist, you must use a constraint to identify the field. With the exception of a constraint, each field is identified by a simple number, which is the number associated with the field.

Because a given event can be generated for various reasons, sometimes constraints are required to determine whether an event is the result of a particular business object. Therefore, you may need to add constraints such as exists.

The following syntax must be used in a constraint to identify a field.

[<array code:array element>-field;type]
 

For example, if the Infranet code 156 represents PIN_FLD_NAMEINFO, and the code 161 represents PIN_FLD_LAST_NAME, the representation of the field PIN_FLD_LAST_NAME contained in the array PIN_FLD_NAMEINFO of element ID 1 is represented in a constraint related to this field with 156:1-161;5 = PINFLDNAMEINFO[1].PIN_FLD_LASTNAME

The last number following the semicolon in a constraint represents the type of the object. The type indicates the type of data on which the comparison must be performed. For example, the number 5 indicates a string. For more information, see the list of associated types in $INFRANET$\Include\pin_type.h.

Adding events to the pin_notify_cw file

When you add new business objects, you must also add events to the pin_notify_cw file. This file contains the names of the connector events. To add events, follow the standard format of the file as seen inDefining event configuration file entries.

The CrossWorlds Event Notification Module (FmCw.dll) verifies the USERID of any Portal Event sent to it (defined in the pin_notify_cw file). If there is no PIN_FLD_USERID associated with the event sent to the module, it will error and cause problems saving the object online. These types of events need to be adjusted (f-lists or the storable classes) to include such an ID. Check for these errors in the log file defined in the crossworlds.cnf configuration file.

The Event Module checks for a USERID to prevent events sent into the application by the connector from being added to the event queue. This is referred to as Ping-Ponging. The "/event/customer/billinfo" is an example of an event type where such a problem exists.

Note:
To identify all the events generated for an Infranet operation, call the event module for all Infranet events (using /event in the load_pin_notify configuration file). The event module will then be triggered for all events raised. Set the log level to 3 in the event module configuration file, and then in the pinlog.log file, you will have the event flist sent by Infranet for this operation.

Copyright IBM Corp. 1997, 2003