Virtual slots

Introduction

Virtual slots allow the transformation of “real” slot values into “virtual” values – and vice versa. Virtual slots can be very powerful, but require some (limited) php coding to be configured.

Virtual slots can be used e.g. for the following purposes :

- Allow users to enter “advanced conditions” in a more user-friendly way. For example, instead of writing a condition of the type “duration > 1800”, virtual slots allow you to write “duration > 30m”

- Transform numeric values into a finite set of output values. For example, the “duration” (time to close) of events may be translated into slices of 15 minutes

- Extract the month, weekday, or hour from a timestamp. For example, this can be used to show the number of events received by month, week, day, etc.

- Transform and regroup string values. For example, regroup all events where the host class contains the word “windows” into the category “Wintel”, and so on.

Configuration

Virtual slots must be manually declared as additional parameters in the $PRODUCT_HOME/config/custom/QuickQueries.conf file, under the [QuickQueries] section. The name of the parameters will directly indicate the name of the virtual slots.

The following parameters can be created as many times as virtual slots are needed.

Parameter	Description
VirtualSlot<Virtual Slot Name>BasedOn	Indicates on which real slot the virtual slot referenced by <Virtual Slot Name> is based upon. Mandatory to declare a new virtual slot.
VirtualSlot<Virtual Slot Name>InFunction	Optional. Name of the PHP function (present in the file data/QuickQueries/CustomVirtualSlots.php) that implements the transformation of a user-input value into a “real” slot value. Useful to allow users to express conditions in a more user friendly way. See “InFunction” details below.
VirtualSlot<Virtual Slot Name>OutFunction	Optional. Name of the PHP function (present in the file data/QuickQueries/CustomVirtualSlots.php) that implements the transformation of a real slot value into a “virtual” slot value. See “OutFunction” details below.
VirtualSlot<Virtual Slot Name>DrillDownFunction	Optional. Name of the PHP function (present in the file data/QuickQueries/CustomVirtualSlots.php) that implements the graph drill-down function, from a “virtual” slot value into a “real” slot value.

InFunction

The “InFunction” is used to translate a query condition built on the virtual slot into a “real” slot condition.

The code of the “InFunction” must be built to take as argument:

- The name of the virtual slot

- The operator used in the query condition

- The user input value.

The code of the “InFunction” must return an array made up of :

- The real condition operator

- The real value to use in the condition (in BAROC form)

Example

A service provider hosts services for his customers. There is a series of hosts that “belong” to each customer, and the service provider wants to provide event reports by customer, hiding away the list of individual hosts.

A virtual slot “customer” is created, and when a QuickQuery condition is created on “customer”, it will be converted in the backend as a condition on the hosts that belong to that customer.

In QuickQueries.conf, add the following line in the [QuickQueries] section :

VirtualSlotMyCustomerBasedOn="mc_host"
VirtualSlotMyCustomerInFunction="CustomerToHosts"

This will look like this in the console (after completing all other steps) :

In the file data/QuickQueries/CustomVirtualSlots.php, we then add the function as follows :

function CustomerToHosts ($slot,$operator,$InputValue)
{
  //$slot is “MyDuration”
  //$operator is the operator chosen in the GUI. For simplicity, we assume it is “equals”
  //$InputValue is the input value 

  $outOperator=”within”;
  $hosts=”[]”; 
  if ( $InputValue == “Customer1”)
  {
    $hosts=”[server1,server2,server3]” ;
  }
  elseif ( $InputValue == “Customer2”)
  {
    $hosts=”[server4,server5,server6]” ;
  }
  return array($outOperator,$hosts);
}

OutFunction

The “OutFunction” is used to translate a real slot value into a more friendly dimension..

The code of the “OutFunction” must be built to take as argument:

- The real value from the slot

The code of the “OutFunction” must return an array made up of :

- The converted value to show in the report

Example

The goal here is to be able to group together events that have been closed 15 minutes or less after their arrival, 15 to 30 minutes after their arrival, and those who have taken more than 30 minutes to close. For this we will create a virtual slot called “DurationInQuarters” based on the real slot “duration”

The configuration is as follows in QuickQueries.conf :

VirtualSlotDurationInQuartersBasedOn="duration"
VirtualSlotDurationInQuartersFunction="ConvertDurationToQuarters"
VirtualSlotDurationInQuartersDrillDownFunction="ConvertMyDurationToRange"

The underlying function that transforms the duration in “quarters” is written into modules/QuickQueries/VirtualSlots.php and is named “ConvertDurationToQuarters”. It takes a “real” duration as input, and transforms it into a string value :

function ConvertDurationToQuarters($duration)
{
  if ($duration <= 900 )
  {
    $myduration="1-15 minutes";
  }
  elseif ($duration < 1800)
  {
    $myduration="15-30 minutes";
  }
  else
  {
    $myduration="> 30 minutes";
  }
  return $myduration;
}

This can be used to generate graphs like follows :

DrillDown function

The virtual slots functionality can also provide the capability to drill down into the underlying events. For example, in the previous example, by clicking on the “> 30 minutes” bar of the graph. This is achieved using the function ConvertMyDurationToRange, which will return a test operator (between or greater_or_equals) as well as a “real value” so that a “real” condition can be created for drill-down purposes. In our case, “MyDuration = “> 30 minutes” should translate into “duration > 1800” :

function ConvertMyDurationToRange($VSlotValue)
{
  if ($VSlotValue == "1-15 minutes")
  {
    $operator="between";
    $value="[0,900]";
  }
  elseif ($VSlotValue == "15-30 minutes")
  {
    $operator="between";
    $value="[901,1800]";

  }
  else
  {
    $operator="greater_than";
    $value="1800";

  }
  return array($operator,$value);
}

Other Examples

Classify events by arrival week day

In this example, we simply want to group (e.g. in a bar chart) events based on the weekday of their arrival.

To do this, we will add the following parameters to QuickQueries.conf :

VirtualSlotWeekDayBasedOn="mc_arrival_time"
VirtualSlotWeekDayOutFunction="FindWeekDay"

The function to derive the weekday from the timestamp is simply (in modules/QuickQueries/VirtualSlots.php) :

function FindWeekDay($timestamp)
{
  $day=strftime("%a",$timestamp);
  return $day;
}

This can be used to create graphs as follows (here using the combination of the two example virtual slots) :

Additional notes

- Due to the additional processing that is performed at runtime, this may slow down the response time of the application

- Virtual slots are not allowed in the “multi slots” bar chart

- Virtual slots are considered of type STRING.