Introducción al API de Activiti

Introducción al API de Activiti

0. Índice de contenidos.

• 1. Introducción.
• 2. Entorno.
• 3. Notación básica BPMN en formato XML de Activiti.
• 4. Construir el diagrama BPM en Activiti.
• 5. Creación de la librería de Activi en Eclipse.
• 6. Configuración del esquema BPMN 2.0 en Eclipse.
• 7. Probar nuestro proceso con JUnit.
• 8. Conclusiones.

1. Introducción

En este tutorial se va continuar enseñando a utilizar la herramienta de BPM Activiti
pero esta vez centrándonos en implementar un proceso de BPM básico de Activiti en el lenguaje Java
usando para ello la herramienta de desarrollo Eclipse.

Para la buena comprensión de este tutorial se aconseja leer previamente el siguiente tutorial : Introducción a Activiti

Nos basaremos en la eleción de un ejemplo «muy básico» que nos sirva para entender como fuciona Activi
en esta parte de forma conceptual.El ejemplo elegido es el siguiente :

• Un estado inicial que se llama «inicio»
• Un tarea que se denomina «tarea»
• Un flujo denominado «flujo1» que conecta el estado inicial con la tarea
• Un flujo denominado «flujo2» que conecta la tarea con el estado final
• Un estado final que se llama «fin»

Comenzamos con la implementación….

2. Entorno.

El tutorial está escrito usando el siguiente entorno:

• Hardware: Portátil Asus G50Vseries (Core Duo P8600 2.4GHz, 4GB RAM,320 GB HD).
• Sistema operativo: Windows Vista Ultimate.
• Mozilla Firefox 2.0.0.20
• Apache Tomcat 6.0.26
• Activiti Alpha 3
• Eclipse Java EE IDE

3. Notación básica BPMN en formato XML de Activiti.

En este punto se va a explicar los elementos más comunes de BPMN cuando se implementa
sobre un fichero de XML en la herramienta Activiti.

Para explicar mejor esta parte vamos a realizar una serie de modificaciones sobre un fichero de prueba
que generaremos, asi ire explicando diferentes puntos de la implementación sobre ese fichero de ejemplo.

Antes de comenzar con la explicación, generamos un fichero que tenga como extensión «.bpmn20.xml» , el motivo
por el que se tiene que finalizar el el fichero de la anterior forma viene dado porque esa extensión es reconocida
por el motor de Activi, por lo que los ficheros que finalicen de esta forma serán tratados por Activi.

Vamos a crear una definición de un proceso BPMN 2.0 en XML :

1) Este fichero al ser un XML deberá de comenzar por la siguiente línea : <?xml version=»1.0″ encoding=»UTF-8″?>

2) Una vez tengamos la anterior línea incorporaremos la siguiente parte :

El elemento raiz en un schema BPMN 2.0 es el elemento : definitions

3) Crearemos un proceso dentro de las etiquetas de definitions para ello introduciremos el siguiente código :

El elemento proceso tiene 2 atributos :

• id :Identificador que se asigna a la propiedad clave en Activiti (Es un atributo obligatorio)
• name :Nombre que de una ProcessDefinition (Es un atributo opcional)

Tipos de elementos :

– Tarea de usuario (User Task)

Es una actividad que necesita ser realizado por un actor humano (usuario o assigne en terminología
Activi). [Ver Ejemplo 1]

Cuando se crea una de estas tareas se asigna a un usuario/s o grupo.

Este tipo de tareas pueden tener asociada una descripción que se implementa mediante
el elemento : documentation [Ver Ejemplo 2].

Nota : La notacion BPMN 2.0 indica que cualquiera de sus elementos puede tener asociada
una descripción. Pero hasta la fecha solamente se puede incorporar la descripción a este tipo
de tareas.

Como son tareas asociados a un actor humano significa que podremos asociarlas de alguna forma
a alguno de los usuarios. Para ellos se utiliza el elemento : humanPerformer [Ver Ejemplo 3].

Nota : Para poder definir un usuario el elemento humanPerformer requiere del elmento resorceAssignmentExpresion
que define el usuario y este a su vez uso del elemento formalExpresion (que es la única forma que
esta soportada a día de hoy) [Ver Ejemplo 4].

Importante : únicamente se puede asociar un usuario a una User Task.

Otra cosa que se puede realizar con este tipo de tareas es la asignación a lo que se denominan usuarios
potenciales (candidatos). Para ello se utiliza el elemento : potencialOwner y requiere definir en el elemento
formalExpresion si nos estamos refiriendo a un usuario (user(XXX) o a un grupo ( group(YYY) [Ver Ejemplo 5].

Nota : Si no indicamos el tipo de elemento user o group el elemento por defecto es el grupo.

Debido a que esto puede llegar a ser un poco engorroso, se han habilitado algunos atributos de extensión
sobre el elemento userTask para simplificar al máximo esta parte.

• assigne :Asigna un usuario directamente [Ver Ejemplo 6]
• candidateUsers :Permite establecer candidatos a la tarea [Ver Ejemplo 7]
• candidateGroup :Permite establecer los grupos de las tareas [Ver Ejemplo 8]

Representación :

  
  
  
  
  
  Descripcion de la tarea  
    
  
  
  
    
      
      Victor  
      
    
  
  
  
  
    
      
      user(Victor), group(management)  
      
    
  
  
  
  
    
      
      management  
      
    
  
  
  
  
  
  
  
  
  
  
  
  

Es cierto, que faltan algunos elementos para completar esta lista pero ya los iré introduciendo en próximos

tutoriales.
4. Construir el diagrama BPM en Activiti.
Tenemos dos opciones para construir el diagrama con notación BPMN en Activiti :
1) Usando la herramienta Modeler facilitada por Activiti
Nota: Se aconseja revisar el tutorial mencionado en el punto de introducción.
Para ello generamos el diagrama anterior mediante esta herramienta.

Guardamos el modelo, por lo que quedará almacenado en el repositorio de modelos que

se encuentra disponible en el ACTIVITI_HOME/apps/activiti-model-repository pudiendo

encontrarse almacenado en algún directorio establecido (en nuestro caso Autentia). 

Como podéis ver se han generado dos ficheros :
-> miProceso.bpmn20.xml
Fichero en el que se detalla de forma automática la expresión del diagrama anterior en formato

XML.

    
        
            
                oryx_383180C9-774A-4AC3-8C04-B8305EBC445E
                oryx_80C1A0B7-5F2E-4119-8F46-B38119A215B0
                oryx_AEB3AB31-D851-450B-874F-2E5807333425
            
        
        
        
        
        
            flujo1
        
        
            flujo2

        
    
    
        
            
            
            
        
        
        
    


Nota : A este fichero le he quitado para mostrarlo de esta forma la línea  : <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
Por lo que se recuerda incorporarla si se copia este código.
Aspectos a tener en cuenta de este fichero :

El código ha sido generado automáticamente por lo que puede haber cosas que no nos faciliten su entendimiento (como casi siempre

  que utilizamos un herramienta que genera código de forma automática 🙂 )
Los identificadores que ha generado han sido automáticos por lo que no son demasiado intuitivos 
El orden de declaración de los elementos sigue su estructura interna
Etc...

-> miProceso.oryx.xml
Fichero utilizado para definir el modelo.

  
  BPMN 2.0
  
                                                                                        tarea                                                                                                                                                                                                              inicio                                  fin   flujo1flujo2]]>


Nota : A este fichero le he quitado para mostrarlo de esta forma la línea  : <?xml version="1.0" encoding="utf-8"?>
Por lo que se recuerda incorporarla si se copia este código.
2) Definiendo el diagrama en un XML
Fichero en el que una vez conocemos la notación en XML podemos definir los diagramas

	
	
	
		
		
		

		
		  Descripcion tarea
		  
		    
		      victor
		    
		  
		
		
		
		
		
		
	



Nota : A este fichero le he quitado para mostrarlo de esta forma la línea  : <?xml version="1.0" encoding="UTF-8"?>
Por lo que se recuerda incorporarla si se copia este código.

5. Creación de la librería de Activi en Eclipse.
En este punto se enseñará a crear la librería de Activi de la que hará uso nuestro proyecto  :
PASO 1 : Accedemos desde Eclipse a Windows -> Preference 

PASO 2 : Seleccionamos Java -> Build Path -> User Libraries 

PASO 3 : Introducimos una nueva librería mediante la opción New... a la que denominamos Activi 

Una vez aceptado se creará la biblioteca pero estará vacia de contenido

PASO 4 : Incorporarmos los JAR del proyeco Activi, para ellos seleccionamos la opcion Add JARs... y añadimos todas las

librerias que se encuentran en el directorio de instalacion de Activi salvo las que contienen "-sources"

Situación final de la librería :

6. Configuración del esquema BPMN 2.0 en Eclipse.
En este punto se enseñará a configurar el esquema de BPMN 2.0 en el catálogo de XML de Eclipse
PASO 1 : Accedemos desde Eclipse a Windows -> Preference 

PASO 2 : Seleccionamos XML -> XML Catalog 

PASO 3 : Introducimos un nuevo esquema en los catalogos definidos de Eclipse pulsando sobre Add... y

seleccionando el fichero BPMN20.xsd que se encuentran en directorio de instalación de Activiti /docs/xsd/BPMN20.xsd  

PASO 4 : Verificar que ha sido incluido  

7. Probar nuestro proceso con JUnit.
Para poder probar nuestro proceso tendremos que crear un test en JUnit, para ello seguiremos los

siguienes pasos :
PASO 1 : Creamos un nuevo proyecto de Java Básico , en mi caso "Proyecto_Activi".
PASO 2 : Incluimos la librería de Activiti que ha sido creada anteriormente.
PASO 3 : Creamos un paquete en src que se denomine : com.acme.activiti.ejemplo1

PASO 4 : Creamos en el interior del paquete un fichero : MiProceso.bpmn20.xml

Le incorporamos el siguiente contenido que ha sido definido manualmente.
 
	
	
	
		
		
		

		
		  Descripcion tarea
		  
		    
		      victor
		    
		  
		
		
		
		
		
		
	



Nota : A este fichero le he quitado para mostrarlo de esta forma la línea  : <?xml version="1.0" encoding="UTF-8"?>
Por lo que se recuerda incorporarla si se copia este código.

PASO 5 : Creamos en el nivel de src el fichero : activiti.properties 
Este fichero contendrá el siguiente contenido :
database=h2
jdbc.driver=org.h2.Driver
jdbc.url=jdbc:h2:mem:activiti
jdbc.username=sa
jdbc.password=
db.schema.strategy=create-drop
job.executor.auto.activate=off

Este fichero configura el uso de la base de datos H2 que como se puede ver se ejecutará en

memoria y cada vez será creada-borrada.

PASO 6 : Creamos un test de JUnit para probar nuestro proceso en el paquete anterior : MiProcesoTest  

Este fichero contendrá las comprobaciones para verficar que es nuestro proceso :
package com.acme.activiti.ejemplo1;

import static org.junit.Assert.assertEquals;

import java.util.List;

import org.activiti.ProcessInstance;
import org.activiti.Task;
import org.activiti.test.ProcessDeclared;
import org.activiti.test.ProcessDeployer;
import org.junit.Rule;
import org.junit.Test;

public class MiProcesoTest {

  /**
   * Se encarga de lanzar el proceso	
   */
  @Rule
  public ProcessDeployer deployer = new ProcessDeployer();

  /**
   * Test que prueba nuestro proceso
   * Se le indica el proceso mediante la anotacion @ProcessDeclares
   */
  @Test
  @ProcessDeclared(resources={"MiProceso.bpmn20.xml"})
  public void testMiProceso() {    
    
    //Inicia la instancia del proceso definido en base a su identificador
    ProcessInstance processInstance = deployer.getProcessService().startProcessInstanceByKey("miProceso");

    //Comprobación de si la instancia del proceso ha sido completada 
    deployer.expectProcessEnds(processInstance.getId());
    
    //Muestra información sobre la instancia del proceso
    System.out.println("[PROCESO] id :"+processInstance.getId()+" | process definition id :"+processInstance.getProcessDefinitionId()+"\n");

    //Devuelve la lista de tareas asignadas a victor y verífica que solamente hay una (La indicada en el proceso)
    List tasksAssigned = deployer.getTaskService().findAssignedTasks("victor");
    System.out.println("Lista de tareas asignadas a victor...\t: "+tasksAssigned.size()+" tareas");
    assertEquals(1, tasksAssigned.size());
    
    //Devuelve la lista de tareas que no asignadas a victor y verifica que no hay ninguna
    List tasksUnassigned = deployer.getTaskService().findUnassignedTasks("victor");
    System.out.println("Lista de tareas NO asignadas a victor...\t: "+tasksUnassigned.size()+" tareas");
    assertEquals(0, tasksUnassigned.size());
    
    //Lista de tareas asignadas
    if (!tasksAssigned.isEmpty()){
    	
    	//Mostrar las tareas asignadas
    	System.out.println("\nLista de tareas asignadas a victor...");
    	for (Task t : tasksAssigned){
    		System.out.println("[TAREA] id :"+t.getId()+" | name :"+t.getName()+" | process definition id :"+t.getProcessDefinitionId()+" | assignee :"+t.getAssignee());
    	}
    	
    	//Verificar que la primera tarea es la establecida
    	Task myTask = tasksAssigned.get(0);
        assertEquals("Mi primera tarea", myTask.getName());
        assertEquals("Descripcion tarea", myTask.getDescription());
        
        // Completar la tarea por lo que el proceso habrá finalizado
        deployer.getTaskService().complete(myTask.getId());
    } 
    
    
  }

}


PASO 7 : Ejecutamos el test 

Con la ejecución de este test verificaremos que hemos realizado bien nuestro proceso,

aunque no tiene demasiado misterio nuestro proceso debido a que era muy sencillito 😉

8. Conclusiones.
Como habéis podido comprobar esto del BPM tiene su miga y más si empezamos a hacer cosas

un poquito serías.Prometo empezar a complicar los modelos en los próximos tutoriales para que

asi podáis ver la potencia de esta gran herramienta.Espero haberos podido ayudar a entender un

poquito mejor como funciona Activiti a la hora de implementar y utilizar los modelos.