KACE Systems Management Appliance 14.1 Common Documents - KACE Service Desk Administrator Guide

Checking for conditions (conditional rules)

You can write Custom Inventory rules that identify whether (true/false) an application is installed.

When using a conditional rule, if the rule returns true, the Display name (Title) of the custom application appears in the Software: Installed Programs section of the Device Detail page in the Inventory section.

The following sections describe the rules that test for conditions:

•

Conditional rule reference

•

Verifying whether a condition exists (Exists rules)

•

Evaluating device settings (Equals rules)

•

Comparing device values (Greater Than and Less Than rules)

•

Testing for multiple conditions

When the rule returns false, the application does not appear in the Installed Programs section in the device’s inventory details.

Tip:	TIP: You can view a list of devices that have the item installed on the Inventory > Custom Inventory > Custom_item: Detail page.

Conditional rule reference

The following table describes which data types can be used for comparison.

Table 24. Data types supported for comparison functions
Conditional rule	Data types supported for comparison functions Equals, GreaterThan, LessThan
EnvironmentVariable	DATE, NUMBER, TEXT
FileInfo	DATE, NUMBER, TEXT
FilenamesMatchingRegex	NUMBER
FileVersion	TEXT
PlistValue	NUMBER, TEXT
ProductVersion	TEXT
RegistryValue	TEXT

The following table describes how comparisons are made.

Table 25. How comparisons are made

Data type

Considerations

DATE

•

Before evaluation, target values are parsed as a date using the same rules as in the PHP DateTime class and then normalized to use the following format:

MM/DD/YYYY HH:MM:SS

•

The timestamp listed in the appliance database uses the 24-hour clock (0 – 24 hours).

•

The timestamp listed in the appliance database reflects UTC (Coordinated Universal Time) time, so that it is normalized for all devices, regardless of their respective timezones.

•

If the target value contains only a date, a timestamp will be added that is based upon midnight for UTC.

NUMBER

•

Only whole numbers are evaluated.

•

If a target value contains any other characters (letters, punctuation marks and so on), only the numbers up to the first non-number are evaluated.

For example, if the target value is 52a1, only 52 is evaluated.

•

Only numbers up to the 32-bit integer maximum positive value (2,147,483,647) are supported.

TEXT

•

Values are evaluated verbatim, without any potential formatting changes (as can occur with DATE and NUMBER data types).

•

Text strings are evaluated in lexicographical order.

•

Commas can be present in the strings being evaluated — no escaping is required.

The following table lists available conditional rules with links to specific details on how to specify the arguments.

Table 26. Conditional rule reference
Syntax	Win	RHEL	OS X	Description
DirectoryExists (path)	X	X	X	Checks for a directory at the specified path on the device.
FileExists (path)	X	X	X	Checks for a file at the specified path on the device. Include the name of the file and extension in the path.
FileVersionEquals (path, version)	X			Verifies that the Version > File Version property of the file specified in the path matches the TEXT value you entered.
FileVersionLessThan (path, version)	X			Verifies that the Version > File Version property of the file you specified as the path is lower than the TEXT value you entered.
FileVersionGreaterThan (path, version)	X			Verifies that the Version > File Version property of the file you specified is higher than the TEXT value you entered.
ProductVersionEquals (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified matches the TEXT value you entered.
ProductVersionLessThan (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified is lower than the TEXT value you entered.
ProductVersionGreaterThan (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified is higher than the TEXT value you entered.
FileInfoGreaterThan (fullpath, attribute, type, value)	X	X	X	Verifies that the File Info property of the executable or installation file you specified is higher than the value you entered.
FileInfoLessThan (fullpath, attribute, type, value)	X	X	X	Verifies that the File Info property of the executable or installation file you specified is lower than the value you entered.
FileInfoEquals (fullpath, attribute, type, value)	X	X	X	Verifies that the attribute of the executable or installation file you specified matches the value you entered.
RegistryKeyExists (registryPath)	X			Verifies that a registry key exists.
RegistryValueEquals (registryPath, valueName, value)	X			Verifies that a registry entry exactly matches the value you specify. Value is compared as TEXT.
RegistryValueLessThan (registryPath, valueName, value)	X			Verifies that the registry entry is lower than the value you specify. Value is a TEXT.
RegistryValueGreaterThan (registryPath, valueName, value)	X			Verifies that the registry entry is higher than the value you specify. Value is a TEXT.
EnvironmentalVariableExists (var)	X	X	X	Verifies that an environment variable with the name you specify exists.
EnvironmentalVariableGreaterThan (var, type, value)	X	X	X	Verifies that the environment variable definition is higher than the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
EnvironmentalVariableLessThan (var, type, value)	X	X	X	Verifies that the environment variable definition is lower than the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
EnvironmentalVariableEquals (var, type, value)	X	X	X	Verifies that the environment variable definition exactly matches the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
PlistValueExists (fullpath, entry)			X	Verifies that a named value exists in a PLIST file.
PlistValueGreaterThan (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT higher than the value you specified.
PlistValueLessThan (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT lower than the value you specified.
PlistValueEquals (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT that exactly matches the value you specified.

For information on Equals, GreaterThan, and LessThan for FilenamesMatchingRegex, see Regular Expression Rule Reference.

Verifying whether a condition exists (Exists rules)

Rules whose name ends with Exists check for the presence of a file, directory, registry key, or other item. If the KACE Agent locates the item on the device, the rule returns true, and the item appears in the device’s Inventory Details as an Installed Program.

Use any of the following Exists rules:

•

DirectoryExists (path)

•

FileExists (path)

•

RegistryKeyExists (registryPath)

•

EnvironmentalVariableExists (var)

•

PlistValueExists (fullpath, entry)

•

FilenameMatchingRegexExist (fullpath, regex)

Example: Check for a directory (folder)

The following example tests whether the Windows directory exists on the device:

DirectoryExists(C:\WINDOWS\)

Example: Check for a file

NOTE: The following example verifies that the pad executable file exists on the device:

FileExists(C:\WINDOWS\notepad.exe)

Evaluating device settings (Equals rules)

Rules whose name ends with Equals compare the value set on the device to the value you specify in the rule. The rules return true if the values exactly match.

Rules that use arguments with set data types can only compare values of the same type.

Use any of the following Equals rules:

•

FileVersionEquals (path, version)

•

ProductVersionEquals (path, version)

•

FileInfoEquals (fullpath, attribute, type, value)

•

RegistryValueEquals (registryPath, valueName, value)

•

EnvironmentalVariableEquals (var, type, value)

•

PlistValueEquals (fullpath, entry, type, value)

•

FilenameMatchingRegexEqual (fullpath, regex, value)

Example: Testing JAVA_HOME setting

To verify that the JAVA_HOME setting is C:\Program Files\Java\jdk1.6.0_02:

EnvironmentVariableEquals(JAVA_HOME, TEXT, C:\Program Files\Java\jdk1.6.0_02)

Example: Testing McAfee® Registry Entry setting

To check the setting use the same format as the date in the entry:

RegistryValueEquals(HKEY_LOCAL_MACHINE\Software\McAfee\AVEngine, AVDatDate, 2014/03/01)

Example: Detecting Windows 7 Service Pack 1

Windows 7 Service Pack 1 appears in Add/Remove programs for devices that were originally on Windows 7 then upgraded to SP1 only. The default application inventory for this item does not reflect devices that are already on SP1 because they were originally imaged at the SP1 level.

When using the appliance to deploy Windows 7 Service Pack 1, create the following Custom Inventory rule for a custom application:

RegistryValueEquals(HKEY_LOCAL_MACHINE\Software\Microsoft\WindowsNT\

CurrentVersion,CSDVersion,Service Pack 2)

You can then exclude devices with this item installed to prevent the appliance from trying to deploy the SP2 to devices that are already at that level (that is, Windows 7 devices that have been upgraded, as well as devices originally imaged with SP1).

Comparing device values (Greater Than and Less Than rules)

Functions whose names end with GreaterThan and LessThan compare values as listed in Table 24.

Use any of the following Greater Than and Less Than rules:

•

FileVersionGreaterThan (path, version) and FileVersionLessThan (path, version)

•

ProductVersionGreaterThan (path, version) and ProductVersionLessThan (path, version)

•

FileInfoGreaterThan (fullpath, attribute, type, value) and FileInfoLessThan (fullpath, attribute, type, value)

•

RegistryValueGreaterThan (registryPath, valueName, value) and RegistryValueLessThan (registryPath, valueName, value)

•

EnvironmentalVariableGreaterThan (var, type, value) and EnvironmentalVariableLessThan (var, type, value)

•

PlistValueGreaterThan (fullpath, entry, type, value) and PlistValueLessThan (fullpath, entry, type, value)

•

FilenameMatchingRegexGreaterThan (fullpath, regex, value) and FilenameMatchingRegexLessThan (fullpath, regex, value)

Example: Testing whether the product version is higher

To verify that the product version is higher than a given number:

ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe, 78)

To verify that the production version is a given number or higher, enter the following:

ProductVersionEquals(C:\Program Files\Mozilla Firefox\firefox.exe, 78)

OR ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe,

78)

Example: Testing for a product version range

To test whether the product version is within a range, combine less than and greater than rules:

ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe, 77)
AND ProductVersionLessThan(C:\Program Files\Mozilla Firefox\firefox.exe, 79)

Important:

IMPORTANT: Do not enter rules on separate lines. Separate the rules by space only. Having rules on separate lines invalidates the compound rule.

Testing for multiple conditions

You can join rules using AND operators or OR operators to test for multiple conditions.

NOTE: Using both AND and OR operators in the same Custom Inventory rule is not supported. Set up separate applications.

Joining conditional rules produces the following results:

•

AND operator: All the rules must return true in order for the results to return true and report the application as an Installed Program.

•

OR operator: Only one rule must return true for the application to be reported as an Installed Program.

Important:

IMPORTANT: Do not enter rules on separate lines. Separate the rules by space only. Having rules on separate lines invalidates the compound rule.

Checking for multiple true conditions (AND)

Use the AND operator to join conditional rules in the Custom Inventory Field when you want the item to be reported as an Installed Program only if all the rules are true.

In the Custom Inventory Field, join rules using the following syntax:

Function
(arguments...
) AND Function
(arguments
) AND ...

Separate the conditional statements from the operator with spaces.

Example: Checking for a registry key and comparing values

To check for a registry key and a registry entry value on a Windows device use AND to combine the rules as follows:

RegistryKeyExists(registryPath
) AND RegistryValueEquals(registryPath, valueName, value)

Checking for one true condition (OR)

When you join rules using the OR operator, if any of the rules in the Custom Inventory Field are true, the application appears in the Installed Program list of the device.

In the Custom Inventory Field, join the rules using the following syntax:

Function
(arguments
) OR Function
(arguments
) OR ...

Separate the function statements and operator using a space.

Example: Checking for either registry value

To check that a registry entry is one value or another:

RegistryValueEquals(registryPath, valueName, value) OR
RegistryValueEquals(registryPath, valueName, value)

Tip:	TIP: To specify a range use RegistryValueGreaterThan and RegistryValueLessThan rules joined by the AND operator.

Getting values from a device (Custom Inventory Field)

The rules that end with ValueReturn enable you to gather information from the device. You can use these rules to collect information that the KACE Agent normally does not collect.

The returned values are set with the custom application display name (Title). This appears on the Device Detail page under Software in Installed Programs and Custom Inventory Fields.

Use the Custom Inventory Field values to manage installations and to distribute software as well as reports, View By filtering, Smart Label search criteria, or any other process that can be performed with an automatically detected setting.

This section covers the following topics:

•

Value Return rule reference

•

Getting registry key values

•

Getting command output

•

Getting PLIST values

•

Getting multiple values

Value Return rule reference

The following table shows all available value return rules that you can use to set a Custom Inventory Field :

Syntax	Win	RHEL	OS X	Description
RegistryValueReturn (registryPath, valueName, type)	X			Returns the value of a registry entry, and sets the datatype to the one you specified.
EnvironmentalVariableReturn (var, type) Specifying environment or user variables	X	X	X	Returns the value of an environment variable, and sets the datatype to the one you specified.
FileInfoReturn (path, attribute, type)	X	X	X	Returns the value of a file attribute, see valid types in Defining rule arguments.
ShellCommandTextReturn (command)	X	X	X	Returns the output of the command, and sets the datatype to TEXT.
ShellCommandDateReturn (command)	X	X	X	Returns the output of the command, and sets the datatype to DATE.
ShellCommandNumberReturn (command)	X	X	X	Returns the output of the command, and sets the datatype to NUMBER.
PlistValueReturn (fullpath, entry, type)			X	Returns the value of the PLIST key, and sets the datatype to TEXT, NUMBER, or DATE.

Getting File Information values

You can set the Custom Inventory Field to any of the Windows File Information attributes using the FileInfoReturn rule.

Example: Getting Mozilla Firefox version

The following example sets the Custom Inventory Field for the Mozilla Firefox Product Version as a NUMBER:

In the Custom Inventory Field, enter the following:

FileInfoReturn(C:\Program Files\Mozilla Firefox\firefox.exe,CurrentVersion,TEXT)

Getting registry key values

You can set the Custom Inventory Field to a registry key using the RegistryValueReturn rule. Where the registryPath (on left) is the path to the entry, the valueName (on right) is the key you want to return. The illustration shows Registry Editor, with a directory tree panel on the left, and name, type and data on the right.

Example: Getting the Mozilla FireFox CurrentVersion key

To set the CurrentVersion registry key as a Custom Inventory Field:

RegistryValueReturn (HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox\CurrentVersion, TEXT

Getting command output

Command rules enable you to set the output of a command to a Custom Inventory Field. The command depends on the command interpreter and executable path on the device.

For example, on Windows devices you can write MS-DOS commands, but not Cygwin-style UNIX commands unless Cygwin is installed and available in the default path for all users.

Use any of the following rules to set the output of the command to a Custom Inventory Field:

•

ShellCommandTextReturn (command)

•

ShellCommandDateReturn (command)

•

ShellCommandNumberReturn (command)

Example: Getting uptime on a Mac OS X

To set the uptime as a Custom Inventory Field:

ShellCommandTextReturn(/usr/bin/uptime | sed -e 's/.*load averages://' | awk '{print $1}')

Getting PLIST values

PlistValueReturn rules enable you to set a Property List (PList) key as a Custom Inventory Field.

Example: Getting the system locale

To distribute applications using Managed Installations based on the System-provided language, enter the following rule to get the device locale and then create a corresponding Smart Label that is applied to the device based on the language code reported by the KACE Agent in the Custom Inventory Field:

PlistValueReturn(~/Library/Preferences/GlobalPreferences.plist, AppleLocale, TEXT)

Getting multiple values

Join ValueReturn rules using either the AND or OR operator. The rule shows the application as an Installed Program, if any of the values are not empty.

The joined values are all set in the same Custom Inventory Field separated by the operator and therefore are technically considered for the purposes of Search Criteria, filters, reports, and other appliance processes as TEXT.

ValueReturn rules joined by the:

•

AND operator: All the values are reported in the Custom Inventory Field.

•

OR operator: All values are reported in the Custom Inventory Field.

In the Custom Inventory field, join rules using the following syntax:

Function(arguments...) AND Function(arguments) AND ...

Separate the conditional statements from the operator with spaces. Do not join AND and OR operators in the same rule.

Matching filenames to regular expressions

Understanding regular expressions

Regular Expression Rule Reference

Regular expressions match a character or the specified string to the filenames in the specified directory.

This section describes the regular expressions that match filenames in Conditional and Value Return rules using a regular expression.

NOTE: The KACE Agent only provides functions that compare filenames using regular expressions.

Understanding regular expressions

You can use regular expression syntax to match filenames.

Tip:	TIP: For more information on writing regular expressions go to http://msdn.microsoft.com/en-us/library/az24scfc.aspx.

The following table provides an overview of the regular expression syntax used to match filenames:

Character	Description	Example Expression	Target Files	Files Matched
(any string)	Non-special characters match any filename that contains the string.	abc	abcFile.xls Example.jpg File.doc Myabc.txt MyFile.abc	abcFile.xls Myabc.txt MyFile.abc
.	Dot matches any single character. When entered alone it matches all files.	.	abcFile.xls Example.jpg File.doc Myabc.txt MyFile.abc	abcFile.xls Example.jpg File.doc Myabc.txt MyFile.abc
\	Backslash is used to escape a special character and for creating a back-reference. For more information, go to http://rexegg.com/regex-capture.html.	.*\.txt$	abcFile.xls Example.jpg File.doc Myabc.txt MyFile.abc	Myabc.txt
^	Caret matches the characters you specify to the start of the filename.	^k	install.exe kinstaller.exe runkbot.bat	kinstaller.exe
\|	Pipe separates a list of options to match.	run\|install	install.exe kinstaller.exe runkbot.bat	install.exe kinstaller.exe runkbot.bat
$	Dollar matches the characters you specify to the end of the filename.	bat$	install.exe kinstaller.exe runkbot.bat	runkbot.bat
?	Question mark makes the preceding character optional in matches.	\.log10?$	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	a.log1 mylog.log10
*	Asterisk matches the preceding character zero or more times.	\.log1*$	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	a.log1 app.log appconf.log11
+	Plus matches the preceding character one or more times.	ap+.*\.log	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	app.log appconf.log11
[ ]	Brackets enclose a character class and match any character within the brackets. Character class special character rules differ from normal regular expressions.	[123]	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	a.log1 afile.txt3 appconf.log11 mylog.log10
()	Parentheses enclosing characters create a back reference and match the preceding characters and/or the enclosed characters. For more information, go to http://rexegg.com/regex-capture.html.	(p)\1	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	app.log appconf.log11
{n}	Curly brackets repeat the preceding character the number of specified times, where n is greater than or equal to 1.	{p}\.log$	a.log1 afile.txt3 app.log appconf.log11 mylog.log10	app.log

Seleziona il prodotto:

Per una maggiore efficacia, compilare l'Obiettivo della chat:

Soluzioni consigliate per il problema

KACE Systems Management Appliance 14.1 Common Documents - KACE Service Desk Administrator Guide

Checking for conditions (conditional rules)

Getting values from a device (Custom Inventory Field)

Matching filenames to regular expressions

Understanding regular expressions