Widgets Bus API overview

• Developer

Learn about the bus that all widgets components are built on.

Related documentation:

• How Widgets works

Overview

Genesys Widgets is built on top of the CXBus messaging bus. CXBus uses the publish-subscribe model to facilitate communication between the Widgets components, all of which are plugins that can both publish events on the bus and subscribe to the events they are interested in.

With the help of the Widgets-Core plugins, CXBus makes it possible to combine the logic implemented by user interface plugins, service plugins, and utility plugins into cohesive products that can provide chat sessions, schedule callbacks, and so on.

Publications and subscriptions are loosely bound so that you can publish and subscribe to any event without that event explicitly being available. This allows for plugins to lazy load into the bus or provide conditional logic in your plugins so they can wait for other plugins to be available.

CXBus events and commands are executed asynchronously using deferred methods and promises. This allows for better performance and standardized Pass/Fail handling for all commands. Command promises are not resolved until the command is finished, including any nested asynchronous commands that command may invoke. This gives you assurance that the command completed successfully and the timing of your follow-up action will occur at the right time. As for permissions, CXBus provides metadata in every command call including which plugin called the command and at what time. This allows for plugins to selectively allow/deny invocation of commands.

You can use three methods to access the Bus:

• Global access
• Genesys Widgets onReady callback
• Extensions

Global access

QuickBus

window._genesys.widgets.bus
For quick access to call commands on the bus, you can access the QuickBus instance after Genesys Widgets loads. QuickBus is a CXBus plugin that is exposed globally for your convenience. Typical use cases for using QuickBus are for debugging or calling a command when a link or button is clicked. Instead of creating your own plugin, you can use QuickBus to add the click handler inline in your HTML.
Example:

<a href="#" onclick="_genesys.widgets.bus.command('WebChat.open');">Open WebChat</a>

Global CXBus

CXBus is available as a global instance named "CXBus" (or window.CXBus). Unlike QuickBus, this is not a plugin but CXBus itself.
CXBus has been updated to include a "command" method that allows you to execute a command directly from the CXBus instance.
Example:

CXBus.command("WebChat.open");

You can use this, like QuickBus, for debugging or setting up click events.

Genesys Widgets onReady callback

Genesys Widgets provides an "onReady" callback function that you can define in your configuration. This will be triggered after Genesys Widgets initializes. QuickBus is provided as an argument in this function, but you may also access CXBus globally in your function.

window._genesys.widgets.onReady = function(QuickBus){
    
    // Use the QuickBus plugin provided here to interface with the bus
    // QuickBus is analogous to window._genesys.widgets.bus
};

Extensions

You can define your own plugins/widgets that interface with Genesys Widgets. For more information, please see Genesys Widgets Extensions.

CXBus Reference

The CXBus instance is exposed globally (window.CXBus) and has several methods available:

• CXBus.command
• CXBus.configure
• CXBus.loadFile
• CXBus.loadPlugin
• CXBus.registerPlugin

CXBus.command

Calls a command on the bus under the namespace "CXBus". Use this to quickly and easily call commands without needing to generate a unique plugin interface object first.

Example

CXBus.command("WebChat.open", {});

Arguments

Name	Type	Description
Command name	string	The name of the command you wish to execute.
Command options	object	Optional: You may pass an object containing properties that the command will accept. Refer to the documentation on each command to see what options are available.

Returns

Always returns a promise. You can define done(), fail(), or always() callbacks for every command.

CXBus.configure

Allows you to change configuration options for CXBus.

Example

CXBus.configure({debug: true, pluginsPath: "/js/widgets/plugins/"});

Arguments

Name	Type	Description
Configuration options	object	An object containing properties, similar to command options. In this object you can change configuration options for CXBus.

Configuration options

Name	Type	Description
debug	boolean	Enable or disable CXBus logging in the javascript console. Set to true to enable; set to false to disable. Default value is false.
pluginsPath	string	The location of the Genesys Widgets "plugins" folder. Example: "/js/widgets/plugins/" The default value here is "". This configuration option is used for lazy loading plugin files. Be sure to configure this option when using Genesys Widgets in lazy loading mode.
pluginMap	object	Used to change the target JS file for each plugin or to add a new plugin. Example: {sendmessage: "https://www.yoursite.com/plugins/custom-sendmessage.js"} CXBus will automatically lazy load plugins defined in this object when something tries to call a command on that plugin. For instance, if SendMessage.open is called and SendMessage isn't loaded, CXBus will fetch it from the default "plugins/" folder. If you want to load a different SendMessage widget, you can override the default URL of the JS file associated with "sendmessage". You can also prevent a plugin from loading by mapping it to false. Example: {sendmessage: false} Important Any number of plugins can be included in this object. Only works when using the lazy-loading method of initializing Widgets. Not intended to be used to load different versions of Genesys Widgets plugins.

Returns

This method returns nothing.

CXBus.loadFile

Loads any javascript file.

Example

CXBus.loadFile("/js/widgets/plugins/webchat.min.js");

Arguments

Name	Type	Description
File path	string	Loads a javascript file based on the file path specified.

Returns

Always returns a promise. You can define done(), fail(), or always() callbacks. When the file loads successfully, done() will be triggered. When the file fails to load, fail() will be triggered.

CXBus.loadPlugin

Loads a plugin file from the configured "plugins" folder.

Example

CXBus.loadPlugin("webchat");

Arguments

Name	Type	Description
Plugin name	string	Loads a plugin from the "plugins" folder by name (configured by the "pluginsPath" option). Plugin names match their CXBus namespaces but are lowercase. Example: To load WebChat, use "webchat". You can refer to the files inside the "plugins" folder as well. The first part of the file name will be the name you use with this function. Example: Use "webchat" to load "webchat.min.js".

Returns

Always returns a promise. You can define done(), fail(), or always() callbacks. When the plugin loads successfully, done() will be triggered. When the plugin fails to load, fail() will be triggered.

CXBus.registerPlugin

Registers a new plugin namespace on the bus and returns a plugin interface object. You will use the plugin interface object to publish, subscribe, call commands, and perform other CXBus functions.

Example

var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");

Arguments

Name	Type	Description
CXBus plugin namespace	string	The namespace you want to reserve for your plugin.

Returns

If the namespace is not already taken, it will return a CXBus plugin interface object configured with the selected namespace. If the namespace is already taken, it will return false.

CXBus Plugin Interface Reference

When you register a plugin using CXBus.registerPlugin(), it returns a CXBus Plugin Interface Object. This object contains many methods that allow you to interact with other plugins on the bus.

Let's start with the assumption that we've created the below plugin interface:

var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");

oMyNewPlugin.registerCommand

Allows you to register a new command on the bus for other plugins to use.

Example

oMyNewPlugin.registerCommand("test", function(e){
	
	console.log("'MyNewPlugin.test' command was called", e)

	e.deferred.resolve();
});

Arguments

Name	Type	Description
Command name	string	The name you want for this command. When other plugins call your command, they must specify the namespace as well. Example: "test" is called on the bus as "MyNewPlugin.test".
Command function	function	The command function that is executed when the command is called. This function is provided an Event Object that contains metadata and any options passed in.

Event object

Name	Type	Description
time	number (integer time)	The time the command was called.
commander	string	The name of the plugin that called your command. Example: If your plugin called a command, the value would be "MyNewPlugin". You can use this information to create plugin-specific logic in your command.
command	string	The name of this command. Example: "MyNewPlugin.test". This can be useful if you are using the same function for multiple commands and need to identify which command was called.
deferred	deferred promise object	When a command is called, a promise is generated. You must resolve this promise in your command without exception. Either execute e.deferred.resolve() or e.deferred.reject(). You may pass values back through these methods. If you pass a value back inside reject() it will be printed in the console as an error log automatically.
data	object	This is the object containing command options passed in when the command was called. If no options were passed, this will default to an empty object.

Returns

Returns true.

oMyNewPlugin.registerEvents

Registering events is a formality that allows CXBus to keep a registry of all possible events. You don't need to register events before publishing them, but it's a best practice to always register events.

Example

oMyNewPlugin.registerEvents(["ready", "testEvent"]);

Arguments

Name	Type	Description
Event name array	array	An array of event names.

Returns

Returns true if at least one value event was included in the array. Returns false if no events are included in the array or no array is passed in.

oMyNewPlugin.subscribe

Subscribes your plugin to an event on the bus with a callback function. When the event is published, the callback function is executed. You can subscribe to any event, even if the event does not exist. This allows for binding events that may come in the future.

Example

oMyNewPlugin.subscribe("WebChat.opened", function(e){
	
	// e = Event Object. Contains metadata and attached data 
	//
	// Example Event Object data:
	//
	// e.time == 1532017560154
	// e.event == "WebChat.opened"
	// e.publisher == "WebChat"
});

Arguments

Name	Type	Description
Event name	string	The name of the event you want to subscribe to. Must include the plugin's namespace.
Callback function	function	A function to execute when the event is published. An Event Object is passed into this function that gives you access to metadata and attached data.

Event object

Name	Type	Description
time	number (integer time)	The time the event was published.
event	string	The name of the event, including namespace. That can be useful if you are using the same function to handle multiple events.
publisher	string	The namespace of the plugin that published the event.

Returns

Returns the name of the event back to you if the subscription was successful. Returns false if you did not specify an event and/or a callback function.

oMyNewPlugin.publish

Publishes an event on the bus under your plugin's namespace.

Example

// Publishes the event "MyNewPlugin.testEvent" with attached data {test: "123"}
oMyNewPlugin.publish("testEvent", {test: "123"});

Arguments

Name	Type	Description
Event name	string	The name of the event you want to publish. Do not include the plugin namespace.
Attached data	object	An object of arbitrary properties you can attach to your event.

Returns

Always returns true.

oMyNewPlugin.republish

A special method of publishing intended for one-off events like "ready". In some cases, an event will fire only once. If a plugin is loaded at a later time that needs to subscribe to this event, it will never get it because it will never be published again. To solve this problem, the "republish" method will automatically republish an event to new subscribers as soon as they subscribe to it.

In Genesys Widgets, every plugin publishes a "ready" event. This event is published using "republish" so that any plugin loaded and/or initialized after can still receive the event.

It is important that you only use "republish" for events that publish once. Using republish multiple times for the same event can cause unwanted behavior.

Genesys Widgets plugins all publish a "ready" event. This is not related to the CXBus plugin interface object's "ready()" method. Calling oMyNewPlugin.ready() will not publish any events.

Example

oMyNewPlugin.republish("ready", {...});

Arguments

Name	Type	Description
Event name	string	The name of the event you want to have republished. Do not include the plugin namespace.
Attached data	object	An object of arbitrary properties you can attach to your event.

Returns

Always returns true.

oMyNewPlugin.publishDirect

A slight variation on "publish", this method will only publish an event on the bus if it has subscribers. The intention of this method is to avoid spamming the logs with events that no plugins are listening to. In particular, if you have an event that publishes frequently or on an interval, "publishDirect" may be used to minimize its impact on logs in the console.

Example

oMyNewPlugin.publishDirect("poll", {...});

Arguments

Name	Type	Description
Event name	string	The name of the event you want to have republished. Do not include the plugin namespace.
Attached data	object	An object of arbitrary properties you can attach to your event.

Returns

Always returns true.

oMyNewPlugin.command

Have your plugin call a command on the bus.

Example

oMyNewPlugin.command("WebChat.open", {...}).done(function(e){

	// If command succeeds
	// e == any returned data

}).fail(function(e){
	
	// If command fails
	// e == any returned data

}).always(function(){
	
	// Always executed
});

Arguments

Name	Type	Description
Command name	string	Name of the command you wish to call.
Command options	string	Optional: An object containing properties the command will use in its execution. Refer to plugin references for a list of options available for each command.

Returns

Always returns a promise. You can define done(), fail(), or always() callbacks for every command.

oMyNewPlugin.before

Allows you to interrupt a registered command on the bus with your own "before" function. You may modify the command options before they're passed to the command, you may trigger some action before the command is executed, or you can cancel the command before it executes.

You may specify more than one "before" function for a command. If you do, they will be executed in a chain where the output of the previous function becomes the input for the next function. You cannot remove "before" functions once they have been added.

Example

oMyNewPlugin.before("WebChat.open", function(oData){

    // oData == the options passed into the command call
    // e.g. if this command is called:   oMyPlugin.command("WebChat.open", {form: {firstname: "Mike"
    // then oData will == {form: {firstname: "Mike"
    // You must return oData back, or an empty object {} for execution to continue.
    // If you return false|undefined|null or don't return anything, execution of the command will be stopped
    return oData;
});

Arguments

Name	Type	Description
Command name	string	Name of the function you want to interrupt with your "before" function.
"before" function	function	A function that accepts command options (oData in above example). If you want the command to continue executing, you must return the oData object. If you want to cancel the command, return false or undefined or don't return anything. You may modify the contents of oData before it is sent to the command. This allows you to override command options or add on dynamic options depending on external conditions.

Returns

Returns true when you pass a properly formatted command name (e.g. "PluginName.commandName"). Returns false when you pass an improperly formatted command name.

oMyNewPlugin.registry

Returns the CXBus Registry lookup table.

Example

oMyNewPlugin.registry();

Arguments

No arguments.

Returns

Returns the internal CXBus registry that tracks all plugins, their commands, and their events.
Registry Structure Example:

{
	"Plugin1": {

		commands: ["command1", "command2"],
		events: ["event1", "event2"]
	},

	"Plugin2": {

		commands: ["command1", "command2"],
		events: ["event1", "event2"]
	}
}

oMyNewPlugin.subscribers

Returns a list of events and their subscribers.

Example

oMyNewPlugin.subscribers();

Arguments

No arguments.

Returns

Returns an object identifying a list of events being subscribed to, and a list of plugin names subscribed to each event.

Example of WebChatService's subscribers:

// Format  {"eventname": ["subscriber1", "subscriber2"]}

{
	"WebChatService.agentConnected":["WebChat"],
	"WebChatService.agentDisconnected":["WebChat"],
	"WebChatService.ready":[],
	"WebChatService.started":["WebChat"],
	"WebChatService.restored":["WebChat"],
	"WebChatService.clientDisconnected":[],
	"WebChatService.clientConnected":[],
	"WebChatService.messageReceived":["WebChat"],
	"WebChatService.error":["WebChat"],
	"WebChatService.restoreTimeout":["WebChat"],
	"WebChatService.restoreFailed":["WebChat"],
	"WebChatService.ended":["WebChat"],
	"WebChatService.agentTypingStarted":["WebChat"],
	"WebChatService.agentTypingStopped":["WebChat"],
	"WebChatService.restoredOffline":["WebChat"],
	"WebChatService.chatServerWentOffline":["WebChat"],
	"WebChatService.chatServerBackOnline":["WebChat"],
	"WebChatService.disconnected":["WebChat"],
	"WebChatService.reconnected":["WebChat"]
}

oMyNewPlugin.namespace

Returns your plugin's namespace.

Example

oMyNewPlugin.namespace();

Arguments

No arguments.

Returns

Returns your plugin's namespace. If your plugin's namespace is "MyNewPlugin", it will return "MyNewPlugin".

oMyNewPlugin.ready

Marks your plugin as ready to have its commands called. This method is required to be called for all plugins. You should call this method after all your commands are registered, initialization code is finished, and configuration has completed. Failure to call this method will result in your commands being unexecutable.

Example

oMyNewPlugin.ready();

Arguments

No arguments.

Returns

Returns nothing.