Creating a Web Service and Consuming it From Client-Side Javascript in Creatio (formerly bpm’online)

One of my favorite features of bpm’online is how you can create your own custom web services that you can consume from the client-side code in the UI. This allows you to offload heavy operations to the server that you can easily call from your code in the UI. These web services are referred to as configuration services. They are written in C# and are really just standard WCF service classes, decorated with the ServiceContract attribute. You can get a connection to the bpm’online instance, use EntitySchemaQuery or Entity classes, return data to the client, etc, whatever you want. Very powerful.

Creating the Web Service

We’ll create a simple sample configuration service.  To do this we’ll need to create a “Source Code” schema in our configuration. This is a type of schema where you create C# code in bpm’online:

Paste in the following code:

namespace Terrasoft.Configuration
{
    using System.ServiceModel;
    using System.ServiceModel.Activation;
    using System.ServiceModel.Web;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrSourceCode1 : BaseService
    {
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Json, ResponseFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped)]
        public string SayHelloTest(string Name)
        {
            return "Hello " + Name + "!";
        }
    }
}

In the code above, we’ve created a class called UsrSourceCode1. It exposes a single service method called SayHelloTest which takes a string name parameter and returns a string. Pretty simple. The class inherits from the BaseService class, which gives you access to things like UserConnection in your code. Also, you can definitely return more than just simple types from the web service. The example above returns a string, but it can be any type, even an object or List of anything. If you want to return an object, you need to decorate the class with the [DataContract] attribute and then any exposed properties within the object with the [DataMember] attribute (and you can optionally specify a Name that you want in the returned object that is different than the original class or property names. Here’s an example of a class that can be returned from your web service:

[DataContract]
public class MyObjectResponse
{
    [DataMember(Name = "someProp")]
    public string SomeProperty { get; set; }
    [DataMember(Name = "intProp")]
    public int IntegerProperty { get; set; }
}

Of course, simple types, or Lists can be returned without any extra attributes.

Consuming the Web Service from Client-Side Javascript in the UI

Now, to call this service from client-side code we’ll need to add ServiceHelper to our AMD modules list of our code. What this means is, in the page code you’re calling this from, you’ll add something like this:

define("ContactPageV2", ["ServiceHelper"], function(ServiceHelper) {
    return {
        entitySchemaName: "Contact",
 
        // ... all the rest of the stuff
 
    };
});

Note the part at the top, you’ll see “ServiceHelper” (in quotes) in the square brackets and ServiceHelper (not in quotes) in the function parameters. Looking at require.js or other searches for AMD modules will show you more info on this topic, but basically it is a way for a module to be provided to your code for you to use.

Now that you’ve added that, it’s easy to use. Note, in the C# code above our class name is UsrSourceCode1 and the service method is named “SayHelloTest”. We’ll send to that service method a payload with the parameters, which ours takes only one named “Name”. We’ll use a function called callService in the ServiceHelper module we’ve imported to call it. It takes the following parameters:

ServiceHelper.callService("ClassName", "MethodName", CallbackFunction, PayloadWithParameters, Context)

Our code looks like this:

// we'll send an object with the parameters the service method takes
var payload = {
    Name: this.get("Name")
};

// now call the service. We'll get the response back as MethodNameResponse (where 
// MethodName is the name of the service method.
ServiceHelper.callService("UsrSourceCode1", "SayHelloTest", function(response) {
    var result = response.SayHelloTestResult;
    // do whatever with the response, we'll just display it in a message dialog
    this.showInformationDialog(result);
}, payload, this);

That’s it. Pretty simple and amazingly powerful. You can combine that call with the bpm’online loading indicator so the user knows something is happening, in cases where your service can take some time to complete. It can greatly simplify the code you add in the UI and provides a great way to split up the code and allow the heavy lifting to run more efficiently on the server. Like I said, it’s one of my favorite things to make use of when developing for bpm’online.