kbee.

workflow Tutorial

Propiedades del documento

Proyecto:

kbee.workflow
Ttulo del documento:

Tutorial

Fecha de versin:

20/11/08
Nmero de versin:

V004
Autor:

Novamens

1
1.1

Introduccin..................................................................................................................................................3
Objetivo............................................................................................................................................................................ 3

2
2.1 2.2

El Problema: publicacin de notas en un medio editorial..................................................................4

Descripcin ...................................................................................................................................................................... 4 Anlisis............................................................................................................................................................................. 4

3
3.1 3.2 3.3 3.4 3.5

Solucin.........................................................................................................................................................6
Configuracin................................................................................................................................................................... 6 Contextos......................................................................................................................................................................... 7 Comunicacin.................................................................................................................................................................. 9 Tareas.............................................................................................................................................................................. 9 Triggers.......................................................................................................................................................................... 12

4
4.1 4.2 4.3

Ejecucin y Pruebas .................................................................................................................................14

Consola Web ................................................................................................................................................................. 14 Lanzamiento de Procesos ............................................................................................................................................ 15 Monitoreo WQL ............................................................................................................................................................. 16

v.004 | kbee.workflow | Tutorial

Pgina 2 de 16

1 Introduccin
1.1 Objetivo
El objetivo de este Tutorial es la solucin de un problema de referencia simple, en el que se puedan mostrar detalles del funcionamiento del kbee.workflow. La red con la especificacin completa del procedimiento de la solucin esta incluida en la distribucin bajo el nombre de publicacin_nota. Para poder ver y revisar la especificacin se debe, con el server en funcionamiento, abrir en el Eclipse la vista correspondiente (Window>Show View->Others->Workflow->Servers) y el procedimiento mencionado.

v.004 | kbee.workflow | Tutorial

Pgina 3 de 16

2 El Problema: publicacin de notas en un medio editorial

2.1 Descripcin
Se necesita implementar un ciclo de produccin editorial para la publicacin de notas en una editorial: El proceso se dispara por un pedido de algn responsable que solicita una nota sobre un tema dado Luego la redaccin de la nota debe ser llevada a cabo por un redactor, Luego la nota debe ser corregida por alguno de los usuarios miembros del plantel de correctores (en este problema, alcanza con que cualquiera de los usuarios miembros del plantel de correctores tome la tarea de corrgir la nota). y finalmente debe ser aprobada por un supervisor antes de su publicacin. adems se requiere que se desestime el pedido en caso de que un redactor no tome la tarea de redaccin de un plazo se tiempo acotado. Como requerimiento no funcional se aclara que toda la solucin debe ser Web.

2.2 Anlisis
Como parte del anlisis y elaboracin del problema, y previo a su construccin, se puede dibujar y documentar el procedimiento requerido. El siguiente formato es independiente de la tecnologa y solo se muestra a manera de sugerencia y como mecanismo de especificacin en detalle del problema de referencia:

2.2.1

Tarea de redaccin

Especificacin: un redactor debe redactar una nota de acuerdo a las indicaciones recibidas. Precondicin: comienzo del proceso. Disparador: manual. El usuario habilitado indica comienzo y fin de tarea.

v.004 | kbee.workflow | Tutorial

Pgina 4 de 16

Actor: redactor. Poscondicin: nota redactada.

2.2.2 Tarea de correccin

Especificacin: un corrector debe realizar correcciones ortogrficas y de forma sobre el trabajo del redactor. Precondicin: nota redactada. Disparador: manual. El usuario habilitado indica comienzo y fin de tarea. Actor: corrector. Poscondicin: nota corregida.
2.2.3 Tarea de aprobacin

Especificacin: el usuario responsable debe aprobar o rechazar el trabajo realizado. Precondicin: nota corregida. Disparador: manual. El usuario habilitado indica comienzo y fin de tarea. Actor: supervisor. Poscondicin: nota aprobada para publicacin o rechazada y enviada nuevamente al redactor.
2.2.4 Tarea de publicacin

Especificacin: tarea automtica que publica la nota aprobada. La publicacin, por ejemplo, podra implicar generacin de un HTML y la copia a un portal pblico. Precondicin: nota aprobada. Cuando se cumple la precondicin la tarea se ejecuta. Disparador: automtico. El usuario habilitado indica comienzo y fin de tarea. Actor: sistema. Poscondicin: nota publicada

v.004 | kbee.workflow | Tutorial

Pgina 5 de 16

3 Solucin
3.1 Configuracin
3.1.1 Propiedades

En el archivo WEB-INF/classes/META-INF/workflow/workflow.properties se definen la siguiente lista de propiedades como parmetros del funcionamiento de la aplicacin:
com.novamens.workflow.datasource.driver com.novamens.workflow.datasource.url com.novamens.workflow.datasource.schema com.novamens.workflow.datasource.user com.novamens.workflow.datasource.password 3.1.2 Beans de Spring

El kbee.workflow se integra con el framework Spring. Con Spring el kbee.workflow, soluciona dos cosas: inyeccin de dependencias y administracin de transacciones. Para la inyeccin de dependencias se crea un contexto Spring de nombre workflow en WEBINF/classes/META-INF/workflow/spring/workflow-context.xml. En este contexto se definen para la aplicacin los siguientes beans:

<beans default-lazy-init="true">
<bean id="sqlDataSource" class="org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy" destroy-method="close"> <constructor-arg index="0" ref="sqlDataSourceImpl"/> </bean> <bean id="sqlDataSourceImpl" class="org.apache.commons.dbcp.BasicDataSource" destroymethod="close"> <property name="driverClassName" value="${com.novamens.workflow.datasource.driver}"/> <property name="url" value="${com.novamens.workflow.datasource.url}"/> <property name="username" value="${com.novamens.workflow.datasource.user}"/> <property name="password" value="${com.novamens.workflow.datasource.password}"/> </bean> <bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> <property name="dataSource" ref="sqlDataSource"/> </bean> <bean id="engineClient" class="com.novamens.workflow.client.impl.HttpClient"> <property name="server" value="http://localhost:8080/kbee/workflow"/> </bean> </beans>

Y cualquier otro bean que necesite ser referenciado desde tareas o evaluacin de condiciones en la ejecucin de los procesos. La definicin del contexto completo se puede ver en los fuentes en el paquete server/src/main/resources/META-INF/workflow/spring

v.004 | kbee.workflow | Tutorial

Pgina 6 de 16

3.1.3

Redefinicin de Beans

Si fuera necesario redefinir beans del contexto base es necesario hacer lo siguiente. Especificar un nuevo modulo del kbee.workflow completando la siguiente propiedad en el archivo de propiedades:
com.novamens.workflow.modules=mi-aplicacin

Luego, se buscaran los beans de este modulo en WEB-INF/classes/METAINF/workflow/mi-aplicacin/spring/mi-aplicacin-context.xml.

3.2 Contextos
Todo token que circula por la red de un proceso contiene una estructura con datos a la que se le llamar contexto. La finalidad del contexto es contener referencias a uno o ms objetos del dominio del problema donde se ejecuta el proceso. Adems, pueden contener informacin vlida solo en el contexto del proceso como pueden ser prioridades o indicaciones particulares para el proceso o tareas.
3.2.1 Especificacin del contexto

El contexto es para el server una caja negra solo accesible a travs de invocaciones JXPATH (Java + XPath). Esto permite un total desacople entre el server y la implementacin seleccionada para el contexto. La implementacin default incluida en el server para un contexto es la de un documento XML. En el problema de referencia respeta el siguiente esquema:
<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'> <xs:element name="Nota"> <xs:complexType> <xs:sequence> <xs:element ref="indicaciones"/> <xs:element ref="id"/> <xs:element ref="titulo"/> <xs:element ref="seccion"/> <xs:element ref="texto"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>

Si bien es deseable que el contexto contenga solo referencias y que la persistencia y administracin de los objetos (o documentos) se deleguen a la capa de aplicaciones , a manera de simplificacin, en problema de referencia, se almacena todo el contenido en el mismo contexto.

v.004 | kbee.workflow | Tutorial

Pgina 7 de 16

3.2.2

WQL

El kbee.workflow tiene la capacidad de gestin de un metamodelo donde se pueden combinar las propiedades de las entidades nativas con las propiedades de los contextos. Esta metamodelo se puede consultar a travs del lenguaje de consulta WQL. Por ejemplo, en el problema de referencia se podran utilizar sentencias del tipo
SELECT ACTIVITY WHERE NOTA=1

Sentencia con la que se pueden obtener todas las actividades relacionadas con el documento particular que se indica.

3.2.3

Registro del contexto

Para que el kbee.workflow pueda sumar al metamodelo el contexto del problema de referencia se debe hacer lo siguiente: En la tabla relacional de nombre PETRI_CLASS se debe agregar una fila con un nombre nico que identifique el contexto a crear. En el caso del los contextos, como el de ejemplo, donde la estructura se implementa como un Xml se espera que el nombre coincida con el elemento raz del documento:
PTR_NAME

Nota

En la tabla relacional de nombre PETRI_DATA de agregar las siguientes filas para describir la estructura:
PTR_DATA Indicaciones Nota Titulo Seccin Texto PTR_PATH Indicaciones nota titulo seccion texto PTR_VARIA BLE 1 1 1 1 1 PTR_INDEXA BLE 1 1 1 1 0 PTR_CLASS Nota Nota Nota Nota Nota PTR_ORDER 1 2 3 4 5

Donde el significado de cada columna es el siguiente: PTR_DATA: identificacin nica del dato PTR_PATH: JXPATH aplicable al contexto para la obtencin del valor correspondiente. PTR_VARIABLE: define si el valor del contexto puede variar durante la vida del proceso. PTR_INDEXABLE: los datos que se definen como indexables extienden el modelo nativo y son consultables va WQL.

v.004 | kbee.workflow | Tutorial

Pgina 8 de 16

3.3 Comunicacin
3.3.1 Comunicacin aplicaciones servidor

La comunicacin de las aplicaciones con el servidor se resuelve con un sistema de mensaje que incluyen, entre otros, los siguientes bsicos y fundamentales. Ejecucin de un Wql: recibe una sentencia Wql y retorna un conjunto de resultados. Cada resultado incluye adems de la meta informacin. La identificacin de cada entidad (workitem, proceso o actividad) Recuperacin de una entidad: para recuperar una entidad. Disparo de un trigger: para lanzamiento de actividad. Finalizacin de actividad: para indicar finalizacin de una actividad.

El transporte de los mensajes se puede hacer de diversas formas. Una primera opcin es usar directamente la Api Java si las aplicaciones y el server funcionan en la misma mquina virtual. La interfase com.novamens.workow.engine.Engie define la fachada del server e incluye estos mensajes bsicos. El bean engine instancia la clase nica que cumple esta funcin. Otra opcin de transporte es la de un cliente remoto. La interfase com.novamens.workflow.client.EngineClient define una interfase para un cliente y el bean engineClient instancia la clase que la implementa. Por ejemplo, la clase com.novamens.workflow.client.impl.HttpClient implementa el transporte Http. La implementacin de servicios Web a partir de estos ejemplos debera ser razonablemente sencilla.

3.4 Tareas
3.4.1 Web Forms

Este tipo de tareas incluyen como definicin bsica la URL de la herramienta que la resuelve. El WQL recupera este dato para cada una de las entidades de sus resultados (actividades o workitems). Con la URL de la herramienta y la identificacin de la activad o workitem se puede recuperar el contexto asociado y tener acceso a las entidades de domino del problema. Como patrn sugerido (solo sugerido!) de solucin se pueden hacer la siguientes cosas: 1. Recuperar los datos de la entidad y contexto correspondiente: a travs del mecanismo de comunicacin aplicacin servidor que se haya seleccionado. Armar un marco HTML que incluya el nombre de la tarea, indicaciones propias del proceso o tarea y botones relacionados con el inicio y fin de la tarea. Pasar los parmetros a la herramienta que se efectivamente se utilice para resolver la tarea: para la solucin del problema de referencia se construye un editor HTML para la nota que es utilizado por las tareas de redaccin, correccin y aprobacin.

2.

3.

v.004 | kbee.workflow | Tutorial

Pgina 9 de 16

v.004 | kbee.workflow | Tutorial

Pgina 10 de 16

Por ejemplo, la tarea de aprobacin (expample/aprobacin.jsp) del problema de referencia, sigue ese patrn:
<%@page import="com.novamens.workflow.client.EngineClientFactory" %> <%@page import="org.dom4j.Document" %> <%@include file="nota.jsp" %> <%@include file="workflowEntity.jsp" %> <% String entityId = request.getParameter("entity"); WorkflowEntity entity = new WorkflowEntity((Document)EngineClientFactory.getInstance().getEntity(entityId)); Nota nota = new Nota(entity.context); String enabled = entity.state.equals("Running")? "true": "false"; %>

La pgina recibe como parmetro la identificacin de la actividad o workitem y la recupera del server a travs del cliente. La clase EngineClientFactory instancia al EngineClient buscando el bean correspondiente en el contexto Spring de la aplicacin. Luego, a partir del contexto de la entidad instancia la clase del problema (una Nota).
<html> <head> <link href="<%=request.getContextPath()%>/wf.css" rel="stylesheet" type="text/css"> <title>Aprobaci&oacute;n Nota <%= nota.id%></title> <meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> </head> <body> <div class="contFormulario"> <h3> Aprobaci&oacute;n Nota <%= nota.id%></h3> <span><%= nota.indicaciones%></span> <jsp:include page="editor.jsp"> <jsp:param name="enabled" value="<%= enabled%>"/> </jsp:include>

Se definen atributos propios de la tarea, como el nombre Aprobacin Nota y luego se incluye la herramienta que resuelve efectivamente la tarea. El editor de notas en este caso.
<% if (entity.isWorkItem()) { %> <a href="../fireTrigger.jsp?entity=<%= entityId %>">tomar</a> <% } %> <% if (entity.isActivity() && entity.state.equals("Running")) { %> <a href="<%=request.getContextPath()%>/example/endActivity.jsp?entity=<%= entityId %>&estado=aprobada">aprobar</a>

v.004 | kbee.workflow | Tutorial

Pgina 11 de 16

<a href="<%=request.getContextPath()%>/example/endActivity.jsp?entity=<%= entityId %>&estado=rechazada">no aprobar</a> <% } %> </div> </body> </html>

3.4.2

Java Script

En estas tareas se puede codificar scripts para resolver tareas automticas. El script recibe como variable la instancia de contexto y a partir de este debera poder acceder a cualquier dato del domino. Un ejemplo de esta clase de tarea es la de de nombre publicacin en el problema de referencia.

3.5 Triggers
3.5.1 Manuales

El trigger manual es aquel que solo puede ser disparado por la accin de un usuario: apretar un botn, por ejemplo. En su especificacin se debe incluir los siguientes datos: Group: el principal o grupo de referencia sobre el que se ejecuta el control del acceso. Lo mas usual es que la verificacin que se ejecute la de pertenencia de un usuario a ese grupo Condition: condicin de activacin sobre el contexto. Para que el trigger se pueda activar debe cumplirse la condicin que se especifique. Si no se especifica ninguna condicin nada se evala. Controller: strategy de control. El strategy Miembro verifica para controlar el acceso de usuario la pertenencia de este al grupo especificado en el trigger. Para la creacin de nuevos controladores solo hay que tener en cuenta que el server busca el bean en el contexto de Spring con el nombre de controlador para su creacin. Ejemplos de triggers manuales son los especificados para las tareas de redaccin, correccin y aprobacin del problema de referencia. Es importante aclarar que la implementacin del manager de seguridad que se distribuye solo cumple una funcin de stub y que debe cambiarse para integrarse con el sistema de seguridad que se requiera (ver el bean securityManager en el contexto de Spring).

3.5.2

Automticos

El trigger automtico es aquel que se dispara cuando se cumple la precondicin de la tarea. En su especificacin se debe incluir los siguientes datos:

v.004 | kbee.workflow | Tutorial

Pgina 12 de 16

 Condition: condicin de activacin sobre el contexto. Para que el trigger se pueda activar debe cumplirse la condicin que se especifique. Si no se especifica ninguna condicin nada se evala. Signaller: el signaller es el responsable del disparo de los eventos para la reevaluacin de la condicin especificada. Ejemplos del signallers pueden ser un timer o un subscriptor de una cola de publicacin JMS. En el primer caso la condicin se reevaluar en cada ciclo de tiempo determinado por el timer y en el segundo caso en cada recepcin de un mensaje JMS. Para la especificacin de otros signallers solo hay que tener en cuenta que el server busca un bean con ese nombre en el contexto de Spring. Ejemplo de trigger automtico es el de la tarea de publicacin en la solucin del problema de referencia.
3.5.3 Timeout

El trigger por timeout es aquel que se dispara cuando se cumple un tiempo especificado. Su especificacin solo incluye el tiempo en cuestin.

v.004 | kbee.workflow | Tutorial

Pgina 13 de 16

4 Ejecucin y Pruebas
4.1 Consola Web
La consola Web incluida del server permite consultar procedimientos, lanzar procesos, consultar los contextos definidos y ejecutar consultas WQL con fines de monitoreo.

v.004 | kbee.workflow | Tutorial

Pgina 14 de 16

4.2 Lanzamiento de Procesos

La consola presenta una herramienta genrica para el lanzamiento de procesos. En esta es necesario ingresar los datos completos del contexto que recibe el nuevo proceso. Por ejemplo, en la siguiente figura se muestra como lanzar un proceso del procedimiento de publicacin de notas (Home->Procedures->publicacin_notas->Start Process):

v.004 | kbee.workflow | Tutorial

Pgina 15 de 16

4.3 Monitoreo WQL

Como parte de la consola se incluye una herramienta para la escritura de sentencias WQL con fines de monitoreo. La herramienta incluye una serie de sentencias a manera de ejemplo:

v.004 | kbee.workflow | Tutorial

Pgina 16 de 16