MicroStrategy ONE

Processing Events during Page Execution

After the beans on the page have been instantiated and initialized, the application is ready to process events. Every request to MicroStrategy Web corresponds to a specific event, or action. An event is the structure used by MicroStrategy Web to identify both the actions that must be performed and the component that should execute the actions. These actions modify the state of the beans and, ultimately, the page that is displayed to the user.

Click on any box in the diagram to see a detailed explanation of that step in page execution. Click here to return to the Overview of Page Execution.

Each event comes with an associated list of required and optional parameters that define the specific request. Within a request, an event is identified by the evt parameter whose value represents an event ID. For example, in the parameter name/value pair,evt=4001, 4001 is the ID of  the event that needs to be handled. The Event Handlers Reference contains a comprehensive list of default event names and IDs for all valid events.

Determining where the event will be handled

When an event occurs, the Controller attempts to handle it first, followed by the page, and then the Web bean. Events are delegated downward until the event is handled, in the order described below.

  1. The Controller basically handles events that require page redirection, such as login, accessing the Report page from the Folder Browsing page, and accessing the Folder Browsing page by clicking a link in the navigational path from the Report page.

    • If the request does not contain a valid event, the Controller automatically executes the WebEventOpenHome event. This event selects the Welcome page, which presents a list of available projects to the user.  

    • If the request contains a valid event and there is a src parameter and the Controller can handle the event, it locates the name of the source page and delegates the event to that page, as described in the step below describing how pages handle events.  

    • If the request contains a valid event and there is no src parameter and the Controller can handle the event, it performs the corresponding actions and page execution continues.  

  2. The page handles events that might affect any bean on the page, such as changing preferences or showing/hiding beans on that page.

    • If the page can handle the event, it performs the corresponding actions and page execution continues.  

    • If the page cannot handle the event, it delegates the event to the Web bean at the next level down, as described in the step below.

  3. Web beans handle events that request the bean to change its status— such as pivoting, sorting, drilling, or refreshing data on the Report page and adding or removing elements on the Prompt page.  

    • If the bean can handle the event, it performs the corresponding actions and page execution continues.  

    • If the bean cannot handle the event, it delegates the event to its child Web bean, as specified in the src parameter.  

Events must be handled by an event handler. An implementation class of EventHandler is associated with the Controller, with each page, and with each Web bean in MicroStrategy Web products. Each event is represented by an event ID, a source location, and arguments (name/value pairs) related to that event.

Mapping one event to another

The path to the bean that originates an event is specified in the src parameter of the request URL. The Controller retrieves this parameter so the event can be processed by the same bean that submitted the event in the first place. However, you can use an event map to modify this behavior. An event map allows you to have a particular Web bean handle an event that it did not originate, based on the information from another event. This can be useful, for example, if you want to have a page generate (and display to the user) links to events that it does not handle.

Event maps for a MicroStrategy Web page are defined in the Page Configuration file. The <event-map> node requires an id attribute (the ID of the original event), a map-id attribute (the ID of the event to map to), and a target attribute (the name of the bean that should handle the request).

Copy 
<event-maps>
    <event-mapid="3032"map-id="128004"target="objectWebSubs">
       <argument id="3001" map-id="128005" />
       <argument id="3007" map-id="128006" />
    ...
</event-maps>

Handling requests with multiple events

A request can contain one or more events (that is, one or more evt parameters). When multiple events are included in a request, only valid events are handled. A valid event is one that has:

  • an event parameter, in the format evt=ID (where ID is the event ID)  

  • a source parameter, in the format src=path.ID  (where path is the path to the bean originating the event and ID is the event ID)   

  • an ID parameter value, in the format ID=xyz (where xyz can be any value ) 

The application attempts to handle multiple events in a request as follows:

  • If there is no valid event in the request, the application automatically executes the WebEventOpenHome event. This event selects the Welcome page, which presents a list of available projects to the user.  

  • If there is only one valid event in the request, the application processes the event after it has selected it.  

  • If there are multiple valid events in the request, the application first identifies all of the events that need to be processed. For each event, it filters the RequestKey object so that it contains only one evt and one src tag and then processes each event individually, using the filtered RequestKey. By design, after each event is processed, the application checks to make sure that the status is "Successful".  If it is not, the remaining valid events are not processed.

If  you want to specify the precise order in which multiple events should be processed, you simply specify the list of events in the ServletEvent.URL_EVENT_ORDER argument (evtorder), in the order in which they should be executed. The application checks the value of this argument and processes the events in this list, in the order in which they appear, before it processes any other events found in the request.

Multiple events allow you to control the flow of page execution, including the ability to specify the precise order in which multiple events should be processed. While the Controller itself does not have the ability to redirect or specify page flow, you can cause different pages to be processed during a single request by sending multiple events in the request. After one page has finished processing, a different page can be displayed.

Customization

Customizing event processing requires both Java programming and the customization of XML parameter files. To add a custom event, you first create a custom event handler (that is, a Java class that contains the logic that you want to apply). Then, you use the Web Customization Editor to define the event handler and its events and assign the event handler to a bean or component. Finally, you add a link in the HTML output to trigger the new custom event. Optionally, if you want an event to be handled by a bean other than the originating bean, you use the Web Customization Editor to modify the event mapping. If  you want to specify the precise order in which multiple events should be processed, you add an evtorder parameter to the URL.

The XML event definition file, events.xml, lists the events that are recognized by the application, by the pages, and by the ApplicationBeans (that is, valid events). For each event, they list the arguments the event expects and specify the names of the arguments as they should appear (as parameters) in the URL.

The page definitions in the XML Page Configuration files include event handlers to be used, events assigned to beans, and event mapping references.

Event handler Java classes contain the logic for executing the actions associated with events.

ClosedClick here to see important classes and files used by the application at this step of page execution.

The following event-related classes play important roles, at the SDK level, during this stage of page execution:

  • WebEvent: A WebEvent represents an action requested by the user and the arguments required to accomplish it. Each link in an html page that generates an HTTP request has a WebEvent associated with it. For example, opening a folder to browse its objects or pivoting the elements on a grid are actions represented by WebEvents.  

  • EventHandler: Each WebBean has an associated EventHandler. The EventHandler is responsible for receiving requests, generating WebEvents and modifying the WebBean based on the WebEvent in the request. For example, in the case of a BROWSE_FOLDER event, the FolderEventHandler would receive the request and change the objectId of its FolderBean based on the folderId argument.  

  • EventHandlerFactory: This is the singleton factory of EventHandlers. It takes the event definition file, events.xml, and returns initialized EventHandlers that generate/handle events as defined in these files.

Another event-related class plays an important role, at the application level, during this stage of page execution:

  • EventMap: By design, beans are independent of each other (that is, a WebBean can handle/generate only events that are intended for itself). Sometimes, however, you need beans to interact with each other. For example, when a user clicks on a report in a FolderBean's output, the report needs to be executed by a ReportBean. An EventMap allows you to indicate that a particular WebBean on a particular page should handle an event from another WebBean. You accomplish this by mapping the event and arguments of the originating WebBean to the event and arguments of the target WebBean. In the example just cited, an EventMap would map the event used by the FolderBean to a ReportBean's EXECUTE_REPORT event and ask the ReportBean to handle the mapped event.

Problem solving at this step in page execution

Problems during this step in page execution generally involve errors that occur while the Controller is retrieving event information or attempting to process the event. The most common errors are:

  • An event handler exists for event specified by the evt parameter in the request, but it is never called.  

  • The event handler defined for the web bean in the Page Configuration file is missing or incorrect.

  • The src parameter in the request is not pointing to the bean to which the event handler is assigned

Other common problems are the result of not placing the Java event-handler class under the classes folder or not having well-formed XML in the Page Configuration file (for example, misspellings or incorrect syntax used when the event-handler was defined).

If an exception is thrown and caught in the process of handling events, the default action is for an error message to be sent to the screen while the stack trace is sent to the HTML source as a comment. Depending on the debug flags that are set, other information is also written to the HTML source. This action is defined by both the default template file for the generic "error" page (Error_Template.jsp/aspx) and the file used by the “error” page section (JSP or ASP.NET), whether it is inherited from the default page, the "error" page, or local to a specific page executing an event-based request. The "error" page section on the default template (mstrWeb.jsp/aspx) uses Generic_Error.jsp/aspx, which renders an error message between horizontal bars on the page. If extra validation needs to be done on the error object (such as determining if and how the error should be displayed to the user), each page can provide its own custom file for the “error” page section in its templates. Depending on whether the error is the result of a runtime exception or a checked exception, execution either continues on the current page (with or without displaying a message related to the error condition) or is redirected to the generic "error" page. You can use all of this information to help resolve problems that you encounter when you perform customizations. In addition to error messages that display on the screen, logging information can be viewed in the log file, and the stack trace and debugging information can be viewed in the HTML source for the page. See Error Handling for a more detailed discussion of error handling in MicroStrategy Web products, and see Logging Architecture for more information about error logging.

It is a good practice to validate XML configuration and layout definition files before starting MicroStrategy Web. Eclipse and other IDEs provide a way to validate these files.

Next step in page execution

The next step in page execution depends on whether the event that was just processed is the only event in the request, one of multiple events in the request that all have the same target page, or one of multiple events in the request that have different target pages.

  • If this is the only valid event in the request, the next step is applying custom logic.  

  • If this is one of multiple valid events in the request and it has the same target page as the request that was just processed, the next step is processing events. (The Process Events phase of page execution is repeated for the next event.)  

  • If this is one of multiple valid events in the request and it has a different target page than the request that was just processed, the next step is applying custom logic. (The difference between this step and the first one is that here, once the custom logic has been applied and the data collected for the current event, page execution returns to selecting the page in the Create Page phase of page execution. The Create Page and Process Events phases of page execution are both repeated for the next event. In the first step, page execution continues in order so that selecting the template comes after applying custom logic.)

Related Scenarios

See also