How to ... Install the Node Component

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

• Cisco Unified Communications Manager 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:

• hello: replies 'hello' to clients, mainly used for testing
• phoneconfig: authenticates Cisco Unified Communications Manager end users, retrieves list of users' phone devices, downloads phone device configuration
• quickcontact: integrates with a directory to search for contacts

Installation

node.csf is based on node.js version 0.6.x
node.csf is currently working on  Unix-based OSes. It was tested on Linux and Mac OS X.

Step 1

Install the latest node.js version 0.6 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, execute the command "node -v". This displays the version of node.js.

node -v
v0.6.11

Step 2

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

To test that npm was installed successfully, execute the command "npm -v". This displays the version of npm.

npm -v
1.0.105

Step 3

Installing the csf package requires the machine to be connected to the Internet temporarily as it fetches extra dependencies from the public npm repository. The csf-x.y.x-rev.tgz is included in CiscoJabberSDK.zip downloadable from the getting started page.

The installation builds a native component automatically, which requires the gcc compiler to be available.
Try "gcc -v" from the command line. If not installed yet, refer to the OS documentation about installing compilers.
Some Linux distributions have build packages ready to be installed, like the "build-essential" one on Ubuntu.

Execute the command "npm install csf-x.y.z-rev.tgz".

$ npm install csf-1.0.4-19288.tgz

If the machine is behind a proxy, use the --proxy option, for example

$ npm --proxy http://myproxy.com:8080 install csf-1.0.4-19288.tgz

To test whether node.csf is installed, execute the command

$ node node_modules/csf/csf.js

This causes a server to start to listen on port 1789 (default). Open http://localhost:1789/hello in a web browser. node.csf replies. Alternatively, use a command-line tool such as curl:

$ curl -X GET http://localhost:1789/hello

$ curl -X POST http://localhost:1789/hello -d "test"

Configuration

node.csf can be configured using a text file that contains JSON. The main options are:

• listening port (http or https)
• the execution environment: "production" (recommended), "beta" (dump exceptions with stack trace) or "development" (same as beta with more logs)
• some directories to be server statically (array of relative or absolute paths)

Cross-domain access CORS (Cross Origin Resource Sharing) is enabled by adding a "cors" property to the configuration file.
The value is a JSON object passed to the connect-xcors module (empty object for default options).

node.csf also supports JSONP (JSON with Padding), which provides another way of accessing cross-domain.
This can be used with jQuery.ajax for example, setting "dataType" to "jsonp".
node.csf replies to a JSONP request by sending an object which can have either an "error" property indicating a failure, or a "data" one containing the requested data.

Secure http (HTTPS) can be enabled by adding a "https" property to the configuration file.
The value is a JSON object with 3 properties: enabled (true or false), key and certificate.
A sample key and self-signed certificates are provided under the config directory. They were generated as explained here.

node.csf loads applicative 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).

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

{
  "port": 1789,
  "env": "production",
  "staticDirs": [],
  "cors": {},
  "https": {
    "enabled": false,
    "key": "node_modules/csf/config/csf-key.pem",
    "cert": "node_modules/csf/config/csf-cert-self.pem"
  },
  "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 the following command:

$ node node_modules/csf/csf.js

To specify a configuration, enter a command similar to the following:

$ node node_modules/csf/csf.js myconfigfile.cfg

To run node.csf in the background, use nohup. For example:

$ nohup node node_modules/csf/csf.js myconfigfile.cfg > node.out 2> node.err < /dev/null &

You can also use the forever utility.

Modules

Hello

The Hello module is mainly used for testing. It replies 'hello' to any received request. Hello is always loaded, even if not listed in the configuration modules. Hello exposes 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 Cisco Unified Communications Manager to provide phone configuration to the Cisco Jabber Software Development Kit (SDK). PhoneConfig exposes the following API:

GET /phoneconfig/devices?ccmcip={ccmcip}

Authenticates (HTTP Basic) end user against Cisco Unified Communications Manager 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.
• uses ldapjs to connect to the directory

The QuickContact module must be configured with:

• the LDAP server address
• the LDAP principal credentials (readonly is acceptable)
• 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"

QuickContact exposes the following API:

GET /quickcontact/name/{name}?max={max}&photo={photo}

Searches contacts whose screen, first, last and display name starts with {name}.
{max} is the maximum number of contacts to return. 0 means unlimited (default), absolute max is 20.
If {photo} equals "yes", each result includes a photosrc property.
Returns an array (possibly empty) of contact objects.

GET /quickcontact/email/{email}?max={max}&photo={photo}

Searches contacts whose email address starts with {email}.
{max} is the maximum number of contacts to return. 0 means unlimited (default), absolute max is 20.
If {photo} equals "yes", each result includes a photosrc property.
Returns an array (possibly empty) of contact objects.

GET /quickcontact/phoneNumber/{phoneNumber}?cc={cc}&max={max}&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).
{max} is the maximum number of contacts to return. 0 means unlimited (default), absolute max is 20.
If {photo} equals "yes", each result includes a photosrc property.
Returns an array (possibly empty) of contact objects.
Note: search by phone number is not fully implemented/optimized yet, and can result in large requests on the directory (LDAP) server itself.
{phoneNumber} should contain as many digits as possible to narrow the search down to less contacts.