1. Inventory Widget

1.1. Purpose

The main purpose of the widget is to count the number of objects respecting certain conditions. Moreover it can sum them and group them according several criteria. The inventory is computed over a sliding period of time, independently of what is available in the Engine. For exemple, one can define an inventory with a period of month; it means that every day, the values corresponds to the last month (30 days). The widget doesn't record the whole history; only the current count of objects (e.g., for the last month) is available.

1.2. Creating widget

To create an Inventory widget, please follow the following steps:

1.2.1. Step 1

1. choose what you'd like to count. It can be either
   • all objects (i.e., all sources, all users, ...)

   • or objects retrieved with an investigation. In this case, only the investigation's conditions on object and on aggregates are considered.

2. select a time period (day, week, month, quarter, year). It correspond to a sliding time window. If 'week' is selected then it means that the value will correspond to the last 7 days.
3. choose how evolution shall be marked: no care, up is bad and down is good, up is good and down is bad.

   
   

1.2.2. Step 2

1. select the attributes for the "sum by"; the list of available fields contains
   • a selection of counted object attributes
   • categories of the object to be counted
   • categories of other objects

   One can select 0 to 5 attributes. Their order as well as the separator can be changed. The order determines how values will be displayed, it can't be changed afterward without impact on data.

   
   Note that access rights are not applied on the result of these selected fields, even for the category used to create hierarchies. It means that a keyword in the result will be displayed for everybody.

   
   

1.2.3. Step 3

1. select additional attributes displayed in details; the list of available fields contains
   • attributes of counted object
   • aggregates of counted object
   • categories of counted object Fields selected for the "sum by" will be also displayed in details, the sum of fields could not exceed 5. Additional fields are always displayed after "sum by" fields.

   
   

1.2.4. Step 4

1. choose the computation mode. Two modes are available:
   • current status: only the current status of each object is taken into account.
   • all statuses: all statuses of each object during the time period is taken into account.
   See below for detailed explanations on how calculation is performed.
2. optionally select a criterion for grouping results:
   • "group by" - it can be any category on any object type, results are classified by keywords
   • "hierarchy" - using a hierarchy permits to structure the result as defined in the hierarchy but also to apply access rights set to users (available only if at least one hierarchy has been defined)
   If one has selected attributes for the "sum by" and a criterion for grouping, one can also chooses which one is displayed as rows or columns.
3. choose if an overall summary should be displayed on top of the resulting table and how many days in the past it should represent

   
   

1.2.5. Step 5

1. select the ratios available in the visualization. Four options are available:
   • overall: the value corresponding to the total for all columns and rows is the reference
   • per column: for each column the total of the column is the reference
   • per row: for each row the total of the row is the reference
   • ratio: the reference is the corresponding value in another inventory widget. In the list appears only inventory widgets based on same object and having the same time period, "sum by" attributes and "group by" option.
   Only options which make sense are enabled. Options "per column" and "per row" are enabled only if there is more than one dimension in the resulting table.

   
   

1.3. How the calculation is performed

1.3.1. Counting objects

Given for example a certain machine M, let us see how it is considered.

Machine M: A+ A+ A-

           ——|——————————————————|—> time
                    period now

• In the time period ending now (i.e. last night), the days the machine was active are considered: A+ and A-

• A+ means: the machine is active and matching the investigation's conditions

• A- means: the machine is active but not matching the investigation's conditions

• Note: if the count was defined by the pull-down menu, rather than by an investigation, there are only A+

The Base inventory on option determines if the machine is counted or not:

• all statuses during the time period: There must be at least one A+. In the above example, the machine would be counted.

• current status only: The most recent status counts. In the above example, the machine would not be counted, because in its last active state, it was not matching the investigation's condition.

• In any case, the machine is not counted if it has never been seen during the period.

1.3.2. Summing

The option Sum counts by define groups of counts. All seen combinations of values of the selected attributes determine these groups.

Using this option will turn the displayed results to a list.

If the fields selected are related to the object, then a given object is counted in one group only. But if fields selected are related to other objects (categories on another object) then the object could correspond to multiple groups.

In both cases, if the object changes of group during the time period, then depending on the Base inventory on option:

• all statuses during the time period: a given object will be in each group it has been seen since the beginning of the time period

• current status only: the object is counted in last group(s) it has been seen.

For example if the inventory counts all sources and sum results by location, if a source of location 'A' is moved to 'B', then in the first case it will appear in group 'A' and in group 'B'. In the second case it appears only in 'B'.

And if the inventory counts all sources and sum results by type of port, a source could the same day uses a port of type 'web' and one of type 'mail'. It will appear in both group 'web' and 'mail', even if current status only is used.

1.3.3. Group by

The Display results option set to grouped by an object category defines an additional grouping,

Using this option will turn the displayed results to a list if the option Sum counts by was not used, and to a table otherwise.

When an object changes of group during the period, it may be counted in each group or not, depending on the Base inventory on option:

• all statuses during the time period: There may be duplicates

• current status only: There are no duplicates, and the object is counted in the last group it was seen.

1.3.4. Recap

Counted objects:

• 		Base inventory on
  		all statuses...	current status only
  Count	all objects	counted if seen at least once
  	investigation	counted if conditions are met at least once when active	counted if conditions are met when last seen active

Display:

• 		Base inventory on
  		all statuses...	current status only
  Display results	Sum by	each state seen	last state
  	Group by	each state seen	last state

1.4. Using widget

If neither "sum by" attributes nor "group by" criterion is selected, a single value is provided:

• 

If only "sum by" attributes or a "group by" criterion is selected, a one-dimensional table is displayed:

• 

If both "sum by" attributes and a "group by" criterion is selected (here by hierarchy), a two-dimensional table is displayed:

• 

When a hierarchy is used to group results then a navigation bar appears to indicate the position in the hierarchy. To drill down, an icon appears near the name of the node. If the widget is configured with multiple hierarchies then you could switch from a hierarchy to another by clicking the down arrow on the left of the hierarchy name. If only one hierarchy is configured there is a right arrow.

• 

To drill up, use the navigation bar and click on a level. The last level could not be clicked since this is the current one.

• 

Note that when a widget is defined to use hierarchies, the content could be different depending on access rights of the user and on domain set to the module. In the previous example the hierarchy is displayed from its root but it could start from a lower node or the drill down limited to a level before than leaves are reached. It could also happen that the user couldn't see anything.

Note that with hierarchies a table is always displayed. If there is no value to display for particular domain, the user assigned to this domain will see a table with only overall row.

1.4.1. Ratio

In tables, depending on what was configured, one can choose to display percentages per row, per column, overall, ratio or no percentage at all.

Here is an example of the ratio based on an another inventory widget:

• 

When the ratio is based on another widget, it needs that both widgets have been computed on the same days to have percentage displayed. When a percentage is selected then all values and charts are displayed in percent.

1.4.2. Overall

When the overall option is enabled, the widget display a chart representing the evolution of the global value.

• 

Depending on the time window configured then it is possible to display the chart using another time scale. Above the chart is displayed in day, there is a point for each day. Below the chart is displayed in week. There is only one point per week, the value for Sunday is used. If the week is not completed, then the last value is displayed using a dashed line. Even if the overall value is valid for each day, since the widget uses a sliding time window, in the chart the value has not the same number of days as the other points.

• 

1.4.3. Details

One can click on the value to access to the list of objects in a separate dialog.

• 

1.4.4. History

Near the value, the last change is displayed using an icon as configured in first step. The first time the widget is computed, the evolution doesn't appear since it needs two computation to compute the evolution.

One can click also on this value to display the history of the inventory. Values for each computed day could be consulted.

They are different modes in the history dialog:

• last change: display objects which have been added or removed
• specific dates: display the history between two dates
• last days: display the history from today for the last x days

• last <time window unit>: depends on the time window configured. Display the history from today for the last x <time window unit>

• month: display the history for a given month
• quarter: display the history for a given quarter
• semester: display the history for a given semester
• year: display the history for a give year

For each mode, the available choices correspond to the dates computed for the widget.

By default, the selected mode correspond to the scale selected for the overall chart to display the same chart as displayed in the widget. It means that last days is selected if chart is displayed in days and last weeks if the chart is displayed in weeks.

The last change mode display the evolution between two last computations of the widget and list the objects added or removed.

• 

All other modes display a chart with the values corresponding to the selected period of time. The minimal and maximal values are highlighted. Except the last <time window unit> mode, the charts are displayed in days.

• 

If a percentage has been selected in the widget, the the history dialog reflects this selection and all values are in percentage.

• 

Note that, all tables can also be directly exported in CSV for processing in another system (e.g., Excel).