“Quality is never an accident. It is always the result of intelligent effort.”
— John Ruskin
Now that we have completed our address verification feature, we can finally turn our full and complete attention to the actual purpose of this entire adventure, which which is to explore the use of ServiceNow Event Management practices on the internal workings of ServiceNow itself. When we last left our Script Include, we had identified a number of places in the script where things could potentially go wrong. As a temporary measure, we just put a simple gs.info statement in each one of those places. Now we want to replace those with Event logging so that we can leverage the built-in power of the ServiceNow Event Management infrastructure.
To make that easier, we built a utility a while back to handle much of the heavy lifting of logging an Event. We can take advantage of that utility and minimize the code that we will need to our Script Include. Each gs.info statement will need to be replaced with something like this:
var seu = new ServerEventUtil();
seu.logEvent(source, resource, metric_name, severity, description, additional_info);
Now we just need to figure out what values to send for each of those function arguments. Let’s take them one at a time.
source
This is the source of the Event, which is our case is the Script Include that is logging the Event. Since the name of the Script Include is always stored in an internal property called type, I just like to pass this.type for this argument, which works in all Script Includes without modification.
resource
This is a reference to thing that you were working on when the problem occurred. In our case, this would be a User, but in the current configuration, we do not have a handle on the User record that is being updated. We could use the address here, just to have some kind of unique value, but when we turn this Event into an Incident, it would be good to know which User was being updated. The solution to that would be to have the calling script pass some reference to User record as an additional argument to the function. That’s a little more work, but it will be worth it in the long run.
metric_name
This is basically the problem that occurred, and we will end up with a different value here for different issues such as an unparsable JSON string or a bad HTTP Response Code.
severity
This is just your standard severity values, and for our purposes, I think we will just pass a hard-coded 3 (Moderate) here.
description
As the name implies, this is just a text description of what happened. Ours will be unique to the problem that occurred.
additional_info
This is an open-ended JSON object into which you can stuff basically anything that you might want to know about what happened that isn’t already in a defined property. The Event logging utility automatically adds some standard things to this object such as user information and a stack trace, but we will want to add some additional information as well such as what was sent to the service and what came back. It takes a bit of code to construct the additional info object, so I like to build a function for that so that it can be called from wherever it is needed instead of duplicating the code everywhere. Here is the one that we will add for this exercise:
buildAdditionalInfo: function(input, response, respObject, exception) {
var additionalInfo = {input: {}, response: {}};
additionalInfo.input.street = input.street;
additionalInfo.input.city = input.city;
additionalInfo.input.state = input.state;
additionalInfo.input.zip = input.zip;
additionalInfo.response.code = response.getStatusCode();
additionalInfo.response.content = response.getBody();
additionalInfo.response.headers = response.getHeaders();
if (respObject) {
additionalInfo.response.object = respObject;
}
if (exception) {
additionalInfo.exception = exception.toString();
additionalInfo.stackTrace = exception.stack;
}
return additionalInfo;
},
Using a function for this not only consolidates the code into a single place, it also ensures some consistency between the various Events, which makes it easier to pull the data back out when you want to use it for things like formatting the description of a resulting Incident.
Now that know how we are going to populate these arguments, let’s go down through the code and replace each of our gs.info statements with Event logging. The first one that we come across is the JSON parsing exception.
try {
respArray = JSON.parse(body);
} catch (e) {
seu.logEvent(
this.type,
user,
'Unparsable response',
3,
'The response content received from the US Address validation service could not be parsed.',
this.buildAdditionalInfo(response, resp, null, e));
}
At this point in the process, we do not have a response object, but we do have an exception, so we pass null as the response object to the function that builds out the additional info. All of the others will be very similar, so we don’t have to go through each one individually. Here is the complete function, with all of the gs.info statements replaced and the user identifier added as a function argument:
validateAddress: function(user, street, city, state, zip) {
var response = {result: 'failure', street: street, city: city, state: state, zip: zip};
var seu = new ServerEventUtil();
var rest = new RESTMessage('US Street Address API', 'get');
rest.setStringParameter('authid', gs.getProperty('us.address.service.auth.id'));
rest.setStringParameter('authToken', gs.getProperty('us.address.service.auth.token'));
rest.setStringParameter('street', encodeURIComponent(street));
rest.setStringParameter('city', encodeURIComponent(city));
rest.setStringParameter('state', encodeURIComponent(state));
rest.setStringParameter('zip', encodeURIComponent(zip));
var resp = rest.execute();
var body = resp.getBody();
if (resp.getStatusCode() == 200) {
var eventLogged = false;
var respArray = [];
try {
respArray = JSON.parse(body);
} catch (e) {
seu.logEvent(
this.type,
user,
'Unparsable response',
3,
'The response content received from the US Address validation service could not be parsed.',
this.buildAdditionalInfo(response, resp, null, e));
eventLogged = true;
}
if (respArray && respArray.length > 0) {
respObj = respArray[0];
if (typeof respObj.analysis == 'object') {
var validity = respObj.analysis.dpv_match_code;
if (validity == 'Y' || validity == 'S' || validity == 'D') {
response.result = 'valid';
response.street = respObj.delivery_line_1;
response.city = respObj.components.city_name;
response.state = respObj.components.state_abbreviation;
response.zip = respObj.components.zipcode;
if (respObj.components.plus4_code) {
response.zip += '-' + respObj.components.plus4_code;
}
} else {
response.result = 'invalid';
}
} else {
seu.logEvent(
this.type,
user,
'Invalid Response Object',
3,
'The response object received from the US Address validation service was not valid.',
this.buildAdditionalInfo(response, resp, respObj));
}
} else {
if (!eventLogged) {
seu.logEvent(
this.type,
user,
'Invalid Response Content',
3,
'The response content received from the US Address validation service was not valid.',
this.buildAdditionalInfo(response, resp));
}
}
} else {
seu.logEvent(
this.type,
user,
'Invalid Response Code',
3,
'The response code received from the US Address validation service was not valid.',
this.buildAdditionalInfo(response, resp));
}
return response;
},
The one place where we had to add a little bit of extra logic was the Event that is triggered when the respArray is empty. One possible reason for that field to be empty would be if we failed to successfully parse the JSON string. When that happens, we have already logged an Event, so we would not want to now log a second one for the same issue. To prevent that from happening, we added the eventLogged variable, and then we only log an Event later on if that variable is still set to false. Other than that one special circumstance, all of these are pretty much the same other than the unique values that are specific to the particular problem triggering the Event.
That completes the modifications necessary to support Event logging, but since we added the user identifier to the list of function arguments, we still have a little work to do to carry that change forward through all of the other components. To begin, we will have to collect the user value from the Ajax parameters and pass that on to the primary function. That client callable function now looks like this:
validateAddressViaClient: function() {
var user = this.getParameter('sysparm_user');
var street = this.getParameter('sysparm_street');
var city = this.getParameter('sysparm_city');
var state = this.getParameter('sysparm_state');
var zip = this.getParameter('sysparm_zip');
return JSON.stringify(this.validateAddress(user, street, city, state, zip));
},
Not much change here; we pull one more parameter into a variable and then add that variable to the function call arguments. Of course, none of that will do any good if we don’t send that extra parameter with the Ajax call, so we will need to modify our Client Script as well. Again, there is not much to change here, but we need to make the change. Our code to value the parameters now has one additional line:
ga.addParam('sysparm_name', 'validateAddressViaClient');
ga.addParam('sysparm_user', g_form.getValue('user_name'));
ga.addParam('sysparm_street', street);
ga.addParam('sysparm_city', city);
ga.addParam('sysparm_state', state);
ga.addParam('sysparm_zip', zip);
That completes the changes that we need to make in order to log an Event whenever something unexpected occurs. We still need to test everything to make sure that it all works, but to do that, we are going to have to force some kind of error to occur. That sounds like a project in and of itself, so this seems like a good stopping place for now. We’ll figure out all of that testing stuff in our next installment.
