Implementation Guide › Implementation › Business Logic Scripting (Business Logic Expert) › Inside the Business Logic › Events Flow

Events Flow

As previously mentioned, the inputs to the Business Logic are the Engine Events and the Raw Data Events.

Raw Data Events received by the Business Logic are determined by the registration function within which the code requests a specific set of raw data events defined by their Event type and Resource identifiers.

In the Business Logic, registration also associates a user-defined subroutine that is executed in order to handle the Raw Data Event once an event is received. (By default, it is the OnXXXEvent, which should be renamed to something more meaningful.)

The Engine Events are triggered by the engine according to the associated Contract and Metric definitions. Once the Engine Event is triggered and received, the engine executes the pertinent event handler. Each Engine Event has an implicit event handler. These event handlers are functions and procedures defined on top of the VBScript. The event handler that handles the registration and the “result” function are both mandatory to implement in the code. All other event handlers are optional. However, the Business Logic does not deal with Engine Events for which event handlers are not implemented. Therefore, it is good practice to leave them all in place (even if not being used) to allow for future enhancements.

Note: When writing the Business Logic script it is important to implement all of the Engine events in order to be able to cover all the final possibilities. For example, even if during the first stage of the implementation a timeslot definition was not applicable, but will be in the future, then all the formulas will require amendment. It is therefore recommended for the Business Logic Expert to define the behavior "in timeslot" and "out of timeslot" periods in advance, even if initially it is not applicable, so that when the behavior is introduced, the required system changes are trivial.

Following are various Engine Events and their event handlers:

• OnLoad (Time)-(optional), called once at the start of calculations when the Contract is being activated. Can be used for initializing global variables.
• OnRegistration (Dispatcher)-(required), procedure for requesting the relevant Raw Data events and associating them with the user-defined procedures with which to be handled. Events are requested and are associated with procedures by using the methods of the Dispatcher object.
  OnRegistration is called once by the calculation engine at the beginning of the calculation of the Metric and again each time a Resource registered for the Metric becomes effective whereupon the Engine evaluates the set of changes done for that resource which can influence the set of Events streamed to the formula. The Engine has the definition of the Event request defined by the Event type and Resources identifiers and in a case where a Resource (or a change set containing multiple resources) changes something related to this set. Once it becomes effective, an OnRegistration event handler is triggered.
• OnPeriodStart (Time)-(optional), called at the beginning of the agent time period (set according to the time unit). The first OnPeriodStart is triggered once the Contract becomes effective, where the balance of the periods start with whole round hour time units. This event handler is usually used to periodically initialize variables, such as a counter that holds the number of incidents opened within the calculation period which should then be initialized to zero at the beginning of each period.
• OnPeriodEnd (Time,IsCompleteRecord)-(optional), called at the end of the agent time period (set according to the time unit). It is always called at the rounded end of the time unit in rounded hours (for example, 24:00). IsCompleteRecord is True when the period of the Metric has ended (according to the real world time of the application server), and is False when making an intermediate calculation. This event handler is usually used to do final calculations for the ending period in order to prepare the ground for the final result that will be supplied by the Result function.
• OnTimeslotEnter (Time)-(optional), called when entering a TimeSlot period based on the associated Metric definition. For example, if the Metric is associated with a timeslot definition of business hours where each day at 8:00 AM is a beginning of time slot, then at this time every day this event handler will be triggered.
• OnTimeSlotExit (Time)-(optional), called when exiting a TimeSlot period based on the associated Metric definition. For example, if the Metric is associated with a timeslot definition of business hours where each day ends at 17:00 PM, then at this time every day this event handler will be triggered.
• Target()-(optional), called when the Metric is specified as having a dynamic target. It allows you to determine the service level target of a Metric during business logic runtime. Such targets can include the consumption of service components or infrastructure changes. It has four values, just like the Result function; one for each mode. This function is executed after the Result function during normal execution.
• Forecast()-(optional), called once when performing a Commit of the contract version by having the calculation engine calculate the contract once in a forecast mode. The Forecast mode is performing a full calculation engine cycle on the contract (from the start to the end date of the contract version). The purpose of this cycle is to calculate the forecast values only. (There are no calculations are done on the T_RAW_DATA table).This function is called in place of the Result function during this execution mode.
• Result()-(required), called by the calculation engine in order to get the result of the calculation for a given period. The Result function is always called after the OnPeriodEnd event handler.

The following are the steps followed by the calculation mechanism (PslWriter service) in order to process a single Business Logic formula:

• PslWriter loads the formula into memory and executes every statement that exists in the declarations section (the declarations section is all the code which is outside of a function or sub-routine). Note also that all attached modules and libraries are included and compiled into this single code module for execution.
• PslWriter calls the OnLoad event handler.
• PslWriter calls OnRegistration.
• Calculation of the period begins with calling to OnPeriodStart.
• For each Raw Data Event registered during OnRegistration that falls within the time range of the period, PslWriter calls the user-defined event handler associated with that Event.
• If the beginning or end of the timeslot falls within the time range of the period, OnTimeslotEnter or OnTimeSlotExit will be called.
• If there is a relevant infrastructure change within the time range of the period, OnRegistration will be called.
• Calculation of the period ends with calling OnPeriodEnd.
• If a Dynamic Target has been specified, then this function will be called.
• The PslWriter calls the Result function in order to get the final result of the period calculation.

  Note: When the contract version is first committed and a forecast has been selected the Forecast function is called instead of the result function. This, however, occurs only this one time for each version)

During each calculation cycle, the Engine evaluates what the relevant Engine Events and Raw Data Events are based upon the calculation time period. It will first sort them by time and then send them to the relevant formulas for calculation. The time of the Raw Data Event is its timestamp and the time of the Engine Event is its triggered time. Both these types of events are then combined in a time sequence, and sent for calculation.

The timings of the Events are according to the associated local Metric, but the Time parameter of the event handlers (ie, OnPeriodStart (Time)) and the timestamp of the Raw Data Event is according to their value in UTC. The Engine compares them according to their values at UTC, so as to use a constant point of reference.

Example:

If a Metric's timezone difference from UTC is two hours (i.e. GMT+2), and an incident opening event has its timestamp as 10:00 AM, then inside the Engine the timestamp that the event handler will be using is actually shifted accordingly and really starts at 8:00am UTC. Assuming the Adapter is configured to use this same timezone, then the raw data events will be shifted back 2 hours to UTC in the database also. When the events are being passed to the Business Logic, the calculation Agent responsible for calculation the Events for the period starting at 10:00 AM will actually be using the UTC time for events, which will be 8:00am onwards. However, if you use the out.log message in the code to print out the timestamps, it will show the timestamp shifted to UTC and hence will show 8:00 AM, despite the specified period (according to the Metric) being for 10am.

In the following calculation requirement it is important to convert the timestamp of the event before using it:

If a Metric is to calculate the number of incidents that were closed on the same day that they were opened, then it is necessary to compare each incident's opening and closing time. If an incident's opening and closing time fall on the same day (and within a defined timeslot), the incident will be counted.

It may happen that during the process of shifting the incident to UTC from its original local time the day will change.(ie. again using GMT+2). An incident opened at 1am, will be shifted back to 11pm the previous day in UTC) It will then not be counted even when it should have been. This is a situation where the time has to first be converted back to the local Metric time, and only then be compared. For such a case, use the GetLocaleTime(utcTime) method. This method converts a time given in an UTC time zone into the time zone of the local Metric.

The following is the event handler code:
Sub OnIncidentEvent(eventDetails)
   If dateDiff("d",Tools.GetLocaleTime(eventDetails.time),_
     Tools.GetLocaleTime(eventDetails("ClosedAt)))=0 then
          CountIncidents=CountIncidents+1
   End If
End Sub