Asynchronous Validation on Pages in Creatio (formerly bpm’online)

Creatio has built in support for performing field validation (see this article on the academy). You add a validator function for a field, then return an object with a validation message in cases where the field didn’t pass validation. Plus, it prevents the user from saving the record if the validation fails and displays your message under the field once the field looses focus.

However, what if you need to do something asynchronous in the validation? This is actually quite common since EntitySchemaQuery is asynchronous. If your validation needs to query values from other objects/records, you won’t be able to use the normal field validation since the query result is asynchronous and won’t return the results within the context of the validation function (there’s no way to make the normal field validation wait for the return).

There is support for performing asynchronous validation in Creatio as well. The BasePageV2, which all pages inherit from, has a method called asyncValidate which is used for just this purpose. The way asyncValidate works is like this:

• Asynchronous validation doesn’t fire until you click save (so you don’t get the little message below the field when it looses focus – instead a message dialog will show when the user clicks save)
• When save is clicked, asyncValidate fires and it passes to you a callback function
• You do your asynchronous operation to validate things, such as an EntitySchemaQuery
• When your results come back from your async operation, you create an object with two properties: success (true/false), and message (the message to display to the user about the failed validation), then you simply call the callback and pass along this object

For a sample, we’ll use the same idea that Tate wrote about in his article Validating That a User Entered Value is Unique in Creatio. In that article, there is a number entered by the user, an EntitySchemaQuery is performed to check to make sure no other records have that number, then a message is displayed and the entered value is cleared (if failed). In our sample, we’ll add this to the asyncValidate method so it prevents the user from saving if the entered value isn’t unique (we’ll be adding one called “Job number” on the OpportunityPageV2). Let’s take a look at the code:

asyncValidate: function(callback, scope) {
	this.callParent([function(response) {
		if (!this.validateResponse(response)) {
			return;
		}

		var jobNum = this.get("UsrJobNumber");
					
		var esq = Ext.create("Terrasoft.EntitySchemaQuery", { rootSchemaName: "Opportunity" });
		esq.addColumn("Id"); 
		esq.filters.addItem(
			esq.createColumnFilterWithParameter(Terrasoft.ComparisonType.EQUAL, "UsrJobNumber", jobNum)
		);
		esq.filters.addItem(
			esq.createColumnFilterWithParameter(Terrasoft.ComparisonType.NOT_EQUAL, "Id", this.get("Id"))
		);
		esq.getEntityCollection(function(result) {
			// create object to hold the validation result
			var validationResult = {
				success: true
			};
			if (result.collection.getItems().length > 0) {
				validationResult.message = "The Job number " + jobNum + " is already in use on another opportunity.";
				validationResult.success = false;
			}
			// call callback function and pass object with validation result
			callback.call(scope || this, validationResult);
		}, this);
	}, this]);	
},

When the user clicks the save button, if this validation fails the user will see the following (and won’t be able to save the record):

One thing to note about the code above. Notice that the function itself is creating a function and passing itself to callParent (in an array). The BasePageV2 will execute all the functions in in this array in a chain until there are no more callbacks to make, then display the final results message. If you have multiple asynchronous validations to perform, you can also use Terrasoft.chain to chain the requests together, passing long the callback to each one. You can see this article below:

Validating Multiple Asynchronous Results in Creatio