Jabber SDK IM and Presence (CAXL) FAQ

[npetrele]

General Questions

• What types of applications is the SDK library set well suited for?
• What types of capabilities are supported?
• What capabilities are supported in the core IM and Presence libraries?
• What XMPP capabilities are NOT supported in the core IM and Presence libraries?
• What capabilities are included in the UI wrapper?
• What browsers are supported?
• Where can I find more information about XMPP?
• Now that I have the AJAX library, what can I connect to?

Common Problems

• Why can't I connect or log in with Chrome?
• Is there another reason why I can't connect or log in?

CAXL Programming Questions

• What is an entity set and how do I use it?
• How can I prevent users from getting logged out from a page refresh?

General Answers

Q. What types of applications make the best use of the library?

The library makes it easy to embed presence and messaging into web-based portals or web-based applications.

Back to top

Q. What capabilities does the library support?

Jabber SDK (CAXL) for IM and Presense has multiple Javascript libraries libraries:

• A Javascript library for standard IM and Presence capabilities
• An optional Javascript library for Cisco-added features to standard IM and Presence
• An optional graphical UI library wrapper.  You do not have to use this UI library in order to make use of the IM and Presence capabilities.

If you intend to integrate Jabber IM and Presence capabilities in a web application based on your own UI or a 3rd party UI library, then you can simply include the core CAXL library something like this, where "path" is the path to the Javascript libraries:  <script type="text/javascript" src="path/jabberwerx.js"></script>

You can also include this library if you want to use Cisco-specific extensions to Jabber messaging, such as LDAP directory group handling and quick contact temporary rosters:  <script type='text/javascript' src='path/jabberwerx.cisco.js'></script>

If you intend to use the built-in UI functions, then include this library, too:  <script type='text/javascript' src='path/jabberwerx.ui.js'></script>


Back to top

Q. What capabilities are supported in the core IM and Presence libraries?

Please refer to the main CAXL library reference.  Two of the most frequently used references from that page are SDK classes and methods and the documentation of events.The reference includes links to some samples, but you can also find more sample code in the /doc/examples directory when you install the SDK.In short, the capabilities include:

• All the basic XMPP features for contacts, groups, sending and receiving messages and presence status
• An Entity Set, which is a collection of objects where you can find information about various entities like groups, contacts, multi-user rooms, etc.
• XMPP events (such as presenceReceived, clientConnected, entityUpdated, chatReceived, etc.) you can bind to functions
• There is a Quick Contacts non-standard extension to XMPP that lets you add contacts to a temporary roster that exists only for the current session
• There is a Cisco extension for LDAP-synchronized users
• There are Cisco extensions high availability

Back to top

Q. What XMPP capabilities are NOT supported in the core IM and Presence libraries?

Some features not supported:

• Message Carbons (two or more active clients show full conversations simultaneously)
  • Standard XMPP conversations begin when you reply to an incoming message, after which the rest of the conversation takes place only in that same client.
• Multi-user chat rooms when connected to Cisco webexconnect Jabber, used internally by Cisco

Back to top

Q. What capabilities are included in the UI wrapper?

There are a number of standard IM and Presence UI features

• Initiate 1:1 chat
• Initiate/join group chat
  • Cisco IM&P Servers (CUPS) supported
  • Webexconnect group chat not supported
• Contact List
  • Ability to add/remove contacts
  • Groups support (not nested)
    • Ability to add/remove/collapse/rename
  • Show basic presence with icon
    • See custom presence text
• Chat emoticons
• Subscription handling
• Robust error handling and reconnect on error
• Other UI Support
  • Independently working contact list and chat panes (dockable)
  • Tabbed UI for one-to-one and group chats
  • Login screen

Back to top

Q. What browsers are supported?

Current List of JabberWerxAJAX supported and tested OS/Browser combinations:

Windows

• Chrome
• Firefox
• Internet Explorer 8
• Internet Explorer 9
• Latest Internet Explorer

When configured to use CORS an additional requirement exists. Internet Explorer requires the http binding URL must be targeted to the same scheme as the hosting page. This means that if your AJAX page is at http://example.com, then your httpBindingURL must also begin with HTTP. Similarly, if your AJAX page is at https://example.com, then your httpBindingURL must also begin with HTTPS. This restriction is for IE only and is resolved in IE 10. Internet Explorer versions 8 and 9 are explicitly tested and documented. IE 10 and later are standards compliant and will be treated like Chrome and Firefox where only the latest versions are regression tested.

Mac OS X

• Chrome
• Firefox
• Safari

Linux

• Chrome
• Firefox

Versions of the Browsers and OS should be the latest, with all service packs and updates installed.

Back to top

Q. Where can I find more information about XMPP?

Please visit: http://xmpp.org/

Back to top

Q. Now that I have the AJAX library, what can I connect to?

Contact your Cisco WebEx representative. They can assist you with getting access to a development and test environment.

Back to top

Answers for Common Problems

Q. Why can't I connect or log in with Chrome?

When you have a relentless connection problem on Chrome when using a secure connection (https), it is most likely due to the way Chrome handles security certificates.

There's an easy way to test to see if this is what is preventing you from connecting.

Assuming you are using a secure connection, navigate directly to the BOSH URL in your browser, for example (where "yourdomain.com" points to your Cisco IM&P server):

  https://yourdomain.com:7335/httpbinding

If you see the "Your connection is not private" page, that's why you can't connect.  Chrome isn't accepting your server's certificate.  If you click on "ADVANCED" and then proceed to your domain, that will solve the problem and you'll now be able to connect once you go back to your Jabber-enabled web page. 

On Chrome, this only solves the problem for the current session.  If you want to solve it permanently, you'll have to add the certificate to Chrome's certificate store.  Firefox makes it easy to add a permanent exception.  It gives you a choice the first time you bump into a certificate it doesn't want to accept. Chrome does not offer an immediate method to do this and the process to do it is fairly arcane and seems to change often depending on the type of certificate you want to add. It is not within the scope of thie FAQ to explore the various ways to add the certificate to Chrome.

Back to top

Q. Is there another reason why I can't connect or log in?

If you have eliminated the certificate as the problem (as well as obvious issues like using the wrong username or password), you may be using an invalid BOSH URL. A typical BOSH URL should look like this (change https to http if you're not using a secure web connection), where "yourdomain.com" points to your Cisco IM&P server.  https://yourdomain.com:7335/httpbinding There's an easy way to test the validity of your BOSH URL.  Simply enter it into the URL field of your browser and browse directly to the URL.  If it is working, you should see something like this:

This URI is for XMPP communication via the BOSH protocol.Please reference the following protocols:

• RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core
• RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence
• XEP-0124: Bidirectional-streams Over Synchronous HTTP (BOSH)
• XEP-0206: XMPP Over BOSH

If that's not what you see, then either something is wrong with your BOSH URL or something is misconfigured at the Cisco IM&P server.Also, your URL may be mostly correct, but may not match you Cisco IM&P Server web client security setting.Log into your Cisco IM&P server and select System->Security->Settings  from the menu.If you have Enable Web Client to IM/P Service Secure Mode checked, then you should use https in your BOSH URL.  If it is not checked, then use http.

Back to top

CAXL Programming Answers

Q. What is an entity set and how do I use it?

The entitySet in the SDK is a collection of objects that stores a wealth of information. There are various ways to use it.  For example, there's a simple method to get all the groups in the roster for the currently logged in user.  var groups = _app.client.entitySet.getAllGroups();
You can also iterate through the entitySet and examine each entity in order to fetch information. For example, you can find the displayName for a particular contact via that contact's JID, represented here by "somejid".  var displayName;
  _app.client.entitySet.each(function(entity) {
    if (entity instanceof jabberwerx.RosterContact && (entity.jid == somejid)) {
      displayName = entity.getDisplayName();
    }
  });


Back to top

Q. How can I prevent users from getting logged out from a page refresh?

There are a number of ways to accomplish this. Check out this example from a directory in your SDK files for one way to do it:

  /doc/examples/persistchatdemo.html

See also the Class jabberwerx.JWApp, which handles persistence by default if you build your application based on this class.

Or you can examine the code below as a different model for handling persistence.

In this example, we define the application by extending the JWModel.  When the browser storage engine is ready, it will try to load the application.  But since you haven't created an application or logged in yet, it will fail. It will then create the application and take you to a login screen. 

Now that you're connected to the server and logged in, when you refresh the page, it will save the application state with a tag you can use to reload it later.  The tag in this example is "app-data-8".  When it goes through the load process this time, it will find the application in local storage, and load it using that tag.

Notice that this time it will go to the _refresh function (not shown here), which checks to see if you're already connected. If so, it bypasses the login screen and just refreshes everything in the UI. Otherwise, it will invalidate the app, remove it from local storage, and present you with a new login screen.

This sample code is meant only to serve as a rough teaching model. We're working on a moderately complete sample Jabber IM client, which includes this capability. We will post that sample here when it is ready for general consumption.

One of the key takaway lessons in the code below is that you should put all the variables, objects and functions that your application has to "remember" where the // comment indicates to do this. That's how you store critical information along with your app.

Also, if you're going to build an application with persistence, you should bind events with invocations of functions included in the application that is put in browser storage (saveGraph). You don't need to use invocation if you aren't building an app with persistence.

  var _app = null;
  var JWA = {};

  $(document).ready( function () {

    _save = function () {
      try {
        jabberwerx.util.saveGraph(_app, "app-data-8");
      } catch (e) {
        log("window", "saving failed: " + e.message);
      }
    };

    _load = function () {
      _app = jabberwerx.util.loadGraph("app-data-8");
      if (!_app) {
        _app = new JWA.Application();
        _app._login();
      } else {
        _app._refresh();
      }
      _app._updateState();
    };

    jabberwerx.$(window).bind("unload", function () {
      _save();
    });

  });

  JWA.Application = jabberwerx.JWModel.extend({

    // put all the vars and functions that the application must remember after a refresh here

    init: function() {

      this.client.event("clientConnected").bind(this.invocation('_onClientConnected'));

      ... etc ...
    },

    _onClientConnected: function() { ...etc...

  }, "JWA.Application");

  jabberwerx.$.jStore.ready(function(engine) {
    engine.ready(function() {
      _load();
    });
  });


Back to top