From KnowledgeTree Document Management Made Simple

Contents 1 SOAP Web Service Specification 1.1 Introduction 1.2 NOTICE 1.3 File Transfer Process 1.3.1 Document Checkin 1.3.2 Document Download/Checkout 1.3.3 Webservices/upload.php 1.3.4 Webservices/download.php 1.3.5 Webservices/cleanup.php 1.4 File Structure 1.5 Status Codes

SOAP Web Service Specification

Introduction

The purpose of this document is to describe a core interface to the KT subsystem so external applications can interact with KT via web services. Currently, it is not focusing on permission, administrative and configuration functions.

NOTICE

Please see Soap Service Documentation for the latest documentation.

Please see web service documentation PHP Web Service API (WSAPI) Guide.

The web service exposes two sets of add_document(). 1) a two phase add_document. It requires an http post to upload the initial document followed by the web service call to add_document. 2) a base64 encoded add_document - called add_base64_document

File Transfer Process

The process of transferring files can be quite bloated. Many people transferring files using webservices implement try to do this by doing it using an encoding such as base64 to convert binary to a format compatible with XML.

I suggest the following solution rather separating the file transfer from the web service.

Document Checkin

• An HTTP post is done to webservices/upload.php.
• upload.php will place the uploaded file into a temporary directory.
• Call the webservice:checkin function specifying the filename in the temporary directory.

Document Download/Checkout

• Call the webservice:checkout function which returns a url on webservices/download.php.
• An HTTP get is done to webservices/download.php

This means we can optimize the file transfer as we don’t need to encode the file into an intermediate format.

Webservices/upload.php

This requires the following post parameters:

• document_name
• session_id
• action

Webservices/download.php

This requires the following post parameters:

• documentid
• sessionid

When the download is completed, the link should no longer be usable.

Webservices/cleanup.php

This is a cleanup function that should cleanup links that have not been accessed via download.php in a configured time period, say after 30 minutes of doing requesting the download or checkout.

---

File Structure

The following directories will be referenced:

• /ktroot/
  • /thirdparty/
    • /soap/
  • /webservices/
    • webservice.php
    • upload.php
    • download.php
    • cleanup.php

---

Status Codes

Status Code	Error	Description
0	SUCCESS
1	ERR_INVALID_SESSION	The sessionid provided does not exist or has been closed.
2	ERR_AUTHENTICATION_ERROR	The username or password is invalid.
3	ERR_INSUFFICIENT_PERMISSIONS	The user does not have sufficient permissions to perform the action required on the document or folder.
10	ERR_FILE_NOT_FOUND	The file that is referenced does not exist.
20	ERR_INVALID_FILENAME	The filename is not valid. Possibly includes a directory or invalid characters.
21	ERR_INVALID_DOCUMENT	The documentid is invalid – probably does not exist.
22	ERR_INVALID_FOLDER	The folderid is invalid – probably does not exist.
23	ERR_INVALID_METADATA	There might be a problem with the meta data that is provided.
24	ERR_INVALID_REASON	The reason might not be provided.
25	ERR_INVALID_DEPTH	The depth might have been specified as a negative number.
99	ERR_DB_PROBLEM	There is a problem accessing the database.