Installing Interspire Knowledge Manager via the XML API

Published 10/7/2008 by David Chandra

Interspire Knowledge Manager contains an XML based installation API that can be used by web hosting companies, partners or ISPs to perform remote installations of Interspire Knowledge Manager. This guide explains how to access and perform installations via the remote XML API.

Introduction
Creating the Request
A Successful Installation Response
An Erroneous Installation Response
Appendix 1: Error Codes

Introduction

Interspire Knowledge Manager contains an XML based API that can be used for remote installation. By passing an XML based request to a remote location, Interspire Knowledge Manager will initialise and complete the installation request.

The remote installation API is useful for web hosting providers or ISPs to leverage for quick deployment of Interspire Knowledge Manager on to remote systems. It assumes that all of the files from the Interspire Knowledge Manager release have already been uploaded to the remote server and the necessary file/folder permissions have been set.

Creating the Request

To remotely install a copy of Interspire Knowledge Manager, the files need to already exist on the remote server. The copy of Interspire Knowledge Manager should not be installed (and when you visit it in your web browser, it should show you the “Interspire Knowledge Manager Installation Wizard”)

To submit an XML based API request to install Interspire Knowledge Manager, you must:

Send a Content-type/Accept header of “application/xml” to http://location.of.the.knowledgebase/admin/
Send the details outlined below as the HTTP POST body in a properly formatted XML feed

XML Reference

request – The root node of the XML document. Outlining that you wish to perform a request
- install
  - (Required) licenseKey ‐ A valid license key for this copy of Interspire Knowledge Manager
  - (Required) knowledgebaseName – The name of this knowledgebase
  - (Required) pathToKB – The URL that the knowledgebase will be accessible from
  - user
    - (Required) username – The username of the knowledgebase administrator
    - (Required) password – The password to assign the knowledgebase administrator account
    - (Required) email – The email address of the knowledgebase administrator
    - (Required) firstname – The first name of the knowledgebase administrator
    - (Required) lastname – The last name of the knowledgebase administrator
  - database
    - (Required) databaseType – The type of database that this knowledgebase will be installed to (MySQL or MSSQL)
    - (Required) dbUser – The username of the Database user
    - (Required) dbPass – The Database password for the above user
    - (Required) dbDatabase – The name of the MySQL database to install the Knowledge Manager in to
    - (Required) dbServer – The hostname of the database server to install on
    - (Required) tablePrefix – The prefix to be added to the beginning of all created database tables
  - sendStats – Include this node and set the value to true or 1 to send anonymous statistics about the remote server back to Interspire

Sample XML Request

<request>
	<install>
		<licenseKey>[LICENCE_KEY]</licenseKey>
		<knowledgebaseName>My Knowledgebase</knowledgebaseName>
		<pathToKB>http://example.com/kb</pathToKB>
		<user>
			<username>admin</username>
			<password>password</password>
			<email>administrator@example.com</email>
			<firstname>John</firstname>
			<lastname>Smith</lastname>
		</user>
		<database>
			<databaseType>mysql</databaseType>
			<dbUser>root</dbUser>
			<dbPass></dbPass>
			<dbDatabase>example_kb</dbDatabase>
			<dbServer>localhost</dbServer>
			<tablePrefix>kb_</tablePrefix>
		</database>
		<sendStats>true</sendStats>
	</install>
</request>

Sample PHP Request (Using CURL)

The following sample code is written in PHP and makes use of PHP’s CURL functionality.

<?php
	$data = '
	<request>
		<install>
			<licenseKey>[LICENCE_KEY]</licenseKey>
			<knowledgebaseName>My Knowledgebase</knowledgebaseName>
			<pathToKB>http://example.com/kb</pathToKB>
			<user>
				<username>admin</username>
				<password>password</password>
				<email>administrator@example.com</email>
				<firstname>John</firstname>
				<lastname>Smith</lastname>
			</user>
			<database>
				<databaseType>mysql</databaseType>
				<dbUser>root</dbUser>
				<dbPass></dbPass>
				<dbDatabase>example_kb</dbDatabase>
				<dbServer>localhost</dbServer>
				<tablePrefix>kb_</tablePrefix>
			</database>
			<sendStats>true</sendStats>
		</install>
	</request>
	';

	$ch = curl_init("http://example.com/kb/admin/");
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_POST, 1);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	"Accept: application/xml",
	"Content‐Type: application/xml"
	));
	echo "<pre>";
	echo htmlspecialchars(curl_exec($ch));
	echo "</pre>";
?>

A Successful Installation Response

A successful installation will return an OK status as well as information about the newly installed knowledgebase. The response will be formatted as XML.

XML Reference

response – The root node of the XML document. Outlining that this is a response to a previous XML request.
- status – Will contain a value of OK for a successful installation.
- kb
  - pathToKB – The URL to the front end of the installed copy of Interspire Knowledge Manager
  - controlPanel – The URL to the control panel of the installed copy of Interspire Knowledge Manager
- user
  - username – The username of the default knowledgebase administrator
  - password – The previously assigned password (from the installation request) for this user

Sample Response

<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<status>OK</status>
	<kb>
		<pathToKB>http://example.com/kb</pathToKB>
		<controlPanel>http://example.com/kb/admin/index.php</controlPanel>
	</kb>
	<user>
		<username>admin</username>
		<password>password</password>
	</user>
</response>

An Erroneous Installation Response

In the event that there is a problem during the installation, or the server does not meet the requirements for Interspire Knowledge Manager, an XML response will be returned containing information about why the installation cannot proceed.

XML Reference

response – The root node of the XML document. Outlining that this is a response to a previous XML request.
- status – Will contain a value of ERROR for an unsuccessful installation.
- message – An overall message stating why the message cannot proceed.
- errors
  - error – This node will be repeated for each error and can contain the following:
    - (Attribute) code An error code associated with this error. See Appendix 1: Error Codes for a full list of error codes
    - (Attribute / Optional) extra – Any additional information that may be useful to help debug this error.
    - Value – The value of the error node contains a friendly error message that can be shown as to why this problem occurred.

Sample Response

The following sample outlines the response you will receive from passing an invalid license key:

<?xml version="1.0" encoding="iso-8859-1" ?>
<response>
  <status>ERROR</status>
  <message>The license key that you entered is invalid. You can generate your license key from the Interspire client area or purchase one from Interspire.com.</message>
  <errors>
      <error code="badLicenseKey">The license key that you entered is invalid. You can generate your license key from the Interspire client area or purchase one from Interspire.com.
      </error>
  </errors>
</response>

In the sample below, a few of the required directories are missing:

<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="iso-8859-1" ?>
<response>
  <status>ERROR</status>
  <message>Before you can install Interspire Knowledge Manager you need to set the appropriate permissions on the files/folders listed below:</message>
  <errors>
      <error code="doesntExist" extra="attachments">Before you can install Interspire Knowledge Manager you need to set the appropriate permissions on the files/folders listed below:</error>
      <error code="doesntExist" extra="templates">Before you can install Interspire Knowledge Manager you need to set the appropriate permissions on the files/folders listed below:</error>
  </errors>
</response>

Appendix 1: Error Codes

The table below outlines all of the possible return values for the error code attribute.

Code	Extra Data	Reason
badLicenseKey	N/A	The supplied license key was invalid.
missingKnowledgebaseName	N/A	The knowledgebase name was not supplied.
missingPathToKB	N/A	The pathToKB value was not supplied containing the URL to the knowledgebase.
missingUsername	N/A	A valid username for administrator was not supplied.
missingPassword	N/A	A valid password for administrator was not supplied.
missingEmail	N/A	A valid email address for administrator was not supplied.
missingFirstname	N/A	First name for administrator was not supplied.
missingLastname	N/A	Last name for administrator was not supplied.
missingDbType	N/A	A valid database type was not supplied. The valid database type should: mysql / mssql.
missingDbServer	N/A	A database server hostname was not supplied.
missingDbUser	N/A	A database username was not supplied.
missingDbPass	N/A	The missing <dbPass> tag in the xml request
missingDbDatabase	N/A	A database name was not supplied.
FailedDatabaseConnection	N/A	The database connection error message as returned from Database server. There was an error connecting to the database server with the supplied details.
FailedCreateAdmin	N/A	Failed when trying to create an admin account.
filePermissions	N/A	The name of the file/folder that does not have the necessary permissions The files listed do not have the necessary write permissions. They need to be chmod depending on returned message.
doesntExist	N/A	The name of the file/folder that does not exist. The files listed do not exist. They need to be created before the installation can proceed.
phpVersion	N/A
invalidRequest	N/A	The version of PHP currently running on the server. The version of PHP running on the server does not meet the minimum requirements.
ApplicationInstalled	N/A	The format of the request XML was not valid.
extensionNotFound	N/A	Missing Extension on the PHP installation

Code

Extra Data

Reason

badLicenseKey

N/A

The supplied license key was invalid.

missingKnowledgebaseName

N/A

The knowledgebase name was not supplied.

missingPathToKB

N/A

The pathToKB value was not supplied containing the URL to the knowledgebase.

missingUsername

N/A

A valid username for administrator was not supplied.

missingPassword

N/A

A valid password for administrator was not supplied.

missingEmail

N/A

A valid email address for administrator was not supplied.

missingFirstname

N/A

First name for administrator was not supplied.

missingLastname

N/A

Last name for administrator was not supplied.

missingDbType

N/A

A valid database type was not supplied. The valid database type should: mysql / mssql.

missingDbServer

N/A

A database server hostname was not supplied.

missingDbUser

N/A

A database username was not supplied.

missingDbPass

N/A

The missing <dbPass> tag in the xml request

missingDbDatabase

N/A

A database name was not supplied.

FailedDatabaseConnection

N/A

The database connection error message as returned from Database server. There was an error connecting to the database server with the supplied details.

FailedCreateAdmin

N/A

Failed when trying to create an admin account.

filePermissions

N/A

The name of the file/folder that does not have the necessary permissions The files listed do not have the necessary write permissions. They need to be chmod depending on returned message.

doesntExist

N/A

The name of the file/folder that does not exist. The files listed do not exist. They need to be created before the installation can proceed.

phpVersion

N/A

invalidRequest

N/A

The version of PHP currently running on the server. The version of PHP running on the server does not meet the minimum requirements.

ApplicationInstalled

N/A

The format of the request XML was not valid.

extensionNotFound

N/A

Missing Extension on the PHP installation

Articles

Blogs

Recent Blogs
(View all blogs)

Installing Interspire Knowledge Manager via the XML API

Contents

Introduction

Creating the Request

A Successful Installation Response

An Erroneous Installation Response

Appendix 1: Error Codes

Comments

Articles

Blogs

Recent Blogs (View all blogs)

Installing Interspire Knowledge Manager via the XML API

Contents

Introduction

Creating the Request

A Successful Installation Response

An Erroneous Installation Response

Appendix 1: Error Codes

Comments

Recent Blogs
(View all blogs)