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

Conditional rules: These rules test whether conditions exist on devices. When a rule returns true, the KACE Agent reports the item as an Installed Program. When the rule returns false, the item does not appear as an Installed Program.

•

Value Return rules: These rules obtain data from devices. If the value exists, the KACE Agent reports the item as an Installed Program and sets a corresponding Custom Inventory Field.

Create Custom Inventory rules

How Custom Inventory rules are implemented

Syntax for Custom Inventory rules

You can create custom applications, and Custom Inventory rules for those applications, so that information about the applications is gathered from managed devices.

Go to the Software Detail page:

Log in to the appliance Administrator Console, https://appliance_hostname/admin. Or, if the Show organization menu in admin header option is enabled in the appliance General Settings, select an organization in the drop-down list in the top-right corner of the page next to the login information.

On the left navigation bar, click Inventory, then click Custom Inventory.

Select Choose Action > New.

Provide general information: Name, Version, Publisher.

For proper downstream reporting, enter this information consistently across software inventory.

Provide the following information:

Option	Description
Restrict To Label	(Optional) The label associated with the item.
Notes	Any additional information you want to provide.
Supported Operating Systems	The operating systems on which the application runs. Applications are deployed only to devices with the selected operating systems.
Custom Inventory Rule	(Optional) The custom inventory rules to apply to the application. Custom inventory rules enable you to detect applications and other items on a device and capture details for reporting. For example, the appliance first verifies whether an application is present on a device before deploying that application. In some instances, however, installed programs do not register in Add/Remove Programs or in standard areas of the registry. In such cases, the appliance might not be able to detect the presence of the application without additional information from the administrator. Therefore, the appliance might repeat the installation each time the device connects. Custom Inventory rules can prevent this repetition. The following rule verifies that the version of the Network Associates VirusScan installed on a device is newer than a given version before deploying it: RegistryValueGreaterThan(HKEY_LOCAL_MACHINE\ Software\Network Associates\TVD\ Network Associates\TVD\Shared Components\ VirusScanEngine\4.0.xx,szDatVersion,4.0.44)

Next to Upload and Associate File, click Choose File to locate a file, then click Open or Choose.

To distribute applications using Managed Installations or File Synchronizations, you need to associate the actual application files with the application.

To prevent the file from being copied to Replication Shares, select Don’t Replicate Associated File. This setting is useful for large files that you do not want users to install from Replication Shares, such as software suites.

Optional: Select a Category and Threat Level for the software.

Click Save.

How Custom Inventory rules are implemented

The KACE Agent receives new Custom Inventory rules during the first device inventory after the rules are created. During that first inventory, the Agent runs the new rules and reports the findings to the appliance.

The Agent runs all rules as well as any other processes scheduled for that session. Therefore, after a device is inventoried, it could take several minutes to run all the rules and other processes before the Agent reports the results.

After the Agent reports the results, the device’s detail page shows the results under Software in Installed Programs and Custom Inventory Fields.

NOTE: The applications with Value Return rules that set a Custom Inventory Field also appear as Installed Programs.

If results are not what you expect, verify that the device has been inventoried recently. The inventory time is shown in the Last Inventory field of the device detail page.

Syntax for Custom Inventory rules

Use the correct syntax for function names and arguments in Custom Inventory rules.

Conditional and Value Return rules use the following syntax:

functionName(argument,argument,...)

For specific information on functions and their arguments see:

•

Checking for conditions (conditional rules)

•

Getting values from a device (Custom Inventory Field)

•

Matching filenames to regular expressions

Function syntax

Enter the functionName followed by an opening parenthesis, enclose the arguments with a closing parenthesis. No spaces are allowed between the name of the function and the opening parenthesis.

Argument syntax

Enter argument syntax for all rules except command and regex (regular expression) as follows:

•

Separate arguments by commas.

•

Commas are not allowed anywhere else in the string, except as described in Commas and parentheses as values in a rule.

•

Do not include single or double quotation marks.

•

White space is trimmed from the front and back of each argument.

For example, the following syntaxes are the same:

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox, CurrentVersion, 78.0.2)
RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox,CurrentVersion,78.0.2)

Commas and parentheses as values in a rule

If comma, open parenthesis, or close parenthesis are to be used as values in a rule, they must be escaped as {{comma}}. {{op}}, and {{cp}}, respectively.

•

In arguments where commas are needed as part of the parameter value, the comma needs to be escaped as {{comma}}, except for the last argument in the function.

For example, if the user want to test against the registry value in which the value name is "test,value", the user would need to escape the comma in this case because registry value name is not the last argument in the Custom Inventory (CI) function.

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\TestSoft, test{{comma}}value, HelloWorld)

If the user wants to test against the registry value where the value itself contains a comma, then there is no need to escape, because value is the last argument in the Custom Inventory function. The following Custom Inventory tests registy value HKLM\SOFTWARE\TestSoft\test1 and looks to see if the value is equal to 2,4.

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\TestSoft,test1,2,4)

If the Custom Inventory function contains only one parameter, it takes everything between the parentheses as the value for the argument. Commas in this case do not need to be escaped and will be part of the argument to the Custom Inventory function.

ShellCommandTextReturn(wmic MEMORYCHIP get BankLabel,Capacity,description,manufacturer)

•

An unmatched literal open parenthesis needs to be escaped as {{op}}. When the parser is tokenizing the arguments for the function, it counts the number of open and close parentheses to determine the end of the function and argument. Therefore, an unmatched literal open parenthesis would throw off the count, and cause the argument value to be parsed incorrectly. If a literal open parenthesis is needed as part of the argument value, it should be represented with {{op}}.

For example, if the user wants to echo the string "Hello ( World", then the CI should look like the following:

ShellCommandTextReturn(echo Hello {{op}} World)

•

Unmatched literal close parentheses needs to be escaped as {{cp}}.

While the parser is tokenizing the arguments for the function, it counts the number of open and close parentheses in order to determine the end of the function when it encounter the last matched close parentheses. However, if the argument value itself contains a close parenthesis that is not matched, the parenthesis tricks the parser to believe that is the end of the function and the argument value will be truncated prematurely.

If a literal close parentheses is needed as part of the argument value, it must be represented with {{cp}}.

For example, if the user wants to echo the string "Hello ) World", then the CI should look like the following:

ShellCommandTextReturn(echo Hello {{cp}} World)