IF-ELSE-STEP Commands

The following is a summary of IF-ELSE-STEP commands used in VSA agent procedures.

IF Commands

Application is Running

Checks to see if a specified application is currently running on the managed machine. If the application is running, the IF command is executed; otherwise, the ELSE command is executed. When this option is selected from the drop-down list, the Enter the application name field appears. Specify the process name for the application you want to test. For example, to test the Calculator application, specify calc.exe, which is the process name that displays in the Processes tab of the Windows Task Manager.

Check Registry Value / Check 64-Bit Registry Value

After entering the registry path, the value contained in the key is returned. A check can be made for existence, absence, equality, or size differences. For example, HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\AppPaths\AgentMon.exe\path contains the directory path identifying where the agent is installed on the target machine. The test determines if the value stored for this key exists, thereby verifying the agent is installed.

A backslash character \ at the end of the key returns the default value of that key. HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\WORDPAD.EXE\ returns a default value, such as %ProgramFiles%\Windows NT\Accessories\WORDPAD.EXE

The available tests are:

• Exists : true if the registry key exists in the hive.
• Does Not Exist : true if the registry key does not exist in the hive.
• = : true if value of the registry key equals the test value.
• Not = : true if value of the registry key does not equal the test value.
• > : true if value of the registry key is greater than the test value (value must be a number).
• >= : true if value of the registry key is greater than or equal to the test value (value must be a number).
• < : true if value of the registry key is less than the test value (value must be a number).
• <= : true if value of the registry key is less than or equal to the test value (value must be a number).
• Contains : true if the test value is a sub string of the registry key value (value must be a string).
• Not Contains : true if the test value is not a sub string of the registry key value (value must be a string).

Check Variable

Enter a variable name, in the form #var_name#, in the space provided. Check Variable evaluates the current values assigned #var_name# and compares it with the supplied value. The supplied value may also be another variable name in the form of #var_name2#.  If the check is true, IF commands are executed. If the check is false, ELSE steps are executed. See Using Variables. The available tests are:

• Exists : true if the variable exists.
• Does Not Exist : true if the variable does not exist.
• = : true if value of the variable equals the test value.
• Not = : true if value of the variable does not equal the test value.
• > : true if value of the variable is greater than the test value.
• >= : true if value of the variable is greater than or equal to the test value.
• < : true if value of the variable is less than the test value.
• <= : true if value of the variable is less than or equal to the test value.
• Contains : true if the test value is a sub string of the variable value.
• Not Contains : true if the test value is not a sub string of the variable value.
• Begins With : true if the test value begins with the variable value.
• Ends With : true if the test value ends with the variable value.

For the tests =, Not =, >, >=, <, and <= the variables compared may be a string, a number, a date in the format of yyyy/mm/dd or yyyy/mm/dd hh:mm or yyyy/mm/dd hh:mm:ss, or a version number containing dots or commas such as 1.2.3 or 4,5,6,7. If a date format is specified, it may be offset using + dd:hh:mm:ss or - dd:hh:mm:ss. Only dd days are required; hh hours, mm minutes, and ss seconds may be omitted and are assumed to be zero when absent. CURRENT_TIMESTAMP may be specified to indicate that the current time be substituted in the comparison at the time the procedure is executed.  e.g. CURRENT_TIMESTAMP - 7:12:00:00 will be evaluated as 7 days and 12 hours subtracted from the time that the procedure is executed.

Evaluate Expression

Enter an expression containing one or more variable names, in the form #var_name#, in the space provided. Evaluate Expression uses the current value assigned to each #var_name#, evaluates the mathematical expression, and compares it with the supplied value. The supplied value may also be another expression. The mathematical expression may contain +, -, *, /, (, and ).  e.g.  (3.7 + (200 * #countA#)) / (#countB# - #countC#). If the check is true, IF steps are executed. If the check is false, ELSE steps are executed. The available tests are:

• = : true if value of the variable equals the test value.
• Not = : true if value of the variable does not equal the test value.
• > : true if value of the variable is greater than the test value.
• >= : true if value of the variable is greater than or equal to the test value.
• < : true if value of the variable is less than the test value.
• <= : true if value of the variable is less than or equal to the test value.

  Note: Cannot be used with Exists, Does Not Exist, Contains, or Not Contains operators.

Service is Running

Determines if a service is running on the managed machine. Specify the service name.

• True if the service name is running.
• False if the service name is stopped or does not exist.

  Note: Be sure to use the service name of the service, not the display name of the service. For example, the display name of the service for Microsoft SQL Server is SQL Server (MSSQLSERVER), but the service name of the service is MSSQLSERVER. For Windows machines, right click any service in the Services window and click the Properties option to see the service name of that service.

Test File

Determines if a file exists on a managed machine. Enter the full path and file name. Test File compares the full path and file name with the supplied value. If the check is true, IF commands are executed. If the check is false, ELSE steps are executed.

Note: Environment variables such as %windir%\notepad.exe are acceptable.

The available tests are:

• Exists : true if the full path and file name exists.
• Does not Exist : true if the full path and file name does not exist.
• Contains : true if the test value is a sub string of the file content.
• Not Contains : true if the test value is not a sub string of the file content.
• Begins With : true if the test value begins with the variable value.
• Ends With : true if the test value ends with the variable value.

Test File in Directory Path

Tests the specified file located at the path returned using the Get Directory Path From Registry step. The available tests are:

• Exists : true if the file name exists.
• Does not Exist : true if the file name does not exist.
• Contains : true if the test value is a sub string of the file content.
• Not Contains : true if the test value is not a sub string of the file content.
• Begins With : true if the test value begins with the variable value.
• Ends With : true if the test value ends with the variable value.

Test Registry Key / Test 64-bit Register Key

Tests for the existence of a registry key. Test Registry Key differs from Check Registry Value since it can check for a directory level registry entry that only contains more registry keys (no values).

True

Selecting True directs the IF commands to execute. Use True to directly execute a series of steps that do not require any decision points, such as determining whether a file exists using Test File.

User Is Logged In

Tests to see if a specific user or any user is logged on the managed machine. Enter the machine user's logon name or leave the field blank to check for any user logged on. The IF commands are executed if a user is logged on. The ELSE steps are executed if the user is not logged on.

User Response is Yes

Displays a dialog box on the managed machine with Yes and No buttons. Also carries out the ELSE command if a specified amount of time has timed out. If Yes is selected by the machine user, the IF command is executed. If the selection times out or the machine user selects No, the ELSE command is executed. This function requests the machine user's permission to proceed with the agent procedure. This query is useful for agent procedures that require a reboot of the managed machine before completion.

Procedure variables, for example #varName#, may be used inside User Response is Yes fields to dynamically generate messages based on procedure data.

STEP Commands

Close Application

If the specified application is running on the managed machine, then that application is closed down. Specify the process name for the application you want to close. For example, to close the Calculator application, specify calc.exe, which is the process name that displays in the Processes tab of the Windows Task Manager.

Delete File

Deletes a file on a managed machine. Enter the full path and filename.

Note: Environment variables are acceptable if they are set on a user's machine.  For example, using a path %windir%\notepad.exe would be similar to C:\windows\notepad.exe.

Note: You can delete a file that is currently in use using the Rename Locked File command.

Delete File in Directory Path

Deletes the specified file located at the path returned using the Get Directory Path From Registry command.

Delete Registry Key / Delete 64-bit Registry Key

Deletes the specified registry key and all its sub-keys.

Delete Registry Value / Delete 64-bit Registry Value

Deletes the value stored at the specified registry key.

Execute File

Executes the specified file on the managed machine. This function replicates launching an application using the Run… command located in the Microsoft Windows Start menu. This function takes three parameters:

• Full path filename to the .exe file.
• Argument list to pass to the .exe file
• Option for the procedure to wait until the .exe completes or not.

  Note: Environment variables are acceptable, if they are set on a user's machine.  For example, using a path %windir%\notepad.exe, would be similar to C:\windows\notepad.exe.

If Execute as the logged on user is selected, then a credential must be specified by running either the Impersonate User or Use Credential command before this command. If run Execute as the system account is selected, execution is restricted to the agent's system level access.

Execute File in Directory Path

Same as Execute File except the location of the .exe file is located at the path returned from a Get Directory Path From Registry command.

If Execute as the logged on user is selected, then a credential must be specified by running either the Impersonate User or Use Credential command before this command. If run Execute as the system account is selected, execution is restricted to the agent's system level access.

Execute Procedure

Causes another named procedure to execute. Use this capability to string multiple IF-ELSE-STEP procedures together. If the procedure no longer exists on the KServer, an error message displays next to the procedure drop-down list. You can use this command to run a system procedure. You can nest procedures to 10 levels.

Execute Shell Command

Allows the procedure to pass commands to the command interpreter on the managed machine. When this command is selected, the field Enter the command to execute in a command shell is displayed. Enter a command in the field. The command must be syntactically correct and executable with the OS version on the managed machine. Commands and parameters containing spaces should be surrounded by quotes. Since the command is executed relative to the agent directory, absolute paths should be used when entering commands.

Note: Execute Shell Command opens a command prompt window on the managed machine to execute in. If you do not want a window opening on the managed machine, because it might confuse users, put all the commands in a batch file. Send that file to the managed machine using the Write File command. Then run the batch file with the Execute File command. Execute File does not open a window on the managed machine.

If Execute as the logged on user is selected, then a credential must be specified by running either the Impersonate User or Use Credential command before this command. If run Execute as the system account is selected, execution is restricted to the agent's system level access.

Get Directory Path From Registry

Returns a file path stored in the specified registry key. Use this command to fetch the file location. For instance, use this command to find the directory where an application has been installed. The result can be used in subsequent steps by:

• Delete File in Directory Path
• Execute File in Directory Path
• Get File in Directory Path
• Rename Locked File in Directory Path
• Test File in Directory Path (an IF command)
• Write File in Directory Path

Get File

Upload the file at the specified path from the managed machine. Be sure to enter a full path filename that you want to upload. Example: news\info.txt. Folders are created when the Get File command is run, if they don't already exist. The file is stored on the KServer in a private directory for each managed machine. View or run the uploaded file using Agent Procedures > Get File.

• Optionally, existing copies of uploaded files are renamed with a .bak extension prior to the next upload of the file. This allows you to examine both the latest version of the file and the previous version.
• Optionally create a Get File alert if the uploaded file differs or is the same from the file that was uploaded previously. You must create a Get File alert for a machine ID using the Monitor > Alerts - Get File page to enable the sending of an alert using the Get File command. Once defined for a machine ID, the same Get File alert is active for any agent procedure that uses a Get File command and is run on that machine ID. Turn off alerts for specific files in the agent procedure editor by selecting one of the without alerts options.

Get File in Directory Path

Just like the Get File command but it adds the path returned from the Get Directory Path From Registry command to the beginning of the remote file path. Access the uploaded file using the Agent Procedures > Get File function.

Get URL

Returns the text and HTML contents of a URL and stores it to a file on the managed machine. To demonstrate this to yourself, try specifying www.kaseya.com as the URL and c:\temp\test.htm as the file to store the contents of this URL. A copy of the web page is created on the managed machine that contains all of the text and HTML content of this webpage. You can search the contents of the file on the managed machine in a subsequent command.

Another use is to download an executable file that is available from a web server, so that you don't need to upload the file to the VSA server nor use the VSA's bandwidth to write the file down to each agent. You can use a subsequent command to run the downloaded executable on the managed machine.

Get Variable

Defines a new agent variable. When the procedure step executes, the system defines a new variable and assigns it a value based on data fetched from the managed machine's agent.

Note: See Using Variables for the types of variable values supported by the Get Variable command.

Impersonate User

Enter a username, password, and domain for the agent to logon with. This command is used in a procedure before an Execute File, Execute File in Directory Path or Execute Shell Command that specifies the Execute as the logged on user option. Leave the domain blank to log into an account on the local machine. Use Impersonate User to run an agent procedure using a credential specified by agent procedure. Use Use Credential to run an agent procedure using a credential specified by managed machine.

Pause Procedure

Pause the procedure for N seconds. Use this command to give Windows time to complete an asynchronous task, like starting or stopping a service.

Reboot

Unconditionally reboots the managed machine. To warn the user first, use the User Response is Yes command before this command. A User Response is Yes command prompts the user before rebooting their machine.

Rename Locked File

Renames a file that is currently in use. The file is renamed the next time the system is rebooted. The specified filename is a complete file path name. Can be used to delete a file that is currently in use if the "new file name" is left blank. The file is deleted when the system is rebooted.

Rename Locked File in Directory Path

Renames a file that is currently in use that is located in the path returned from a Get Directory Path From Registry command. The file is renamed the next time the system is rebooted. Can be used to delete a file that is currently in use if the "new file name" is left blank. The file is deleted when the system is rebooted.

Schedule Procedure

Schedules a procedure to run on a specified machine. Optionally specifies the time to wait after executing this step before running the procedure and the specified machine ID to run the procedure on. If no machine is specified, then the procedure is run on the same machine running the agent procedure. Enter the complete name of the machine, for example, machine.unnamed.org. This command allows an agent procedure running on one machine to schedule the running of an agent procedure on a second machine. You can use this command to run a system procedure. You can nest procedures to 10 levels.

Send Email

Sends an email to one or more recipients. Specifies the subject and body text of the email.

Send Message

Sends the entered message to a managed machine. An additional checkbox, if checked, sends the message immediately. If unchecked, sends the message after the user clicks the flashing agent system tray icon.

Send URL

Displays the entered URL in a web browser window on the managed machine. An additional checkbox, if checked, displays the URL immediately. If unchecked, the URL is displayed after the user clicks the flashing agent system tray icon.

Set Registry Value / Set 64-bit Registry Value

Writes data to the specified registry value. This function takes three parameters:

• Enter the full path to a registry key containing a value - Specify the (Default) value for a registry key by adding a trailing backslash \. Otherwise specify a name for an existing value or to create a new value. See Name column in image below.
  Example of setting the (Default) value: HKEY_LOCAL_MACHINE\SOFTWARE\000Sample\
• Enter the data to write to the registry value
• Select the data type
  • REG_SZ - String value.
  • REG_BINARY - Binary data displayed in hexadecimal format.
  • DWORD - Binary data limited to 32 bits. Can be entered in hexadecimal or decimal format.
  • REG_EXPAND_SZ - An "expandable" string value holding a variable. Example: %SystemRoot%.
  • REG_MULTI_SZ - A multiple string array. Used for entering more than one value, each one separated by a \0 string. Use \\0 to include \0 within a string array value.

  

Update System Info

Updates the selected System Info field with the specified value for the machine ID this procedure runs on. The System Info fields you can update include all columns in vSystemInfo except agentGuid, emailAddr, Machine_GroupID, machName, and groupName. vSystemInfo column information is used by Audit > System Info, Agent > System Status, the Filter Aggregate Table in View Definitions, and the Aggregate Table report.You can update a System Info field using any string value, including the value of any previously defined agent procedure variable.

Use Credential

Uses the credentials set for the machine ID in Set Credential. This command is used in a procedure before an Execute File, Execute File in Directory Path or Execute Shell Command that specifies the Execute as the logged on user option. Also used to access a network resource requiring a credential from a machine when a user is not logged on. Use Impersonate User to run an agent procedure using a credential specified by agent procedure. Use Use Credential to run an agent procedure using a credential specified by managed machine.

Note: A procedure execution error is logged if a Set Credential procedure command encounters an empty username.

Note: Patch Management > Patch Alert can alert you—or run an agent procedure—if a machine ID's credential is missing or invalid.

Write Directory

Writes a selected directory, including subdirectories and files, from Manage Files Stored on Server to the full path directory name specified on the managed machine.

Write File

Writes a file selected from Manage Files Stored on Server to the full path filename specified on the managed machine. Enter a new filename if you want the file to be renamed.

Each time a procedure executes the Write File command, the agent checks to see if the file is already there or not by hashing the file to verify integrity. If not, the file is written. If the file is already there, the procedure moves to the next step. You can repeatedly run a procedure with Write File that sends a large file to a managed machine and know that the VSA only downloads that file once.

Note: Environment variables are acceptable if they are set on a user's machine. For example, using the path %windir%\notepad.exe would be equivalent to C:\windows\notepad.exe.

Write File in Directory Path

Writes the specified filename to the path returned from a Get Directory Path From Registry command.

Write Procedure Log Entry

Writes the supplied string to the Agent Procedure Log for the machine ID executing this agent procedure.

Topic 674: Send Feedback. Download a PDF of this online book from the first topic in the table of contents. Print this topic.