Online Chat
 Call Us: 
1-877-744-1221
Browse Submit a Ticket
 
Advanced Search
Tools
Rss Categories

Installation API

Author: Edward Hardin Reference Number: AA-00464 Views: 10280 Last Updated: 09/01/2010 04:18 PM 100 Rating/ 1 Voters

KMP features an XML RPC based installation API that can be used by ISP companies, web hosting companies, and anyone who needs to automate the installation process to perform remote installations of KMP. This guide explains how to perform installations via the remote XML API.

The remote installation API helps with fast deployment of new KMP packages. It assumes that all package files are already extracted from the package and uploaded to the remote server, and all necessary file/folder permissions are set.

Contents

Creating the Request

Before launching remote installation of KMP copy, make sure that:

  • All files are uploaded on the remote server.
  • Correct permissions are set.
  • Package is not installed yet.

To submit an XML based API request to install Knowledgebase Manager Pro, you must send the details outlined below as the HTTP POST body in a properly formatted XML feed.

XML Reference

  • xml version - XML declaration which specifies the version of XML being used
  • methodCall - The root node of the XML document. It outlines your request
    • methodName - type of request. It must be "install.setup" for installation request.
    • params - This node contains all parameters that you send
      • product_key - Product key for KMP. You can get it from your member area.
      • db_prefix - Prefix for database tables (optional)
      • db_host - Database server address
      • db_login - The username of the Database user
      • db_password - The Database password for the above user
      • db_name - The name of the MySQL database to install the KMP in to
      • acc_login - The username of the knowledgebase administrator
      • acc_password - The password to assign the KMP administrator account
      • acc_first_name - The first name of the knowledgebase administrator
      • acc_last_name - The last name of the knowledgebase administrator
      • acc_email - The email address of the knowledgebase administrator
      • smtp_host - SMTP (mail) server address
      • smtp_port - SMTP server port

Sample XML Request

Sample XML Request
<?xml version="1.0"?>
<methodCall>
  <methodName>install.setup</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>activation_code</name>
            <value>
              <string>[License_Key]</string>
            </value>
          </member>
          <member>
            <name>db_prefix</name>
            <value>
              <string>kmp_</string>
            </value>
          </member>
          <member>
            <name>db_host</name>
            <value>
              <string>localhost</string>
            </value>
          </member>
          <member>
            <name>db_login</name>
            <value>
              <string>root</string>
            </value>
          </member>
          <member>
            <name>db_password</name>
            <value>
              <string></string>
            </value>
          </member>
          <member>
            <name>db_name</name>
            <value>
              <string>kb</string>
            </value>
          </member>
          <member>
            <name>acc_login</name>
            <value>
              <string>admin</string>
            </value>
          </member>
          <member>
            <name>acc_password</name>
            <value>
              <string>password</string>
            </value>
          </member>
          <member>
            <name>acc_first_name</name>
            <value>
              <string>John</string>
            </value>
          </member>
          <member>
            <name>acc_last_name</name>
            <value>
              <string>Doe</string>
            </value>
          </member>
          <member>
            <name>acc_email</name>
            <value>
              <string>administrator@example.com</string>
            </value>
          </member>
          <member>
            <name>smtp_host</name>
            <value>
              <string>mail</string>
            </value>
          </member>
          <member>
            <name>smtp_port</name>
            <value>
              <string>25</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>


Sample PHP Request (Using CURL and IXR)

The following sample code is written on PHP with usage of CURL functionality.

You can also find this sample in the KMP package: /examples/installation-api/rpc_install.php

Although it uses IXR as XML RPC library (include 'inc/xmlrpc.php') it is just a sample, and you may use any library suitable for you.

Sample PHP Request

<?php 
error_reporting(E_ALL);
include 'inc/xmlrpc.php';

$client = new IXR_Client('http://localhost/kmp/admin/install/rpc.php');

$client->debug = true;

$params = array(
    'product_key' => 'ABCD-EFGH-IJKL-MNOP',
    'db_prefix'       => 'kmp_',
    'db_host'         => 'localhost',
    'db_login'        => 'root',
    'db_password'     => '',
    'db_name'         => 'kmp',
    'acc_login'       => 'admin',
    'acc_password'    => '',
    'acc_first_name'  => 'John',
    'acc_last_name'   => 'Doe',
    'acc_email'       => 'john.doe@example.com',
    'smtp_host'   => 'mail',
    'smtp_port'   => '25'
);

if (!$client->query('install.setup', $params)) {
   die('An error occurred - '.$client->getErrorCode().":".$client->getErrorMessage());
}

echo '<pre>';
print_r($client->getResponse());
echo '</pre>';

?>


A Successful Installation Response

A successful installation response has the following format.

Successful Installation Response

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <string>Installation completed successfully</string>
      </value>
    </param>
  </params>
</methodResponse>


An Erroneous Installation Response

If an error occurred during installation or server doesn't meet KMP requirements, you will get an erroneous installation message. It includes error code and error message with information why installation cannot proceed.

Erroneous Installation Response

<?xml version="1.0"?>
<methodResponse>
  <fault>
    <value>
      <struct>
        <member>
          <name>faultCode</name>
          <value><int>-101</int></value>
        </member>
        <member>
          <name>faultString</name>
          <value><string>Not all parameters specified. Following parameters are required: acc_login, acc_password, acc_first_name, acc_last_name</string></value>
        </member>
      </struct>
    </value>
  </fault>
</methodResponse>


Error Codes

The table below outlines all possible error messages for faultCode attribute.

Error Code Message
 -101  Not all parameters specified. Following parameters are required: [list of parameters]
-201   Your PHP version is not compatible. Current PHP version is [current version]. Required version: [required version]
-202   Some of the required modules are missing: [list of missing extensions]
-203   Some of the required custom checks has been failed: [list of custom checks]
-301   File system permissions are incorrect: [list of files with incorrect permissions]
-401   Can not connect to database server
-402   Can not select database
-403  Unknown error while database connection 
-410  MySQL error when executing sql dump: [mysql error] 
-411   MySQL error when executing sql dump for administrator's account: [mysql error]
-501   Error when setup configuration file
-502   Error when setup file [file name]
-601   Wrong license key
-701  Unable to run installation process because KMP has been already installed

Installation by Shell Script

Installation shell script supports installation of KMP from UNIX shell. Before starting the script:

  • Check that server meets the KMP requirements
  • Upload files from the KMP package on server
  • Setup correct permissions
  • Create an empty database for KMP
  • Specify correct installation details including database connection parameters, administrator account details, etc in the installation script

Installation script performs the following actions:

  • Installs KMP via XML API
  • Provides you with the URL to installed KMP

Parameters to Customize in the Installation Shell Script

KMP_KEY="ABCD-EFGH-IJKL-MNOP" # Product key for Knowledgebase Manager Pro (KMP). You can get it from your member area at http://web-site-scripts.com/member-area/

KMP_URL="http://localhost/kmp/" # URL of the destination directory

KMP_DB_HOST="localhost" # Name of database server (default value = localhost)

KMP_DB_PREFIX="" # Prefix for database tables (optional)

KMP_DB="kmp" # Database name

KMP_DB_USER="" # Database user

KMP_DB_PASS="" # Database user password

KMP_USER="admin" # Desired login for KMP administrator account

KMP_PASS="" # Desired password for KMP administrator account

KMP_ACC_FNAME="John" # KMP administrator first name 

KMP_ACC_LNAME="Doe" # KMP administrator last name 

KMP_EMAIL="john.doe@example.com" # KMP administrator email

KMP_SMTP_HOST="localhost" # SMTP server name (default value = localhost)

KMP_SMTP_PORT="25" # SMTP server port (default value = 25)

PHP_PATH="/usr/bin/php" # Command to run PHP executable (default value = /usr/bin/php)