Editing the options of an investigation
Editing the options of an investigation
To edit the options of an existing investigation, either:
- Right-click the investigation name in the Investigations section of the left and select Edit.
- Execute the investigation and click the pencil and paper icon that appears in the top right corner of the list of results.
When you create a new investigation or edit an existing investigation, the Finder opens a dialog that lets you set all the options of the investigation.
The first thing that you find at the top of the dialog is the name of the investigation and an optional description of what it does. Click the name or the description to modify their contents.
Below the name and the description, you find three distinct sections that let you design the investigation to get the desired results:
In the Retrieve section, choose the object, activity or event of interest. The execution of the investigation returns a list of results with items of the selected type.
In the upper-right part of the Retrieve section, find three check boxes to select the platforms that are applicable to the investigation. The conditions and display fields that you are able to edit in the investigation depend on the platforms that you select here.
- If you choose one platform, you can use conditions and display fields available for that platform.
- If you select multiple platforms, only those conditions and display fields shared by all the selected platforms are available.
For instance, if you select to retrieve devices of the Mobile platform, you can only set conditions on devices or user fields, because all other objects are not available for Mobile.
In a similar way, if you choose to retrieve an object type that is not available in all platforms, the check boxes of the platforms in which the object is not available are ineligible.
For example, if you choose to retrieve domains, which are only available for the Windows platform, the check boxes of both Mac OS and Mobile platforms are disabled.
By default, when you create a new investigation, only the Windows platform is ticked in this section.
In the Matching section, you select the criteria that the objects, activities or events of the type that you chose in the Retrieve section must fulfill to appear in the list of results. The Matching section is divided into two subsections: Conditions and Time Frame.
The matching Conditions are a set of rules that apply to any type of item related to the one selected in the Retrieve section. You can set constraints on the properties or categories of objects, activities or events to filter the results of your investigation.
To add a new condition:
- In the Conditions subsection, click the link Click here to add a new condition. The placeholders for the condition fields show up.
- Set the object, activty or event to which the condition applies.
- Set the attribute or category that you want to constraint.
- Set the operator for comparison (e.g. is, is not, starts with, etc).
- Set the matching value, if you selected an attribute constraint, or the matching keyword, if you selected a category constraint.
Some combinations of conditions and display settings are incompatible. If you add a condition and a red exclamation mark appears on its right side, the condition may conflict with another condition or with one of the chosen attributes to display. Hovering the mouse over the exclamation icon will tell you the reason for the conflict. Investigations with conflicting conditions cannot be saved. Deselect the conflicting display attributes or delete the conflicting condition before saving the investigation.
To delete a condition:
- Click the trash icon to the right of the condition fields.
To make a template investigation:
- Instead of providing a matching value in the last condition field, click the question mark to its right to transform the investigation into a template investigation. The actual matching value is provided as a parameter when executing the investigation.
By default, the results of an investigation must fulfill all the expressed conditions. That is, the resulting filter is a logical AND of all the conditions. If you want to combine the conditions in a different way:
- Click the Advanced area to expand it.
- Combine the conditions in the Logical expression field using the numbers of the conditions and the Boolean operators AND and OR. For instance: 1 AND (2 OR 3).
The final and in the Conditions section allows you to specify a condition on an aggregate of the object selected in the Retrieve section. Activities and events do not have associated aggregate values.
Beware of literal translations of natural language to logical conditions, because you can get unexpected results. To express what you really mean in an investigation, keep in mind that relations between objects in Nexthink are all related to events in some way. For example, if a device is linked to an application, it is because the application was executed at some point in that device. The system iterates through these relations to return the results of an investigation.
Now consider a case where you want to get a list of the devices that have executed two different applications (e.g. Internet Explorer and Firefox) within a particular time frame, whose duration is irrelevant to our discussion. You may be tempted to use a logical AND (the default) to combine the conditions of an investigation on devices:
- Condition 1: Application name is Internet Explorer
- Condition 2: Application name is Firefox
- Logical expression: 1 AND 2
If you run this investigation, the list of devices that you get is always empty. The reason is that any relation between a device and an application ultimately relies on executions and no execution may simultaneously satisfy the two conditions: it is either an Internet Explorer execution or a Firefox execution, but not both. When the system iterates through these relations, it discards them all because none is matching the two conditions at the same time, as required by the logical operator AND. Hence the empty result.
To properly state the desired query, keep the same conditions but modify a couple of inputs. First, change the logical expression from AND to OR:
- Logical expression: 1 OR 2
In this way, the system keeps the relations that match either the first condition or the second. That is, you get all the devices that executed either Internet Explorer, Firefox, or both; although you are only interested in the last group.
Last, restrict the output to only those devices that executed the two applications. Add the following aggregate condition at the end of the section:
- Aggregate condition: Number of applications is 2
If you change your mind afterwards and decide to ask for the devices that executed either Internet Explorer or Firefox, but not both, use the following aggregate condition instead:
- Aggregate condition: Number of applications is 1
Although not useful in the example, the logical AND is still the most common operator to combine conditions. Use it when you want to enforce two compatible conditions at the same time. For instance, to know the devices that use Internet Explorer for browsing a particular domain, say www.example.com, create an investigation on devices with the following conditions:
- Condition 1: Application name is Internet Explorer
- Condition 2: Domain name is www.example.com
- Logical expression: 1 AND 2
To limit the results of the investigation to a particular range of time, use one of the following options:
- Full available period (start date to end date)
- Do not limit the results. The investigation uses the full range of time available in the Engine, which is stated in the start and end dates. This option is not available for investigations based on activities or events nor for any investigation based on objects that needs to go through activities or events.
- On date
- Limit the results of the investigation to a particular day.
- During the last x days / hours.
- Get the most recent matching results, that is, those that occurred less than the specified number of days or hours ago. Note that, when expressed in days, the time is partitioned in natural days, going from 0h to 23h59. As a consequence, it is not the same to restrict the time frame to the last day (from midnight today until now) than to the last 24 hours.
- From start date and hour to end date and hour
- Specify the period limit manually.
Additionally, for specified time frames that span through several days (with the exception of the Full period choice), you can optionally specify a range of hours of interest:
- Between start hour and end hour
- Choose a period of interest inside every single day included in the investigation.
In the Display section, determine how the Finder presents the results of the investigation. Choose between showing all the available results or just a fixed number of entries, according to some sorting criterion. In addition, select the fields (attributes and categories) of the retrieved objects that will be arranged as columns in the list of results.
Optionally restricting the number of results
To either display all the results of the investigation or restrict their number, use the option that you find at the top of the Display section. Choose between:
- All results
- Display all retrieved items without limit.
- The top x items ordered by field ascending / descending
- Limit the list of results to the first x items in ascending or descending order, according to the specified field.
Selecting the columns
Under Columns, specify the fields whose values you wish to see as columns in the list of results of the investigation. Select the fields by means of a label selector, where each label holds the name of a field. The Finder pre-populates the label selector with a set of default fields that depend on the type of item to retrieve and the previously specified options for the investigation.
To add a column to the list of results:
- Click the label selector to place the cursor on it. A selection menu exhibits all available fields organized by sections.
- Select the field either by clicking or by typing its name:
- Click the name of the field that you want to add as column. The field must not have been already added to the label selector (in which case, it is disabled in the menu).
- Start typing in the name of the desired field. The selection menu pops up, showing only those fields whose name includes the characters entered.
- Optional: Click the name of the desired field in the selection menu to add it directly. As indicated above, the field must not have been already added.
- Optional: Press Tab to auto-complete the name of the field if it is the only field left in the menu.
To be eligible, fields must be compatible with the options specified for the investigation (e.g. some aggregates are not available if the time frame selected is the full period available). Hover the mouse cursor over a disabled field to know about the reasons for the incompatibility.
To remove a column from the list of results, either:
- Click the cross sign on the right side of the label that holds the field name.
- Place the cursor to the left of the field label and press Delete or to the right of the field label and press Backspace. To remove all the labels at once, press Ctrl+A to select them all and press Delete.
Note that if you have restricted the number of results according to the value of a field, that field is mandatory and it cannot be removed from the label selector.
In any case, the set of labels in the label selector must never be empty. If you remove all the labels from the selector, then the a label with the identifier of the object (ID field) is automatically added.
Estimation of the time of execution of an investigation
The time of execution of an investigation depends on the complexity of the investigation and on the size of the database. Aggregate values, large time frames and elaborate conditions add up to the total complexity of an investigation. Based on these parameters, the estimated run time indicator in the bottom left corner of the dialog gives you a hint of the total execution time of the investigation that you are editing.
The indicator has three levels: low, medium and high. These levels are expressed graphically by means of three bars. One blue bar meaning low run time, two yellow bars meaning medium run time and three red bars meaning high run time. For small databases, the difference in the time of execution between a low run time investigation and a high run time investigation is hardly noticiable by the user. On the other hand, for big databases, the difference may be much more appreciable.
If you hover the mouse over the estimated run time indicator, a tool tip gives you some instructions on how to reduce the time of execution of the investigation.