How Events Work

This article is designed to illustrate the powerful features of the xTuple ERP "Event Management" system. To take full advantage of these features, it's important to have an understanding of how events work.

Overview

This article is designed to illustrate the powerful features of the xTuple ERP "Event Management" system. To take full advantage of these features, it's important to have an understanding of how events work.

Let's begin with a few definitions:

  • Event: Any one of a limited set of possible occurrences precipitated by user activity which xTuple ERP defines as having special importance. 

  • Event notification: A system-generated alert sent to a user whenever an event the user subscribes to occurs.

  • Event Fence: A setting on the item site master specifying the period of time, measured in days, within which event notifications related to the item site should be issued.

Initiating an Event

If these terms seem confusing now, they shouldn't by the time you finish reading. The aim of this section is to clarify these definitions with concrete examples showing just how events work. Perhaps the best way to begin is to imagine a manufacturing scenario. For the purpose of this exercise, let's say we manufacture toy trucks. One of our bestsellers is item YTRUCK1, whose "Bill of Materials" appears below:

Bill of Materials for Manufactured Item

1-hew003

Rather than consider all the available events at once, let's look at one which might affect item YTRUCK1. Let's consider the event called "WoQtyChanged." This event occurs, or is triggered, if a user ever changes the quantity of a work order. To see this event in action, we will create a work order for 100 units of item YTRUCK1. The following screenshot shows the work order we are creating:

Work Order for Manufactured Item

2-hew004v2

To initiate the event, we will need to change the work order quantity from 100 units to some other quantity. However, before we do that, let's make sure our test user is subscribed to this event within the work order's supplying site (i.e., WH1). Users must be subscribed to an event if they are to be notified when the event occurs.

Note: Users must be subscribed to an event if they are to be notified when the event occurs.

We can verify which events our user is subscribed to by following these steps:

  • Go to "System" from the top menu
  • Select the "Preferences" submenu
  • The "User Account Preferences" window will open
  • Select the "Events" tab:
  • The following screen will appear:

User Event Notification Screen

3-hew005v2

Notification Options

The "User Event Notification" screen is where we check on user event subscriptions. If a user is subscribed to an event, the user will be notified whenever that event occurs. For this exercise we are interested specifically in the event "WoQtyChanged." As you can see in the example, this event has been highlighted. Simply click on an event to highlight it.

Once the desired event has been highlighted, we look next to the list of sites found on the right-hand side of the screen. If a warehouse has been subscribed to the event, the "Notify" column next to the warehouse will read "Yes." If not subscribed, the "Notify" column will read "No." As you can see from the screenshot, the site is subscribed to the "WoQtyChanged" event. This means the user is subscribed to it. To link a site to the event, simply double-click on the site after the desired event has been highlighted.

Information: If you double-click on an event, you can change the notification status for all sites simultaneously. This technique avoids having to select each site individually.

Remembering that the WH1 site is specified as the supplying site on the work order we created for item YTRUCK1—meaning this is the site where a change in work order quantity would occur, triggering an event—we click on site WH1. Doing so changes the notification status for WH1 to "No," but, for this example, we want "Notify" to remain "Yes" so the user is subscribed to the "WoQtyChanged" event.

Event Fences

Before we change the work order quantity, let's first examine how "Event Fences" fit into the equation. As you recall from the initial definition, an event fence is a setting on the item site master specifying the period of time, measured in days, within which event notifications related to the item site should be issued. Looking at the item site master for item YTRUCK1, we see that the event fence is set to ten days, as shown below:

Event Fence for Manufactured Item

4-hew006v2

Given their measurement in days, event fences relate to the timing of events. You might ask, "How does timing relate to events?" A majority of events are tied to sales orders or work orders, since orders have definite due dates and start dates, they are time-sensitive.

Let's return to our specific example. Look back at the work order we created for item YTRUCK1 in the example. The start date is 03/10/2015. We recall that the event fence setting for item YTRUCK in site WH1 is ten days. That means in terms of calendar days, the event fence for this work order ranges over a period of ten days from 03/11/2015 to 03/21/2015. If a system-defined event occurs within this event fence, and you are subscribed to that event in the correct site, you will receive notification that the event has occurred. If the event occurs prior to the event fence, no notification will be issued.

Since today's date is 03/10/2015, so we are within the specified event fence for the YTRUCK item site. Let's initiate the "WoQtyChanged" event and track the results:

  • Go to the "Manufacture" module from the top menu
  • Select the "Work Order" submenu
  • Choose the "Change Quantity" option
  • The "Change W/O Quantity Order" window will open
  • In the "Work Order #" box, type in or search for the work order we made earlier
  • For this example, we will change the original work order quantity from 100 units to 75 units:

Event Initiated by Change in Work Order Quantity

5-hew007

The Event Manager

After initiating the event, a couple of things happen. For starters, the event notification button, a light-bulb icon, will pop up in the lower left-hand corner of your desktop. This button alerts you that an event you are subscribed to has occurred:

Event Notification Alert

8-hew002

To see details about the event, we click on the alert button. Doing so opens the xTuple ERP event manager, as shown in the following screen:

Event Shown in Event Manager

6-hew001v3

The event manager can be accessed regardless of whether the event notification button has appeared. Simply select the "Event Manager" option from the "System" module menu.

As you can see in the example, the event for the current user is displayed. If you are a manager with permission to view event details pertaining to other users, you would have the ability to select another user on this screen. Looking at the details for our current user, we see the site where the event occurred, the time and date of occurrence, the type of event, and the associated order number. To acknowledge receipt of the notification, we select the "Acknowledge" option from the right-click menu. Finally, to confirm the time and date of acknowledgement, we select the "Show Acknowledged Events" option, as shown in the following screen:

Event Acknowledged in Event Manager

7-hew008v2

We have now followed a complete life cycle for the event "WoQtyChanged." You can apply the same techniques discussed in this example when subscribing to and tracking other system-defined events.