1.3 Event Life Cycle

This section helps you learn GroupWise Web Services Events from the perspective of an event listener application and the GroupWise POA. It covers the following topics:

1.3.1 Application Perspective

Applications can track events for one or many GroupWise users. In order to call any of the event methods, you first need to call loginRequest on a specific user. The event methods will apply to that user.To track events, an application should perform the following basic steps:

  1. Call the configureEventsRequest method to set up event configurations for each GroupWise user.

    In this step, applications tell the POA which event types they want to track. The configureEventsRequest method also tells the POA if the application should be notified when an event takes place.

    Applications should listen for notifications. Listening reduces network traffic and reduces the workload on the POA. If notifications are not used, the POA might need to handle dredging requests from applications for many users (which increases the work load on the POA).

    However, applications are not required to listen for notifications. An application can periodically call the getEventsRequest method to get a list of changes for a user.

  2. If notifications are enabled, the application listens for notifications from the POA.

    A notification provides a userid and configuration key. A notification looks like the following:

    <notify>
       <userid>username</userid>
       <key>Key Name</key>
    </notify>\r\n
    

    Each notification ends with the \r\n characters.

  3. When the application receives a notification from the POA, the application can spin off a worker thread to call getEventsRequest.

    The response from the getEventsRequest method provides additional information such as the event type, item ID, and time the item changed.

  4. If the application requires more information, it calls getItemsRequest to retrieve the details for each item.

    The getItemsRequest method is part of GroupWise Web Services and allows you to retrieve a list of items, no matter where the item is located in a mailbox. For an example, see the getItemsRequest method.

    You should limit the number of items that you retrieve in a single iteration of getItemsRequest. We recommend that you retrieve no more than 250 items.

1.3.2 Post Office Agent Perspective

The GroupWise Post Office Agent (POA) handles the delivery and other events for each user on the post office. When an event occurs on a user's mailbox, the POA performs the following basic steps:

  1. Checks to see if there are event configurations for the user.

  2. If there are event configurations, it determines if any of the event configurations match the triggered event.

  3. If there is a match, it creates an event record in the GroupWise user's store that describes the event.

  4. If notifications are enabled, the POA notifies the application an event has occurred.

    After the notification, the application is removed from the notification list. However, the application can re-insert itself into the notification list by calling getEventsRequest and passing True for the notify element. Prior to GroupWise 8.0.2, the user was dropped from the notification list whether or not the notification is sent. Now, the user is not removed from the notification list, but is inactive. That is, the user will not be notified if a new event happens, until the application calls getEventsRequest and passes True for the notify element.

  5. The POA does not wait for an ACK from the application because the notification was patterned after UDP.

To help reduce the load on the POA, we recommend that applications throttle the number of getEventsRequest methods that occur per user. A good idea is to have only one getEventsRequest method in progress per user at any single time.

1.3.3 Other POA Duties

The POA has other management responsibilities for GroupWise Web Services Events. The POA also accepts SOAP requests from applications to handle the following methods:

Method

Description

configureEventsRequest

Creates a new event configuration record for a specific user. It defines what type of events are stored in an event record in the user's store. It also defines the notification address.

getEventConfigurationRequest

Returns the selected configuration or all configurations for a specific user.

getEventsRequest

Returns the list of events that have occurred for a specific user.

getItemsRequest

Returns the specified items. This method is usually called after the application has been notified. The application then calls getEventsRequest and gets a list of items that have changed. The getItemsRequest method is used to retrieve the changed items.

removeEventConfigurationRequest

Removes an event configuration for a specific user.

removeEventsRequest

Removes event records stored in a user's store.

cleanEventConfigurationRequest

Deletes event records in a user's database, based on how long the item has been in the store. It is used for nightly maintenance to reduce the size of user's stores.