This document explains how to install the Cisco Jabber SDK node component (referred as node.csf).
node.csf is an optional server-side component which brings advanced features to clients:

• CUCM end user authentication
• phone device configuration retrieval
• directory integration

node.csf exposes an HTTP REST API, and the reference implementation is based on Node.js.

node.csf is made of independent modules. The reference implementation contains 3 modules by default:

• hello: replies 'hello' to clients, mainly used for testing
• phoneconfig: authenticates CUCM end user, retrieve user's phone devices list, download phone device configuration
• quickcontact: integrates with a directory to search for contacts

Installation #

node.csf is based on node.js version 0.4.
node.csf is currently working on 32-bit Unix-based OSes, it was tested on Linux and Mac OS X.

Step 1 #

Install the latest node.js version 0.4 on a 32-bit Unix-based OS. Some Linux distributions have binary packages ("nodejs"), or the source code can be downloaded and built directly. See http://nodejs.org/#download

To test node.js, enter in a terminal "node -v", this should display the version of node.js.

Step 2 #

node.js has a package manager called "npm" (node package manager). node.csf is provided as an npm package.
Install npm, see instructions on http://npmjs.org

To test npm was successfully installer, enter in a terminal "npm -v", this should display the version of npm.

Step 3 #

Installing the "csf.npm" package requires the machine to be (temporarily) connected to the Internet as it grabs extra dependencies from the public npm repository.

Enter in a terminal "npm install csf-version-revision.tgz".
Example: "npm install csf-1.0.4-19288.tgz"
If the machine is behind a proxy, use the --proxy option of npm, for example
"npm --proxy http://myproxy.com:8080 install csf-1.0.4-19288.tgz"

To test node.csf is installed, enter "node csf.js", this should start a server listening on port 1789 (default).Open in a web browser http://localhost:1789/hello, node.csf should reply.Alternatively, use a command-line tool such as curl:curl -X GET http://localhost:1789/hellocurl -X POST http://localhost:1789/hello -d "test"

Configuration #

node.csf can be configured via a text file containing JSON.
node.csf loads modules specified in the "modules" map of the configuration file.
Each module is configured using either a JSON object (which can be empty),
or a string referring to an extra configuration file, specific to the module
(absolute path or relative to the main configuration file path).

Template of configuration file for node.csf included in the package, under node_modules/csf/config/node.csf.cfg

{
  "port": 1789,
  "env": "production",
  "staticDirs": [],
  "modules": {
  	"hello": {},
  	"phoneconfig": {},
  	"quickcontact": {
		"ldap": {
			"host": "",
			"port": 389,
			"credentials": {
				"user":"",
				"password":""
			},
			"treebase": "",
			"mapping": {
				"screenName":"",
				"firstName": "",
				"lastName": "",
				"displayName": "",
				"email": "",
				"jabberId": "",
				"phoneNumbers":{
					"work": "",
					"mobile": ""
				},
				"photosrc": ""
			}
		}
  	}
  }
}

Running #

To start node.csf with the default configuration, change to the installation directory and enter
node node_modules/csf/csf.js
To specify a configuration, enter for example
node node_modules/csf/csf.js myconfigfile.cfg

To run node.csf in the background, use nohup
nohup node node_modules/csf/csf.js myconfigfile.cfg > node.out 2> node.err < /dev/null &

Another possibility is to use the forever utility,
see http://blog.nodejitsu.com/keep-a-nodejs-server-up-with-forever

MODULES #

Hello #

The Hello module is mainly used for testing. It replies 'hello' to any received request.
Hello supports the following API:

GET /hello
replies "Hello" with current date and time

POST /hello
replies with "Hello {post data}"

PhoneConfig #

The PhoneConfig module interacts with CUCM to provide phone configuration to the Cisco Web Communicator (CWC).

GET /phoneconfig/devices?ccmcip={ccmcip}
authenticates (HTTP Basic) end user against CUCM with address {ccmcip}
returns a JSON array with all phone devices associated to the user. Each device is a JSON object with the properties

• name: device name (String)
• model: device model (String)
• description: device description (String)

GET /phoneconfig/device/user/{user}/client/cwc?tftp={tftp}
returns the phone device configuration (XML) associated to user {user} and client type "cwc".
configuration is a JSON object with the properties

• name: device name (String)
• tftp: the successful TFTP address (String)
• configuration: a String containing the XML <device>...</device>

QuickContact #

The QuickContact module:

• integrates with a directory to provide contact information to clients.
• currently supports LDAP to search for a directory.
• relies on a native binding to OpenLDAP to communicate with the LDAP server
• requires the OpenLDAP library to be available on the server

The QuickContact module must be configured with:

• the ldap server address
• the ldap principal credentials (readonly is fine)
• the search tree base
• the attributes mapping

The photosrc can contain the {screenName} pattern to be replaced with the screenName value, for example:
"photosrc": "http://mydirectory.com/photo/{screenName}.jpg"

GET /quickcontact/name/{name}?photo={photo}
searches contacts whose screen, first, last and display name starts with {name}
returns an arrays of contact objects

GET /quickcontact/email/{email}?photo={photo}
searches contacts whose email address starts with {email}
returns an array (possibly empty) of contact objects

GET /quickcontact/phoneNumber/{phoneNumber}?cc={cc}&photo={photo}
searches contacts whose phone number starts with {phoneNumber} (sequence of digits)
if {cc} equals "yes", {phoneNumber} starts with a country code (false by default)
returns an array (possibly empty) of contact objects