IF-ELSE-STEP Service Desk Commands

The following is a summary of IF-ELSE and STEP statements used in Service Desk procedures.

IF-ELSE Statements

STEP Statements

Where Used

These IF-ELSE and STEP statements are used by the following types of Service Desk procedures.

IF-ELSE in Detail

checkVariable()

Enter the name of the variable in the format #var_name#. It can be a global variable or a procedure variable that was defined earlier in the current procedure or a parent procedure. If a global variable, then the global variable's Set value must be compatible with the procedure being run. See Procedure Variables and Working with Variables for more information about variables.

Enter a string comparison operator. The same string comparison options are available for all IF commands. See String Comparisons and Date/Time Comparisons.

Then enter a second value to compare against the first value. Instead of a value you can also enter a property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables.

If the test is true, IF steps are executed. If the test is false, ELSE steps are executed.

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.

isDuplicateRequest()

This IF command is only available in a Ticket Request De-Dup procedure.

Tests a ticket request to see if it is a duplicate of any existing ticket. Prevents multiple tickets from being created for the ticket request, within a specified time limit.

Ticket requests are created from either inbound emails or system events, such as alert conditions. Incoming Email and Alarm Settings and linked service desk procedures determine how ticket requests are processed into tickets, what service desks are used to create the tickets, and whether ticket requests are canceled.

The following dialog displays in the right hand pane of the ticket editor when this command is selected in the procedure editor. The test tests true if all fields that have an entered value match their corresponding values in a ticket request record. See Source Properties for more information.

• Match the submitter name
• Match the submitter email address
• Match the request subject
• Match the source type - The Source Type column. Example values include:
  • Counter
  • Service
  • Process
  • SNMP
  • Alert
  • System Check
  • KES
  • Log Parser
• Match the first reference field - The Source Value 1 column.
• Match the second reference field - The Source Value 2 column. Example values include:
  • web server check
  • dns check
  • port check
  • ping
  • custom
• Match the machine
• Match the machine group
• Enter Recurrence Time (Integer) / The Unit of Time - Limits matching to the most recent <N> number of periods, based on the ticket creation date.
• Include Closed Tickets - If checked, open and closed tickets are searched for duplicates. If unchecked, only open tickets are searched for duplicates.

isTicketClosed()

Tests whether the ticket being mapped is closed. Typically used prior to a reOpenTicket() step. Applies only to a Ticket Request Mapping procedure.

inReopenTicket()

Tests whether the ticket was previously reopened.

isWithinCoverage()

This IF command is not available for Ticket Request De-Dup and Ticket Request Mapping procedures.

Tests whether a ticket or KB article is currently within the coverage schedule.

testIncidentCustomField()

Enter the name of the custom field in the format custom_field, without bracket characters of any kind.

Enter a string comparison operator. The same string comparison options are available for all IF commands. See String Comparisons and Date/Time Comparisons.

Then enter a second value to compare against the first value. Instead of a value you can also enter a property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

If the test is true, IF steps are executed. If the test is false, ELSE steps are executed.

testIncidentProperty()

Select a ticket property from the drop-down list.

Enter a string comparison operator. The same string comparison options are available for all IF commands. See String Comparisons and Date/Time Comparisons.

Then enter a second value to compare against the first value. Instead of a value you can also enter a property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Property and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

For testing the value of a Category property, use two bar characters || to delimit levels of categories. For example: Hardware||CPU||Overheating

If the check is true, IF steps are executed. If the check is false, ELSE steps are executed.

testTicketProperty()

This IF command is only available in a Ticket Request Mapping and Ticket Request De-Dup procedures.

Select a ticket property from the drop-down list, in the format objectname, without bracket characters of any kind.

Enter a string comparison operator. The same string comparison options are available for all IF commands. See String Comparisons and Date/Time Comparisons.

Then enter a second value to compare against the first value. Instead of a value you can also enter a property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

For testing the value of a Category property, use two bar characters || to delimit levels of categories. For example: Hardware||CPU||Overheating

You can also test a source property.

If the test is true, IF steps are executed. If the test is false, ELSE steps are executed.

STEP in Detail

addNote()

Adds a note to the ticket being processed by the procedure. Additional parameters include:

• Selecting a note template instead of entering a note.
• Making the note hidden or not.

Note text can include an property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

addNoteWithTime()

Adds a note and time to the ticket being processed by the procedure. Additional parameters include:

• Selecting a note template instead of entering a note.
• Making the note hidden or not.
• The time in minutes added with the note.
• Marking time added as billable or not.
• Selecting a Default User to associate the time entry with.
• Overriding the Default User with the user manually editing the ticket.

  Note: Overriding the Default User is unavailable for Goal, Escalation, Ticket Request De-Dup, or Ticket Request Mapping, since no user is manually editing the ticket just before these procedures are run.

Note text can include an property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

assignCustomField()

Assigns a value to a custom field in a ticket. Enter the name of the custom field in the format custom_field, without bracket characters of any kind. Then enter a value that matches the range of possible values allowed for this custom field. The range of possible values is specified using the Service Desk > Desk Definition > Properties > Custom Fields tab.

You can also enter a property variable in the format [$objectname$] or a global variable or procedure variable in the format [=var_name=]. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

assignCustomObjectField()

Assigns a value to the custom field of a new ticket created in a previous service procedure step using the createTicket() command.

• The name of the global variable used to reference the New Ticket - Enter the name of the global variable without [= and =] brackets. If multiple createTicket() steps are included in the same procedure, each should specify a different global variable so that each new ticket can be uniquely identified in subsequent steps.
• The name of the property to assign - The name of the custom field to assign.
• The value for the property - The value to assign the custom field. The range of possible values is specified using the Service Desk > Desk Definition > Properties > Custom Fields tab.

assignObjectProperty()

Assigns a value to the property of a new ticket created in a previous service procedure step using the createTicket() command.

• The name of the global variable used to reference the New Ticket - Enter the name of the global variable without [= and =] brackets. If multiple createTicket() steps are included in the same procedure, each should specify a different global variable so that each new ticket can be uniquely identified in subsequent steps.
• The name of the property to assign - The name of the ticket property to assign.
• The value for the property - The value to assign the ticket property.

The set of properties that can be assigned are displayed in a drop-down list. See Working with Variables for more information about variables.

For assigning the value of a Category property, use two bar characters || to delimit levels of categories. For example: Hardware||CPU||Overheating

Note: Use Assign Ticket Property to assign a value to the property of the current ticket.

assignTicketProperty()

Assigns a value to the property of the current ticket. The set of properties that can be assigned are displayed in a drop-down list. The supplied value may be a global variable name or procedure variable name in the format [=var_name=]. See Procedure Variables and Working with Variables for more information about variables.

For assigning the value of a Category property, use two bar characters || to delimit levels of categories. For example: Hardware||CPU||Overheating

Note: Use assignObjectProperty() to assign a value to the property of a new ticket created using the createTicket() command.

cancelTicketCreation()

Cancels the creation of the ticket. There are no parameters to set. Applies to Ticket Request Mapping procedures only.

comment()

Adds a one line comment to the procedure.

createTicket()

Creates a new ticket in a specified service desk.

• The name of the service - The name of the service desk.
• Summary for the new ticket - The summary of the ticket.
• (Description) - The description of the ticket.
• The global variable where the reference to the new ticket - The name of a global variable used to reference this newly created ticket in subsequent assignObjectProperty() steps. If multiple createTicket() steps are included in the same procedure, each should specify a different global variable so that each new ticket can be uniquely identified in subsequent steps. Enter the name of the global variable without [= and =] brackets.

Events occur in the following order:

1. assignObjectProperty() steps in subsequent steps assign values to the properties of the newly create ticket.
2. After the new tickets are created, if there are properties of the ticket that have not been set using assignObjectProperty() steps, but have defaults in the service desk, those default values are applied to the ticket.
3. If there is a stage entry procedure for the service desk associated with the new ticket's beginning stage, that is run last.

deleteTicket()

Deletes the ticket being processed by the procedure.

executeSubProcedure()

Causes a sub-procedure to execute. Use this capability to string multiple IF-ELSE clauses together. You can nest the execution of procedures to 10 levels.

executeExternalScript()

Note: A No Approved External Scripts message displays in the Choose the external script to execute drop-down list if no external scripts have been manually added to the Kaseya Server, as described below.

Executes a script written in VB.Net (.vb) or CSharp (.cs) on the Kaseya Server from the following file locations.

• <KaseyaInstallDirectory>\xml\SDProcExecuteScript\0 - Files stored in the 0 directory are available in every partition. (Default)
• <KaseyaInstallDirectory>\xml\SDProcExecuteScript\1 - The 1 directory in this example matches partition ID 1. Files stored in a partition-specific directory are available only in that partition.

executeExternalScript() XML files can have any filename. You can have multiple scripts in one file. You can also have multiple files. The scripts referenced by an XML file should be stored in the same location as the XML file under a \Script folder.

Example of VB.Net Script

This script writes to a file if the file exists.

Dim FILE_NAME As String = "c:\temp\test.txt"

If System.IO.File.Exists(FILE_NAME) = True Then

     Dim objWriter As New System.IO.StreamWriter( FILE_NAME )

     objWriter.Write( "Hello" )

     objWriter.Close()

End If

Place the script file in this location:

<KaseyaInstallDirectory>\xml\SDProcExecuteScript\0\script\CreateFile.vb

Note: This example requires the creation of c:\temp\test.txt prior to execution. Also, the group IIS_IUSRS must have permissions to C:\temp.

Example of XML File

The XML should be structured like the following example, which includes 2 external scripts.

<?xml version="1.0" encoding="utf-8" ?>

<externalScriptList>

	<externalScriptDef label="First Script" fileName="createFile.vb">

	</externalScriptDef>

	<externalScriptDef label="Second Script" fileName="createFile2.vb">

	</externalScriptDef>

</externalScriptList>

Place the script file in this location:

<KaseyaInstallDirectory>\xml\SDProcExecuteScript\0\VB.xml

Example of C#.Net Script

This script writes to a file if the file exists.

string FILE_NAME = "c:\\temp\\test.txt";

if (System.IO.File.Exists(FILE_NAME) == true) {

 System.IO.StreamWriter objWriter = new System.IO.StreamWriter(FILE_NAME);

 objWriter.Write("Hello");

 objWriter.Close();

}

Place the script file in this location:

<KaseyaInstallDirectory>\xml\SDProcExecuteScript\0\script\CreateFile.cs

Note:: This example requires the creation of c:\temp\test.txt prior to execution. Also, the group IIS_IUSRS must have permissions to C:\temp.

Example of XML File

The XML should be structured like the following example, which includes 1 external script.

<?xml version="1.0" encoding="utf-8" ?>

<externalScriptList>

    <externalScriptDef label="Write to a file" fileName="CreateFile.cs">

    </externalScriptDef>

</externalScriptList>

Place the script file in this location:

<KaseyaInstallDirectory>\xml\SDProcExecuteScript\0\CS.xml

Definitions

• label - The name that displays in the drop-down list of available scripts to execute. Should be informative of what the script does. Required.
• filename - The filename of the script. The script must be located in the same folder as the XML statement under a \Script folder. Required.
• name - The name of an additionalAssembly. Each additionalAssembly should have its own node in the XML statement. Optional.

exitProcedure()

Exits the current procedure. There are no parameters to set.

executeShellCommand()

Note: A No Approved Shell Command message displays in the Choose the command to execute in a command shell drop-down list if no SQL commands have been manually added to the Kaseya Server, as described below.

Executes a shell command on the Kaseya Server from the following file locations.

• <KaseyaInstallDirectory>\xml\SDProcShellCommand\0 - Files stored in the 0 directory are available in every partition.
• <KaseyaInstallDirectory>\xml\SDProcShellCommand\1 - The 1 directory in this example matches partition ID 1. Files stored in a partition-specific directory are available only in that partition.

Shell commands stored in these locations are formatted as XML files and can have any filename. You can have multiple commands in one XML file. You can also have multiple XML files.

Example

The XML should be structured like the following example, which includes 2 shell commands.

<?xml version="1.0" encoding="utf-8" ?>

<shellCommandList>

<shellCommandDef label="Shell Command 1" commandToExecute="echo hello" waitForCompletion="true" sendOutputToLog="true" outputFile="c:\temp\fromcmd.log" outputVariable="" />

<shellCommandDef label="Shell Command 2" commandToExecute="echo hello" waitForCompletion="true" sendOutputToLog="true" outputFile="c:\temp\fromcmd2.log" outputVariable="" />

</shellCommandList>

Definitions

• label - The name that displays in the drop-down list of available commands to execute. Should be informative of what the shell command does. Required.
• commandToExecute - The shell command. Required.
• waitforCompletion - True to wait. False to not wait. Required.
• sendOutputToLog - True to send output. False to not send output. Required.

At least one of the following is required. If both are filled in outputFile has precedence.

• outputFile - Full file path and name where the output is saved if sendOutputToLog is true. Optional.
• outputVariable - Name of the variable the output goes to. Optional.

executeSqlNonQuery()

Note: A No Approved SQL message displays in the SQL Command to Execute drop-down list if no SQL commands have been manually added to the Kaseya Server, as described below.

Updates the database—such as updating the value in a column or inserting a row—by running a selected SQL "nonquery" statement. Global "nonquery" statements are specified in the following location: <C:\Kaseya\xml\SDProcSQL\0\SQLNonQuery\<filename.xml>.

Warning: Direct manipulation of the Kaseya Server database can result in a massive loss of data.

Filenames can be any name with an .xml extension so long as they are formatted correctly internally. Multiple statements specified using one or more XML files display as a single combined combo box list in the user interface. Each SQL statement in the XML file has a unique label, and only the labels are shown in the combo box. If no SQL statements are defined, then *No Approved SQL* displays in the combo box.

Partition-Specific Statements

Partition-specific folders can contain partition-specific SQL statements. For example: <C:\Kaseya\xml\SDProcSQL\123456789\SQLNonQuery\<filename.xml>. Users can select and run all 0 folder SQL "nonquery" statements and all SQL "nonquery" statements located in the partition path that matches the partition they are using.

Example Format

<?xml version="1.0" encoding="utf-8" ?>

<queryList>

    <queryDef label="Update Table" sql="UPDATE table1 SET column2 = value2 WHERE column1 = value1" />

</queryList>

executeSqlQuery()

Note: A No Approved SQL message displays in the SQL Command to Execute drop-down list if no SQL commands have been manually added to the Kaseya Server, as described below.

Returns a value from the database and stores it to a named variable by running a selected SQL "query" statement. Global "query" statements are specified in the following location: <C:\Kaseya\xml\SDProcSQL\0\SQLQuery\<filename.xml>

Filenames can be any name with an .xml extension so long as they are formatted correctly internally. Multiple statements specified using one or more XML files display as a single combined combo box list in the user interface. Each SQL statement in the XML file has a unique label, and only the labels are shown in the combo box. If no SQL statements are defined, then *No Approved SQL* displays in the combo box.

Partition-Specific Statements

Partition-specific folders can contain partition-specific SQL statements. For example: <C:\Kaseya\xml\SDProcSQL\123456789\SQLQuery\<filename.xml>. Users can select and run all 0 folder SQL "query" statements and all SQL "query" statements located in the partition path that matches the partition they are using.

Example Format

<?xml version="1.0" encoding="utf-8" ?>

<queryList>

    <queryDef label="Agent Guid" sql="SELECT machName FROM dbo.machNameTab WHERE agentGuid = 12345678910111213141516171" />

</queryList>

failCurrentTicketTransaction()

If included in a procedure, cancels all changes to the ticket. Cancels both ticket changes made manually before saving the ticket and ticket changes made within the procedure being processed prior to this step being run. Does not cancel sendEmail() or sendMessage() steps processed before this step is run. Cancels all steps in the procedure after this step is run.

getAgentInfo()

Returns a selected property value from the last audit of the agent machine associated with the ticket.

• The vMachine property to retrieve from the agent - See Audit > Audit Summary for a description of each property.
• The variable to hold the value of the agent property - Specify the variable name without brackets. Example: var_name.
• Perform Step On - Specify the type of operating system to perform this step on.

getVariable()

Defines a new procedure variable and assigns it a value. Specify the variable name without brackets. Example: var_name.

You can refer to this variable in text fields in any subsequent steps by adding [= and =] around the variable name. Example: [=var_name=]. See Procedure Variables and Working with Variables for more information about variables.

• Constant Value - Enter a value for the variable.

linkTickets()

Links the ticket being processed to a specified ticket ID or knowledge base article ID.

pauseStageGoal()

Pauses counting elapsed time against the current stage goal. Goal procedures are linked to stages using the Service Desk > Desk Definition > Processing > Stage > Procedures tab.

pauseTicketGoal()

Pauses counting elapsed time against the ticket goal. The ticket goal determines the due date for the entire ticket. Goals are linked to a service desk using the Desk Definition > Properties > General > Procedures tab.

reOpenTicket()

Changes an End-stage (for example, Closed) ticket to a Begin-stage (for example, New) ticket. Applies only to a Ticket Request Mapping procedure.

resumeStageGoal()

Resumes counting elapsed time against the current stage goal. Goal procedures are linked to stages using the Service Desk > Desk Definition > Processing > Stage > Procedures tab.

resumeTicketGoal()

Resumes counting elapsed time against the ticket goal. The ticket goal determines the due date for the entire ticket. Goals are linked to a service desk using the Desk Definition > Properties > General > Procedures tab.

scheduleProcedure()

Runs a selected agent procedure for a specified machine. Use [$FullMachineName$] to specify the machine name and machine group, assuming a machine is associated with the ticket. Otherwise you can enter a procedure variable for the machine name or specify a fixed machine name value.

sendEmail()

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

Optionally check the Send the email if the body contains the [$ChangesAsHtml$] or [$Changes$] and those properties are empty due to hidden notes. This prevents emails with "empty" notes from being sent.

You can include property variables, global variables and procedure variables in the To, From, Subject, and Body fields of a sendEmail() command. You can reference property variables, global variables and procedure variables in the message templates you link to in a sendEmail() command. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

You can also enter the name of a pool of users. Names are delimited using commas or semi-colons. The following order of precedence determines the email addresses of recipients. The name in the To field of a sendEmail() step is checked to see if it:

• Exists as a user name. If that name is found, and an email address exists for that user, then that email address is used.
• Conforms to an SMTP email address. For example, user@domain.com. If the name matches that pattern, that name is used for the email address. If a service desk pool name conforms to an email address, then email will be sent to that email address, not to the pool of users in that pool.
• The name is looked up as a service desk pool. The email is sent to the email addresses associated with each user in the pool.

sendMessage()

Sends a message to the Inbox of a user.

You can only enter one user name in the To field of the sendMessage() dialog box. Use sendMessage() to User Pool to send a message to multiple users.

You can include property variables, global variables and procedure variables in the To, From, Subject, and Body fields of a sendMessage() command. You can reference property variables, global variables and procedure variables in the message templates you link to in a sendMessage() command. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

sendMessageToPool()

Sends a message to the Inbox of all users in a selected pool.

You can include property variables, global variables and procedure variables in the Subject, and Body fields of a sendMessageToPool() command. You can reference property variables, global variables and procedure variables in the message templates you link to in a Send Message to User Pool command. See Ticket Properties and Variables for a list of property variables. See Procedure Variables and Working with Variables for more information about variables.

setEscalationTime()

Sets the time a ticket is escalated. Overrides the default escalation time set for a stage using the Service Desk > Desk Definition > Processing > Stage > Procedures tab. The escalation time can be calculated using the coverage schedule associated with the ticket or using calendar time. For example, if a coverage schedule does not include weekend coverage, and the ticket escalation procedure runs during the weekend, escalation of the ticket will not start counting until coverage begins on Monday morning. If escalation time is calculated using:

• Calendar time, and a coverage schedule is associated with the ticket, calendar time is used.
• A coverage schedule, and no coverage schedule is associated with the ticket, calendar time is used.

setGoalTime()

Sets the time the goal for a stage is scheduled to be completed. Overrides the default goal time set for a stage using the Service Desk > Desk Definition > Processing > Stage > Procedures tab.

setTicketGoalTime()

Sets the time the goal for a ticket is scheduled to be completed. The ticket goal determines the due date for the entire ticket. Overrides the default goal time set for a ticket using the Desk Definition > New or Edit > Procedures tab.

writeProcedureLogEntry()

Writes the supplied string to System > Application Logging.