SOAP
OpenKM has a limited API exposed via REST. This means you can call any of these API methods from any programming language, like Java, PHP or Python among others. This feature makes it possible to create a custom client, or integrate with third-party applications like a CRM or a CMS.
SOAP API will no longer be supported, we've bit for RESTful, that's actually more complete. We will continue maintaining SOAP for historical reasons, but in the future we will definitely deprecate it and it'll be removed from OpenKM.
We encourage move to RESTful.
If you point your browser to http://localhost:8080/OpenKM/services, you can see all available webservices. At the beginning you'll see the the Available SOAP services section.
OpenKM SOAP WSDL follow document / literal style. To learn more visit Which style of WSDL should I use?.
You can use MTOM. For more information read Enabling MTOM support in JAX-WS bindings. The feature has been introduced from version 6.4.4.
Java samples
Use Java OpenJDK 1.8 or upper.
Create the client stuff:
$ wsimport -p com.openkm.ws.client -keep http://localhost:8080/OpenKM/services/OKMAuth?wsdl
You can use the following script to generate a complete OpenKM webservices client library:
#/bin/bash
wsimport -p com.openkm.ws.client.auth -keep http://localhost:8080/OpenKM/services/OKMAuth?wsdl
wsimport -p com.openkm.ws.client.bookmark -keep http://localhost:8080/OpenKM/services/OKMBookmark?wsdl
wsimport -p com.openkm.ws.client.document -keep http://localhost:8080/OpenKM/services/OKMDocument?wsdl
wsimport -p com.openkm.ws.client.folder -keep http://localhost:8080/OpenKM/services/OKMFolder?wsdl
wsimport -p com.openkm.ws.client.mail -keep http://localhost:8080/OpenKM/services/OKMMail?wsdl
wsimport -p com.openkm.ws.client.note -keep http://localhost:8080/OpenKM/services/OKMNote?wsdl
wsimport -p com.openkm.ws.client.notification -keep http://localhost:8080/OpenKM/services/OKMNotification?wsdl
wsimport -p com.openkm.ws.client.propertyGroup -keep http://localhost:8080/OpenKM/services/OKMPropertyGroup?wsdl
wsimport -p com.openkm.ws.client.property -keep http://localhost:8080/OpenKM/services/OKMProperty?wsdl
wsimport -p com.openkm.ws.client.repository -keep http://localhost:8080/OpenKM/services/OKMRepository?wsdl
wsimport -p com.openkm.ws.client.search -keep http://localhost:8080/OpenKM/services/OKMSearch?wsdl
wsimport -p com.openkm.ws.client.workflow -keep http://localhost:8080/OpenKM/services/OKMWorkflow?wsdl
jar cvf okm-ws-client-6.2.jar com
rm -rf com
Change address dynamically from a request
OKMAuth okmAuth = new OKMAuth_Service(new URL(url + "/services/OKMAuth?wsdl"),
new QName("http://ws.openkm.com", "OKMAuth")).getOKMAuthPort();
or
((BindingProvider) port).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "192.168.1.64");
Authentication
package com.openkm.ws.test;
import com.openkm.ws.client.auth.OKMAuth;
import com.openkm.ws.client.auth.OKMAuth_Service;
public class Authentication {
public static void main(String[] args) {
try {
OKMAuth okmAuth = new OKMAuth_Service().getOKMAuthPort();
// Login
String token = okmAuth.login("okmAdmin", "admin");
System.out.println("Token: " + token);
// Logout
okmAuth.logout(token);
} catch (Exception e) {
e.printStackTrace();
}
}
}
Metadata groups
package com.openkm.ws.test;
import java.util.ArrayList;
import java.util.List;
import com.openkm.ws.client.auth.OKMAuth;
import com.openkm.ws.client.auth.OKMAuth_Service;
import com.openkm.ws.client.PropertyGroup;
import com.openkm.ws.client.PropertyGroup_Service;
import com.openkm.ws.client.StringPair;
public class PropertyGroups {
public static void main(String[] args) throws Exception {
OKMAuth okmAuth = new OKMAuth_Service().getOKMAuthPort();
OKMPropertyGroup okmPg = new OKMPropertyGroup_Service().getOKMPropertyGroupPort();
// login
String token = okmAuth.login("okmAdmin", "admin");
// property groups
List<StringPair> spList = new ArrayList<StringPair>();
StringPair sp = new StringPair();
sp.setKey("okp:technology.comment");
sp.setValue("Other comment from PHP");
spList.add(sp);
okmPg.setPropertiesSimple(token, "/okm:root/test/hosts.txt", "okg:technology", spList);
// logout
okmAuth.logout(token);
}
}
.NET
Create a single webservice
.Net framework comes with "wsdl.exe" utility ( by default it's not in your environment path).
$ wsdl.exe http://localhost:8080/OpenKM/services/OKMAuth?wsdl /out:AuthService.cs
Create all webservices in one library package
Create file called openkm.wsdl with contents:
<wsdlParameters xmlns="http://microsoft.com/webReference/">
<nologo>true</nologo>
<parsableerrors>true</parsableerrors>
<sharetypes>true</sharetypes>
<documents>
<document>http://localhost:8080/OpenKM/services/OKMAuth?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMBookmark?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMDocument?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMFolder?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMMail?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMNote?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMNotification?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMPropertyGroup?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMProperty?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMRepository?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMSearch?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMWorkflow?wsdl</document>
<document>http://localhost:8080/OpenKM/services/OKMDashboard?wsdl</document>
</documents>
<webReferenceOptions>
<verbose>false</verbose>
<codeGenerationOptions>properties newAsync enableDataBinding</codeGenerationOptions>
<style>client</style>
</webReferenceOptions>
</wsdlParameters>
Execute the command:
$ wsdl.exe /par:openkm.wsdl /out:Webservice.cs /n:OpenKM.ws
If you need a class for VB.net you have to change the command to:
$ wsdl.exe /l:VB /par:openkm.wsdl /out:Webservice.vb /n:OpenKM.ws
Will be create a file named Webservice.cs with namespace OpenKM.ws into.
For more information about wsdl.exe options refer to Web Services Description Language Tool (Wsdl.exe)
Suggested changes in generated classes
Pay attention in public AuthService class ( like others ), it'll be generated some AuthService() constructor that you should like to change to take advantatge of host variable:
public AuthService() {
this.Url = http://127.0.0.1:8080/OpenKM/services/OKMAuth;
}
change to (or create another method with this parameter):
public AuthService(String host) {
this.Url = host + "/OKMAuth";
}
PHP
Remote method info
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
// Disable WSDL cache
ini_set('soap.wsdl_cache_enabled', 0);
ini_set('soap.wsdl_cache_ttl', 0);
ini_set('soap.wsdl_cache', 0);
echo "<br>**** FUNCTIONS ****<br>";
foreach ($OKMAuth->__getFunctions() as $function) {
echo $function."<br>";
}
echo "<br>**** TYPES ****<br>";
foreach ($OKMAuth->__getTypes() as $types) {
echo $types."<br>";
}
?>
Authentication
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token;
// Logout
$OKMAuth->logout(array('token' => $token));
?>
List folders and documents
<?php
function printFolder($folder) {
echo "[FOLDER] Path: ".$folder->path.", Author: ".$folder->author."<br>";
}
function printDocument($document) {
echo "[DOCUMENT] Path: ".$document->path.", Author: ".$document->author.", Size: ".$document->actualVersion->size."<br>";
}
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMDocument = new SoapClient('http://localhost:8080/OpenKM/services/OKMDocument?wsdl');
$OKMFolder = new SoapClient('http://localhost:8080/OpenKM/services/OKMFolder?wsdl');
$path = '/okm:root';
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token."<br>";
echo "Path: ".$path."<br>";
// List folders
$getChildrenResp = $OKMFolder->getChildren(array('token' => $token, 'fldId' => $path));
if (isset($getChildrenResp->return)) {
$folderArray = $getChildrenResp->return;
if ($folderArray) {
if (is_array($folderArray)) {
foreach ($folderArray as $folder) {
printFolder($folder);
}
} else {
printFolder($folderArray);
}
}
}
// List documents
$getChildrenResp = $OKMDocument->getChildren(array('token' => $token, 'dstId' => $path));
if (isset($getChildrenResp->return)) {
$documentArray = $getChildrenResp->return;
if ($documentArray) {
if (is_array($documentArray)) {
foreach ($documentArray as $document) {
printDocument($document);
}
} else {
printDocument($documentArray);
}
}
}
// Logout
$OKMAuth->logout(array('token' => $token));
?>
Create document
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMDocument = new SoapClient('http://localhost:8080/OpenKM/services/OKMDocument?wsdl');
$file = '/etc/hosts';
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token."<br>";
// Create document
$doc = array('path' => '/okm:root/hosts.txt', 'mimeType' => null,
'actualVersion' => null, 'author' => null, 'checkedOut' => false,
'created' => null, 'keywords' => 'test', 'language' => null,
'lastModified' => null, 'lockInfo' => null, 'locked' => false,
'permissions' => 0, 'size' => 0, 'subscribed' => false, 'uuid' => null,
'convertibleToPdf' => false, 'convertibleToSwf' => false,
'compactable' => false, 'training' => false, 'convertibleToDxf' => false,
'signed' => false, 'cipherName' => null, 'subscriptors'=>null, 'title'=>null,
'description'=>null, 'categories'=>null, 'notes'=>null);
$createResp = $OKMDocument->create(array('token' => $token, 'doc' => $doc, 'content' => file_get_contents($file)));
$newDoc = $createResp->return;
echo "[DOCUMENT] Path: ".$newDoc->path.", Author: ".$newDoc->author.", Size: ".$newDoc->actualVersion->size."<br>";
// Logout
$OKMAuth->logout(array('token' => $token));
?>
We encourage using createSimple method rather create method.
About document variables during creation process only will be take on consideration the "path2 variable, the others will be filled internally during creation process.
Create document and set a category
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMDocument = new SoapClient('http://localhost:8080/OpenKM/services/OKMDocument?wsdl');
$OKMProperty = new SoapClient('http://localhost:8080/OpenKM/services/OKMProperty?wsdl');
$OKMRepository = new SoapClient('http://localhost:8080/OpenKM/services/OKMRepository?wsdl');
$file = '/etc/hosts';
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token."<br>";
// Create document
$createResp = $OKMDocument->createSimple(array('token' => $token, 'docPath' => '/okm:root/hosts.txt', 'content' => file_get_contents($file)));
$newDoc = $createResp->return;
echo "[DOCUMENT] Path: ".$newDoc->path.", Author: ".$newDoc->author.", Size: ".$newDoc->actualVersion->size."<br>";
// Category assign
$getNodeUuid = $OKMRepository->getNodeUuid(array('token' => $token, 'path' => '/okm:categories/invoice'));
$catId = $getNodeUuid->return;
$OKMProperty->addCategory(array('token' => $token, 'nodeId' => $newDoc->path, 'catId' => $catId));
// Logout
$OKMAuth->logout($token);
?>
Search by content
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMSearch = new SoapClient('http://localhost:8080/OpenKM/services/OKMSearch?wsdl');
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token."<br>";
$findByContentResp = $OKMSearch->findByContent(array('token' => $token, 'content' => 'test'));
if (isset($getChildrenResp->return)) {
$queryResultArray = $findByContentResp->return;
if ($queryResultArray) {
if (is_array($queryResultArray)) {
foreach ($queryResultArray as $queryResult) {
echo "-> ".$queryResult->document->path." (".$queryResult->score.")<br>";
}
} else {
echo "-> ".$queryResultArray->document->path." (".$queryResultArray->score.")<br>";
}
}
}
// Logout
$OKMAuth->logout(array('token' => $token));
?>
Search with parameters
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMSearch = new SoapClient('http://localhost:8080/OpenKM/services/OKMSearch?wsdl');
// Login
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token."<br>\n";
$qp = new QueryParams();
$qp->domain = 1; // DOCUMENT = 1; FOLDER = 2; MAIL = 4; DOCUMENT & FOLDER = 3; etc..
$qp->content = 'test';
$findResp = $OKMSearch->find(array('token' => $token, 'params' => $qp));
if (isset($getChildrenResp->return)) {
$queryResultArray = $findResp->return;
if ($queryResultArray) {
if (is_array($queryResultArray)) {
foreach ($queryResultArray as $queryResult) {
echo "-> ".$queryResult->document->path." (".$queryResult->score.")<br>\n";
}
} else {
echo "-> ".$queryResultArray->document->path." (".$queryResultArray->score.")<br>";
}
}
}
// Logout
$OKMAuth->logout(array('token' => $token));
class QueryParams {
var $content = '';
var $dashboard = false;
var $domain = 0;
var $id = 0;
var $properties = array();
}
?>
Set metadata group values
The metadata group definition used:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 2.0//EN"
"http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
<property-group label="Technology" name="okg:technology">
<select label="Type" name="okp:technology.type" type="multiple">
<option label="Alfa" value="t1"/>
<option label="Beta" value="t2" />
<option label="Omega" value="t3" />
</select>
<select label="Language" name="okp:technology.language" type="simple">
<option label="Java" value="java"/>
<option label="Python" value="python"/>
<option label="PHP" value="php" />
</select>
<input label="Comment" name="okp:technology.comment"/>
<textarea label="Description" name="okp:technology.description"/>
<input label="Link" type="link" name="okp:technology.link"/>
</property-group>
</property-groups>
The node must already have set the group, otherwise you'll get an error when trying to set values of a non previous added metadata group.
<?php
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMPropertyGroup = new SoapClient('http://localhost:8080/OpenKM/services/OKMPropertyGroup?wsdl');
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
echo "Token: ".$token;
$docPath = "/okm:root/hosts.txt";
$entry['key'] = 'okp:technology.comment';
$entry['value'] = 'Other comment from PHP 3';
$properties = array($entry);
$OKMPropertyGroup->setPropertiesSimple(array('token' => $token, 'nodeId' => $docPath, 'grpName' => 'okg:technology', 'properties' => $properties));
$OKMAuth->logout($token);
?>
Exception handling
The "finally" has been introduced from PHP version 5.5.
<?php
// Register WSDL
$OKMAuth = new SoapClient('http://localhost:8080/OpenKM/services/OKMAuth?wsdl');
$OKMDocument = new SoapClient('http://localhost:8080/OpenKM/services/OKMDocument?wsdl');
function format_exception($e) {
if (isset($e->detail)) {
$reflectionObject = new ReflectionObject($e->detail);
$properties = $reflectionObject->getProperties();
$exceptionName = $properties[0]->name;
} else {
$exceptionName = "Exception";
}
return $exceptionName.": ".$e->faultstring;
}
try {
$loginResp = $OKMAuth->login(array('user' => 'okmAdmin', 'password' => 'admin'));
$token = $loginResp->return;
$getPropertiesResp = $OKMDocument->getProperties(array('token' => $token, 'docPath' => '/okm:root/nofile.txt'));
$docProps = $getPropertiesResp->return;
print_r($docProps);
} catch (Exception $e) {
echo format_exception($e);
}
$OKMAuth->logout(array('token' => $token));
?>
Proxy configuration
$client = new SoapClient("some.wsdl", array('proxy_host' => "https://example.org", 'proxy_port' => 443);