Class: RouterClientConstructor

Router Client

The Router Client sends and receives event messages between Finsemble components and services. See the Router tutorial for an overview of the Router's functionality.

Router callbacks for incoming messages are always in the form callback(error, event). If error is null, then the incoming data is always in If error is set, it contains a diagnostic object and message. On error, the event parameter is not undefined.

new RouterClientConstructor
(clientName, transportName)
clients/routerClientConstructor.js, line 39

Name Type Description
clientName string

router base client name for human readable messages (window name is concatenated to baseClientName)

transportName string optional

router transport name, currently either "SharedWorker" or "OpenFinBus" (usually this is autoconfigured internally but can be selected for testing or special configurations)


(channel, eventHandler)
clients/routerClientConstructor.js, line 890

Add listener for incoming transmit events on specified channel. Each of the incoming events will trigger the specified event handler. The number of listeners is not limited (either local to this Finsemble window or in a seperate Finsemble window).

See transmit for sending a cooresponding event message to listener. See removeListener to remove the listener.

Name Type Description
channel string

any unique string to identify the channel (must match correspond transmit channel name)

eventHandler function

function (see example below)

FSBL.Clients.RouterClient.addListener("SomeChannelName", function (error, response) {
			if (error) {
				Logger.system.log("ChannelA Error: ' + JSON.stringify(error));
			} else {
				var data =;
				Logger.system.log("ChannelA Response: ' + JSON.stringify(response));

(topic, initialState, params, callback)
clients/routerClientConstructor.js, line 1095

Add a PubSub responder for specified topic. All subscribes and publishes to the topic will comes to responder (whether from local window or another window). Only one PubSub responder allowed per topic value in Finsemble application; however, the topic value may be a regular-expression representing a set of related topics, in which case the PubSub responder will responder to all matching topics. When a regEx topic is used, the same default functionality is provides for each matching topic -- the difference is only one PubSub responder is needed to cover a set of related topics, plus the same callback handers can be used (if provided).

All the callback function are optional because each PubSub responder comes with build-in default functionality (described below).

Note an exact topic match will take precedence over a regEx match, but otherwise results are unpredictable for overlapping RegEx topics.

See subscribe and publish for corresponding functions sending to the PubSub responder.

Name Type Description
topic string

unique topic for this responder, or a topic RegEx (e.g. '/abc.+/') to handle a set of topics

initialState object optional

initial state for the topic (defaults to empty struct); can be any object

params object optional

optional parameters

Name Type Description
subscribeCallback function optional

allows responder know of incoming subscription and accept or reject it (default is to accept)

publishCallback function optional

allows responder to use the publish data to form a new state (default is the publish data becomes the new state)

unsubscribeCallback function optional

allows responder to know of the unsubscribe, but it must be accepted (the default accepts)

callback function optional

optional callback(err,res) function. If addPubSubResponder failed then err set; otherwise, res set to "success"

function subscribeCallback(error, subscribe) {
	if (subscribe) {
		// must make this callback to accept or reject the subscribe (default is to accept). First parm is err and second is the initial state
		subscribe.sendNotifyToSubscriber(null, { "NOTIFICATION-STATE": "One" });
function publishCallback(error, publish) {
	if (publish) {
		// must make this callback to send notify to all subscribers (if error parameter set then notify will not be sent)
function unsubscribeCallback(error, unsubscribe) {
	if (unsubscribe) {
		// must make this callback to acknowledge the unsubscribe
FSBL.Clients.RouterClient.addPubSubResponder("topicABC", { "State": "start" },


FSBL.Clients.RouterClient.addPubSubResponder("topicABC", { "State": "start" });


FSBL.Clients.RouterClient.addPubSubResponder(\/topicA*\/, { "State": "start" });

(channel, queryEventHandler)
clients/routerClientConstructor.js, line 958

Add a query responder to the specified channel. The responder's queryEventHander function will receive all incoming queries for the specified channel (whether from this Finsemble window or remote Finsemble windows).

Note: Only one responder is allowed per channel within the Finsemble application.

See query for sending a corresponding query-event message to this responder.

Name Type Description
channel string

any unique string to identify the channel (must match correspond query channel name); only one responder allower per channel

queryEventHandler function

function to handle the incoming query (see example below); note incoming queryMessage contains function to send response

FSBL.Clients.RouterClient.addResponder("ResponderChannelName", function (error, queryMessage) {
	if (error) {
		Logger.system.log('addResponder failed: ' + JSON.stringify(error));
	} else {
			console.log("incoming data=" +;
			var response="Back at ya"; // Responses can be objects or strings
		queryMessage.sendQueryResponse(null, response); // A QUERY RESPONSE MUST BE SENT OR THE REMOTE SIDE WILL HANG

clients/routerClientConstructor.js, line 1240

Removes all listeners, responders, and subscribers for this router client -- automatically called when client is shutting down. Can be called multiple times.

clients/routerClientConstructor.js, line 811

Checks if router is ready. May be invoked multiple times. Invokes cb when ready, which may be immediately. Router is not ready until underlying transport to router service is ready.

Name Type Description
cb function

callback function to invoke when router is ready

(topic, event)
clients/routerClientConstructor.js, line 1185

Publish to a PubSub Responder, which will trigger a corresponding Notify to be sent to all subscribers (local in this window or remote in other windows). There can be multiple publishers for a topic (again, in same window or remote windows)

See addPubSubResponder for corresponding add of a SubPub responder to handle the publish (i.e. sending notifications to all subscriber). See Subscribe for corresponding subscription to receive publish results (in the form of a notify event)

Name Type Description
topic string

topic being published to

event object

topic state to be published to all subscriber (unless the SubPub responder optionally modifies in between)

FSBL.Clients.RouterClient.publish("topicABC", topicState);

(responderChannel, queryEvent, params, responseEventHandler)
clients/routerClientConstructor.js, line 1001

Send a query to responder listening on specified channel. The responder may be in this Finsemble window or another Finsemble window.

See addResponder to add a responder to receive the query.

Name Type Description
responderChannel string

a unique string that identifies the channel (must match the channel name on which a responder is listening)

queryEvent object

event message sent to responder

params any

optional params

Name Type Default Description
timeout number 20000 optional

timeout value for a query-response timer. Timer defaults to 5000 milliseconds if no params value is passed in. Set timeout to zero to wait indefinitely. If the timer expires, this function call will return with an error.

responseEventHandler function

event handler to receive the query response (sent from a responder that is listening on this channel)

FSBL.Clients.RouterClient.query("someChannelName", {}, function (error, queryResponseMessage) {
	if (error) {
		Logger.system.log('query failed: ' + JSON.stringify(error));
	} else {
		// process income query response message
		var responseData =;
		Logger.system.log('query response: ' + JSON.stringify(queryResponseMessage));

FSBL.Clients.RouterClient.query("someChannelName", { queryKey: "abc123"}, { timeout: 1000 }, function (error, queryResponseMessage) {
	if (!error) {
		// process income query response message
		var responseData =;

(channel, eventHandler)
clients/routerClientConstructor.js, line 927

Remove event listener from specified channel for the specific event handler (only listeners created locally can be removed).

See addListener for corresponding add of a listener.

Name Type Description
channel string

unique channel name to remove listener from

eventHandler function

function used for the event handler when the listener was added

clients/routerClientConstructor.js, line 1131

Remove pubsub responder from specified topic. Only locally created responders (i.e. created in local window) can be removed.

See addPubSubResponder for corresponding add of a SubPub responder.

Name Type Description
topic string

unique topic for responder being removed (may be RegEx, but if so much be exact regEx used previously with addPubSubResponder)


clients/routerClientConstructor.js, line 1033

Remove query responder from specified channel. Only a locally added responder can be removed (i.e. a responder defined in the same component or service).

See addResponder for corresponding add of a query responder.

Name Type Description
responderChannel string

string identifying the channel to remove responder from


(topic, notifyCallback){object}
clients/routerClientConstructor.js, line 1163

Subscribe to a PubSub Responder. Each responder topic can have many subscribers (local in this window or remote in other windows). Each subscriber immediately (but asyncronouly) receives back current state in a notify; new notifys are receive for each publish sent to the same topic.

See addPubSubResponder for corresponding add of a SubPub responder to handle the subscribe. See publish for corresponding publish to notify the subscriber.

Name Type Description
topic string

topic being subscribed to

notifyCallback function

invoked for each income notify for the given topic (i.e. initial notify plus for each publish)

Type Description
object subscribe-id optionally used for unsubscribing later
var subscribeId = RouterClient.subscribe("topicABC", function(err,notify) {
		if (!err) {
			var notificationStateData =;
			// do something with notify data

(toChannel, event)
clients/routerClientConstructor.js, line 911

Transmit event to all listeners on the specified channel. If no listeners the event is discarded without error. All listeners to the channel in this Finsemble window and other Finsemble windows will receive the transmit.

See addListener to add a listener to receive the transmit.

Name Type Description
toChannel string

any unique string to identify the channel (must match correspond listener channel name)

event any

any object or primitive type to be transmitted

FSBL.Clients.RouterClient.transmit("SomeChannelName", event);

clients/routerClientConstructor.js, line 1225

Test an incoming router message to see if it originated from the same origin (e.g. a trusted source...not cross-domain). Currently same origin is known only because a sharedWorker transport is used (by definition SharedWorkers do not work cross-domain). This means any message coming in over the OpenFin IAB will not be trusted; however, by default all same-origin components and services connect to the router using a SharedWorker transport.

Name Type Description
incomingMessage object

an incoming router message (e.g. transmit, query, notification) to test to see if trusted.

Type Description
boolean true if message is same origin (i.e. received over SharedWorker transport).

clients/routerClientConstructor.js, line 1203

Unsubscribe from PubSub responder so no more notifications received (but doesn't affect other subscriptions). Only works from the window the PubSub responder was created in.

See subscribe for corresponding subscription being removed.

Name Type Description
subscribeID object

the id return from the corresponding subscribe for the topic