This guide explains how to add Active Response feature to a form on your website. Active Response helps you to provide an always available self-service to your customers, allowing them to find the answers to their questions immediately instead of submitting them to your support or sales department and waiting for the answer. While user types text in the form with Active Response feature, he sees suggested articles from the knowledgebase below. Active response system analyzes user input and finds the most accurate answers to his question from the knowledge base.

• Enable API in KMP
• Upload files to the server
• Adjust the URL and the token
• Copy CSS and JavaScript references
• Adjust the form fields

Enable API in KMP

Go to Administration > General Settings > API Server page and tick the checkbox against "Enable API Server". Then click "Save".

Notice the Server Link here, you'll need it later.

Upload files to the server

Download the active-response.zip file below on this page. Unzip it and copy its contents to a directory on the website (this may any directory and it doesn't have to be on the same site as KMP). You'll be launching your API script from that directory.

Adjust the URL and the token

Adjust the URL to KMP API server and the token in the config.php file:

To get a token, you need to create a Staff user (Users & Groups > Staff > Add Staff User) and assign him to a group. Then re-open the user edit window. You can copy the token from it.

Please note that the token is being used for authentication, so if you're using the token of a certain user account, it means that each article that the user can see may be shown to public via the form with Active Response. We would recommend to create a user with special access permissions, and use his token here to avoid exposure of restricted information. Alternatively you can enable the "Allow Anonymous Access" option at the API settings page (Administration > General Settings > API Server).

You can get the URL to the API server from the Administration > General Settings > API Server page.

Copy CSS and JavaScript references

Adjust the URLs as mentioned below and copy-paste this code to the <head></head> section of the page were you want to have the Active Response feature.

where:

http://www.web-site-scripts.com/knowledge-base/ - needs to be replaced with the URL to your KMP main front-end page

http://demo/active-response/ - needs to be replaced with with the URL to the folder with the aforementioned API files.

Adjust the form fields

Edit the form which you're going to plug Active Response feature to, and add some IDs to it.

Wrap it with:

Add id="askSubject" to the Subject field of the form (optional - only if you wish that field to be searchable):

Add id="ask-question" to the text area for user question:

Add image that will show loading animation to a desired place on the form page:

Add this div to the place where you want to show articles suggested by Active Response:

That's it! Now you can open the form in your browser and try typing something that can be found in your knowledge base. You'll see the Active Response in action.

If you would need any help in configurung Active Reponse, feel free to contact us.

• Introduction
• Possible Requests
• Getting Started
• Submitting a Request
• API Usage Examples

Introduction

The KMP XML API is a remotely accessible service API to allow KMP users to run many of the KMP API functions using XML requests.

The KMP XML API makes it possible to programmatically use your system without needing to physically access it. As XML is a general purpose markup language you can use it to communicate between other applications to KMP application base.

For example you could set your system up to get search results for a custom search phrase or use the Active Response feature remotely, and many other functions.

Possible Requests

This section will describe the different functions that can be used by the KMP XML API.

• Get full set of article properties by its code (including article title, body, assignment, creation date, attachments, related articles, and much more – all properties are available via one simple call).
• Get comments by article id.
• Get list of articles (all articles from the knowledge base, or from any category – including subcategories or not – by your choice).
• Get list of the most popular featured articles (this and all coming article lists can be pulled from the whole knowledge base, or from a category– including subcategories or not – by your choice).
• Get list of the most discussed articles.
• Get list of the most popular articles.
• Get list of the recently created articles.
• Get list of the recently updated articles.
• Get list of the top rated articles.
• Get list of categories (all categories from the knowledge base, or from a given category).
• Get tree of categories (the whole tree or specified branch).
• Get list of glossary terms.
• Search attachments and articles by content and comments (the same search function, that is available in Knowledgebase Manager Pro, can be accessed via API; you can specify search method, and use any search fields you wish, including custom fields).
• Get list of searched categories.
• Get suggested articles for search query (the Active Response feature that provides quick answers to user question while he is typing it into the Ask Question form – now available via API).
• Get search suggestions for search query, search by article, category, and attachment titles (smart search suggest – exactly the same that you can see when you start typing a phrase into the search field in Knowledgebase Manager Pro – now available via API).
• Search glossary terms.
• Create a category.
• Create an article.
• Create a user.
• Activate a user.
• Deactivate a user.
• Delete a user.
• Get an array of the available API methods.
• Get the description for a specified API method.
• Get input and output format for a given API method.
• Combine multiple RPC calls in one request (API method that lets you combine several requests and gain a lot in performance).

You can find description of the request and response for each method by opening the api.php page of your KMP installation:

http://location.of.the.knowledgebase/api.php

Getting Started

The API server is disabled by default. To enable it, go to Administration > General Settings > API Server and turn on "Enable API Server" option.

You many want to enable the "Allow Anonymous Access" option. If it is enabled, you do not need to specify a token in each API request. Though, you would need to use a user token if you need to get to some restricted data.

The "Save Logs" option enables logging of all API requests. They are stored in Administration > Logs for the specified amount of time. Logs will help you to monitor and troubleshoot your API requests.

Submitting a Request

All XML POST request should be sent to:

http://location.of.the.knowledgebase/api.php

API Usage Examples

You can download API usage examples below on this page. We are using a native XML RPC library that is located in the /examples/api/lib/ directory. It encodes your API requests to XML-RPC format and decodes responses from XML-RPC.

To try an example you need to:

1. Upload the /examples/api/ folder to a web server with PHP support. This could be a remote server in relation to the server where KMP installed.
2. Turn on the API server. To do that, go to Administration > General Settings > API Server and turn on "Enable API Server" option.
3. Copy your token to a sample script like shown on the screenshots.
   
   
   
   
   
   
   Config

   Please note that sample scripts located in the /examples/api/ folder include the config.php from the same folder and so use the same configuration.

   On the contrary, each script from the /examples/api/simple-examples/ folder use its own config. To change a token, you need to edit the script file itself.

4. You may want to edit the parameters script sends to the API server, for example you may want to specify an article ID in the get.article.php, or search phrase in the search.Articles.php. Otherwise you may get a zero response or an error if object that you're requesting for (e.g. article) doesn't exist.
5. Call the sample script via your browser.

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
  
• 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.

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 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.

A Successful Installation Response

A successful installation response has the following format.

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

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