Creating an Event

Warming up

Before including an event declaration in your application’s code, you must follow these steps:

  1. Install the Notifications and Collaboration module. First of all the Notification and Collaboration module must be installed. To do this follow this link.
  2. Initialize the module’s data. For the basic data needed for the Event the Event Type initialization should be executed. For more information read Initializing event types.
  3. Create an event type

The next step is to create an Event Type for the event. The event type will be used to define how this event should be processed. For more information read Creating an Event Type.

Declaring an event in the application’s logic

After the previous steps are done, it is time to call the K2BTools.Notifications.NewEvent procedure.

In this section we will consider an example to illustrate how the API should be used. The example is declaring a “product price changed” event.

The NewEvent receives the following parameters:

  • EventTypeEntityName: The name of the Entity. In the example it will be “Product”

  • EventTypeName: The name of the Event Type. In the example it will be “PriceChanged”

  • EventTypeInstanceRef: The primary key of the Entity in which the Event occurs. In the example it will be the Product transaction primary key: ProductId.

  • RelevantData: Is an SDT that contains relevant data related to the Event. It contains information that will be substituted in the event type’s message templates.

    In the example, suppose that in the “Product PriceChanged” event type we have a message template for a web notification that says: "The price of the product %ProductDescription% has been changed. The previous value was %OldProductPrice% The new value is %NewProductPrice%."

    The values to be replaced must be in the RelevantData. So the RelevantData should be a collection containing these elements

    • {Name=ProductDescription, Value=ProductDescription}

    • {Name=NewProductPrice, Value=ProductPrice}

    • {Name=OldProductPrice, Value=ProductPrice.OldValue()}

  • EventExpirationDate: The date on which the event should expire, as described in Event expiration and cancelation. In this example, it may be determined that the price change is no longer relevant after 30 days.

  • EventTargetUrl: Is a url that shows the event’s data. In the example, it can be a link to the Product Entity Manager.

  • UserCodes: A collection of users to be notified about the event. These users will be notified along with those that subscribed to the event (if the event type supports user subscription). See more information in Creating an Event Type. In this example, it can be blank.

  • InhibitedSubscriptionUserCodes: There are many scenarios in which some subscribed users should not be notified about an event. For example, the user that performed an action should not be notified that the action took place. In the example, the user that changed the price should be included in this list.

A code sample is included below, showing how the example could be implemented. This implementation is divided into two parts: The transaction rules, and a procedure (called ProductPriceChangedEvent) to declare the event if needed.

In the Product transaction this rule is added

&ProductPriceOld = ProductPrice.GetOldValue() on AfterComplete;

ProductPriceChangedEvent(ProductId, ProductDescription, &ProductPriceOld, ProductPrice) on AfterComplete;
And the procedure should have the following implementation
if &OldProductPrice <> &NewProductPrice
    &RelevantDataItem = new()
    &RelevantDataItem.Name = !"ProductDescription"
    &RelevantDataItem.Value = &ProductDescription
    &RelevantData.Add(&RelevantDataItem)   

    &RelevantDataItem = new()
    &RelevantDataItem.Name = !"OldProductPrice"
    &RelevantDataItem.Value = &OldProductPrice.ToString().Trim()
    &RelevantData.Add(&RelevantDataItem)
   
    &RelevantDataItem = new()
    &RelevantDataItem.Name = !"NewProductPrice"
    &RelevantDataItem.Value = &NewProductPrice.ToString().Trim()
    &RelevantData.Add(&RelevantDataItem)

    NewEvent(!"Product", !"PriceChanged", &ProductId.ToString().Trim(), 
             &RelevantData, ServerDate() + 30, 
             EntityManagerProduct.Link(K2BTrnMode.Display, ProductId, ""), &UserCodes, &InhibitedUsers)

EndIf
Each time the Price of the Product is changed a notification will appear using the Delivery Medias supported by the Event Type (Imagen de una web notification)

When should the NewEvent procedure be called?

The NewEvent procedure can be called whenever the developer finds that an event should be triggered. The developer can call the procedure many times for the same event, the module will process these events as defined in the event type policy.

For more information, see Creating an Event Type.

Having performance / dropped connections / database locking issues?

Strategies to avoid these problems are found in Performance considerations creating multiple events.