Filters

Tags ITAM

Filters are listed on the left hand side of various windows. They are used to filter the display of these windows, allowing an Administrator to quickly find and focus on only certain items.

Each record in the Programs window potentially represents an aggregate of several individual program versions. A search filter looks for satisfaction based on ANY of the individual versions within the aggregate. This can sometimes lead to confusing results.

For example, compare a [search for all programs that ARE published by Microsoft] with a [search for all programs NOT published by Microsoft]. Chances are that there exist program line items (i.e. program variants listed in the Programs window) that satisfy both searches! All it takes is a variant that includes one program version with Microsoft in the publisher field while a second program version (aggregated into the same variant) has no publisher in the publisher field.

Computer and Program filters can also have associated Rules which are applied when computers or programs are discovered (or when new information about an existing item is discovered). If you add a rule to a filter in these windows, it floats to the top of the filter list.

Filters can also be used to restrict the scope of reports. With a filter selected, right-click to see the drop down menu which includes a list of all the reports that will accept the selected filter as a restriction. For example, a program filter can be used to restrict any report that deals with programs (e.g. a report whose detail lines are programs).

Filters can be applied by clicking just to the left of the filter you wish to apply in the selected window. Doing so will change which items are displayed in the main pane. You can also double-click a filter, which will open up a new window that will display only the filtered items. This window will not have the left-hand section which the main window has. It also has a section at the top where the filter can be edited, and which can either be collapsed or expanded.

Check marks are used in each pane of the Display column (left side of the window) to activate individual Filters, Divisions, Folders, etc. A combination of check marks will select all items that match at least one check marked condition in every pane that is used for the selection (e.g. has at least one check mark). This means that when a pane is being used for selection (so it has at least one check mark), an additional check mark will generally increase the number of items displayed as a match. If an additional pane is activated for the selection (by adding a check mark to a pane that had none), then the number of items displayed as a match will generally decrease.

To make a Filter, right click in the Filters section of the left pane of any Window and choose New Filter.

Filter Details

There are three ways of specifying a filter:

  • Match This String is a generic option to find a string that exists in any common field of the object type. That is, you could type in "bill" and in the Computers window this would find any computers who's name contained bill, had a last user that contained bill, was in a division named billing, etc. It is the quickest and easiest way to find things, but it is very broad.
  • Match These Values has a multiple selection list of items appropriate for the window in which you're creating the filter. This is an easy pick and choose interface where you don't need to worry about writing a custom query. The more options you choose, the more granular the search results will be (these are "and" matches).
  • Match This Filter allows you to write complex custom filters that the UI does not allow for, including filtering on custom fields in the computer window. See below for more on this type.

If you click the Apply button at the top, the filter will be saved with the name you gave it, and the results will be shown in the pane at the bottom of the window.

For Computers or Programs, there is a Rule sub pane in the upper right. Once you verify the filter works using Apply, you can check off actions to turn the filter into a Rule. In the future, any computer that connects will be processed by the Rule, for example to sort into a Division according to Name.

Group membership can be specified as a selector when creating a Computer filter in the graphical interface - but the behavior may be surprising! Computers which are members of the group due to a Node, Location, or Division clause in the Group definition will be selected as expected. But a computer that is a member of the group due only to external authentication will not be included among the selected computers when using the filter! This is because authentication generally bases group membership on user name, rather than computer, and it is not terribly meaningful to check the “Last User” for group membership. Also, if a group is specified in a filter, but the group contains only filters, the filter by group will not include computers that match the filter defined in the group - since this extra level of indirection is not necessary.

Custom Filters

The Match This Filter option allows for custom selection criteria specified using less common fields which are not included in the graphical interface. Also, it allows you to specify multiple values for the same field, or use boolean logic beyond simply the "AND" operator.

If you start out by choosing various conditions in the Match These Values section, and then change to Match This Filter, you will see a text representation of the filter you have specified. The basic format is a series of conditions in parentheses, separated by " && ". Each condition involves one field name and one constant. Here is a list of rules for writing filters.

  • Each condition should be surrounded by parentheses.
  • Each condition should involve one field and one constant.
     
  • For a list of possible fields, see the following table descriptions:
    • KSComputers Table Description - for computer filters
    • KSPolicies Table Description - for policy filters
    • KSProducts Table Description - for product filters
    • KSPrograms Table Description - for program filters
    • KSPurchase Table Description - for purchase filters

    In the filter string, you can use columns from the appropriate table, but you should drop the table prefix. e.g. instead of “computerFreeSpace”, use “FreeSpace”. Most fields will work in the filter string, but a few may not. Note that if you are using Computer Custom Columns, you should use usr0 through usr9 as the column names in any filters for custom Label 1 through 10.

  • Constants should match the type of the field they are being compared to. There are three different types of constants:
    • Numbers are specified simply by typing them without any special escape sequence - e.g. (FreeSpace>10000). They can also be specified using standard hex syntax - e.g. (ClientVersion>=0x6008)
    • Strings must be surrounded by either single or double quotes - e.g. (Notes="special"). A backslash can be used to escape a single or double quote within the string constant - e.g. (Name="Bob\'s Computer"). A literal backslash must be escaped by a second backslash, e.g. ("\\WINDOWS\\"~=Path)
    • Dates are specified using "General Time Format". This format is either:
      • @yyyymmddhhmmssZ - the specified date/time in the local timezone - e.g. @20040122154655Z
      • @yyyymmddhhmmss+oooo - the specified date/time with the specified offset from GMT - e.g. @20040122154655+0400 (the time specified is four hours later than GMT)
      • @yyyymmddhhmmss-oooo - the specified date/time with the specified offset from GMT - e.g. @20040122154655-1000 (the time specified is ten hours earlier than GMT)
      • @-duration - the specified duration in seconds before now - e.g. @-60 (one minute ago)
      e.g. (Discovered>@20040122154655Z)
       
  • You may also compare a field to "NULL" - this means the field has no value. e.g. (LastAudit=NULL) specifies that the LastAudit field has no value (which will be the case if a computer has never been audited).
     
  • The following types of comparisons can be performed:
    • (field=value) - field is equal to value
    • (field!=value) - field is not equal to value
    • (field>value) - field is greater than value
    • (field>=value) - field is greater than or equal to value
    • (field
    • (field<=value) - field is less than or equal to value
    • ("value"~=field) - text field contains "value"
    • ("value"*=field) - text field starts with "value"
    • ("value"%=field) - text field ends with "value"
  • Special items:
    • ('foldername'=fldr.name) - items that are in Folder of 'foldername'. Also works for Divisions (note name.subname syntax for nested divisions or use ~= for contains per above).
    • ('sectionname'=section.name) - items that are in a given computer section.
    • ('tagname'&=tagd) - items that have Tag matching 'tagname'. Note the special syntax and operator for tags, the normal logical operators above do not work. Also note tag.subtag syntax for nested tags. Will only match a full tag name or 'tagname*' for a tag starting with tagname and ending with anything. Values of tags are not part of this operation, only the tag itself.
  • Conditions can be combined using boolean logic and nested parentheses
    • !(condition) - negate a condition (i.e. everything that does not match condition)
    • (condition1) && (condition2) - AND of two conditions (must match both)
    • (condition1) || (condition2) - OR of two conditions (only has to match one)

Here are some complex examples:

  • (Platform=Macintosh)&&(osvr<> - Show all MacOS systems that are pre High Sierra.
  • (LastLogin<@20060315120000Z) && ((LastUser="lab user") || (LastUser="anonymous")) - selects computers which have not had someone login since 12:00:00 on March 15, 2006, and where the last user was either "lab user" or "anonymous"
  • (LastAudit=NULL) && (Audit=1) && (ClientVersion>=0x6008) - selects computers which are set to be audited, but have never completed an audit, where the client version is at least 6.0.0.8
  • (Audit=1) && (LastLogin>@20060401080000Z) && ((LastAudit=NULL) || (LastAudit<@20060101120000Z)) - selects computers which are set to be audited and have logged in after 8:00 on April 1, 2006, but have either never completed an audit, or have not completed an audit since January 1st, 2006
  • (Platform=Windows) && (Path!="") && (!("C:"*=Path)) - selects windows programs where the sample path is not empty, but the sample path doesn't start with "C:"

Specific Items

There are a number of special criteria that are stored in various flag values in the database. These are not specifically documented, but can be useful in many common cases. Here are some useful filter strings that may be of interest:

  • (flag&8) - When used in the Products window, this will show products that are hidden from lists in the Web UI.
  • (covd=2) - Used in the Computers window, this shows computers marked as Remote Only in the Map Availability option. Other values are 0 for Physical and Remote, 1 for Physical only, and 3 for Not Displayed.
  • (enfr=2) - Used in the Policy window, this will show Strict enforced policies. Other values are 0 for no enforcement and 1 for Relaxed.
  • (flag&0x00200000) - Used in the Computers window, this will show computers that currently have a Remote Session.
  • !(flag&0x1000) - Used in the Products window, this will show only Editions (e.g. NOT Family products).
  • (impa<8) -="" used="" in="" the="" products="" window,="" this="" will="" show="" definitions="" imported="" from="" prs="" in="" the="" last="">
  • !('*'&=tagd) - Usable in any window, this shows items with no tags.
  • (capa&0x00004000) - Used in the Computers window, this attempts to show computers using disk encryption. As this is based on various OS queries and mechanisms are varied, this will not find all instances.
  • !(Refs&2) - Use in the Products window, shows products that are not in policies directly (inherited from family will show).

Sample Filters – Import & Export

The standard ksp-admin installation includes an xml file, placed in "Sassafras K2/Admin/Misc/", that defines several sample filters. You may find these useful either directly or as a basis for your own further customization. To import only relevant sample filters for use in just one of KeyConfigure's list windows, simply drag the xml file, "Sample Filters.xml", and drop it onto the filters area of the window. Alternatively, the entire set of sample filters can be imported all at once by dragging the "Sample Filters.xml" file and dropping it onto the KeyConfigure program file itself. To save an xml copy the current filters defined for a particular list window, use the Export context menu item under the Filter section label. [Note: these xml files are readable as text, so you may find "Sample Filters.xml" useful to look at even without importing.]

Print Article