This document is the first in a set of tutorials to introduce writing calculations in Service Desk. For a beginner the learning curve of calculations can appear very steep so these documents will attempt to demystify this very powerful area of the product. The documents have been split into specific topics and so do not need to be read in order to learn a specific area.
This first document is a general introduction to the concept of calculations in Service Desk and the technologies used.
Some experience in object and process design in Service Desk is recommended to understand how calculations build on these existing concepts. For more information on object and process design please see the Designers manual.
What is a calculation?
The concept of a calculation in Service Desk is a formula (aka code/script) written to programmatically set a value for something. Calculations always return a single value and that value is then used in one of the following ways:
1. To set the value of an attribute on an object. A calculation can be added to an attribute as part of the object design. The value of that attribute is then dictated by the returning value of the calculation. When a calculation is added to an attribute in this way the attribute will only ever be set by the calculation and will appear Read Only when displayed on windows.
2. To set the value of an attribute as part of an automatic process action. A calculation can be used to set the value of an attribute in an automatic action the same way a runtime value can be used. This allows you to set the value to an attribute that can otherwise be updated manually.
3. To make up half of a process condition. A process condition compares two values to dictate the flow of a process. The returning value of a calculation can be used as the first half of a process condition.
A calculation could be one line of code to simply add two numbers together or combine some text from different fields, or even hundreds of lines of code with complex logic for example to determine if an Incident is ready to be automatically closed or not.
In all cases a calculation knows which object the attribute or condition belongs to. It can access the attributes on this object as well as any collections and relationships to other objects. For example if you add a calculation to an attribute on the Note object under Incident Management the calculation can access all the other attributes on the Note object, plus attributes on the Incident the Note belongs to and all the collections and relationships from the Incident. There is no limit on how far down the object chain you go so from the Note you can access multiple levels of relationships such as the Note's Incident's Raise User's Current Group's Parent Group's Title.
How do you write calculations?
In all three areas listed above you write the calculations in the built-in calculation editor interface in the Service Desk Console. The Designer manual gives a detailed explanation of how to access and use the calculation editor in the section Using the calculation editor. You can find the specific topic directly in Console by going to Contents... under the Help menu and searching for calculation editor.
The language used for writing calculations is called Boo.
What is Boo?
Boo is the programming language used in calculations. Boo is a simple language designed to give you access to a very powerful set of programming tools but without a lot of the hard or tedious work normally involved in writing compliant code. A calculation in Service Desk is a Boo function that returns a value.
You can read more about Boo itself at its official website Home · bamboo/boo Wiki · GitHub. It includes some tutorials on writing Boo code however a lot of this is irrelevant for the way it is implemented in Service Desk. Instead this set of tutorials will show the concepts and syntax of the Boo language as it is relevant to Service Desk.
Boo itself is the language but it is there to act as a gateway to access the .NET Framework. In a nutshell the .NET Framework is a huge library of programming capabilities to achieve almost anything. It is created by Microsoft and is the basis of all their major programming languages, most notably Visual Basic and C#. The use of .NET will be covered more in later tutorials.
Your first calculation (Hello World!)
This exercise will show you how to create a calculation for the first time (informally known in most programming tutorials as the "Hello World!"). We will create a new String attribute on the Incident object that says "Hello" to the Raise User of an Incident.
1. Within Console launch Object Designer and open the Incident Management -> Incident object.
2. From the Actions panel select New Attribute.
3. Give the attribute a Title - "Hello Raise User".
4. The Data Type will already be String but we need to set the Max. Length. Find that property in the Properties panel on the right and set it to 200.
Now we need to add the calculation itself to the attribute. To do this we first set the Calculation Type. There are three types of calculations on attributes (not to be confused with the three types of calculations in general as listed earlier in this document!) - Before Save, After Read, and Scheduled. The Designers manual explains the difference between these in section Creating a calculated attribute, you can access the specific topic directly in Console by going to Contents... under the Help menu and searching for beforesave.
5. Find the Calculation Type property in the Properties panel and change this from None to Before Save. This will automatically load the calculation editor.
When the calculation editor loads the main editor panel will show the following template to write your calculation over:
import System static def GetAttributeValue(Incident): Value = return Value
It is worth at this point quickly explaining what each of these lines mean:
This is referring to the System namespace within .NET. You should never change this line but in more advanced calculations you might want to add extra "import" lines to the top of a calculation. For now though just remember that you shouldn't ever touch this line or the calculation won't work.
static def GetAttributeValue(Incident):
This line is the start of the Boo function definition. Again you should never change this or the calculation won't work. Notice that it says Incident within the brackets - that will always be the object the calculation is being written against so if you see example calculations with a different object listed here it just means the calculation was written against a different object to yours.
Value = return Value
This is the calculation formula/code/script itself that you can edit all you like.
6. Modify the 3rd line to look like this:
Value = 'Hello ' +
Make sure you put Hello in quotes, you can use either single or double quotes. The quotes tell you that the text within them is to be displayed as is and it isn't referring to an attribute or something else called Hello. Add a space to the end of the line to help keep it readable for the next step. Keep the cursor flashing at the end of the line.
6. Using the Attributes panel on the left find Raise User and click the expand button. Then double click on Title in the expanded branch.
A couple of things will happen now. Firstly the calculation will have updated to show the following:
import System static def GetAttributeValue(Incident): Value = 'Hello ' + Incident.RaiseUser.Title return Value
Double-clicking the attribute added Incident.RaiseUser.Title to the calculation at the current cursor position. Having the + sign and then the reference to this attribute will concatonate (combine) the text 'Hello ' with the Title of the Raise User, for example 'Hello Stu'.
Also RaiseUser was added to the Dependencies panel on the right hand side of the editor. This is very important because this panel lists which attributes the calculation depend on, or more specifically which attributes will trigger the calculation to run. In simple calculations like this the editor can figure out the dependencies automatically but don't rely on this in more advanced ones. You can uncheck the Auto-detect dependencies checkbox and manually type or drag attributes into the list. For now though as long as RaiseUser is listed you don't need to do anything else.
7. Press the Test Syntax button. This will confirm if the calculation syntax is valid. Note that this will not mean the calculation will always work but does at least mean it will attempt to run.
8. Press OK to close the editor.
9. Press the Save button in Object Designer to save the new attribute and its calculation.
The calculation is now in place and will run whenever the Raise User on an Incident is set or updated. We will now add it to the Incident window so we can see it in action.
10. Within Window Manager open the Incident window.
11. Add the Hello Raise User attribute to the window.
12. Save the window.
Now launch a new incident, select a Raise User and press Save - the calculation attribute will populate. Notice that the calculation attribute appears Read Only - the only way the value will ever get set or updated is by the calculation. The finishing touch is to make the calculation run as soon as you select the Raise User so you don't have to wait until you press Save.
13. Go back into the window design and select the Raise User dropdown.
14. From the Properties panel set Is calculate on change? to True.
15. Save the window.
Now launch a new incident and select a Raise User - the calculation attribute will populate. Note that as of Service Desk version 7.5 the Is calculate on change? property is only supported in Console at present and not Web Access, although this is due to change in a future release.
The next tutorial will explain the concepts of variables and conditional logic. Read it here: Calculation Writing Tutorial - 2. Variables and Conditional Logic ("if" statements).