This document is the second in a set of tutorials on writing calculations in Service Desk. Each topic can be read independently but for an introduction to calculations please see the following document: Calculation Writing Tutorial - 1. What is a calculation? What is Boo?.
Some experience in object and process design is recommended, as well as the basic concept of calculations as covered in the first tutorial (linked above).
In calculations you will often use what are known as variables. A variable is an alias to a value, similar to referring to a number as "x" in algebra. The value can be anything - some text, a number, an incident note record, etc.
Here is an example to demonstrate the use of variables in a calculation, this is the same calculation as used in the first tutorial that says Hello to the Raise User of an Incident:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title return Value
This calculation uses a variable called Value and assigns it a value "'Hello ' + Incident.RaiseUser.Title". The name "Value" is arbitrary and could just as easily be named Bob as long as it is a single word. You should however give your variables a name relevant to what value it holds, such as MyText, AssignmentCount, etc.
The variable value set here is in the syntax of "VariableName = VariableValue". This is the standard way to set the initial value for a variable, however if you then want to modify that value there are a few ways to do this depending on the type of data being stored.
- To replace the variable value with another value - Simply repeat the same "VariableName = VariableValue" syntax with the new value.
- To append the variable value with more data - If you wanted to add the text ", welcome!" to the end of the example above you could use the syntax "VariableName += AppendingValue" and the += dictates that you are appending the value rather than replacing it.
- To increase or decrease a number by 1 - With numbers in variables you might be counting something so it is a common requirement to add or subject 1 to/from the current value. This can be done with the syntax "VariableName++" or "VariableName--". The ++ or -- dictates that you want to add/subtract 1 to/from the current value.
Once a variable is set it can then be referenced, in the example above we use it as the return value for the calculation. This calculation doesn't actually need to use a variable, you could instead just have a calculation that says "return 'Hello ' + Incident.RaiseUser.Title" but it is best practice to set values to variables as when your calculations become more complex they will be needed in most cases.
Conditional Logic ("if" statements)
If you consider the example calculation used above it will always return the same with the only difference being the Raise User.Title value being whichever user is specified on the Incident. But in a lot of cases the reason to use a calculation is to add something dynamic and this is where you use logic to perform certain tasks only in certain circumstances.
This is done in calculations with "if" statements made up of a condition and some code to perform if that condition is true. To add to the existing example we could add some extra text to our Hello message if the Category of the Incident being logged is "Hardware":
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title if Incident.Category.FullName == 'Hardware': Value += '. This is a hardware issue!' return Value
The syntax as shown above for an "if" statement is "if something == something else: do something". A few things to note are:
- The word "if" is in lowercase. Using any capital letters here will cause the calculation to be invalid.
- Between the two values are two equals signs - this is the "operator" and means "is equal to". This should not be confused with the single equals sign used when assigning variables.
- There is colon separating the condition and the code to execute if the condition is true.
This particular example will append the Value variable with some extra text if the Category.FullName (which is the attribute on Category that gets displayed in the dropdown) is Hardware. The text Hardware is in quotes because we are comparing against some text. If it wasn't in quotes the calculation would be looking for a variable of that name which obviously doesn't exist and the calculation would fail.
Operators other than "Is equal to"
Checking that something is the same as something else is the most common operator in an "if" statement but what if you want to check if something isn't the same as something else? Here is a list of the most common operators:
|==||Is equal to|
|!=||is NOT equal to|
|>||is greater than|
|<||is less than|
|>=||is greater than or equal to|
|<=||is less than or equal to|
Note that the last four operators are generally for when comparing numbers only.
Checking multiple conditions at once
To build on the above example if you only wanted to show the extra text if the Category is Hardware and also if the Raise User is "Bob" you can do this quite simply:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title if Incident.Category.FullName == 'Hardware' and Incident.RaiseUser.Title == 'Bob': Value += '. This is a hardware issue!' return Value
As well as the "and" keyword there is the "or" keyword to only require one of the conditions to be true. You can string as many conditions as you need together and also use parenthesis to dictate the order they are processed, for example:
if x == y or (y > z and z != a): ...
In this example either x must equal y, or y must be greater than z and z must not equal a.
"if then else" conditions
The examples above check the condition and then execute some code if it is true. More complex conditional logic allows you to perform different code depending on the condition result in two ways:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title if Incident.Category.FullName == 'Hardware': Value += '. This is a hardware issue!' else: Value += '. This is NOT a hardware issue!' return Value
This example will append the text '. This is a hardware issue!' if the condition is met, but by using the else condition if it isn't met it instead appends the text '. This is NOT a hardware issue!'. As well as a two way condition like this you can add multiple conditions:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title if Incident.Category.FullName == 'Hardware': Value += '. This is a hardware issue!' elif Incident.RaiseUser.Title == 'Bob': Value += '. This is NOT a hardware issue but the Raise User is Bob!' else: Value += '. This is NOT a hardware issue and the Raise user ISN'T Bob!' return Value
The elif condition says "else if" or "otherwise if" which means it is only checked if the condition above it is false. You can add as many elif lines as you need one after the other and you don't need an else condition at the end if it isn't required.
Executing multiple lines of code as the result of an "if" statement
In all the above examples only one line of code is executed if the condition is true (appending the text to the Value variable). If you want to run multiple lines of code this can be done too, for example:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title if Incident.Category.FullName == 'Hardware': Value += '. This is a hardware issue!' Value += ' And here is more text appended.' return Value
This example will now execute two lines of code if the condition is met. They are on separate lines and indented further than the rest of the calculation. Indenting is a very important part of writing calculations so it has its own section in this document...
The next tutorial will explain the important concepts of indenting and checking values are set before using them. Read it here: Calculation Writing Tutorial - 3. The importance of Indenting and checking NULL values.