Using a calculation to create a single field from the Search Matches

You can use the calculation editor to manipulate your Service Desk or Asset Manager data. This section describes how to create a calculation that iterates through the Search Matches collection to create a single field that can be displayed or e-mailed to the appropriate user.

For more information about using calculations, see the Designer Guide.

The Search Matches collection generated by the Automatic Search behavior usually includes different types of object – for example, Incidents and Articles. These objects have different attributes, so it is difficult to write a calculation that returns records from this collection, as you cannot be sure which attributes you are expecting to find. For example, Incident contains a Raise Date attribute but Article doesn't, whereas Article contains an Effectiveness attribute but Incident doesn't. The GetReferencedObject("") function in the calculation editor enables you to iterate through the Search Matches collection, identifying which object each record refers to, and then request appropriate attributes for that record in the next part of the calculation.

The example calculation below iterates through the rows in the Search Matches collection and identifies if the row corresponds to an Article or an Incident. If the row is an Article, it generates the string Article Title=title, where title is the title of the Article; if the row is an Incident, it generates the string Incident Id=Id, where Id is the Reference Number of the Incident.

import System
static def GetAttributeValue(Incident):
	Value = ""
	for item in Incident.SearchMatches:
		Value += item.SerialNumber + "="
		obj = item.GetReferencedObject("MatchingObject")

		if obj.ClassType.FullName == "Knowledge.Article":
			Value += "Article Title=" + obj.Title
		if obj.ClassType.FullName == "IncidentManagement.Incident":
			Value += "Incident Id=" + obj.Id
	Value += " / "
return Value

First, the Value variable is set to blank, then the line starting for instructs the calculation to iterate through each item in the Search Matches collection on the Incident object.

Each time the calculation passes Value +=, the text generated by the rest of that line is concatenated to the end of the current string stored in the Value variable. So the first time the calculation passes the line Value += item.SerialNumber + "=", it reads the SerialNumber of the first item (which will be 1), and adds = to generate the string 1=.

The line obj = item.GetReferencedObject("MatchingObject") uses the GetReferencedObject("") function to set the variable called obj to be equal to the object for the item in the current row of the collection. This is then used by the if statements later in the calculation.

if obj.ClassType.FullName == "Knowledge.Article": tests if the object returned in the previous line is Knowledge.Article; if the object returned is NOT Knowledge.Article, the calculation advances to the line if obj.ClassType.FullName == "IncidentManagement.Incident": to test if the object returned is IncidentManagement.Incident.

If the object returned is Knowledge.Article, the line Value += "Article Title=" + obj.Title runs and adds the text Article.Title=<article title> to the Value variable (where <article title> is the title of the corresponding article. If the object returned is IncidentManagement.Incident, the line Value += "Incident Id=" + obj.Id runs and adds the text Incident Id=<incident id> to the Value variable (where <> is the Reference Number of the corresponding Incident.

The line Value += " / " then adds / to the end of the Value variable, and the calculation loops back through to the next item in the collection, adding the next record, and so on to the end of the collection.

When the calculation completes, it will have generated a string of the form:

1=Article Title=Title of first item in the collection / 2=Incident.Id=12033 / ...

In this example, the first item in the Search Matches collection is an Article with the title Title of first item in the collection, and the second item is Incident 12033.

With the example calculation, if the Search Matches collection contains items other than Articles or Incidents, the if statements will not find a match, and the corresponding line will be blank except for the item serial number at the start of the line. You could fix this by adding another if statement for the new object.