js-zimbra

Javascript library to easily access Zimbra's SOAP API. Handles authentication using password auth or preauth keys, request sending, response interpreting and batch processing.

This is basically a JS-port of the Python-Zimbra library, but does a few things differently.

The main difference is, that only JSON-based requests are supported, no XML. The whole library is asynchronous and based on callbacks.

For details, please see the official API documentation.

Getting Started

Install the module with: npm install js-zimbra

Afterwards you can use the library by requiring it:

var jszimbra = require('js-zimbra');

Authentication handling

To authenticate against a Zimbra server, use the "auth" method of the communication API like this:

var jszimbra = require('js-zimbra');

// Initialize the communication object with the SOAP-API URL

var comm = new jszimbra.Communication({
    url: "https://your-zimbra-server/service/soap"
    });
    
// Authenticate
    
comm.auth({
    "username": "zimbrauser",
    "secret": "fowunfguipht542uip5nupfnru2ütu3ü2brtufwe"
}, function (err) {

    if (err) {
    
        // An error occured authenticating!
    
    }
    
    // Now, carry on creating requests and sending them
};

In this example, a Preauthkey was used. If you'd like to use a password instead, you can do this by setting the option "isPassword" in the options object passed to the auth-method to true:

comm.auth({
    "username": "zimbrauser",
    "secret": "verysecretpassword",
    "isPassword": true
},(...)

If you're authenticating against the Zimbra Admin backend, you have to set the option "isAdmin" to true. Currently, Zimbra only supports password-based authentication for the administration backend, so the option "secret" has to be the password of an administrator. "isAdmin" implies "isPassword", so you don't have to set that as well.

Request/Response handling

Like in the python version of this library, requests are built inside a "request handler". You can get one by using the "getRequest"-method of the communications api.

Afterwards, you can add one or multiple (see BatchRequest-handling) requests. Finally, supply the built-up request handler to the "send"-method of the communications api and you'll retrieve a "response handler".

This handler has a "get"-method that returns the Zimbra response for your request as a plain javascript object.

Here's an example for the workflow:

var jszimbra = require('js-zimbra');

// Initialize the communication object with the SOAP-API URL

var comm = new jszimbra.Communication({
    url: "https://your-zimbra-server/service/soap"
    });
    
// Authenticate
    
comm.auth({
    "username": "zimbrauser",
    "secret": "fowunfguipht542uip5nupfnru2ütu3ü2brtufwe"
}, function (err) {

    if (err) {
    
        // An error occured authenticating!
    
    }
    
    comm.getRequest({}, function (err, req) {
    
        if (err) {
        
            // Can't create a new request
        
        }
        
        req.addRequest({
            name: "GetAccountInfoRequest",
            namespace: "zimbraAccount",
            params: {
                "account": {
                    "by": "name",
                    "_content": "[email protected]"
                }
            }, function (err) {
            
            if (err) {
            
                // Can not add request to the request handler
            
            }
            
            comm.send(req, function (err, response) {
            
                if (err) {
                
                    // Can not send request
                
                }
                
                // response holds our response
                
                console.log(response.get().GetAccountInfoResponse);
            
            });
            
        });
    
    });

});

Batch Requests

js-zimbra also supports batch requests. This has to be enabled in the getRequest-method by setting the option "isBatch" to true. Afterwards, subsequent calls to request#addRequest will add requests to this batch and return the request id to the callback.

var comm = new jszimbra.Communication({
    url: "https://your-zimbra-server/service/soap"
});

comm.auth({
    "username": "zimbrauser",
    "secret": "fowunfguipht542uip5nupfnru2ütu3ü2brtufwe"
}}, function (err) {

        comm.getRequest({
            isBatch: true
        }, function (err, req) {

            req.addRequest({
                name: "GetAccountInfoRequest",
                namespace: "zimbraAccount",
                params: {
                    "account": {
                        "by": "name",
                        "_content": "zimbraid"
                    }
                }
            }, function (err, reqid) {
            
                // reqid holds the id of the added request and can be used to
                // identify the request in the response

                req.addRequest({
                    name: "GetAccountInfoRequest",
                    namespace: "zimbraAccount",
                    params: {
                        "account": {
                            "by": "name",
                            "_content": "zimbraid"
                        }
                    }
                }, function (err, reqid) {

                    comm.send(req, function (err, response) {
                    
                        // Shows an array with two members

                        console.log(response.GetAccountInfoRequest);                        

                    });

                });

            });

        });

        done();

    }
);

Logging

js-zimbra uses the excellent Winston framework for logging. To make it easier to configure js-zimbra-specific logging, we use our own logger called "js-zimbra".

You can configure the logger by issuing something like the following commands before requiring the js-zimbra library:

// Set js-zimbra's maximum log level to "error" to mostly silence it.

var winston = require('winston');

winston.loggers.add("js-zimbra", {console: {level: "error"}});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using

grunt

You may also (and are suggested to) check the code coverage of your new or changed code by running

grunt coverage

License

Copyright (c) 2015 Dennis Ploeger
Licensed under the MIT license.