SOAP

OpenKM tiene una API limitada expuesta mediante REST. Esto significa que puede llamar a cualquiera de estos métodos de la API desde cualquier lenguaje de programación, como Java, PHP o Python, entre otros. Esta funcionalidad permite crear un cliente personalizado o integrarse con aplicaciones de terceros como un CRM o un CMS. 

Precaución

La API SOAP dejará de recibir soporte; hemos apostado por RESTful, que en realidad es más completa. Seguiremos manteniendo SOAP por motivos históricos, pero en el futuro la declararemos obsoleta y se eliminará de OpenKM.

Le animamos a migrar a RESTful.

Nota

Si dirige su navegador a http://localhost:8080/OpenKM/services, podrá ver todos los servicios web disponibles. Al principio verá la sección Available SOAP services.

Consejo

El WSDL SOAP de OpenKM sigue el estilo document / literal. Para saber más, visite Which style of WSDL should I use?.

Puede utilizar MTOM. Para más información, lea Enabling MTOM support in JAX-WS bindings. La funcionalidad se introdujo a partir de la versión 6.4.4.

Ejemplos en Java

Nota

Utilice Java OpenJDK 1.8 o superior.

Cree lo necesario para el cliente:

$ wsimport -p com.openkm.ws.client -keep http://localhost:8080/OpenKM/services/OKMAuth?wsdl

Puede utilizar el siguiente script para generar una biblioteca cliente completa de los servicios web de OpenKM:

/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

Cambiar la dirección dinámicamente desde una petición

OKMAuth okmAuth = new OKMAuth_Service(new URL(url + "/services/OKMAuth?wsdl"),
    new QName("http://ws.openkm.com", "OKMAuth")).getOKMAuthPort();

o

((BindingProvider) port).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "192.168.1.64");

Autenticación

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

Grupos de metadatos

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

Crear un único servicio web

Nota

.NET Framework incluye la utilidad “wsdl.exe” (por defecto no está en la variable de entorno path).

$ wsdl.exe http://localhost:8080/OpenKM/services/OKMAuth?wsdl /out:AuthService.cs

Crear todos los servicios web en un único paquete de biblioteca 

Cree un archivo llamado openkm.wsdl con el siguiente contenido:

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

Ejecute el comando:

$ wsdl.exe /par:openkm.wsdl /out:Webservice.cs /n:OpenKM.ws

Nota

Si necesita una clase para VB.net, debe cambiar el comando por:

$ wsdl.exe /l:VB /par:openkm.wsdl /out:Webservice.vb /n:OpenKM.ws

Se creará un archivo llamado Webservice.cs con el espacio de nombres OpenKM.ws.

Nota

Para más información sobre las opciones de wsdl.exe, consulte Web Services Description Language Tool (Wsdl.exe)

Cambios sugeridos en las clases generadas

Preste atención a la clase pública AuthService (como a las demás): se generará un constructor AuthService() que conviene cambiar para aprovechar la variable host:

public AuthService() {
    this.Url = http://127.0.0.1:8080/OpenKM/services/OKMAuth;
}

cámbielo por (o cree otro método con este parámetro): 

public AuthService(String host) {
    this.Url = host + "/OKMAuth";
}

PHP

Información de los métodos remotos

<?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>";
  }
?>

Autenticación

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

Listar carpetas y documentos

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

Crear un documento

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

Nota

Le recomendamos utilizar el método createSimple en lugar del método create.

Respecto a las variables del documento, durante el proceso de creación solo se tendrá en cuenta la variable “path2”; el resto se rellenarán internamente durante el proceso de creación.

Crear un documento y asignar una categoría

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

Buscar por contenido

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

Buscar con parámetros

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

Establecer los valores de un grupo de metadatos

La definición del grupo de metadatos utilizada:

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

Nota

El nodo debe tener ya asignado el grupo; de lo contrario, obtendrá un error al intentar establecer valores de un grupo de metadatos que no se ha añadido previamente.

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

Gestión de excepciones

Nota

“finally” se introdujo a partir de la versión 5.5 de PHP.

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

Configuración del proxy

$client = new SoapClient("some.wsdl", array('proxy_host' => "https://example.org", 'proxy_port' => 443);