Sending a Message from Server-Side C# to Client-Side Javascript in Creatio (formerly bpm’online)

Bpm’online has a powerful backend due to the ability to create processes. You can do just about anything at all in these processes. However, there are times that you’ll want to let the front-end javascript know that something happened on the backend, so it can respond as needed, for example to refresh the screen and see the changes made by the process. The same is true about configuration web services (which I’ll cover in a future post). Luckily, there is a mechanism in the MsgChannelUtilities object, built on SignalR, that provides this capability.

In your C# code (such as a script task in a process), you’ll use the following to send the message:

Terrasoft.Configuration.MsgChannelUtilities.PostMessageToAll("SomeMessageId", "My message value");

The PostMessageToAll method takes two parameters, the first is the message ID to identify your specific message, the second is the message you want to send. In the code above, the “SomeMessageId” is your unique value for your particular message. You’ll need to use this to know if you’ve received your intended message in the code that you want to receive the message. The “My message value” can be whatever you want to send to the client-side code. It could be a single string, or something more complex like a list of values, which you can use as an array on the receiving end.

In your javascript, you’ll use the following to receive the message. We’ll wire up a function to get the messages in the page’s init function and also unregister it, so we’ll stop getting messages, in the page’s destroy function:

init: function() {
    this.callParent(arguments);
    // register our function to receive messages
    Terrasoft.ServerChannel.on(Terrasoft.EventName.ON_MESSAGE, this.onServerMessageReceived, this);
},

onServerMessageReceived: function(scope, message) {
    var sender = message && message.Header.Sender;
    // make sure the message received is the one you sent
    if (sender === "SomeMessageId") {
        // if you sent some data with the message you can get it from the message Body
        var someMessageText = message.Body;
        // do something here as needed
    }
},

destroy: function() {
    // unregister so we no longer get messages
    Terrasoft.ServerChannel.un(Terrasoft.EventName.ON_MESSAGE, this.onServerMessageReceived, this);
    this.callParent(arguments);
}

This is an easy way to send a message from a process or a service on the server to the client allowing your server-side code to easily communicate with your client-side code.

Note, in the example above the server code is sending a message containing a single value to the client. You can also send objects serialized as JSON to the client as well. For example, the following code creates a dynamic object with multiple properties, then serializes it as JSON and includes it in the message to the client:

// create a dynamic object
var payload = new { 
	user = user, 
	messageId = someMessageId,
	message = someMessage,
	otherStuff = someOtherThings
};

// serialize the object as JSON to send to client
Terrasoft.Configuration.MsgChannelUtilities.PostMessageToAll("SomeMessageId", Newtonsoft.Json.JsonConvert.SerializeObject(payload));

Now, when the message is received on the client, the body can be used as JSON:

onServerMessageReceived: function(scope, message) {
    var sender = message && message.Header.Sender;
    // make sure the message received is the one you sent
    if (sender === "SomeMessageId") {
        // if you sent some data with the message you can get it from the message Body
        // since the body is an object, convert JSON string to an object
        var data = Ext.decode(message.Body);
        // this message is for a specific user
        if (data.user == Terrasoft.SysValue.CURRENT_USER_CONTACT.value) {
            Terrasoft.showInformation("You got the message: " + data.message);
        }
    }
}