“It is necessity and not pleasure that compels us.”
— Dante Alighieri
Occasionally, we will get an Incident Ticket that references another task present in the system. This is usually a status request on a Service Catalog Request or a problem with a recent Change. It would be nice to be able to just click on those recognizable task numbers, but both the Short Description and the Description are plain text fields where that is not an option. There is, however, a handy out-of-the-box UI Formatter that you can include on your Incident Form that provides the capability to link other tasks to your Incident. The name of the Formatter is Task Relations, and I like to drag it onto the Incident Form in the Forms Designer right underneath the Formatter for Contextual Search Results. Once you have that Formatter present on your Incident Form, you can click on the green plus sign and link other tasks of various types to your Incident.
That’s a really cool feature that allows you click on the related tasks to open them up, but being the lazy developer that I am, I would prefer not to have to go through all of the manual work to set up all of the links to the things mentioned in the text of the ticket. In my ideal world, the system would be smart enough to read the text, recognize a task number, and then build the link for me so that I don’t have to do all of that work by hand, and also to make sure that I did not miss anything. How hard could that be?
My thought was that I could create a Business Rule linked to the Incident table that would examine the two primary text fields (Short Description and Description), look for anything that appeared to be a task number, search the Task table to see if it really was a task number, and if so, build the link for me. It seemed like a relatively simple thing to do, so I went to work.
It felt as if there might be a lot of code involved, so instead of putting all of that in the Business Rule itself, I decided to build a Script Include that I could call from the Business Rule. I thought that if I could make the function generic enough, I might be able to reuse it for other Business Rules linked to different Task tables. Plus, putting all of the code in the Script Include keeps the Business Rule a lot cleaner. Here are the things that I thought that I needed to do in order to get this all to work:
- Combine the two text fields on the Incident into a single string variable for examination,
- Convert the text to upper case,
- Convert all line feeds to spaces,
- Remove all characters that are not letters, numbers, or spaces,
- Split the string by spaces creating an array of words,
- Unduplicate the array of words so that we only looked at each unique word once,
- Examine each word to see if it started with a known task number prefix,
- Read the Task table for every word that started with a known task number prefix, and
- Build a relationship record for every Task record that was found on the Task table.
All we need to do now is turn that into code.
Combine the two text fields on the Incident into a single string variable for examination:
var text = taskGR.short_description + ' ' + taskGR.description;
Convert the text to upper case:
text = text.toUpperCase();
Convert all line feeds to spaces:
text = text.replace(/\n/g, ' ');
Remove all characters that are not letters, numbers, or spaces:
text = text.replace(/[^A-Z0-9 ]/g, '');
Split the string by spaces creating an array of words:
var words = text.split(' ');
Unduplicate the array of words so that we only looked at each unique word once:
var unduplicated = {};
for (var i=0; i<words.length; i++) {
var thisWord = words[i];
unduplicated[thisWord] = thisWord;
}
Examine each word to see if it started with a known task number prefix:
for (var word in unduplicated) {
for (var x in prefix) {
if (word.startsWith(prefix[x])) {
this._findTask(word, taskGR.getUniqueValue());
}
}
}
Read the Task table for every word that started with a known task number prefix:
_findTask: function(number, child) {
var taskGR = new GlideRecord('task');
if (taskGR.get('number', number)) {
this._documentRelationship(taskGR.getUniqueValue(), child);
}
},
Build a relationship record for every Task record that was found on the Task table:
_documentRelationship: function(parent, child) {
var relGR = new GlideRecord('task_rel_task');
relGR.addQuery('parent', parent);
relGR.addQuery('child', child);
relGR.query();
if (!relGR.next()) {
relGR.initialize();
relGR.parent = parent;
relGR.child = child;
relGR.type = 'd80dc65b0a25810200fe91a7c64e9cac';
relGR.insert();
}
},
Before I create a relationship record, I want to make sure that there isn’t already a relationship record out there, so I do a quick query just to check before I commit to inserting a new one. The two records don’t need to be linked more than once. I also hard-coded the relationship type, which works for my current purpose, but if I ever want to expand this out to other use cases, I may eventually want to pass that in as an argument as I did with the task number prefixes. Here is the whole thing, all put together:
var TaskReferenceUtils = Class.create();
TaskReferenceUtils.prototype = {
initialize: function() {
},
linkReferencedTasks: function(taskGR, prefix) {
var text = taskGR.short_description + ' ' + taskGR.description;
text = text.toUpperCase();
text = text.replace(/\n/g, ' ');
text = text.replace(/[^A-Z0-9 ]/g, '');
var words = text.split(' ');
var unduplicated = {};
for (var i=0; i<words.length; i++) {
var thisWord = words[i];
unduplicated[thisWord] = thisWord;
}
for (var word in unduplicated) {
for (var x in prefix) {
if (word.startsWith(prefix[x])) {
this._findTask(word, taskGR.getUniqueValue());
}
}
}
},
_findTask: function(number, child) {
var taskGR = new GlideRecord('task');
if (taskGR.get('number', number)) {
this._documentRelationship(taskGR.getUniqueValue(), child);
}
},
_documentRelationship: function(parent, child) {
var relGR = new GlideRecord('task_rel_task');
relGR.addQuery('parent', parent);
relGR.addQuery('child', child);
relGR.query();
if (!relGR.next()) {
relGR.initialize();
relGR.parent = parent;
relGR.child = child;
relGR.type = 'd80dc65b0a25810200fe91a7c64e9cac';
relGR.insert();
}
},
type: 'TaskReferenceUtils'
};
Now that we our Script Include, we need to build the Business Rule that calls it. For my purpose, I added a Business Rule to the Incident table and called it LinkReferencedTasks. I checked the Advanced checkbox and made it active async on Insert whenever there was text in either of the two description fields. I could have also triggered it on Update as well, but in my experience, the Incident description is usually captured when the Incident is created an rarely updated after that.
Under the Advanced tab, I entered the following script:
(function executeRule(current, previous) {
new TaskReferenceUtils().linkReferencedTasks(current, ['REQ','RITM','SCTASK','CHG']);
})(current, previous);
In addition to the current GlideRecord, you also need to pass in a string array of task table prefixes which will be used somewhat like a filter to only link tasks that start with those values. If you want a different mix of task types, you can just update that list. That’s it. We are done. Well, maybe we had better test it out first, but the building part is done anyway. Testing should be simple enough: we just need to find an existing task that we want to reference and then include that task number in the text of a new incident. Let’s do that now.
Now all we have to do is hit that Submit button and see if those tasks referenced in the text are automatically linked to the Incident. Seems as if a little drum-roll would be appropriate here …
Well, nothing ever goes right the very first time! It looks like we managed to create a link to the RITM, but not to the Request. Fortunately, it turns out that this is a tester error and not a developer error. When I typed in the Request number, I missed a zero. The actual Request number is REQ0010005, not REQ001005. Of course, my explanation for that is that I did that on purpose to demonstrate that it will only link real requests, and if your request number is not a real request, then it won’t bother to attempt to create a link to it. That’s it — I did it on purpose — it was all part of the plan. You know that you have to test for failure as well as success — I just did it all in one test because I am so efficient. Sometimes I even amaze myself!
Anyway, it all seems to work, so for those of you who like to play along at home, here’s an Update Set with all of the parts.
Update: There is a better (corrected) version here.
