Subflow – Page 2 – snhackery

Service Account Management, Part VI

Posted on November 30, 2022 | by snhackery

“Never discourage anyone who continually makes progress, no matter how slow.”
— Plato

Last time, we built out a fulfillment Subflow for one of our two example Service Account types, so now we can build the primary Flow that will call that Subflow and do all of the other work required to fulfill the request. Although you can configure a Flow to call a Subflow using the Flow Designer, you have to specify the Subflow during the development process. In our case, the Subflow that we will want to use will be dependent on the type of Service Account requested, so we will not know which Subflow will need to be called until execution time. Ideally, we would want to look the type requested, read the record for that type to get the Subflow, and then execute the Subflow specified in the type record. Since there doesn’t seem to be a way to do that out of the box, we will need to build out a custom Action to make the Subflow call via script. I created a simple Action called Create Service Account that takes the name of the Subflow and the Requested Item record as input and returns the same outputs as our fulfillment Subflows. The script for that Action looks like this:

(function execute(inputs, outputs) {
	try {
        var result = sn_fd.FlowAPI.getRunner()
            .subflow(inputs.subflow)
            .inForeground()
            .withInputs({requested_item: inputs.requested_item})
            .run();
		var returned = result.getOutputs();
		for (var name in returned) {
			outputs[name] = returned[name];
        }
    } catch (e) {
        outputs.success = false;
		outputs.failure_reason = 'Subflow execution failed with error: ' + e.getMessage();
    }
})(inputs, outputs);

All it does is launch the Subflow with the Requested Item record passed and returns whatever is returned by the called Subflow. This will essentially perform the same function as the Call Subflow action, but with the added benefit of allowing us to pass in the name of the Subflow to be called rather than have it hard-coded in the Flow.

Now that we have the ability to call a configured Subflow, we can jump back into the App Engine Studio and build out the primary Flow. On the dashboard for our application, we can scroll down to the Logic and automation section and then click on the Add button right after the section header.

*To create a new Flow, click on the Add button near the Logic and automation section header*

Once you click on the Add button, a selection list appears, with Flow being the first option.

On this screen, we simply select Flow from the available options, which takes us to the next screen.

On this screen we enter Service Account Request Fulfillment in both the Name and the Description fields and then click on the Continue button.

The next screen just comes up long enough for the basic Flow to be created, after which we are brought to the successful completion screen.

At this point, the Flow now exists, but it has no steps, so we will want to click on that Edit this flow button to start building out the logic of the Flow. We will select Service Catalog as the trigger, and as we did with our sample Subflow, the first thing that we will want to do is to gather up the variable values from the Requested Item.

*Grabbing the variable values from the Requested Item*

This time, we will need the type, the responsible_group, and the account_id from the request. The next thing that we will want to do is to read the Service Account Type record for the requested type, so we will select Look Up Record for our action.

*Fetching the Service Account Type record*

We are looking for the record where the Name field matches the type selected on the Catalog Request. Once we have the variable values from the request and the matching type record, we can call our type-specific Subflow using the Action that we created for that purpose.

*Creating the Service Account using the type-specific Subflow*

Now we need to check to make sure that the account was created, so we add an If condition based on the success flag returned by the Subflow.

If the account was created successfully, we will want to create a record for the account in our Service Account table, but before we can do that we need to fetch the record for the responsible group from the sys_user_group table. We have the name of the group from the catalog item variables, but we need the sys_id of the record to populate the Service Account record. We can do this with another Look Up Record action, searching the table for a record with the same name.

With the user group record now in hand, we have enough information to create the new record in our Service Account table.

*Creating the new Service Account table record*

Once we have created a record for the new Service Account, we will want to inform the user that the account has been created and is available for use. I took a short-cut here and just stubbed out a simple email, but ideally you would want to use a mail template and include some boiler-plate verbiage about company policies on the use of Service Accounts, security concerns, and related information on the owner’s responsibilities. All of that would ultimately be up to anyone attempting to implement such as system, and has little relevance to the workings of the process, so I will leave that to others and just include something simple as an example.

*Informing the user of the account’s availability*

The password for the account should be sent out in a separate email, but before we do that, let’s go ahead and close the Requested Item now that the account has been created and the requested notified. To do that, we will select Update Record for our action and then drag in the pill for the Requested Item record, which will then populate the Table value.

Now all that is left to do is to send the password for the account to the requester. I took another short-cut here in that the only contents of the body of the email is the password itself with no other information, but again, this is only a sample. An encrypted email from a template would obviously be preferable here, but this at least provides a placeholder for performing this task in a much better way.

That completes the process for a successful account creation, but if the account could not be created for any reason, we still need to close out the Requested Item with that information. To do that, we will add an Else condition to our If and then insert one more step under the Else.

*Closing the Requested Item on account creation failure*

And that’s all there is to that. Now that we have our completed Flow, we can go back into our Catalog Item and specify this Flow for fulfillment. Once that has been done, we can finally request the item to generate a Requested Item record that we can use to test all of this out. That will probably be a little bit of an adventure, so let’s save all of that for our next time out.

Service Account Management, Part V

Posted on November 28, 2022 | by snhackery

“One step at a time is all it takes to get you there.”
— Emily Dickinson

Last time, we built out the majority of the Catalog Item that we are creating for the purpose of requesting a new Service Account. All that is left for us to do now is to create the process that will fulfill the request once it has been made. Because our intent is to create a single Catalog Item for any type of account, and each type of account will have its own unique account creation process, we will want to build a generic workflow of some kind that will look at the type requested and then launch the appropriate fulfillment process based on that type. Before we jump in and start creating things, though, we will need to come up with a strategy that will facilitate combining a generic outer process with a type-specific inner process.

Assuming that each type will have its own Subflow unique to the type, we will want to store a link to that Subflow on the type record that we created earlier. This way, the generic process can look at the type requested, read the record for that type, and then grab the link to the Subflow so that it can be launched. To make that work, we will need to devise some kind of standard for the Subflow in terms of inputs and outputs so that the generic process can consistently communicate with any given fulfillment Subflow. For input, the Requested Item record should suffice, but the outputs will depend on how much work will be delegated to the Subflow and how much will be handled by the primary process.

In addition to the creation of the account, our process should also perform a number of other tasks such as notifying the user of the account’s creation, sending them the assigned password, creating the record in the accounts table, and closing the request. Since everything except the account creation is universal, our Subflow should be limited to just the steps necessary to create the account, and all other activities should be handled by the primary request. For that to work, the Subflow will need to return sufficient data to the primary process so that it can successfully complete all of the other work. We also have to allow for the possibility that the account could not be created for whatever reason, and that information will need to be communicated back as well. This may change over time as we get into the weeds, but for now, I think that the following should be able to handle everything needed.

Success flag
Failure Reason
Account ID
Account Password
Account Owner Instructions

Since we will need a working Subflow to test out the primary process, it might be wise to start with that first, and then circle back to the primary process once we have a working Subflow to call. Before we do that, though, we need to figure out a way to generate a password. If you search through all of the Script Includes bundled with the product for anything that has the word password in the name, you can find a lot of password generation scripts already out there. Unfortunately, these are all in the global scope, and their access is limited to the global scope, so we can’t call any of these from our Scoped Application. If you search the Internet for password generation scripts, you can find even more, but most of these are much more sophisticated that I was looking for. Ultimately, I borrowed a few things from here and there and came up with a simple Action that had no inputs, one output, and a single script execution step with the following logic.

(function execute(inputs, outputs) {
	var upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
	var lower = 'abcdefghijklmnopqrstuvwxyz';
	var number = '0123456789';
	var special = '!@#$%&*()_+<>[].~';
	var source = upper + lower + number + special;
	outputs.password = '';
	while (outputs.password.length < 32) {
		outputs.password += source.charAt(Math.floor(Math.random() * (source.length + 1)));
    }
})(inputs, outputs);

This does not guarantee that you will have at least one of each category of character, but with 32 positions, the chances are still pretty good that you will. I ran it a few times to see, and I didn’t think that the results looked all that bad.

dPoxtBDUqaCtFaH2knI]XI0Ts*#1rKyT
xnDRzngKOMy~py8xK[xV]2S2CTkh]RWv
knUHn*0WJ4H_Ww90gq[2TqJmKKb0Xu9v
OcWe4TKQN#0[RM1wj$p$(#_Sp.~CVTiM
>wEE!CbrFGwYccWb#H>+6pyEpZwjcJ%A

Each one seems to have a little bit of everything, so I think it is good enough for what we are trying to do here. So now that we have that in place, we can start working on our Subflow. Unfortunately, you can build a Flow in the App Engine Studio, but not a Subflow (or at least if you can, I cannot figure out how to do that). So, to build out our Subflow, we will have to jump into the old Flow Designer. To create a new Subflow, we select New -> Subflow up in the upper right-hand corner and give it a name of ServiceNow Service Account Creation. The first thing that we will do is create all of the inputs and outputs listed above.

Once we have our inputs and outputs defined, we can jump down in the Actions section and start adding steps to the flow. The first thing that we will want to do is to grab the requested account ID from the Requested Item, so we will select Get Catalog Variables from the list of available actions and drag in the Requested Item pill from the inputs.

*Fetching the account ID from the Requested Item*

For the template, we select our new Service Account Catalog Item, and once we do that, all of the variables defined for that item appear in the Available list, from which we can select account_id. This will give us an account_id pill which we can use in future steps.

The next thing that we will want to do is to find out if the requested account ID is already in use. We can do that by reading the sys_user table, so for our next step we select Look Up Record from the list of actions and select the User table from the list of tables.

*Checking the sys_user table for an existing account*

Our only condition for this is that the User ID is the requested account ID, which we again drag over from the inputs. Once we attempt to fetch the record, the next thing that we will want to do is to check and see if a record was returned, so for our next step we will select If from the Flow Logic options.

*Checking to see if a record was found on the sys_user table*

If a record was returned with the requested account ID, then we want to stop the process and return a failure message back to the calling Flow. To do that, we select Assign Subflow Outputs for our next step and fill in the values for the output fields.

*Setting the Subflow outputs for existing User ID failure*

Hopefully, the account will not already exist, so we will want to put all of our other steps under an Else condition. The first step under our Else condition will be to generate the password using the Action that we created earlier.

Once we generate the password we have enough data to create the user record, so for our next step we will select Create Record from the list of actions and populate the record with data pills from the input and preceding processes.

*Creating the new Service Account record*

Once the record has been created, we need to report back to the calling Flow, so once again we will select Assign Subflow Outputs and populate the appropriate fields.

*Setting the Subflow outputs for successful completion*

Now all we need to do is to Save and Publish our Subflow and we will have one example to use for testing. We will still need to create one more for our other example use case, but we won’t need to do that just yet. Let’s see if we can make all of this work with our first example before we run off and build another.

At this point, it would be good to test this out to make sure that it all works, but to do that we will need a valid Requested Item record to send in as input, and since we have not completed our Catalog Item, we can’t really do that just yet. Let’s build our primary Flow first, and then update the Catalog Item to point to that Flow, and then we can publish the item and do some testing. To build the Flow, we can go back into the App Engine Studio, so let’s dive into that next time out.

Collaboration Store, Part XXXII

Posted on November 17, 2021 | by snhackery

“There are two ways to write error-free programs; only the third works.”
— Alan J. Perlis

Now that we have all of the Javascript functions needed to push a new application version out to all of the Client instances, we need to create an Action that will call the root function and then create a Subflow that will utilize the new Action. Since we already created a similar Action for the process that shares new Client instances with existing Client instances, the easiest thing to do will be to bring that guy up in the Flow Designer and make a copy. To make a copy, pull up the Action that you want to copy, and use the ellipses menu to select Copy from the drop-down menu.

*Making a copy of the Publish New Instance Action*

Once we have our copy, we need to make the necessary changes to adapt it to our purpose. The publishNewVersion function that we just created takes three arguments (newVersion, targetInstance, and attachmentId), so we will need to modify the Action Inputs to bring in those values. The new Action Inputs now look like this:

Similarly, we will need to modify the Input Variables of the Script Step to pass along these values:

The last thing that we need to do is modify the script itself. The existing script in the cloned Action was pretty simple, as it was just a call to one of our Script Include functions:

(function execute(inputs, outputs) {
	var csu = new CollaborationStoreUtils();
	csu.publishNewInstance(inputs.new_instance, inputs.target_instance);
})(inputs, outputs);

We also want to call a function, and it is in the very same Script Include, so our modification is just a matter of changing the name of the function along with the arguments passed.

(function execute(inputs, outputs) {
	var csu = new CollaborationStoreUtils();
	csu.publishNewVersion(inputs.new_version, inputs.target_instance, inputs.attachment_id);
})(inputs, outputs);

That’s it for the changes, so now all we have to do is Save and Publish the new Action and we are ready to utilize it in our new Subflow. Creating the Subflow will be another Copy operation, this time from our existing New_Collaboration_Store_Instance Subflow. We’ll call our copy Distribute_New_Application_Version, and once again, we will need to make some modifications to adapt it to our new purpose. The original Subflow had a single input, the New Instance. Instead of a new instance, we will be distributing a new application version, so we can replace the New Instance input with a New Version input that will contain the sys_id of the new version record. We will also need the sys_id of the Attachment record, so we will add an Attachment ID input as well.

*Modified Inputs for the new Distribute_New_Application_Version Subflow*

The target instances for this process will be the same as those for the original Subflow: all instances in the community except for the Host instance and the instance from which the data was provided (which could also be the Host in this case, since Host instances can publish applications just like any other Client instance). To filter out the data providing instance, we will need to add a new step to use the passed version record sys_id to fetch the GlideRecord that will lead us to the instance that produced the application.

This gives us the information that we need to complete the filter on the query of the instance table so that we can gather up all of the instances except for the Host and the instance that produced the application.

*Modified query filter using the data available in the fetched version record*

Now all we need to do is to replace the original custom Action inside of the loop with the new Action that we just created.

*New Action added to push application artifacts to the target instance*

This completes the changes needed to the cloned Subflow, so again, all we need to do is to Save and Publish and we are all ready to go. Now all we need to is to come up with a way to launch this Subflow whenever a new application version is sent over to the Host instance. We’ll take a look at that next time out, and hopefully release a new Update Set as well so that those of you that have been kind enough to participate in the testing can give this all a trial run.

Collaboration Store, Part XXXI

Posted on November 15, 2021 | by snhackery

“Someone’s sitting in the shade today because someone planted a tree a long time ago.”
— Warren Buffett

While we wait for additional test results to come in from the corrected Update Set for our latest iteration, it would be a good time to take a look at what we will need to do to complete the last remaining step in the application publishing process. What we have completed so far pushes all of the new application version artifacts to the Host instance. Now we need to build out the process for the Host instance to send out all of those artifacts to all of the other Client instances. Fortunately, we already have in hand most of the code to do that; we just need to clone a few things and make a number of modifications to fit the new purpose.

We have already built a Subflow to push new Client instance information out to all of the existing Client instances during the new instance registration process. Pushing out a new version of an application to those same instances is essentially the same process, so we should be able to clone that guy, and the associated Action, to create our new process. We have also created functions to push over the application record, the version record, and the attached Update Set XML file, and we should be able to copy over those guys as well to complete the process. In fact, we should probably start with the JavaScript functions, as we will need to call the root function in the Action, which will need to be created before it can be referenced in the Subflow.

The functions as written are hard-coded to send everything over to the Host instance. We will want to do basically the same thing, but this time we will be sending things out to various Client instances. Ideally, I should just refactor the code to have the destination instance and credentials passed in so that one function would work in both circumstances, but at this point it was less complicated to just make copies of each function and hack them up for their new purpose. I don’t really like having two copies of essentially the same thing, though, so one day I am going to have to go back and rework the entire mess.

But for now, this is what I came up with when I copied what was once called processPhase5 to create the new publishNewVersion function:

publishNewVersion: function(newVersion, targetInstance, attachmentId) {
	var targetGR = new GlideRecord('x_11556_col_store_member_organization');
	if (targetGR.get('instance', targetInstance)) {
		var token = targetGR.getDisplayValue('token');
		var versionGR = new GlideRecord('x_11556_col_store_member_application_version');
		if (versionGR.get(newVersion)) {
			var canContinue = true;
			var targetAppId = '';
			var mbrAppGR = versionGR.member_application.getRefRecord();
			var request  = new sn_ws.RESTMessageV2();
			request.setHttpMethod('get');
			request.setBasicAuth(this.WORKER_ROOT + targetInstance, token);
			request.setRequestHeader("Accept", "application/json");
			request.setEndpoint('https://' + targetInstance + '.service-now.com/api/now/table/x_11556_col_store_member_application?sysparm_fields=sys_id&sysparm_query=provider.instance%3D' + mbrAppGR.getDisplayValue('provider.instance') + '%5Ename%3D' + encodeURIComponent(mbrAppGR.getDisplayValue('name')));
			var response = request.execute();
			if (response.haveError()) {
				gs.error('CollaborationStoreUtils.publishNewVersion: Error returned from Target instance ' + targetInstance + ': ' + response.getErrorCode() + ' - ' + response.getErrorMessage());
				canContinue = false;
			} else if (response.getStatusCode() == '200') {
				var jsonString = response.getBody();
				var jsonObject = {};
				try {
					jsonObject = JSON.parse(jsonString);
				} catch (e) {
					gs.error('CollaborationStoreUtils.publishNewVersion: Unparsable JSON string returned from Target instance ' + targetInstance + ': ' + jsonString);
					canContinue = false;
				}
				if (canContinue) {
					var payload = {};
					payload.name = mbrAppGR.getDisplayValue('name');
					payload.description = mbrAppGR.getDisplayValue('description');
					payload.current_version = mbrAppGR.getDisplayValue('current_version');
					payload.active = 'true';
					request  = new sn_ws.RESTMessageV2();
					request.setBasicAuth(this.WORKER_ROOT + targetInstance, token);
					request.setRequestHeader("Accept", "application/json");
					if (jsonObject.result && jsonObject.result.length > 0) {
						targetAppId = jsonObject.result[0].sys_id;
						request.setHttpMethod('put');
						request.setEndpoint('https://' + targetInstance + '.service-now.com/api/now/table/x_11556_col_store_member_application/' + targetAppId);
					} else {
						request.setHttpMethod('post');
						request.setEndpoint('https://' + targetInstance + '.service-now.com/api/now/table/x_11556_col_store_member_application');
						payload.provider = mbrAppGR.getDisplayValue('provider.instance');
					}
					request.setRequestBody(JSON.stringify(payload, null, '\t'));
					response = request.execute();
					if (response.haveError()) {
						gs.error('CollaborationStoreUtils.publishNewVersion: Error returned from Target instance ' + targetInstance + ': ' + response.getErrorCode() + ' - ' + response.getErrorMessage());
						canContinue = false;
					} else if (response.getStatusCode() != 200 && response.getStatusCode() != 201) {
						gs.error('CollaborationStoreUtils.publishNewVersion: Invalid HTTP Response Code returned from Target instance ' + targetInstance + ': ' + response.getStatusCode());
						canContinue = false;
					} else {
						jsonString = response.getBody();
						jsonObject = {};
						try {
							jsonObject = JSON.parse(jsonString);
						} catch (e) {
							gs.error('CollaborationStoreUtils.publishNewVersion: Unparsable JSON string returned from Target instance ' + targetInstance + ': ' + jsonString);
							canContinue = false;
						}
						if (canContinue) {
							targetAppId = jsonObject.result.sys_id;
						}
					}
				}
			} else {
				gs.error('CollaborationStoreUtils.publishNewVersion: Invalid HTTP Response Code returned from Target instance ' + targetInstance + ': ' + response.getStatusCode());
			}
			if (canContinue) {
				this.publishVersionRecord(targetInstance, token, versionGR, targetAppId, attachmentId);
			}
		} else {
			gs.error('CollaborationStoreUtils.publishNewVersion: Version record not found: ' + newVersion);
		}
	} else {
		gs.error('CollaborationStoreUtils.publishNewVersion: Target instance record not found: ' + targetInstance);
	}
},

Unlike the original application publication process, we are not bouncing back and forth between the client side and the server side, so with the successful completion of one artifact, we can simply move on to pushing over the next artifact. To create the next step in the process, the publishVersionRecord function, I started out with a copy of the original processPhase6 function. Here is the end result:

publishVersionRecord: function(targetInstance, token, versionGR, targetAppId, attachmentId) {
	var canContinue = true;
	var payload = {};
	payload.member_application = targetAppId;
	payload.version = versionGR.getDisplayValue('version');
	var request  = new sn_ws.RESTMessageV2();
	request.setBasicAuth(this.WORKER_ROOT + targetInstance, token);
	request.setRequestHeader("Accept", "application/json");
	request.setHttpMethod('post');
	request.setEndpoint('https://' + targetInstance + '.service-now.com/api/now/table/x_11556_col_store_member_application_version');
	request.setRequestBody(JSON.stringify(payload, null, '\t'));
	response = request.execute();
	if (response.haveError()) {
		gs.error('CollaborationStoreUtils.publishVersionRecord: Error returned from Target instance ' + targetInstance + ': ' + response.getErrorCode() + ' - ' + response.getErrorMessage());
		canContinue = false;
	} else if (response.getStatusCode() != 201) {
		gs.error('CollaborationStoreUtils.publishVersionRecord: Invalid HTTP Response Code returned from Target instance ' + targetInstance + ': ' + response.getStatusCode());
		canContinue = false;
	} else {
		jsonString = response.getBody();
		jsonObject = {};
		try {
			jsonObject = JSON.parse(jsonString);
		} catch (e) {
			gs.error('CollaborationStoreUtils.publishVersionRecord: Unparsable JSON string returned from Target instance ' + targetInstance + ': ' + jsonString);
			canContinue = false;
		}
		if (canContinue) {
			targetVerId = jsonObject.result.sys_id;
			this.publishVersionAttachment(targetInstance, token, targetVerId, attachmentId);
		}
	}
},

The last step in the process, then, is to send over the Update Set XML file attachment. For that one, I started out with the processPhase7 function and ended up with this:

publishVersionAttachment: function(targetInstance, token, targetVerId, attachmentId) {
	var gsa = new GlideSysAttachment();
	var sysAttGR = new GlideRecord('sys_attachment');
	if (sysAttGR.get(attachmentId)) {
		var url = 'https://';
		url += targetInstance;
		url += '.service-now.com/api/now/attachment/file?table_name=x_11556_col_store_member_application_version&table_sys_id=';
		url += targetVerId;
		url += '&file_name=';
		url += sysAttGR.getDisplayValue('file_name');
		var request  = new sn_ws.RESTMessageV2();
		request.setBasicAuth(this.WORKER_ROOT + targetInstance, token);
		request.setRequestHeader('Content-Type', sysAttGR.getDisplayValue('content_type'));
		request.setRequestHeader('Accept', 'application/json');
		request.setHttpMethod('post');
		request.setEndpoint(url);
		request.setRequestBody(gsa.getContent(sysAttGR));
		response = request.execute();
		if (response.haveError()) {
			gs.error('CollaborationStoreUtils.publishVersionAttachment: Error returned from Target instance ' + targetInstance + ': ' + response.getErrorCode() + ' - ' + response.getErrorMessage());
		} else if (response.getStatusCode() != 201) {
			gs.error('CollaborationStoreUtils.publishVersionAttachment: Invalid HTTP Response Code returned from Target instance ' + targetInstance + ': ' + response.getStatusCode());
		}
	} else {
		gs.error('CollaborationStoreUtils.publishVersionAttachment: Invalid attachment record sys_id: ' + attachmentId);
	}
},

So that takes care of the functions. Now we have to create an Action in the Flow Designer that will call the function, and then produce a new Subflow that will leverage that action. That sounds like a good subject for our next installment.

Special Note to Testers

If you want to test the set-up process, you can do that with a single instance. You just have to select the Host option during the set-up process. If you want to test the Client set-up process, you will need at least two instances, one to serve as the Host, which you will need to reference when you set up the Client (you cannot be a Client of your own Host). But if you really want to test out the full registration process, including the Subflow that informs all existing instances of the new instance, you will need at least three participating instances: 1) the Host instance, 2) the new Client instance, and 3) an existing Client instance that will be notified of the new member of the community.

The same holds true for the application publishing process. You can test a portion of the publishing process by publishing an app on a single Host instance, but if you want to test out all of the parts and pieces, you will want to publish the app from a Client instance and make sure that it makes its way all the way back to the Host. Once we complete the application distribution process, full testing will require at least three instances to verify that the Host distributes the new version of the application to other Clients.

Collaboration Store, Part XIII

Posted on August 18, 2021 | by snhackery

“First, solve the problem. Then, write the code.”
— John Johnson

Today we need to build out the Subflow that we referenced in the Script Include function that we built last time out. To create a new Subflow, open up the Flow Designer, click on the New button to bring up the selection list, and select Subflow from the list.

When the initial form pops up, all you really need to enter is the name of the Subflow, which we already referred to in our Script Include function as New_Collaboration_Store_Instance.

Once you submit the initial properties form, the new Subflow will appear in the list of Subflows, and from there you can bring it up in full edit mode. In edit mode, we can add the one Input to the Subflow, the name of the new instance.

Since we will be launching this Subflow to run on its own in the background, there is no need for any Outputs.

Once we configure the Inputs and Outputs, we can move on to the steps of the Subflow. Our first step will be to gather up all of the records in the table of instances except for two: the Host instance, which has already been updated, and the new instance, which already knows about itself.

We select the Look Up Records Action, select the Member Organization table, and then define two Conditions to get the records that we want: 1) the host value is false, and 2) the instance is not the instance that we brought in as Input. It really doesn’t matter for our purposes what sequence the records come in, but I went ahead and sorted the records by instance, just so they we will always work through them in the same order.

Our next step, then is to loop through the records. We do that with a For Each Item Flow Control step, setting the items to the records obtained in the first step.

Now we have the basic structure of the Subflow; we just need to perform the tasks necessary to notify each host of the new instance, and notify the new instance of each host within the the For Each Item loop. This could all be done with additional Subflow steps, but I took the easy way out here and just built another function in our Script Include to handle the REST API calls to the instances. In fact, I built two functions, one to make the call, and another to call that function twice, once to tell the existing host about the new host, and then again to inform the new host of the existing host. To run that script, I had to create a custom Action, which is just a simple Script Action that calls the function, passing in the names of the two instances (existing, from the current record, and new, from the Subflow input). Once I built the custom Action, I was able to select it from the list and then configure it.

That completes the Subflow, but once again, we have referenced a function in our Script Include that does not exist, so we will have to get into that in our next installment.

Collaboration Store, Part XII

Posted on August 13, 2021 | by snhackery

“The slogan ‘press on’ has solved and always will solve the problems of the human race.”
— Calvin Coolidge

In the previous installment in this series, we created a new Scripted REST API Resource and referenced another nonexistent function in our Script Include. Now it is time to create that function, which will perform some of the work required to register a new client instance and then hand off the remaining tasks to an asynchronous Subflow so that the function can return the results without waiting for all of the other instances to be notified of the new client instance. The only thing to be done in the function will be to insert the new client instance into the database and kick off the Subflow. But before we do that, we need to first check to make sure that the Client has not already registered with the Host.

var result = {body: {error: {}, status: 'failure'}};

var mbrGR = new GlideRecord('x_11556_col_store_member_organization');
if (mbrGR.get('instance', data.instance)) {
	result.status = 400;
	result.body.error.message = 'Duplicate registration error';
	result.body.error.detail = 'This instance has already been registered with this store.';
} else {
	...

As we did before, we construct our result object with the expectation of failure, since there are more error conditions than the one successful path through the logic. In the case of an instance that has already been registered, we respond with a 400 Bad Request HTTP Response Code and accompanying error details. If the instance is not already in the database, then we attempt to insert it.

mbrGR.initialize();
mbrGR.name = data.name;
mbrGR.instance = data.instance;
mbrGR.email = data.email;
mbrGR.description = data.description;
mbrGR.token = data.sys_id;
mbrGR.active = true;
mbrGR.host = false;
mbrGR.accepted = new GlideDateTime();
if (mbrGR.insert()) {
	result.status = 202;
	delete result.body.error;
	result.body.info = {};
	result.body.info.message = 'Registration complete';
	result.body.info.detail = 'This instance has been successfully registered with this store.';
	result.body.status = 'success';
	...

If the new record was inserted successfully, then we response with a 202 Accepted HTTP Response Code, indicating that the registration was accepted, but the complete registration process (notifying all of the other instances) is not yet complete. At this point, all we have left to do is to initiate the Subflow to handle the rest of the process. We haven’t built the Subflow just yet, but for the purposes of this exercise, we can just assume that it is out there and then we can build it out later. There a couple of different ways to launch an asynchronous Subflow in the background, the original way, and the newer, preferred method. Both methods use the Scripted Flow API. Here is the way that we used to do this:

sn_fd.FlowAPI.startSubflow('New_Collaboration_Store_Instance', {new_instance: data.instance});

… and here is way that ServiceNow would like you to do it now:

sn_fd.FlowAPI.getRunner()
	.subflow('New_Collaboration_Store_Instance')
	.inBackground()
	.withInputs({new_instance: data.instance})
	.run();

Right now, both methods will work, and I’m still using the older, simpler way, but one day I’m going to need to switch over.

There should never be a problem inserting the new record, but just in case, we make that a conditional, and if for some reason it fails, we respond with a 500 Internal Server Error HTTP Response Code.

result.status = 500;
result.body.error.message = 'Internal server error';
result.body.error.detail = 'There was a problem processing this registration request.';

That’s it for all of the little parts and pieces. Here is the entire function, all put together.

processRegistrationRequest: function(data) {
	var result = {body: {error: {}, status: 'failure'}};

	var mbrGR = new GlideRecord('x_11556_col_store_member_organization');
	if (mbrGR.get('instance', data.instance)) {
		result.status = 400;
		result.body.error.message = 'Duplicate registration error';
		result.body.error.detail = 'This instance has already been registered with this store.';
	} else {
		mbrGR.initialize();
		mbrGR.name = data.name;
		mbrGR.instance = data.instance;
		mbrGR.email = data.email;
		mbrGR.description = data.description;
		mbrGR.token = data.sys_id;
		mbrGR.active = true;
		mbrGR.host = false;
		mbrGR.accepted = new GlideDateTime();
		if (mbrGR.insert()) {
			result.status = 202;
			delete result.body.error;
			result.body.info = {};
			result.body.info.message = 'Registration complete';
			result.body.info.detail = 'This instance has been successfully registered with this store.';
			result.body.status = 'success';
			sn_fd.FlowAPI.startSubflow('New_Collaboration_Store_Instance', {new_instance: data.instance});
		} else {
			result.status = 500;
			result.body.error.message = 'Internal server error';
			result.body.error.detail = 'There was a problem processing this registration request.';
		}
	}

	return result;
}

Now we have completed the nonexistent function that was referenced in the REST API Resource, but we have also now referenced a new nonexistent Subflow that we will need to build out before things are complete. That sounds like a good subject for our next installment.

Fun with Webhooks, Part VI

Posted on February 25, 2021 | by snhackery

“The most exciting phrase to hear in science, the one that heralds discoveries, is not ‘Eureka!’ but ‘Now that’s funny …'”
— Isaac Asimov

Even though we are not quite finished building out our new Subflow just yet, we have enough elements in place that we can try out what we have so far, and see if it actually works. The simplest way to do that would be to create a Webhook Registry that watches a single Incident, and then go make a qualifying change to that Incident and see what happens. Let’s go find an open Incident and then we can set up our registry.

In my instance, INC0000002 seemed like a likely candidate, so I pulled up the list of Webhook Registrations, clicked on the New button, and created the following new Webhook Registry entry to track changes to that specific Incident.

For the URL, I used that same webhook.site address that I had used before so that I could see the result on the other end of the transaction. Once I had saved my new Webhook Registry entry, all I needed to do in order to test it out was to make a change to the Incident. For my first test, I simply changed the Assignment Group from Network to Hardware, which also then removed the Assigned to field value, since the original person specified in that field was not a member of the new Assignment Group. After making the change, I went over to webhook.site to see if anything showed up as a result of that modification. Sure, enough, a new POST had just been received by that site shortly after I saved the record.

*New Webhook posting after updating an Incident*

Although that proves that the process does indeed work as intended, I did notice one thing that is going to require a little bit of rework. Take a look at the second line of the message property:

Assigned To changed from Howard Johnson to  on INC0000002.

The Assigned to field changed from having a value to not having a value. The code that we have in our buildPayload function doesn’t really handle that circumstance in a way that produces the appropriate text to explain that in plain English. Here is the logic that creates that portion of the message:

if (current.assigned_to != previous.assigned_to) {
	payload.assigned_to = current.assigned_to;
	if (previous.assigned_to) {
		payload.message += separator + 'Assigned To changed from ' + previous.assigned_to + ' to ' + current.assigned_to + ' on ' + payload.id + '.';
	} else {
		payload.message += separator + 'Assigned To set to ' + current.assigned_to + ' on ' + payload.id + '.';
	}
	separator = '\n\n';
}

There is a check to see if the previous value was blank, but there is no check to see if the new value is blank. It wouldn’t take much to throw that in there, though, so let’s go ahead and do that now while we are thinking about it.

if (current.assigned_to != previous.assigned_to) {
	payload.assigned_to = current.assigned_to;
	if (previous.assigned_to) {
		if (current.assigned_to) {
			payload.message += separator + 'Assigned To changed from ' + previous.assigned_to + ' to ' + current.assigned_to + ' on ' + payload.id + '.';
		} else {
			payload.message += separator + 'Assigned To ' + previous.assigned_to + ' removed.';
		}
	} else {
		payload.message += separator + 'Assigned To set to ' + current.assigned_to + ' on ' + payload.id + '.';
	}
	separator = '\n\n';
}

That’s better. While we are at it, we might as well make the same change to the code for the Assignment group, as that is pretty much a line for line copy of the code for the Assigned to field. Everything else looks to be OK. The State is mandatory, so it will never have a new blank value, and the Comments and Work Notes fields are based on new entries and not on changes to existing entries, so if either of those are ever blank, we won’t be doing anything with them at all.

Still, other than that one little annoying language problem, the test was actually quite successful. Our Business Rule fired, the change was detected, our new Subflow was launched, our payload was generated, and the payload was successfully POSTed to the appropriate URL. All in all, I would have to say that that was a pretty good first test of the process. Obviously, we need to do a lot more testing, but this was a great start.

At this point, all I really wanted to do was to make sure that everything was working so far, which I think we accomplished. Before we do too much more testing, though, I think we need to go back and finish up the rest of the Subflow. We still have to add in the step that logs the activity, and we also have to add any error handling for when things don’t go as planned. Once we build all of that out, then we can do a lot more testing to validate the entire process from end to end. It was good to take a quick break and make sure that everything was working up to this point, but now that we know that it is, we need to get back to work on finishing up our development efforts.

Useful ServiceNow links:
Main web site:	https://servicenow.com
Developer site:	https://developer.servicenow.com
Annual Conference:	https://knowledge.servicenow.com