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 = ; // Initialize the communication object with the SOAP-API URL var comm = url: "https://your-zimbra-server/service/soap" ; // Authenticate comm
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
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 = ; // Initialize the communication object with the SOAP-API URL var comm = url: "https://your-zimbra-server/service/soap" ; // Authenticate comm
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 = url: "https://your-zimbra-server/service/soap"; comm;
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 = ; winstonloggers;
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.