From KnowledgeTree Document Management Made Simple

IMPORTANT:
February 2008:  Please note that this is a PHP Web Service API (WSAPI) Guide - this 
document is out of date, and may not be compatible with the latest versions of KnowledgeTree.

For a more up to date information please review  SOAP Web Service Functions.

Contents 1 What is KnowledgeTree? 2 What is the KnowlegeTree web service? 3 PHP Tutorial 3.1 Requirements 3.2 Authentication 3.3 Dealing with errors 3.4 Locating a folder or document 3.5 Adding Documents And Metadata 3.6 Document and Folder Information 3.7 Creating and Deleting Folders 3.8 Checking out documents 3.9 Copying and Moving documents 3.10 Accessing the Core Web Service Directly 4 PHP Examples 4.1 Adding a document to KnowledgeTree 4.2 Creating folders 4.3 Checkout and Checkin 5 Core Web Service Reference 6 Web Service Object Model Reference 7 Upcoming Developments on Web Services 7.1 Providing Web Service object models in different languages 7.2 Improving Performance of the Web Service Object Model 8 Acknowledgements

What is KnowledgeTree?

KnowledgeTree is a document management system providing extended features around managing documents – such as document versioning, permissions, auditing, workflow, etc.

What is the KnowlegeTree web service?

KnowledgeTree web services is an extension to KnowledgeTree that allows external parties to integrate directly into the core of KnowledgeTree, bypassing the traditional user interface. This allows third party application developers to extend their systems to access information in different ways.

Utilizing the SOAP protocol, core functionality is exposed to third parties in a manner that is platform independent and programming language independent.

PHP Tutorial

This tutorial will demonstrate the KnowledgeTree web service php object model.

The KnowledgeTree Web Service object model, often refered to as KTWSAPI can be ported to different languages, so this documentation can be used similarly in those environments.

Requirements

The PHP Web Services Object Model has the following dependencies:

• Libcurl
• PEAR::SOAP

The API has been developed to work under PHP4 and PHP5. It depends on the libcurl extension for PHP, so this must be enabled in the php.ini.

; to enable under windows
extension=php_curl.dll

; to enable under linux
;extension=php_curl.so

Libcurl.dll should be included in the library search path. Libcurl can be obtained from http://libcurl.haxx.se/

The PHP KTWSAPI is also dependant on the PEAR SOAP libraries. http://pear.php.net/ provides more information on installing the PEAR libraries.

The PHP KTWSAPI library must be installed somewhere in your PHP include path, or you should refer to it explicitly. Prior to using the object model, the library should be included for use.

; assuming that ktwsapi.inc.php is in the include path
require_once('ktwsapi.inc.php');

; create a reference to the ktapi library
$ktapi = new KTWSAPI(KTWebService_WSDL);

Authentication

Authentication can be done using username and password, or anonymously.

To authenticate with a username and password:

; to authenticate with username (admin) and password (123) 

$response = $ktapi->start_session('admin','123');
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
}

; note that the error handling shown in this tutorial is very harsh, and that
; you should provide a more user friendly mechanism for displaying errors.

To start an anonymous session:

; to authenticate with username (admin) and password (123) 

$response = $ktapi->start_anonymous_session();
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
}

Note that anonymous sessions must be configured in the config.ini before they can be utilized.

Once authenticated, a session needs to be maintained. If you are working in a web site, you may wish to persist this in some way, such as in a session variable.

$session= $ktapi->session;

; assuming session_start() has been called already

$_SESSION[‘ktapi_session’] = $session;

In order to minimize the load on the server, you should implement the authentication so that the starting of a knowledgeTree session is done once, and the token is then used thereafter.

; assuming session_start() has been called already

$session = $_SESSION[‘ktapi_session’];

; we can now reuse an existing knowledgetree session for successive actions
; on different pages in the 3rd party application.

$response = $ktapi->active_session($session);
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
}

Dealing with errors

All functions in the model normally return something to indicate success. However, to maintain consistency with the rest of KnowledgeTree and portability across PHP4 and PHP5, the PEAR_Error class may also be returned in case of some failure. It is important that you test for errors after each call as the results can be unpredictable otherwise.

In the authentication process above, we have demonstrated this process, however, in the following examples we will omit them to ease the documentation process.

If you are working with another other languages, the KTWSAPI model for your language may utilise exception handling.

Locating a folder or document

The following actions can be done to locate folders:

// get a reference to a folder based on folder id – 1 = root folder
$root = $ktapi->get_folder_by_id(1);

// to get a reference to the root folder
$root = $ktapi->get_root_folder();

// to locate Root/sub folder
$folder = $root->get_folder_by_name(‘sub folder’);

// to locate Root/sub folder/another
$another_folder = $folder->get_folder_by_name(‘another’);

// using the full path
$another_folder = $root->get_folder_by_name(‘sub folder/another’);

The following actions can be done to locate documents:

// get a reference to a document based on document id 
$document = $ktapi->get_document_by_id(1); 

// assuming we have a reference to a folder, we can locate it by title
$document = $folder->get_document_by_name(‘introduction’);

// assuming we have a reference to a folder, we can locate it by filename
$document = $folder->get_document_by_name(‘budget.xls’);

// assuming we have a reference to a folder, we can locate it by filename
$document = $folder->get_document_by_name(‘budget.xls’);

Adding Documents And Metadata

; to add a document to the folder
$document = $folder->add_document(‘c:/temp/budget.xls’,’Budget 2007’, ‘Default’);

; to update the document’s metadata

$metadata = array(
	array(
		‘fieldset’=>’Sales Info’,
		‘fields’=>array(
			‘Invoice No’=>’10001’,
			‘Invoice Date’=>’2007/03/19’,
			‘Customer’=>’Joe Blogs Ltd’
			‘Currency’=>’USD’
			‘Amount’=>’54.99’
		)
	),
	array(
		‘fieldset’=>’Delivery Info’,
		‘fields’=>array(
			‘Recipient’=>’Jane Doe’,
			‘Address’=>’Somewhere’,
		)
	)
);

$document->update_metadata($metadata);

Document and Folder Information

Once you have obtained a reference to a document, you may wish to look at various properties it may contain.

; To mention a few properties that may be available on documents:
$document = $ktapi->get_document_by_id(1);

print ‘Document ID: ’. $document->document_id . “\n”;
print ‘Title: ’. $document->title . “\n”;
print ‘Document Type: ’. $document->document_type . “\n”;
print ‘Version: ’. $document->version . “\n”;
print ‘Workflow: ’. $document->workflow . “\n”;
print ‘Workflow State: ’. $document->workflow_state . “\n”;
print ‘Full Path: ’. $document->full_path . “\n”;

; Some properties on the root folder
$root = $ktapi->get_root_folder(); 

print ‘Folder ID: ’. $root->folderid . “\n”;
print ‘Folder Name: ’. $root->folder_name . “\n”;
print ‘Parent ID: ’. $root->parent_id . “\n”;
print ‘Full Path: ’. $root->full_path . “\n”; 

Creating and Deleting Folders

To create a folder:

; obtain a reference to the parent folder
$root = $ktapi->get_root_folder();

; use the reference to create the subfolder
$folder = $root->add_folder(‘sub folder’);

To delete a folder:

; obtain a reference to the folder required
$folder = $ktapi->get_folder_by_name(‘sub folder’);

$result = $folder->delete(‘we don\\t need this anymore’);

Checking out documents

To check a document out of the repository:

$document = $ktapi->get_document_by_id(1);

$result = $document->checkout(‘I need to update the budget’,’c:/working directory’);

To check the document back into the repository:

$document = $ktapi->get_document_by_id(1);

; checking a document, but only update minor version
$result = $document->checkin(
	‘c:/working directory/budget.xls’,
	 ‘Updated the 2007 budget. Increased entertainment expenses.’,
	false);

The KTWSAPI will manage the uploading of documents automatically to the repository.

To undo a document checkout, rather than doing a checkin:

$document = $ktapi->get_document_by_id(1);

$result = $document->undo_checkout(‘No change required’);

Copying and Moving documents

To move a document to another location:

$document = $ktapi->get_document_by_id(1);

$target_folder = $ktapi->get_folder_by_id(10);

; to copy a document to a target location
$result = $document->copy($target_folder,’because we can’);

; to move a folder to a target location
$result = $document->move($target_folder,’because we can’,
					’budget 2008’,’budget2008.xls’);

Accessing the Core Web Service Directly

Possibly, you don’t want to use the object model, but want to use the core web service directly. The following example demonstrates this using PEAR::SOAP.

require_once('SOAP/Client.php');

$wsdl = new SOAP_WSDL(‘http://ktdms/ktwebservice/webservice.php?wsdl’);
$soapclient = $wsdl->getProxy();
$soapclient->setOpt('timeout', 30); // 30 seconds

$kt_response = $soapclient->login(‘admin’,’123’,’1.1.1.1’);
$session = $kt_response->message;

$root = $soapclient->get_folder_detail($session, 1);

PHP Examples

Adding a document to KnowledgeTree

require_once('../ktwsapi.inc.php');

$ktapi = new KTWSAPI('http://ktdms/ktwebservice/?wsdl');

$response = $ktapi->start_session('admin','admin');
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
}

$root = $ktapi->get_root_folder();

// adds a document to the root folder
$root->add_document('c:/temp/test.doc');

$ktapi->logout();

Creating folders

require_once('../ktwsapi.inc.php');

$ktapi = new KTWSAPI('http://ktdms/ktwebservice/?wsdl');

// here we use a session that has been created before using the start_session() method.

$response = $ktapi->active_session('qekolkpkk9mq2nlc31ghndi1l2');
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
} 

$root = $ktapi->get_root_folder();
if (PEAR::isError($root))
{
	print $root->getMessage();
	exit;
}

// add a folder to the root folder
$folder = $root->add_folder('test folder');
if (PEAR::isError($folder))
{
	print $folder->getMessage();
	exit;
}

// add a folder to the test folder
$subfolder = $folder->add_folder('test sub folder');
if (PEAR::isError($subfolder))
{
	print $subfolder->getMessage();
	exit;
}

Checkout and Checkin

require_once('../ktwsapi.inc.php');

$ktapi = new KTWSAPI(‘http://ktdms/ktwebservice/webservice.php?wsdl’);

// here we use a session that has been created before using the start_session() method.

$response = $ktapi->active_session('sj5827sohdoj6h3nvifrcsa1f2');
if (PEAR::isError($response))
{
	print $response->getMessage();
	exit;
}

$root = $ktapi->get_root_folder();
if (PEAR::isError($root))
{
	print $root->getMessage();
	exit;
}

// adds a document to the root folder
$document = $root->add_document('c:/temp/test.doc');
if (PEAR::isError($document))
{
	print $document->getMessage();
	exit;
}

// check out the document - the downloaded document should be c:\test.doc
$result = $document->checkout('going to update','c:/');
if (PEAR::isError($result))
{
	print $result->getMessage();
	exit;
}

// check in the document
$result = $document->checkin('c:/test.doc','have updated',false);
if (PEAR::isError($result))
{
	print $result->getMessage();
	exit;
}

Core Web Service Reference

This core web service reference provides a definitive guide to functions that have been exposed at this time.

Web Service Object Model Reference

This core web service object model provides a guide to the objects, their attributes and methods that are exposed by the client library in different languages. The current documentation is based on the PHP implementation and may have some subtle variations in other languages.

The web service object model] is supposed to be similar to the core web service reference, except that this layer hides the communication process that is taking place under the hood.

Upcoming Developments on Web Services

The client libraries for the KTWSAPI are merely wrappers for the functionality exposed by the KnowledgeTree SOAP interface. The following developments should be catered for to enhance the accessability and usability of KnowledgeTree by third parties.

Providing Web Service object models in different languages

Although by providing the web service to KnowledgeTree via SOAP, in order to make KnowledgeTree more easily accessible, we can write the Web Service Object Model in different languages so that the programmers don’t have to worry about the communications mechanism, and simply rely on the interface.

Languages to address would be: C# .NET, Delphi, Java, Python, Ruby, C/C++

Improving Performance of the Web Service Object Model

The initial implementation of the Web Service Object Model implements only a wrapper around the functions exposed by the SOAP layer.

In order to improve performance:

• Caching from within the object model so that unnecessary calls are avoided
• Extending validation based on known information to avoid unnecessary load on the server

Acknowledgements

We wish to thank the following persons for their contributions to the project:

• Antonio Rizzelli, of Ethica System srl, for sparking the initial web service project and input
• Matthew Evans for his effort in making a quick port of the KTWSAPI to C# .NET