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. 

Caution

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.

Note

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.

Tip

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

Note

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

Note

.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

Note

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.

Note

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

Note

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>

Note

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

Note

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);