configureEventsRequest

Defines the configuration name, what events should be tracked, event persistence, notifications, etc.

Request

<configureEventsRequest>
  <events type="Events"/>
</configureEventsRequest>

<Events enabled=””>
  <key/>
  <persistence/>
  <ipAddress/>
  <port/>
  <http/>
  <ignoreAfter/>
  <definition type="EventDefinition"/>
</Events>

<EventDefinition>
  <events>
  <type>
  <field>
  <containers>
  <subType>
</EventDefinition>

Response

<configureEventsResponse>
   <status>
      <code>0</code>
   </status>
</configureEventsResponse>

Definitions

enabled

Boolean. Enables or disables event processing. True (1) creates event records. False (0) disables event processing for that event configuration. Other event configurations are not affected.

key

String. Uniquely identifies the event configuration in a user's database. It is up to the application to control the uniqueness of the application key. GroupWise Web Services Events uses any key that it is passed. If two applications or two instances of an application pass the same key, GroupWise Web Services Events maps both to one event configuration structure in the user’s database.

persistence

A duration, from 0-20 days, that specifies how long old event records remain in a user’s database. If not defined, the default is seven days. For more information on how the persistence value is used to remove event records, see Event Records.

ipAddress

Identifies the IP address, DNS name, or the HTTP URL that should be used for event notification.

port

Identifies the IP port on which the application is listening for event notifications.

http

Specifies whether event notification should occur through TCP/IP or HTTP. If False (0), the value in ipAddress is treated as an IP address, and a TCP/IP stream is used for the notification. If True (1), the value in the ipAddress element is treated as an HTTP URL, such as http://www.acme.com/events.

ignoreAfter

Some applications are only concerned for events on items in a certain range of days. You can specify a number of days. If an event happens on an item that was created before the day limit, no event will be recorded.

--For GroupWise 8.0 SP2 and later.

events

Identifies the specific events that an application wants to track. For example, if an application wants to create event records when items are added and deleted from a folder, the event element contains FolderItemAdd ItemDelete. The list of event types is space-delimited. For a complete list of event types, see EventType in the events.xsd schema.

type

Identifies the specific item types that an application wants to track. For example, if an application wants to create event records only when a specific action occurs to appointments and tasks, the type element contains Appointment Task. The list of item types is space-delimited. For a complete list of item types, see itemType in the events.xsd schema.

field

Identifies the specific item fields that an application wants to track. The field element applies only to items that are modified. For example, if an application wants to create event records only when the PersonalSubject and Category fields are modified, the field element contains PersonalSubject Category. The list of fields is space-delimited. For a complete list of fields, see FieldList in the events.xsd schema.

containers

Identifies specific containers where an application wants to track folder events. If no container is specified, events are reported for all containers in the user's account, except folders shared with the user.

subType

Identifies a custom item type. Applications can create custom item types by adding the subType element when creating an item. The subType element is defined in the GroupWise types.xsd schema.

During the creation of the item, an application could provide a unique string in the subType element. For example, the application could provide Acme as the subType element and any items that are created have an Acme subType. Applications can search and filter items based on the subType element.

This is GroupWise Web Services implemention of className in the GroupWise Object API.

The GroupWise Web Services Events subType element can be used to track events only on the items that have a subType field that matches the subType. For example, if an application creates an item with a subType of Acme and wants to track all items with an Acme subType, the application provides Acme in the subType element while calling configureEventsRequest.

status

Specifies whether getEventsRequest was successful.

code

Provides the error number related to the event. 0 means that the request was successful.

Remarks

Applications call the configureEventsRequest method to create an event configuration for a GroupWise user. Event records are not created for a user unless this method is called.

Each configureEventsRequest takes a key as a parameter. The key is the name of the event configuration record. You can update an existing event configuration record by using the same key as an existing configuration record. Event definitions can be added at any time.

Event records will not be created unless the <enabled> element is set to True.

Users can have more than one event configuration. If an event applies to more than one configuration record, two separate event records are created, one for each event configuration.

In some cases, an event will not specify what container an item is in, such as an ItemModify event. It can be quite time consuming to retrieve the item because we need to validate that the application has rights to read the item. To speed up the validation, we put in a special format for an id when getting the item using getItemsRequest. The format is id@Event:uid, where id and uid are from the event. For example, here is an event:

<event>ItemModify</event>
  <id>4D51518E.domain.PO1.100.1776172.1.25DEE.1</id>
  <sid>155118</sid>
  <timeStamp>2011-02-08T21:26:02Z</timeStamp>
  <field>MessageBody</field>
  <key>test</key>
  <uid>585352</uid>
  <type>Mail</type>
</event>

The call to getItemsRequest would then be:

<getItemsRequest>
  <container>folders</container>
  <items>
    <item>4D51518E.domain.PO1.100.1776172.1.25DEE.1@Event:585352</item>
  </items>
</getItemsRequest>

We use the event record to validate that the user has access to the item. Thus, for this to work, the event record cannot be deleted before you try to read the item. To save one database read, the id can be formatted with the <sid> value instead of the <id> value. So the id for the above item could have been:

<item>155118@Event:585352</item>

Example

<configureEventsRequest>
   <events enabled="1">
      <key>AcmeEvents</key>
      <persistence>7</persistence>
      <ipAddress>app1.widgets.com</ipAddress>
      <port>5221</port>
      <event>
         <event>FolderItemAdd</event>
         <event>FolderItemMove</event>
         <event>FolderItemRemove</event>
         <event>ItemAccept</event>
         <event>ItemComplete</event>
         <event>ItemDecline</event>
         <event>ItemDelete</event>
         <event>ItemMarkRead</event>
         <event>ItemMarkUnread</event>
         <event>ItemPurge</event>
         <event>ItemUndelete</event>
            <type>Appointment Mail Note Task</type>
        </event>
      <containers>
         <container>7.AutoDomain.AutoPO1.100.0.1.0.1@16</container>
         <container>A.AutoDomain.AutoPO1.100.0.1.0.1@19</container>
      </containers>
   </events>
</configureEventsRequest>