Tools

Installation API

Author: Edward Hardin Reference Number: AA-00464 Views: 82794 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.

Creating the Request

XML Reference
Sample XML Request
Sample PHP Request (Using CURL)

A Successful Installation Response
An Erroneous Installation Response
Error Codes
Installation by Shell Script

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

<?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)