Event Definitions

All of the out-of-the-box events in MicroStrategy Web are defined in an event definition XML file called events.xml (located by default in the WEB-INF/xml/config subfolder of your MicroStrategy Web installation). This file contains the definition of the events (which includes the name and the mapping to the set of arguments it uses) for the application and SDK components, including:  

• the events of the Servlet or ASP.NET file, pages, and the application and SDK beans 

• the list of arguments expected by the event 

• the names of arguments as they should appear in the URL.

The unique identifiers for each of the events supported by a bean are defined in an interface named Enum<bean type>BeanEvents.java , where <bean type> has a value such as Admin, View, Wizard, UserFrame, and so on. Each interface also defines the identifiers for all the arguments for each event it contains. All of these interfaces are declared in one of three packages— com.microstrategy.web.beans, com.microstrategy.web.app.beans, and com.microstrategy.web.admin.beans.

A complete list of event handlers associated with all beans can be found in the Event Handlers Reference.

Sample event definition code

Event definitions are grouped by event handler type. The following code sample shows two events that the event handler of type 4 (that is, the event handler for reports) can support. The first event is a pivot event with an id = 4002; the second event is a disable subtotal event with an id = 4007. The child nodes define the arguments for each event. For each child <argument> node, there is an argument ID, the argument name, and an attribute (that is, the required attribute) indicating whether the argument is required for processing this event.

Required event arguments

The required attribute in the <argument> node of events.xml accepts either “0” or “1” to indicate whether a single specific value for an event argument is required. In the sample code above, all but one of the arguments is required for the first event. If the application does not find each of these arguments during validation, it throws an exception. However, it is possible to define a group of event arguments, where only one— but at least one— of the arguments is required. Validation succeeds if the application can find any one of the arguments in the group. The required attribute value "1" still marks a single argument as required. This scheme simply extends the concept of a required argument to include multiple options that can meet the requirement.

To create a group of values for a required argument, you must create a separate <argument> node for each argument in the group and set the required attribute in each node to the same group number. You can use any cardinal number other than “0” or “1”. The only requirement is that each argument in the same group must use the same group number for the required attribute.

If the application does not find a single required event argument or at least one of a group of required arguments during validation, GenericWebEvent#validateRequiredArguments throws an appropriate exception. This needs to be explicitly invoked in the event handler.

The sample code below illustrates how to group arguments for the folder browsing event. In this example, the folderID and systemFolder arguments each use the same value— “4”— as the value of the required attribute, indicating that they are in the same group.  As a result, the browse event (that is, the event to which these required arguments belong) expects at least one of the following to be defined: folderID or systemFolder. (Remember that the specific number used as the value of the required attribute is not important— only that the same number be used for all arguments in the same group.)

The table below provides an explanation for the event defined above— including the name and ID of each event argument and whether or not it is required (represented by the values of the appropriate attributes in each <argument> node), as well as a description of the argument and the name of the associated argument constant (from the enumeration).

See also

• Implementing custom events: Creating a Custom Event