Create your own import station plugin

Para crear su propio plugin de importación, debe crear una nueva clase que implemente la interfaz PropertiesProcessor:

public interface PropertiesProcessor extends Plugin {
    String getName();
    String getDescription();
    Class<?> getFormBeanClass();
    boolean doJob(long executionTaskId, FormProperties formProperties, OKMWebservices webService);
    String getAddTaskFormName();
    String getEditTaskFormName();
}

Precaución

No olvide la etiqueta @PluginImplementation; de lo contrario, el sistema de plugins de la aplicación no podrá recuperar la nueva clase.

La nueva clase debe cargarse en el paquete com.openkm.processor, porque el sistema de plugins de la aplicación intentará cargarla desde ahí.

Descripción de los métodos

Método	Retorno	Descripción
getName()	String	Este método proporcionará el nombre del plugin.
getDescription()	String	Descripción detallada del plugin que se muestra bajo el combo llamado “Processor” en la vista de edición de tareas.
getFormBeanClass()	Class<?>	Devuelve el bean usado para almacenar la información del formulario de la aplicación.
doJob(long executionTaskId, FormProperties formProperties, WsInterface wsInterface)	boolean	Este es el método principal del plugin.
getAddTaskFormName()	String	Devuelve el nombre del formulario usado para crear propiedades.
getEditTaskFormName()	String	Devuelve el nombre del formulario usado para editar propiedades.

Bean del formulario

El plugin debe tener asociada una clase bean que se usa para establecer las propiedades personalizadas del plugin. Estas propiedades se almacenarán en un mapa llamado customProperties.

La clase Form bean debe extender la clase FormProperties.

Nota

Puede obtener estos valores de propiedad desde el objeto formProperties en el método doJob. El objeto formProperties tiene un campo llamado customProperties.

Precaución

Restricciones:

• Las claves del mapa deben coincidir con los nombres del formulario HTML.

Ejemplo:

Por ejemplo, si queremos almacenar una propiedad String llamada path en este formulario, el nombre del campo del formulario HTML debe ser <input name=“path” …>.

Formularios HTML

El plugin debe tener dos formularios:

• Formulario de creación de tarea.
• Formulario de edición de tarea.

Deben ubicarse en la carpeta src/main/html.

Nota

Necesitamos estos formularios porque cada plugin tendrá sus propias propiedades personalizadas.

La convención de nombres debería ser: <name_of_plugin>-form.html y <name_of_plugin>-form-edit.html, aunque pueden ser cualquier nombre.

Esta convención es útil para evitar sobrescribir formularios predefinidos.

Ejemplo:

• Clase del plugin en src/main/java/com/openkm/processor/ExampleProcessor.class
• Formulario de creación en src/main/html/ExampleProcessor-form.html
• Formulario de edición en src/main/html/ExampleProcessor-form.html

Estos formularios se cargarán en las pantallas web de Add Task y Edit Task cuando cambie el combo de processor.

Deben contener el código HTML y JavaScript necesario para guardar y cargar las propiedades del Processor.

Precaución

En el formulario de edición, para rellenar los campos automáticamente debe usar la clase class=“form-control parameter”.

Por ejemplo:

Esto establecerá el parámetro userPath en el campo cuyo nombre sea “userPath”.

Registro de eventos

La aplicación cuenta con una funcionalidad de registro que proporciona una traza completa de lo que ocurre al procesar una tarea.

Nota

Registrar eventos o no es una decisión de implementación de quien diseña el plugin. Recomendamos registrar todos los eventos; sin embargo, es decisión de quien diseña el plugin hacerlo o no.

Para este propósito, la clase usada para registrar eventos es ImportStationLogger.

Los siguientes métodos están disponibles:

Método	Retorno	Descripción
logOk(long taskExecutionId, String description)	void	Registra un evento para indicar que la operación fue correcta
logErrorEvent(long taskExecutionId, String description)	void	Registra un evento para indicar que hubo un error.
logErrorEvent(long taskExecutionId, String header, Exception e)	void	Registra un evento para indicar que hubo un error. Este método registrará la traza de la excepción como descripción. El parámetro header se usa para añadir un mensaje de registro a la traza de la excepción.

Ejemplo:

long taskExecutionId = ...;
// Mark as ok
ImportStationLogger.logOkEvent(taskExecutionId, "description");
// Mark with errors
ImportStationLogger.logErrorEvent(taskExecutionId, "description of error");
// Mark with error and exception detail
ImportStationLogger.logErrorEvent(taskExecutionId, "header", new Exception("exception"));

Ejemplo

Este es un ejemplo de configuración de pom.xml:

Nota

Puede descargar el código fuente de ejemplo aquí: import-station-example-plugin.zip

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>copm</groupId>
  <artifactId>com</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>example</name>
  <properties>
    <java.version>11</java.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <openkm-sdk4j.version>4.1</openkm-sdk4j.version>
    <jspf.version>1.0.3.1</jspf.version>
    <openkm-import-station-core.version>3.0</openkm-import-station-core.version>
  </properties>
  <repositories>
    <repository>
      <id>openkm.com</id>
      <name>OpenKM Maven Repository</name>
      <url>https://maven.openkm.com</url>
    </repository>
  </repositories>
  <dependencies>
    <dependency>
      <groupId>com.openkm</groupId>
      <artifactId>import-station-core</artifactId>
      <version>${openkm-import-station-core.version}</version>
      <classifier>core</classifier>
    </dependency>
    <!-- Plugin framework -->
    <dependency>
      <groupId>com.google.code</groupId>
      <artifactId>jspf.core</artifactId>
      <version>${jspf.version}</version>
    </dependency>
    <!-- OpenKM SDK -->
    <dependency>
      <groupId>com.openkm</groupId>
      <artifactId>sdk4j</artifactId>
      <version>${openkm-sdk4j.version}</version>
      <exclusions>
        <exclusion>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-log4j12</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
  </dependencies>
  <build>
    <resources>
      <resource>
        <directory>src/main/html</directory>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.1</version>
        <configuration>
          <source>${java.version}</source>
          <target>${java.version}</target>
          <encoding>UTF-8</encoding>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.19.1</version>
      </plugin>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Clase ExampleProcessor:

Consejo

Descripción: importa solo los ficheros de una carpeta origen específica.

@PluginImplementation
public class ExampleProcessor implements PropertiesProcessor {

    @Override
    public boolean doJob(long executionTaskId, FormProperties formProperties, OKMWebservices webServices) {
        boolean returnValue = true;
        File folder = new File((String) formProperties.getCustomPropertiesMap().get(ProcessorConstants.USER_PATH));
        if (folder.exists() && folder.isDirectory()) {
            for (File file : folder.listFiles()) {
                if (file.isFile() && file.canRead()) {
                    try {
                        uploadDocument(file, formProperties, webServices);
                        ImportStationLogger.logOkEvent(executionTaskId, "File uploaded: " + file.getName());
                    } catch (IOException | UnsupportedMimeTypeException | FileSizeExceededException | UserQuotaExceededException
                            | VirusDetectedException | ItemExistsException | PathNotFoundException | AccessDeniedException
                            | RepositoryException | DatabaseException | ExtensionException | AutomationException
                            | UnknowException | WebserviceException e) {
                        ImportStationLogger.logErrorEvent(executionTaskId, "Error uploading file" + file.getName(), e);
                        returnValue = false;
                    }
                }
            }
        }
        return returnValue;
    }

    private void uploadDocument(File file, FormProperties formProperties, OKMWebservices webServices) throws IOException, UnsupportedMimeTypeException,       FileSizeExceededException, UserQuotaExceededException, VirusDetectedException, ItemExistsException, PathNotFoundException, AccessDeniedException,       RepositoryException, DatabaseException, ExtensionException, AutomationException, UnknowException, WebserviceException {
        String fldPath = formProperties.getObjectProperty(ProcessorConstants.DESTINY_PATH);
        String docName = FilenameUtils.getBaseName(file.getName()) + "." + FilenameUtils.getExtension(file.getName());
        String fldUuid = webServices.repository.getNodeUuid(fldPath);

        // Create document
        webServices.document.create(fldUuid, docName, FileUtils.openInputStream(file));
    }

    @Override
    public String getAddTaskFormName() {
        return "ExampleProcessor-form.html";
    }

    @Override
    public String getDescription() {
        return "This is my custom form";
    }

    @Override
    public String getEditTaskFormName() {
        return "ExampleProcessor-form-edit.html";
    }

    @Override
    public Class<?> getFormBeanClass() {
        return ExampleFormProperties.class;
    }

    @Override
    public String getName() {
        return "ExampleProcessor";
    }

}

Código del bean. Solo almacena la ruta local del usuario y la ruta de destino en OpenKM:

Clase ExampleFormProperties:

Consejo

Descripción:

• Establece la ruta de la carpeta origen.
• Establece la carpeta de destino en OpenKM.

public class ExampleFormProperties extends FormProperties {

    /**
     * Public constructor.
     *
     * @param parameterMap
     *        map with values
     */
    public ExampleFormProperties(final Map<String, Object> parameterMap) {
        super(parameterMap);

        // Add custom properties
        addProperty(ProcessorConstants.USER_PATH,
                parameterMap.get(ProcessorConstants.USER_PATH) instanceof String[]
                        ? ((String[]) parameterMap.get(ProcessorConstants.USER_PATH))[0]
                        : parameterMap.get(ProcessorConstants.USER_PATH));
        addProperty(ProcessorConstants.DESTINY_PATH,
                parameterMap.get(ProcessorConstants.DESTINY_PATH) instanceof String[]
                        ? ((String[]) parameterMap.get(ProcessorConstants.DESTINY_PATH))[0]
                        : parameterMap.get(ProcessorConstants.DESTINY_PATH));
    }

}

ExampleProcessor-form.html

Consejo

Descripción:

• Campo de formulario para la carpeta origen.
• Campo de formulario para la carpeta destino.

<div class="form-group">
  <label class="control-label col-sm-2" for="userPath">User path:</label>
  <div class="col-sm-10">
    <input type="text" class="form-control" name="userPath"
      placeholder="user path" required />
  </div>
</div>
<div class="form-group">
  <label class="control-label col-sm-2" for="destinyPath">Destiny path into OpenKM:</label>
  <div class="col-sm-10">
    <input type="text" class="form-control" name="destinyPath" placeholder="/okm:root/import/" required />
  </div>
</div>

ExampleProcessor-form-edit.html

Consejo

Descripción:

• Campo de formulario para la carpeta origen.
• Campo de formulario para la carpeta destino.

Nota: los campos tienen una clase llamada “parameter” para su inicialización automática.

<div class="form-group">
  <label class="control-label col-sm-2" for="userPath">User path:</label>
  <div class="col-sm-10">
    <input type="text" class="form-control parameter" name="userPath"
      value="${userPath}" required />
  </div>
</div>
<div class="form-group">
  <label class="control-label col-sm-2" for="destinyPath">Destiny path into OpenKM:</label>
  <div class="col-sm-10">
    <input type="text" class="form-control parameter" name="destinyPath" placeholder="/okm:root/import/" required />
  </div>
</div>