ZCS 6.0:Zimlet Developers Guide:Examples:SOAP API Basics

Introduction

Getting Started

Dev Environment Setup

Developing Zimlets

Advanced Concepts

API Specifications

Example Zimlets

Article Information
This article applies to the following ZCS versions. ZCS 8.0 ZCS 7.0 ZCS 6.0

Description

This zimlet shows the basics for calling the Zimbra SOAP API from a zimlet. The zimlet shows calling the <GetAccountInfoRequest> SOAP command using the XML format and the JSON format.

Definition File

<zimlet name="com_zimbra_example_soap" version="1.0" description="Example SOAP request/response">
  <include>com_zimbra_example_soap.js</include>
  <handlerObject>com_zimbra_example_soap_HandlerObject</handlerObject>
  <zimletPanelItem label="Example SOAP Request/Response" icon="zimbraIcon">
  <toolTipText>Right-click for menu options</toolTipText>
    <contextMenu>
      <menuItem label="Submit SOAP Request (XML)" icon="zimbraIcon" id="menuId_soap_request_xml"/>
      <menuItem label="Submit SOAP Request (JSON)" icon="zimbraIcon" id="menuId_soap_request_json"/>
    </contextMenu>
  </zimletPanelItem>
</zimlet>

Handler Object

This code snippet from the Zimlet Handler Object shows creating the SOAP request (in XML format) and submitting that request asynchronously to the server. The callback method is called when the response returns.

/**
 * Submits a SOAP request in XML format.
 * 
 * <GetAccountInfoRequest xmlns="urn:zimbraAccount">
 *     <account by="name">user1</account>
 * </GetAccountInfoRequest>
 *
 * @private
 */
com_zimbra_example_soap_HandlerObject.prototype._submitSOAPRequestXML =
function() {
		
    var soapDoc = AjxSoapDoc.create("GetAccountInfoRequest", "urn:zimbraAccount");

    var accountNode = soapDoc.set("account", appCtxt.getUsername());
    accountNode.setAttribute("by", "name");
	
    var params = {
		soapDoc: soapDoc,
		asyncMode: true,
		callback: (new AjxCallback(this, this._handleSOAPResponseXML)),
		errorCallback: (new AjxCallback(this, this._handleSOAPErrorResponseXML))
		};

    appCtxt.getAppController().sendRequest(params);
};

This code snippet from the Zimlet Handler Object shows creating the SOAP request (in JSON format) and submitting that request asynchronously. The callback method is called when the response returns.

/**
 * Submits a SOAP request in JSON format.
 * 
 * 
 * GetAccountInfoRequest: {
 *   _jsns: "urn:zimbraAccount",
 *   account: {
 *     _content: "user1",
 *     by: "name"
 *    }
 * }
 *
 * @private
 */
com_zimbra_example_soap_HandlerObject.prototype._submitSOAPRequestJSON =
function() {

    var jsonObj = {GetAccountInfoRequest:{_jsns:"urn:zimbraAccount"}};
    var	request = jsonObj.GetAccountInfoRequest;
    request.account = {_content: appCtxt.getUsername(), by: "name"};
	
    var params = {
		jsonObj:jsonObj,
		asyncMode:true,
		callback: (new AjxCallback(this, this._handleSOAPResponseJSON)),
		errorCallback: (new AjxCallback(this, this._handleSOAPErrorResponseJSON))
	};
	
    return appCtxt.getAppController().sendRequest(params);
};

This section of code shows reading information from the SOAP result and response.

/**
 * Handles the SOAP response.
 * 
 * @param	{ZmCsfeResult}		result		the result
 * @private
 */
com_zimbra_example_soap_HandlerObject.prototype._handleSOAPResponseXML =
function(result) {

    if (result.isException()) {
	// do something with exception
	var exception = result.getException();		
	return;
    }
	
    // do something with response (in JSON format)
    var response = result.getResponse().GetAccountInfoResponse;

    var name = response.name;
    var soapURL = response.publicURL;
    var soapURL = response.soapURL;
    var zimbraId = result.getResponse().GetAccountInfoResponse._attrs.zimbraId;
    var zimbraMailHost = result.getResponse().GetAccountInfoResponse._attrs.zimbraMailHost;

    appCtxt.setStatusMsg("GetAccountInfoResponse (XML) success - "+name);	
};

Download

Zimlet Package

com_zimbra_example_soap.zip

Useful Links

• Zimlet Definition File Reference