“To take the ‘easy way’ is to walk a path that doesn’t exist to the edge of a cliff that does.”
— Craig D. Lounsbrough
Today we will set the widget aside for a bit and focus on one of the Scripted REST API services, the one needed to verify the Host instance entered by the user. We could use the stock REST API for the new instance table, but that would require authentication and would not give us the opportunity to inject some additional logic beyond just the value of the table fields. The scripted approach is a little more work, but in this case, it is work that needs to be done. Basically, we want to allow unauthenticated users to obtain information about the Host instance directly from the Host instance to verify that it really is a Collaboration Store Host. The format of the JSON string returned would look something like this:
{
"result": {
"status": "success",
"info": {
"instance": "dev00001",
"accepted": "2021-07-22 21:59:48",
"description": "Test Collaboration Store",
"sys_id": "2be69501076130103457f2218c1ed02b",
"name": "Test Collaboration Store",
"email": "storekeeper@example.com"
}
}
}
To produce that kind of an output, you need to create a Scripted REST Resource, but before you can build a resource you have to first create a Scripted REST Service, which is the umbrella record under which you can then define multiple Scripted REST Resources. Here is the record for the service that I will be using for all of the resources needed for this app:
Normally, the API ID would be something a little descriptive to identify the purpose of the API, but since this is a Scoped Application, the application scope is already part of the URI, so it seemed rather redundant to put something like that in again. Instead, I just set the API ID to V1, indicating that this is Version #1 of this API.
With that out of the way, we can now go down to the Related Records list and use the New button to create our Scripted REST Resource. I called this one info, which also becomes part of the URI for the service, and with the application scope prefix and the APP ID from the parent service, the full URI for this resource becomes:
/api/x_11556_col_store/v1/info
I also set the HTTP Method to GET, since all we are doing is retrieving the information. Here is the basic information for the resource:
For the script itself, I decided to place all of the relevant code in the Script Include, and just code a simple function call in the resource script definition itself:
(function process(request, response) {
var result = new CollaborationStoreUtils().processInfoRequest();
response.setBody(result.body);
response.setStatus(result.status);
})(request, response);
Of course, that just means that we have a lot of work to do in the Script Include, but that’s a better place for all of that code, anyway. We already created the empty shell for the Script Include previously, so now we just need to add a new function called processInfoRequest that returns an object that contains a body and a status.
Underneath the script, there is series of tabs, and under the Security tab, you want to also make sure that the Requires authentication checkbox is unchecked. At this point in the set-up process the prospective client does not have any credentials to use for authentication, so we want this info-only service to be open to everyone. There isn’t any sensitive information contained here, so that shouldn’t present any kind of security risk.
As for the Script Include function itself, we will want to verify that this is, in fact, a Host instance, and then go get the details for the instance from the database table. We can easily tell if it is a Host instance by comparing the stock System Property instance_name with the application’s System Property x_11556_col_store.host_instance. If they match, then we can go fetch the record from the database, and if that operation is successful, we can build the response. If we fail to obtain the record for whatever reason, then something has gone horribly wrong with the installation, and we will respond with a generic 500 Internal Server Error. If the two properties do not match, then this is not a Host instance, and in that case, we respond with a 400 Bad Request, which we will call an Invalid instance error. Here is how the whole thing looks in code:
processInfoRequest: function() {
var result = {body: {error: {}, status: 'failure'}};
if (gs.getProperty('instance_name') == gs.getProperty('x_11556_col_store.host_instance')) {
var mbrGR = new GlideRecord('x_11556_col_store_member_organization');
if (mbrGR.get('instance', gs.getProperty('instance_name'))) {
result.status = 200;
delete result.body.error;
result.body.status = 'success';
result.body.info = {};
result.body.info.instance = mbrGR.instance;
result.body.info.accepted = mbrGR.accepted;
result.body.info.description = mbrGR.description;
result.body.info.sys_id = mbrGR.sys_id;
result.body.info.name = mbrGR.name;
result.body.info.email = mbrGR.email;
} else {
result.status = 500;
result.body.error.message = 'Internal server error';
result.body.error.detail = 'There was an error obtaining the requested information.';
}
} else {
result.status = 400;
result.body.error.message = 'Invalid instance error';
result.body.error.detail = 'This instance is not a ServiceNow Collaboration Store host.';
}
return result;
}
I start out by building the result object with the expectation of failure, and then override that if everything works out. The main reason that I do that is because there are more failure conditions than success conditions, and so that simplifies the code in more places that if I had done it the other way around. That may not be the most efficient way to approach that, but it works.
That wraps up all of parts for providing the service, and since it is just a simple unauthenticated GET, you can even try it out by simply entering the full URL in a browser. Of course, it will come out formatted in XML instead of JSON, but at least you can see the result. This completes the Host instance side of the interface, but to complete our widget, we still need to build the Script Include function that will run on the instance being set up before all of this will work. That may end up being a little bit of work, so that sounds like a good subject for our next installment in this series.
