Search Engine: Elastic

Article ID: 3339, created on Nov 30, 2007, last review on May 10, 2014

  • Applies to:
  • H-Sphere


H-Sphere XML API is designed to manage H-Sphere services via SOAP protocol. It is based on Apache Axis implementation of SOAP and runs under Apache Tomcat engine.

You can download Axis libraries and the latest version of H-Sphere Axis-based Web services from PSoft site.

H-Sphere XML API is an experimental feature. Please be careful in using it for critical tasks!


Enabling XML API

To enable XML API in H-Sphere:

  1. Log into the CP server as the cpanel user.

  2. H-Sphere 2.4.3 Patch 11 and up: Edit the ~cpanel/shiva/psoft_config/ file to grant access to CP server via SOAP port from external IPs.

    If the file does not exist, SOAP access is blocked for all IPs.

    [-] SOAP access in earlier H-Sphere versions

    Important: In H-Sphere before 2.4.3 Patch 11 SOAP access to CP server via standard 8080 port was provided by default.
    The following procedure explains how to configure SOAP access via port 8180 and should not be performed in H-Sphere 2.4.3 Patch 11 and up!

    1. Copy the wsdd config file:
      cp ~cpanel/shiva/psoft/hsphere/axis/server-config.wsdd ~cpanel/hsphere/WEB-INF/
      Skip this step if the file is already in the target location.
    2. Edit the Tomcat XML configuration file:
      vi ~cpanel/jakarta/conf/server.xml
    3. Find the following commented fragment:
      <!--Connector port="8080"
                  maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                  enableLookups="false" redirectPort="8443" acceptCount="100"
                  debug="0" connectionTimeout="20000"
                  disableUploadTimeout="true" /-->
      and replace it with the following code:
      <Connector port="8180"
              maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
              enableLookups="false" acceptCount="100"
              debug="0" connectionTimeout="20000"
              disableUploadTimeout="true" />
      Optionally, leave the port at 8080.
  3. Restart H-Sphere.

After that, XML API will be available. You may wish to test if it works correctly by means of our test Java classes that use H-Sphere XML API.


Testing HS XML API

  1. Make sure you are logged into the CP server as the cpanel user.
  2. Download the latest version of test Java classes from PSoft site to the ~cpanel/shiva/psoft/hsphere/axis/test directory (create it first if it does not exist):
    cd ~cpanel/shiva/psoft/hsphere/axis/test/
  3. Extract the archive with the command:
    tar zxf AxisExamples.tgz
    Java source .java files will be added into the current ~cpanel/shiva/psoft/hsphere/axis/test/ directory.

  4. Edit the necessary test classes (at least replacing URL in the folowing line:
    String endpoint = "http://localhost:8080/psoft/servlet/AdminServices.jws";
    with your URL:
    String endpoint = "http://your_cp_host:8180/your_cp_url_path/AdminServices.jws";
    where your_cp_url_path is by default psoft/servlet but you may change it in your Tomcat configuration.
    If you have enabled XML API with port 8180, make sure it is specified in the URL.

  5. Compile Java classes:
    cd ~cpanel/shiva/psoft/hsphere/axis/test/
    javac *.java
  6. Upon the successful compilation, run the following command:
    java psoft.hsphere.axis.test.AdminServicesTest admin <hs_admin_password>
  7. You will see the > prompt. Here, enter the line:
    searchbydomainname domain-name
    where domain-name is a customer's domain name.
  8. On the next > invitation, press Enter to force the service to run.
  9. Repeat the previous two steps testing other services, for instance getAccounts, getDomains, searchbydomainname, etc:
    [cpanel@exampleuser test]$ java psoft.hsphere.axis.test.AdminServicesTest admin admin

    no domains
    See H-Sphere XML API Reference in HTML or PDF format to learn how to invoke other Web services via XML interface.
  10. Press CTRL-D to stop.


Getting the List of Available Services

You may get the list of available XML services by typing in your browser:

your_cp_host   is your CP host domain (CP_HOST in, and
your_cp_url_path   is usually psoft/servlet if not configured otherwise in your Tomcat configuration.

If this doesn't work, check servlet mapping in your Tomcat configuration:

  1. As the cpanel user, open the ~cpanel/hsphere/WEB-INF/web.xml file for edition:
    vi ~cpanel/shiva/psoft/hsphere/WEB-INF/web.xml
  2. Make sure the following lines are present in the file:
    <display-name>Apache-Axis Servlet</display-name>
  3. Find the following mapping block:
    and add the following lines right underneath:
  4. Restart H-Sphere

  5. Try again this URL in your browser:

You may also wish to test AxisTestServlet from the package of test Java classes:



Generating WSDL

You can generate WSDL files for H-Sphere XML API services by means of the Axis' org.apache.axis.wsdl.Java2WSDL utility.

For example, to generate a WSDL file for SupportServices, log into CP server as cpanel and run:

java org.apache.axis.wsdl.Java2WSDL -o SupportService.wsdl -l"http://localhost:8080/psoft/servlet/AxisServlet" psoft.hsphere.axis.SupportServices

Example: H-Sphere XML API signup form implementation in PHP 5 (SOAP client embedded) via WSDL.

f213b9fa8759d57bee5d547445806fe7 3ef1f5f998c0dc182718a7fe4376f875

Email subscription for changes to this article
Save as PDF