Agent Procedures

April 15, 2021

User Guide

Version R95

English

The purchase and use of all Software and Services is subject to the Agreement as defined in Kaseya’s

“Click-Accept” EULATOS as updated from time to time by Kaseya at

http://www.kaseya.com/legal.aspx. If Customer does not agree with the Agreement, please do not

install, use or purchase any Software and Services from Kaseya as continued use of the Software or

Services indicates Customer’s acceptance of the Agreement.”

Contents

Agent Procedures Overview

Contents

Agent Procedures Overview ....................................................................................................................... i

Manage Procedures .................................................................................................................................... ii

Schedule / Create ................................................................................................................................. ii

Action Buttons ............................................................................................................................. ii

Scheduling Agent Procedures .................................................................................................. iii

Creating / Editing Agent Procedures ......................................................................................... v

IF-ELSE-STEP Commands ....................................................................................................... viii

IF Commands ...................................................................................................................... xi

STEP Commands ............................................................................................................... xv

64-Bit Commands ................................................................................................................. xxxvi

Using Variables .................................................................................................................... xxxvii

Variable Manager ........................................................................................................................ xl

Manage Files Stored on Server ................................................................................................ xli

Folder Rights .............................................................................................................................. xli

Distribution ........................................................................................................................................ xlii

Agent Procedure Status .................................................................................................................. xliii

Pending Approvals .......................................................................................................................... xliv

Installer Wizard ......................................................................................................................................... xlv

Patch Deploy ..................................................................................................................................... xlv

Application Deploy ......................................................................................................................... xlvii

Creating Silent Installs .......................................................................................................... xlviii

File Transfer ............................................................................................................................................. xlix

Get File .............................................................................................................................................. xlix

Distribute File ........................................................................................................................................ l

Administration ............................................................................................................................................ lii

Application Logging ........................................................................................................................... lii

Index ........................................................................................................................................................... 55

Agent Procedures Overview

Agent Procedures

The Agent Procedures module automates tasks performed on managed machines. Agent procedures

can be run immediately, by schedule, or in response to a VSA system event or API request. The Agents

Procedures module also enables you to:

 Approve newly created or edited agent procedures using Pending Approvals (page xliv). As a

security precaution, all agent procedures must be signed and approved before they can be run.

 View the status of all procedures run on a managed machine using Agent Procedure Status

(page xliii).

 Spread out the impact agent procedures have on network traffic and server loading using

Distribution (page xlii).

 Transfer files to and from managed machines using Get File (page xlix) and Distribute File (page l).

 Schedule the installation of Microsoft and non-Microsoft applications and patches using Patch

Deploy (page xlv) and Application Deploy (page xlvii).

Note: See Patch Management (http://help.kaseya.com/webhelp/EN/KPATCH/9050000/index.asp#2200.htm)

to install Microsoft patches on managed machines.

Functions

Description

Schedule / Create (page

ii)

Automates user-defined tasks on managed machines by creating

and scheduling agent procedures.

Distribution (page xlii)

Minimizes network traffic and server loading by executing agent

procedures evenly throughout the day.

Agent Procedure Status

(page xliii)

Shows the status of agent procedures executed on managed

machines.

Pending Approval (page

xliv)

Approves newly created or edited agent procedures.

Patch Deploy (page xlv)

Use this wizard tool to create procedures to deploy Microsoft

patches to managed machines.

Application Deploy (page

xlvii)

Use this wizard tool to create procedures to deploy non-Microsoft

install packages (setup.exe) to managed machines.

Get File (page xlix)

View and manage files uploaded to the Kaseya Server from

managed machines using the getFile() agent procedure

command.

Distribute File (page l)

Write files to all selected managed machines and maintain them.

Application Logging

Shows the audit of agent procedures executed on managed

machines.

ii Contents

Manage Procedures

Schedule / Create

Agent Procedures > Manage Procedures > Schedule / Create

The Schedule / Create page automates user-defined tasks on managed machines by creating and

scheduling agent procedures. See the following topics for details:

 Action Buttons (page ii)

 Scheduling Agent Procedures (page iii)

 Creating / Editing Agent Procedures (page v)

 IF-ELSE-STEP Commands (page viii)

 64-Bit Commands (page xxxvi)

 Using Variables (page xxxvii)

 Variable Manager (page xl)

 Manage Files Stored on Server (page xli)

 Folder Rights (page xli)

Related Topics

 Alert triggered agent procedures - Almost all configurable alerts in the VSA include a Run Agent

Procedure option that you can use to run a selected agent procedure if the alert is triggered. For

example, the Alerts page contains a list of alerts that include this option.

 Agent Procedure Failure Alerts - The Alerts - Agent Procedure Failure page triggers an alert when an

agent procedure fails to execute on a managed machine. For example, if you specify a file name,

directory path or registry key in an agent procedure, then run the agent procedure on a machine

ID for which these values are invalid, you can be notified about the agent procedure failure using

this alerts page.

 Logging Failed Steps in Procedures - The System > Configure page includes the following option -

Enable logging of procedure errors marked "Continue procedure if step fail" - If checked, failed steps in

procedures are logged. If blank, failed steps in procedures are not logged.

 Preventing the Logging of Successful Child Script Execution - The System > Configure page includes

the following option - Enable logging of successful child script execution in agent procedure log - If

unchecked, child script success entries are not included in the agent procedure log. This can

reduce the size of the agent procedure log tremendously. It takes up to 5 minutes for the KServer

to read this setting change.

 View Definitions - You can filter the display of machine IDs on any agent page using the following

agent procedure options in View Definitions.

 With procedure scheduled/not scheduled

 Last execution status success/failed

 Procedure has/has not executed in the last N days

 Service Desk - When a ticket service procedure is run, it can execute an agent procedure

(http://help.kaseya.com/webhelp/EN/KSD/9050000/index.asp#6267.htm).

Action Buttons

Agent procedures are organized using three folder trees in the middle pane, underneath Private, Shared

and System cabinets. The following action buttons display, depending on the object selected in the

folder tree.

When a Cabinet is Selected

iii

 Collapse All - Collapses all branches of the folder tree.

 Expand All - Expands all branches of the folder tree.

Always Available

 Manage Files - See Manage Files Stored on Server (page xli) for more information.

 Manage Variables - See Variable Manager (page xl) for more information.

 (Apply Filter) - Enter text in the filter edit box, then click the funnel icon to apply filtering to the

folder trees. Filtering is case-insensitive. Match occurs if filter text is found anywhere in the folder

trees.

When a Folder is Selected

 Share Folder - Shares a folder with user roles and individual users. Applies to shared cabinet

folders only.

Note: See guidelines for share rights to objects within folder trees in the Folder Rights (page xli)

topic.

 New Procedure - Opens the agent procedure editor to create a new procedure in the selected folder

of the folder tree. See Creating / Editing Agent Procedures (page v).

 New Folder - Creates a new folder underneath the selected cabinet or folder.

 Delete Folder - Deletes a selected folder.

 Rename Folder - Renames a selected folder.

 Import Folder/Procedure - Imports a folder or procedure as children to the selected folder in the

folder tree. Applies to private cabinet folders only.

Note: The Import Center will import a previously exported

shared

agent procedure folder or procedure

to the Shared cabinet. It will not overwrite any folder or procedure using the same name and tree

path.

 Export Folder - Exports the selected folder and all its procedures as an XML file. The XML file can

be re-imported.

Additional Actions When a Procedure is Selected

 Edit Procedure - Opens the agent procedure editor to edit the selected procedure. See Creating /

Editing Agent Procedures (page v).

 Rename Procedure - Renames the selected procedure.

 Delete Procedure - Deletes the selected procedure. Agent procedures that are used by other agent

procedures cannot be deleted.

 Export Procedure - Exports the selected procedure.

Scheduling Agent Procedures

Manage the scheduling of agent procedures using tabs in the right hand pane. When a procedure is

selected in the middle pane, the following tabs display In the right-hand pane.

Schedule Tab

Select one or more machine IDs in this tab's table to schedule agent procedure.

Action Buttons

 Schedule - Select one or more machine IDs in this tab's table, then click one of the following action

buttons:

iv Contents

 Schedule Procedure - Schedule a task once or periodically. Each type of recurrence—Each

type of recurrence - Once, Minutes, Hourly, Daily, Weekly, Monthly—displays additional

options appropriate for that type of recurrence. Periodic scheduling includes setting start and

end dates for the recurrence. Not all options are available for each task scheduled. Options

can include:

 Schedule will be based on the timezone of the agent (rather than server) - If checked, time

settings set in the Scheduler dialog reference the local time on the agent machine to

determine when to run this task. If blank, time settings reference server time, based on

the server time option selected in System > Preferences. Defaults from the System >

Default Settings page.

 Distribution Window - Reschedules the task to a randomly selected time no later than the

number of periods specified, to spread network traffic and server loading. For example,

if the scheduled time for a task is 3:00 AM, and the distribution window is 1 hour, then

the task schedule will be changed to run at a random time between 3:00 AM and 4:00

AM. Distribution Window must be greater than or equal to the Recurrence Interval.

 Skip if offline - If checked and the machine is offline, skip and run the next scheduled

period and time. If blank and the machine is offline, run the task as soon as the

machine is online again. Applies only to recurring schedules, a 'Once' schedule always

executes the next time the agent is online.

 Power up if offline - Windows only. If checked, powers up the machine if offline. Requires

Wake-On-network or vPro and another managed system on the same network.

 Exclude the following time range - Applies only to the distribution window. If checked,

specifies a time range to exclude the scheduling of a task within the distribution

window. Specifying a time range outside of the distribution window is ignored by the

scheduler.

Note: You can stagger the running of scheduled agent procedures using Agent Procedures

> Distribution (page xlii).

 Run Now - Run this agent procedure on each selected machine ID immediately.

 Cancel - Cancel the scheduled agent procedure on each selected machine ID.

 Refresh - Refreshes the table.

Note: The Cancel button only cancels the Agent Procedure

schedule

. It does not stop execution of a

procedure that has already started running. Once a procedure has started running, it will run to

completion unless the agent goes offline or the Kaseya Agent service is stopped or restarted.

Columns

 Check-in Status - These icons indicate the agent check-in status of each managed machine.

Hovering the cursor over a check-in icon displays the agent Quick View window.

Agent is currently offline

User Logged In and Agent is Active

User Logged In and Agent is Inactive

User Not Logged In and Agent is online

User Not Logged In and Agent is Idle

The agent has been suspended

Agent has never checked in

 Machine ID - The list of Machine.Group IDs displayed is based on the Machine ID / Machine

Group FilterMachine ID / Machine Group Filter and the machine groups the user is authorized to

see using System > User Security > Scopes.

 Last Time Exec - The time the agent procedure was last executed on selected machines.

 Last Exec Status - Time of the last known status of the executed agent procedure.

 Next Exec Time - The time the next agent procedure will execute on selected machines.

 Current Logged In User - Logon name of the machine user currently logged into the machine.

 Last Logged In User - Logon name of the last person to log into the machine.

 Approval History - Displays a list of dates and users that approved the procedure.

Page Selector

If the selector panel list is longer than one page, the page selector enables you to browse through

multiple pages. You can set the number of rows displayed on each page.

View Procedure tab

Provides a display only view of the procedure. A user can execute an agent procedure and view it

without necessarily being able to edit it. See Folder Rights (page xli) for more information.

Used by tab

Displays a list of other procedures that execute this procedure. Agent procedures that are used by

other agent procedures cannot be deleted.

Columns

 Folder - The name of folder that are used by other agent procedures.

 Procedure - The name of executed procedure.

Creating / Editing Agent Procedures

To create a new procedure:

1. Select a cabinet or folder in the middle pane.

2. Then click the New Procedure button to open the Creating / Editing Agent Procedures dialog.

To edit an existing procedure:

1. Select the procedure.

2. Then click the Edit Procedure button to open the Creating / Editing Agent Procedures dialog. You

can also double-click a procedure to edit it.

Note: Access to creating or editing a procedure depends on your Folder Rights (page xli).

vi Contents

The Agent Procedure Editor

The Procedure Editor has 3 main sections: the Statements pane, the Procedure pane, and the

Properties pane. All statements you can add to an agent procedure display in the left-hand pane.

Agent procedures display in the middle pane of the editor on one more tabs. The parameters for each

statement display in the right-hand pane.

Note: See IF-ELSE-STEP Statements (page viii) for a detailed explanation of each statement's

parameters.

The Statements pane

The Statements pane contains the available IFS and STEPS (statements) that can be used to create

each procedure line.

The Procedure pane

The Procedure pane displays all of the lines that make up the procedure script.

Action Buttons

These buttons display in the middle pane of the procedure editor.

 Procedure

 New - Creates an empty tab for a new procedure.

 Open - Edits an existing procedure.

 Save - Saves the currently selected procedure.

 Save As - Saves the procedure to a different name. A dialog enables you to select the folder

used to save the procedure.

 Publish - Publishes the procedure to a shared folder.

 Upload File - Uploads file to the File Manager.

 Edit - The following buttons are only enabled when one or more statements are selected.

 Undo - Undoes the last edit.

 Redo - Redoes the last edit.

 Cut - Cuts selected lines.

 Copy - Copies selected lines.

 Paste - Pastes copied lines.

vii

 Remove - Removes selected lines.

 Goto Line - Selects the line number you specify.

 Search - Searches for matching text in commands, parameters and values.

 Insert Lines - Inserts a blank line that you can then begin typing into. This displays a

drop-down list of commands that you can select a command from and insert into the

procedure.

 Indent Lines - Indents selected lines

 Outdent Lines - Outdents selected lines.

 Help

 Help Tips - Display tooltips on how to use the procedure editor.

 Online Help - Displays online help.

 Auto Save - Allows to save automatically the opened procedures.

 Dark/Light Mode - Toggles the interface between dark or light mode.

 Toolbar - Provides commonly used actions to initiate quickly through a single mouse click.

Drag and Drop

 Drag and drop any statement above or below any other statement.

 Drag and drop any comment above or below any statement.

 A statement is automatically indented when dropped below an IF statement, except for an ELSE

statement.

 You can nest steps within multiple IF or ELSE statements. Just drag-and-drop an IF or ELSE

statement below an IF statement to insert it as a child statement.

The Properties pane

The Properties pane displays procedure and statement properties.

Editing lines

One method of editing procedure lines is by using the Properties Pane. Only a single procedure line

can be edited at a time. If there are no lines selected, this pane can be used to edit overall procedure

properties (such as the procedure description).

Guidelines

 Click any STEP, IF or ELSE statement in the middle pane to see its settings in the right-hand

pane. You can edit these settings in the right hand pane or click any value in a statement directly

to edit it.

 Multiple lines can be selected and acted on at one time.

 Right click selected lines to get additional options.

 Enter a value in search box in Statement pane to filter the list of statements you can select.

 Hovering the cursor over any statement in Procedure pane displays a tooltip description of that

statement. The same description displays on Properties pane.

 Hovering the cursor to the left of selected statements displays icons. Click these

icons to remove, indent or outdent selected statements.

 When entering a value for a variable into a parameter:

 Enter a < to select from a list of system variables.

 Enter a # to select from a list of user defined variables (page xxxvii).

 Open and work on multiple procedures simultaneously. Each procedure you open displays in a

separate tab. Copy and paste selected statements between tabs.

viii Contents

viii

 You can set a STEP to Continue on Fail. This allows a procedure to continue running even if

that particular STEP fails.

 Click the blank line at the bottom of the procedure to edit the description for the entire procedure.

IF-ELSE-STEP Commands

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

IF Definitions

checkVar() (page xi)

Evaluates the given agent variable. See Using Variables (page

xxxvii).

else (page xii)

Adds an Else branch to run steps when an If branch returns a False

result.

eval() (page xii)

Compares a variable with a supplied value.

getOS() (page xii)

Determines if the current Windows OS is 32 or 64-bit.

getRAM() (page xii)

Evaluates the total amount of memory reported by the latest audit of

the agent.

getRegistryValue() (page xiii)

Evaluates the given registry value.

hasRegistryKey() (page xiii)

Tests for the existence of the given registry key.

isAppRunning() (page xiii)

Checks to see if a specified application is currently running on the

managed machine.

isServiceRunning() (page xiv)

Determines if a service is running on the managed machine.

isUserActive() (page xiv)

Determines whether the user is either:

 Idle or not logged on, or

 Active

isUserLoggedin() (page xiv)

Tests whether a specific user, or any user, is logged in or not.

isYesFromUser() (page xiv)

Presents a Yes/No dialog box to the user.

testFile() (page xiv)

Tests for the existence of a file.

testFileInDirectoryPath() (page xv)

Tests for the existence of a file in the current directory path returned

by getDirectoryPathFromRegistry().

true (page xv)

Always returns True, executing If branch.

STEP Definitions

alarmsSuspend() (page xv)

Suppresses alarms on a machine for a specified number of minutes.

alarmsUnsuspendAll() (page xv)

Stops the suppression of alarms on a machine.

captureDesktopScreenshot() (page xvi)

Captures a desktop screenshot of the agent machine and uploads it

to the Kaseya Server.

changeDomainUserGroup() (page xvi)

Changes a domain user's membership in a domain user group.

changeLocalUserGroup() (page xvi)

Changes a local user's membership in a local user group.

closeApplication() (page xvi)

Closes a running application.

comment() (page xvi)

Adds a one-line comment to the procedure.

copyFile() (page xvi)

Copies a file from one directory to another.

copyFileUseCredentials() (page xvii)

Copies a file from one directory to another using a user credential.

createDomainUser() (page xvii)

Adds a new user to an Active Directory domain when run on a domain

controller.

createEventLogEntry() (page xvii)

Creates an event log entry in either the Application, Security or

System event log types. You can create a Warning, Error or

Informational event with your own description.

createLocalUser() (page xvii)

Adds a new local user account to a machine.

createWindowsFileShare() (page xvii)

Creates a new file share on a Windows machine.

deleteDirectory() (page xviii)

Deletes a directory from the agent machine.

deleteFile() (page xviii)

Deletes a file from the managed machine.

deleteFileInDirectoryPath() (page xviii)

Deletes file in directory returned by getDirectoryPathFromRegistry().

deleteRegistryKey() (page xviii)

Deletes a key from the registry.

delete64BitRegistryKey() (page xviii)

Deletes a 64-bit (page xxxvi) key from the registry.

deleteRegistryValue() (page xviii)

Deletes a value from the registry.

delete64BitRegistryValue() (page xviii)

Deletes a 64-bit (page xxxvi) value from the registry.

deleteUser() (page xix)

Deletes a user from the agent machine.

disableUser() (page xix)

Disables a user, preventing logon to the agent machine.

disableWindowsService() (page xix)

Disables a Windows service.

enableUser() (page xix)

Enables a previously disabled user, allowing the user to logon to the

OS.

executeFile() (page xix)

Executes any file as if it was run from the Run item in the Windows

Start menu.

executeFileInDirectoryPath() (page xx)

Same as execute file. File location is relative to the directory returned

by getDirectoryPathFromRegistry().

executePowershell() (page xx)

Executes a powershell file, or command with arguments or both.

executePowerShell32BitSystem (page xx)

Executes a powershell file, or command with arguments or both, as a

32 bit system command.

executePowerShell32BitUser (page xx)

Executes a powershell file, or command with arguments or both, as a

32 bit user command.

executePowerShell64BitSystem (page xx)

Executes a powershell file, or command with arguments or both, as a

64 bit system command.

executePowerShell64BitUser (page xx)

Executes a powershell file, or command with arguments or both, as a

64 bit user command.

executeProcedure() (page xxi)

Starts another VSA agent procedure on the current machine.

executeShellCommand() (page xxi)

Runs any command from a command shell.

executeShellCommandToVariable() (page

xxii)

Executes a shell command and returns output created during and

after its execution to a variable.

executeVBScript() (page xxii)

Runs a Vbscript, with or without command line arguments.

getDirectoryPathFromRegistry() (page

xxii)

Returns the directory path stored in the registry at the specified

location. Result used in subsequent steps.

getFile() (page xxiii)

Gets a file from the managed machine and saves it to the Kaseya

Server.

getFileInDirectoryPath() (page xxiii)

Gets a file from the managed machine located relative to the directory

returned by getDirectoryPathFromRegistry() and saves it to the Kaseya

Server.

getURL() (page xxiii)

Returns the text and HTML contents of a URL and stores it to a file on

the managed machine.

x Contents

getURLUsePatchFileSource() (page xxiv)

Downloads a file from a given URL to a target folder and file for that

agent. Uses the Patch Management > File Source settings.

getVariable() (page xxiv)

Gets a value from the agent on the managed machine and assigns it

to a variable. See Using Variables (page xxxvii).

getVariableRandomNumber() (page xxv)

Generates a random number.

getVariableUniversalCreate() (page xxv)

Gets a variable that persists outside of the immediate procedure's

execution.

getVariableUniversalRead() (page xxv)

Reads up to three variables you have previously created using the

getVariableUniversalCreate() step.

giveCurrentUserAdminRights() (page xxv)

Adds the current user to the local administrator’s group on the agent

machine, either permanently or for a temporary period of time.

impersonateUser() (page xxvi)

Specifies the user account to use when executing a file or shell when

Execute as the logged on user is specified in a subsequent command.

installAptGetPackage() (page xxvi)

Silently installs a package using the apt-get command in Linux.

installDebPackage() (page xxvi)

Silently installs a Debian package on any Linux OS that supports

.deb packages.

installDMG() (page xxvi)

Silently installs a .DMG package in OS X.

installMSI() (page xxvii)

Installs an MSI file for Windows.

installPKG() (page xxvii)

Silently installs a .PKG package in OS X.

installRPM() (page xxvii)

Silently installs an RPM package on any Linux OS that supports

installing RPMs.

logoffCurrentUser() (page xxvii)

Automatically logs off the current user.

pauseProcedure() (page xxvii)

Pauses the procedure for N seconds.

reboot() (page xxvii)

Reboots the managed machine.

rebootWithWarning() (page xxvii)

Reboots a machine, displaying a warning message to the end-user

before the reboot process occurs.

removeWindowsFileShare() (page xxviii)

Removes a file share from a Windows agent.

renameLockedFile() (page xxviii)

Renames a file that is currently in use.

renameLockedFileInDirectoryPath()

(page xxviii)

Renames a file currently in use in directory returned by

getDirectoryPathFromRegistry().

scheduleProcedure() (page xxviii)

Schedules an agent procedure to run on a specified machine.

sendAlert() (page xxviii)

Creates an alert based on a previous getVariable() command.

sendEmail() (page xxx)

Sends an email to one or more recipients.

sendMessage() (page xxx)

Displays a message in a dialog box on the managed machine.

sendURL() (page xxx)

Opens a browser to the specified URL on the managed machine.

setRegistryValue() (page xxx)

Sets the registry value to a specific value.

set64BitRegistryValue() (page xxx)

Sets the 64-bit (page xxxvi) registry value to a specific value.

sqlRead() (page xxxi)

Returns a value from the database and stores it to a named variable

by running a selected SQL "read" statement.

sqlWrite() (page xxxii)

Updates the database by running a selected SQL "write" statement.

startWindowsService() (page xxxii)

Runs a Start command for a Windows service, if it exists.

stopWindowsService() (page xxxii)

Runs a Start command for a Windows service if it exists.

transferFile() (page xxxiii)

Transfers a file from the agent machine running this step to another

agent machine.

uninstallbyProductGUID() (page xxxiii)

Silently uninstalls a product based on its MSI GUID.

unzipFile() (page xxxiii)

Extracts the contents of a specified zip file to a target folder.

updateSystemInfo() (page xxxiii)

Updates the selected System Info field with the specified value.

useCredential() (page xxxiii)

Specifies that the agent credential should be used when Execute as the

logged on user is specified in a subsequent command.

windowsServiceRecoverySettings()

(page xxxiv)

Sets the Service Recovery Settings for any given service in Windows.

writeDirectory() (page xxxiv)

Writes a directory from the server to the managed machine.

writeFile() (page xxxiv)

Writes a file stored on the Kaseya Server to the managed machine.

writeFileFromAgent() (page xxxv)

Transfers a file from another agent machine to the agent machine

running this step.

writeFileInDirectoryPath() (page xxxv)

Writes a file stored on the Kaseya Server to the managed machine

using the directory returned by getDirectoryPathFromRegistry().

writeProcedureLogEntry() (page xxxv)

Writes a string to the Agent Procedure Log.

writeTextToFile() (page xxxv)

Writes text to a file on the agent machine.

zipDirectory() (page xxxvi)

Compresses a directory and any subdirectories or files it contains into

a zip file on the agent machine.

zipFiles() (page xxxvi)

Compresses a single file or files into a zip file on the agent machine.

IF Commands

checkVar()

Enter a variable name, in the form #var_name#, in the space provided. checkVar() 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 (page xxxvii). The available tests are:

 Exists : true if the variable exists.

Note: If this test is run on a managed variable (page xl), this step will fail for all machine groups that

don’t have a value specified for the managed variable. An error message will display in the agent

procedure log, stating Script Variable Not Found.

 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 variable value begins with the test value.

 Ends With : true if the variable value ends with the test 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. Values in variables are stored as strings, so

compared numbers must be of equal string length. If a date format is specified, it may be offset using +

xii Contents

xii

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.

Example - Sample Procedures.Managed Services.Network Tests.Ping IP Address 2

If checkVar("#pingtest#") Does Not Contain "Lost = 0"

else

Adds an Else command underneath a corresponding If command. Any steps listed under the Else

command are executed when the corresponding If command returns a False result.

Example - Sample Procedures.Managed Services.Disk Mgmt.Clean.Windows Disk Cleanup (wdc)

hasRegistryKey("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Expl

orer\VolumeCaches\Compress old files") Does Not Exist

executeProcedure(WDC Step 1", " ", "Immediate", "All Operating Systems", "Halt on

Fail")

Else

executeProcedure(WDC Step 2", " ", "Immediate", "All Operating Systems", "Halt on

Fail")

eval()

Enter a numerical expression containing one or more variable names, in the form #var_name#, in the

space provided. eval() 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.

Example

If eval("#currentvalue# + 1") Is Greater Than "#maximumValue#"

getOS()

Determines if the current Windows OS is 32 or 64-bit.

Operating systems supported: Windows

Example

If getOS() 64-Bit Windows

getRAM()

Evaluates the total amount of memory in megabytes reported by the latest audit of the agent. This

could come in helpful in ensuring a system meets the resource requirements of an application before

an installation is attempted.

Operating systems supported: Windows, OS X, Linux

Example

xiii

If getRAM() Is Less Than "8500"

hasRegistryKey() / has64BitRegistryKey()

Warning: Certain registry locations require 64-Bit Commands (page xxxvi) for 64-bit Windows machines.

Tests for the existence of a registry key. hasRegistryKey() differs from getRegistryValue() (page xiii)

since it can check for a directory level registry entry that only contains more registry keys (no values).

Example - Core.1 Windows Procedures.Desktops.Maintenance.Common Maintenance Tasks.Disk

Cleanup.Windows Disk Cleanup

hasRegistryKey("HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\Current

Version\explorer\VolumeCaches\Compress Old Files\") Exists

getRegistryValue() / get64BitRegistryValue

Warning: Certain registry locations require 64-Bit Commands (page xxxvi) for 64-bit Windows machines.

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.ex

e\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.

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).

Using the Backslash Character (\)

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 last single backslash in a string is used to delimit the registry key from the registry value. To

include backslashes as part of the value string, specify double slashes for each slash character. For

example, the string HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey\Value\\Name is interpreted as the

key HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey with a value of Value\Name.

Example

if isUserLoggedIn(" ")

getVariable("Registry Value",

"HKEY_CURRENT_USER\KaseyaAgent-HKCUTest\TestREG_DWORD", "regDWORD", "All Operating

Systems, "Halt on Fail"

isAppRunning()

Checks to see if a specified application is currently running on the managed machine. If the application

xiv Contents

xiv

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.

Example

If isAppRunning("Skype.exe")

isServiceRunning()

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.

Example

If isServiceRunning("RemoteRegistry")

isUserActive()

Determines whether the user is either:

 Idle or not logged on, or

 Active

Operating systems supported: Windows, OS X, Linux

Example

If isUserActive() User is idle or not logged in

isUserLoggedin()

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 a user is not logged on.

Example

If isUserLoggedIn(" ")

isYesFromUser()

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 isYesFromUser() fields to dynamically

generate messages based on procedure data.

Delimit the text displayed by the button labels and message using three or more plus characters (+++).

Example - Sample Procedures.Agent Control.Reboot-Ask-Yes-2

If isYesFromUser("+++YES:Reboot Now+++NO:Continue Working+++The system

administrator needs to Reboot your computer. Reboot now?", 5)

testFile()

Determines if a file exists on a managed machine. Enter the full path and file name. testFile() 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. (Case Sensitive)

 Not Contains : true if the test value is not a sub string of the file content. (Case Sensitive)

 Begins With : true if the test value begins with the variable value.

 Ends With : true if the test value ends with the variable value.

Example - Core.1 Windows Procedures.Desktops.Machine Control.Networking.Block Websites.Clear

All Blocked Websites

If testFile("%windir%\System32\drivers\etc\hosts") Exists

testFileInDirectoryPath()

Tests the specified file located at the path returned using the getDirectoryPathFromRegistry() (page

xxii) 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.

Example - Core.3 Linux Procedures.Software Control.Applications.Install CHKCONFIG

If testFileInDirectoryPath("/var/tmp/installed-software.read") Contains

"chkconfig"

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 testFile() (page xiv).

Note: Using IF TRUE is not required. It is included for backwards compatibility with 5.x scripts and

earlier that have been migrated forward.

Example - Sample Procedures.Agent Control.Reboot

If true

reboot("All Operating Systems", "Halt on Fail")

STEP Commands

alarmsSuspend()

Suppresses alarms on a machine for a specified number of minutes. Updates the status of machines

on the Monitor > Status > Suspend Alarm page.

Example - Core.1 Windows Procedures.Servers.Print Server.Print Server

alarmsSuspend(1, "All Windows Operating Systems", "Halt on Fail")

alarmsUnsuspendAll()

Stops the suppression of alarms on a machine. Updates the status of machines on the Monitor >

Status > Suspend Alarm page.

Example - Core.1 Windows Procedures.Servers.Print Server.Print Server

xvi Contents

xvi

alarmsUnsuspendAll("All Windows Operating Systems", "Halt on Fail")

captureDesktopScreenshot()

Captures a desktop screenshot of the agent machine and uploads it to the Kaseya Server. The

screenshot is saved as a PNG file with a unique name in a folder dedicated to that agent. You can

access these files from the Audit > Documents page or from Live Connect. End-user notification

options must be selected based on the level of user notification desired, silently capturing a

screenshot, notifying the user that the capture will take place, or asking to approve the capture. A

custom message can be entered if end-user notification or permission requesting is selected.

Otherwise a standard message displays.

Operating systems supported: Windows, OS X

Example

captureDesktopScreenshot("Silent Capture", " ", "All Operating Systems", "Halt on

Fail")

changeDomainUserGroup()

Changes a domain user's membership in a domain user group. This STEP must be run on a domain

controller. Enter the domain username of the member being added or removed from the domain user

group. Then select whether to add or remove membership. Then select the domain user group.

Operating systems supported: Windows

Example

changeDomainUserGroup(#username", "Add Permission", "Domain Users", "All Operating

Systems", "Halt on Fail")

changeLocalUserGroup()

Changes a local user's membership in a local user group. Enter the local username of the member

being added or removed from the local user group. Then select whether to add or remove membership.

Then select the group.

Operating systems supported: Windows

Example

changeLocalUserGroup("#username#", "Add Permission", "Users", "All Operating

Systems", "Halt on Fail")

closeApplication()

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.

Example

closeApplication("Skype.exe", "All Operating Systems", "Halt on Fail")

comment()

Adds a one line comment to the procedure.

Example

// The IRPStackSize setting for this machine is #IRPStackSize#

copyFile()

Copies a file from one directory to another on the agent machine. If the target file exists, you must

check a box to overwrite an existing file. Be sure to keep in mind folder syntax when running this STEP

across different operating systems, for example, c:\temp\tempfile.txt for Windows and

/tmp/tempfile.txt for OS X and Linux.

Operating systems supported: Windows, OS X, Linux

xvii

Example

copyFile("%appdata%\Microsoft\Templates\#template#",

"e:\templates_archive\#template#", true, "All Operating Systems", "Halt on Fails")

copyFileUseCredentials()

Copies a file from a directory on a machine and attempts to copy the file to a target directory and

filename. The copy process uses either:

 The agent credential specified for an agent using Agent > Manage Agents, or

 The user credential specified by an impersonateUser() (page xxvi) step before this step.

This STEP is mostly used for accessing files across network UNC shares. If the target file exists, you

must check a box to overwrite an existing file. Be sure to keep in mind folder syntax when running this

STEP across different operating systems, for example, c:\temp\tempfile.txt for Windows and

/tmp/tempfile.txt for OS X and Linux.

Operating systems supported: Windows, OS X, Linux

Example

useCredential("All Operating Systems", "Halt on Fail")

copyFileUseCredentials("c:\logging\logfile.log",

"\\fileserver\log_archive\logfile.log", true, "All Operating Systems", "Halt on

Fail")

createDomainUser()

Adds a new user to an Active Directory domain when run on a domain controller. Enter a domain user

name to create, then a password that meets the domain's complexity requirements for user accounts,

then select the domain group the user will be added to, either Domain Users or Domain Admins.

Operating systems supported: Windows

Example

createDomainUser("#username#", "******", "Domain Users", "All Operating Systems",

"Halt on Fail")

createEventLogEntry()

Creates an event log entry in either the Application, Security or System event log types. You can create

a Warning, Error or Informational event with your own description. The created event is hard-coded to

use an Event ID of 607.

Operating systems supported: Windows

Example

createEventLogEntry("This is a test event log entry", "Error", "Application", "All

Operating Systems", "Halt on Fail")

createLocalUser()

Adds a new local user account to a machine. Enter a local user name to create, then a password that

meets local user account complexity requirements, then select the group the user will be added to.

Operating systems supported: Windows, OS X, Linux

Example

createLocalUser("#username#", "******", "Administrator", "All Operating Systems",

"Halt on Fail")

createWindowsFileShare()

Creates a new file share on the Windows machine being managed by the agent. You must type in the

name of the file share as it will be accessed over the network—without the \\computername\

prefix—and enter the source folder on the agent machine for the file share. This folder will be created if

it does not yet exist. You can remove a file share using the removeWindowsFileShare() (page xxviii)

command.

xviii Contents

xviii

Operating systems supported: Windows

Example

createWindowFileShare("#sharename#", "c:\sharedlocalfolder", "All Operating

Systems", "Halt on Fail")

deleteDirectory()

Deletes a directory from an agent machine. Ensure you have your directory syntax correct for Windows

vs. OS X/ Linux. To ensure all sub-directories and files are also removed, check the Recursively delete

subdirectories and files checkbox.

Operating systems supported: Windows, OS X, Linux

Example

deleteDirectory("#localfolder#", "Recursively delete", "All Operating Systems",

"Halt on Fail")

deleteFile()

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

 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.

 You can delete a file that is currently in use using the renameLockedFile() (page xxviii) command.

Example

deleteFile("#pathfilename#", "All Operating Systems", "Halt on Fail")

deleteFileInDirectoryPath()

Deletes the specified file located at the path returned using the getDirectoryPathFromRegistry()

(page xxii) command.

Example

If isUserLoggedIn(" ")

getDirectoryPathFromRegistry(HKEY_CURRENT_USER\KaseyaAgent-HKCUTest\TestDirect

oryPath", "All Operating System, "Halt on Fail")

deleteFileInDirectoryPath(test.txt", "All Operating Systems", "Halt on Fail")

deleteRegistryKey() / delete64BitRegistryKey()

Warning: Certain registry locations require 64-Bit Commands (page xxxvi) for 64-bit Windows machines.

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

Example - Core.1 Windows Procedures.Desktops.Maintenance.Common Maintenance Tasks.Disk

Cleanup.Windows Disk Cleanup

deleteRegistryKey("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\E

xplorer\VolumeCaches\Compress old files", "All Operating Systems", "Halt on Fail")

deleteRegistryValue() / delete64BitRegistryValue

Warning: Certain registry locations require 64-Bit Commands (page xxxvi) for 64-bit Windows machines.

Deletes the value stored at the specified registry key. The last single backslash in a string is used to

delimit the registry key from the registry value. To include backslashes as part of the value string,

specify double slashes for each slash character. For example, the string

HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey\Value\\Name is interpreted as the key

HKEY_LOCAL_MACHINE\SOFTWARE\SomeKey with a value of Value\Name.

Example - Core.4 Other Tools and Utility Procedures.AutoAdminLogon.Disable AutoAdminLogon

deleteRegistryValue("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows

NT\CurrentVersion\Winlogon\DefaultPassword", "Windows 8.1", "Continue on Fail")

xix

deleteUser()

Deletes a user from the agent machine.

Operating systems supported: Windows, OS X, Linux

Example

deleteUser("#admin_name#", "All Operating Systems", "Halt on Fail")

disableUser()

Disables a user, preventing logon to the agent machine.

Operating systems supported: Windows, OS X, Linux

Example

disableUser("#username#", "All Operating Systems", "Halt on Fail")

disableWindowsService()

Disables a Windows service. See startWindowsService() (page xxxii), stopWindowsService() (page

xxxii), and windowsServiceRecoverySettings() (page xxxiv).

Operating systems supported: Windows

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.

Example

disableWindowsService("#service_name#", "All Operating Systems", "Halt on Fail")

enableUser()

Enables a previously disabled user, allowing the user to logon to the OS.

Operating systems supported: Windows, OS X

Example

enableUser("#username#", "All Operating Systems", "Halt on Fail")

executeFile()

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

impersonateUser() (page xxvi) or useCredential() (page xxxiii) command before this command. If run

Execute as the system account is selected, execution is restricted to the agent's system level access.

xx Contents

Note: To avoid risk of privilege escalation attacks, scripts and files which run under System context, or as

an Administrator level user, should be executed from a folder with locked down ACL permissions. The

VSA agent provides a default folder called "System", under the Agent Working Directory

(http://help.kaseya.com/webhelp/EN/VSA/9050000/#250.htm), which is intended for this use. It can be stored as

a variable by selecting "Secure Agent Working Directory Path" from the getVariable() (page xxiv)

command.

Example - Sample Procedures.Managed Services.System Mgmt.Shutdown

executeFile("%windir%\system32\shutdown.exe", "-s -f", "Execute as System and

Continue", "Windows 8.1", "Halt on Fail")

executeFileInDirectoryPath()

Same as executeFile() (page xix) except the location of the .exe file is located at the path returned from

a getDirectoryPathFromRegistry() (page xxii) command.