Contratos y formularios

Ejercicios de demostración de cómo manejar los contratos y formularios de un proceso en Bonita BPM Suite. Cuando estos estén definidos, podremos ejecutar el proceso para comprobar el flujo de datos. Estamos en un ambiente de desarrollo, no se espera que los formularios estén muy pulidos, como deberán estarlo en producción.

Aunque no vamos a especificar nada concreto, podemos pensar que alguien hace una solicitud o alegación y otra persona responderá a esa solicitud. La solicitud tendrá datos de identificación del solicitante, la fecha en que se hizo y un texto con lo que alega o solicita. Una tarea posterior responderá a esa alegación con otro texto y finaliza.

Todos esos datos están disponibles a lo largo de la ejecución del proceso. Pero es que, además, podemos hacer uso de la API de Bonita BPM, en concreto la REST API.

Este ejercicio consta de 5 partes que van acumulando modificaciones:

PP02. Contratos y formularios

Resumen

El modelo de datos de negocio (BDM) es general y usable por cualquier proceso. En realidad, es una definición de tabla de base de datos.
Un proceso instancia un BDM lo que, en realidad, se convierte en una fila de una tabla.
Una variable de negocio se puede usar en todo el proceso, y forma parte de los datos de archivo del proceso una vez se ha ejecutado completamente.
Las variables de proceso están accesibles durante todo el proceso o solo en una tarea —depende de donde se definan—, pero se "pierden" cuando este o esta terminan.
El contrato es la declaración de qué variables y restricciones vamos a utilizar.
Los formularios implementan la entrada de datos a esas variables, si es que se necesita un formulario.
En tareas humanas sí hay formulario, en otros tipos de tareas no.
Las operaciones se ejecutan al final de la tarea, una vez que el formulario se ha cerrado.

Lo que vamos a hacer es cambiar ligeramente el uso de formularios. En concreto, en la tarea vamos a usar una variable de proceso independiente de la variable de negocio del proceso. Más información sobre variables.

Es muy importante que sigas al pie de la letra los pasos y respetes los nombres de variables, tareas, etc. El más mínimo cambio —incluso el uso de mayúsculas o minúsculas— puede resultar en que alguno de los pasos no te funcione bien y el proceso no haga lo que esperamos de él.

Nuevo diagrama

Abre un diagrama nuevo y pon un evento de fin. La tarea será de intervención humana.

Cambia el nombre a la tarea: Haciendo algo

Pincha en el pool —no en la senda— y cambia el nombre del proceso: Contratos y formularios

Pincha fuera del proceso y mira el panel inferior de Bonita. Ahora se muestra la información del diagrama entero y, entre otras cosas, se puede editar el nombre de este. Esto se reflejará en el nombre del fichero que guardaremos en el disco duro. Cambia ese nombre a PP02 Contratos y formularios.

Es posible que te parezca que, tras aceptar el cambio de nombre del diagrama, que no ha hecho nada. Es un problema de refresco: pincha en el diagrama, en cualquier sitio fuera de la caja del proceso, y verás como se actualiza.

Exporta el diagrama

Esto no es necesario ahora mismo pero, para que compruebes el efecto de lo que hemos hecho antes, vamos a exportar el diagrama a un fichero independiente de Bonita. Esto te permitirá guardarlo como copia de seguridad e importarlo en otra máquina o en otra sesión.

Menu:Archivo/Exportar...
En el siguiente diálogo, elige la ruta donde lo quieras guarda y Finalizar

Puedes comprobar que, en el lugar elegido, se ha creado un fichero con extensión .bos; es el fichero que puedes utilizar para recuperar el proceso o migrarlo a otra instalación. Recuerda que, ahora mismo, solo hemos definido el diagrama, todo lo que viene a continuación necesita otra exportación si queremos guardarlo.

Crea un modelo de datos de negocio

- Menu:Desarrollo/Modelo_de_datos_de_negocio/Definir
- Añadir: y cambiar nombre a probando
- En panel derecho, Atributos, Añadir:

solicitanteID, LONG (requerido)

fecha, DATE-TIME (NO TIME ZONE)

alegacion, TEXT

respuesta, TEXT

- Finalizar

crea variable de negocio

Selecciona el pool (o senda)

- PanelInferior:Datos/Variables_de_proceso/Variables_de_Negocio/Agregar…
- En el diálogo que se abre, da nombre pruebadatos a la variable y selecciona probando en Objeto de Negocio
- Finalizar

Define contrato de instanciación

- PanelInferior:Ejecución/Contrato/Entradas/Añadir desde datos…
- Con la variable de negocio marcada, Siguiente>
- Deja marcado únicamente alegacion y Finalizar
  - Este es el dato que generará un widget en el formulario —si así se requiere en el contrato—, junto con un botón submit; en el formulario se podrán recuperar datos de negocio e incluso actualizarlos.
  - La definición del contrato provoca la generación automática —si se desea, también puede editarse manualmente— del código de inicialización de las variables utilizadas.
  - El ID del solicitante y la fecha las vamos a obtener del sistema, no hace falta que el usuario las introduzca en el formulario.
  - La "respuesta" se utilizará más adelante en el proceso.

Define formulario de instanciación

Con UI Designer marcado,

- pinchar en el "lápiz" a la derecha de Formulario de destino
- se abre una ventana de navegador con un diseño básico de formulario, Guardar con nombre probandoFini.

Ten en cuenta que, con este formulario, estamos instanciando el proceso y, entre otras cosas, inicializando la variable de negocio con sus primeros valores. Pero, recalcamos, solo en el atributo alegación.

Hemos terminado, casi, con la instanciación del proceso. Ahora vamos a hacer prácticamente lo mismo pero con la tarea Haciendo algo.

Define contrato de tarea

Con la tarea seleccionada

- PanelInferior:Ejecución/Contrato/Entradas/Añadir desde datos...
- Con pruebadatos marcada, Siguiente>
- Marca únicamente respuesta, y Finalizar

Define formulario de tarea

Con UIDesigner marcado,

- pinchar en el "lápiz" a la derecha de Formulario de destino

Se abre una ventana de navegador con un diseño básico de formulario

- Guardar con nombre probandoF

Observa que, automáticamente, se han añadido todos los atributos de la variable de negocio. En este caso, lo dejamos todo tal cual está.

De momento, nada más hay que hacer. Vamos a comprobar cómo funciona el proceso.

Ejecuta el proceso

Con el pool seleccionado,

- Botonera/Ejecuta

Te aparece un formulario en el navegador de internet

- Pon cualquier texto en el campo de alegación y pincha Submit.

Ha fallado, verás un texto de error. Te informa de que solicitanteID, que hemos definido como "de valor requerido", no tiene valor ninguno (null),

Recuerda que en el contrato de instanciación solo hemos marcado la propiedad alegación de la variable de negocio. De hecho, el formulario que hemos intentado ejecutar solo tenía eso. La instanciación del proceso genera el primer valor de las variables de negocio. Si no se utililzan en el contrato, Bonita no genera ningún código para ello.

PP02B. Modificando la inicialización de la variable de negocio

Bonita Studio —más bien el servidor Bonita BPM que este incorpora— viene con una organización de usuario predefinida, válida para entornos de desarrollo. En particular, cada vez que ejecutamos un proceso, nos identificamos como Walter Bates, un usuario de esa organización. Ese usuario, como los otros, tiene un identificador, aparte de otros datos personales.

Cuando ejecutamos —como si fuéramos Walter—, el dato del identificador del iniciador del proceso está disponible, simplemente no lo hemos usado. Pretendemos capturarlo y almacenarlo en nuestra variable de negocio. Ese identificador, posteriormente, nos permitirá acceder a otros datos como nombre y apellidos y, en general, nos permitirá almacenar quién ha hecho la solicitud.

Eso lo podemos hacer nada más iniciarse el proceso, durante la instanciación del modelo de datos de negocio —la creación de la variable de negocio—.

Modifica la inicialización del BDM

Con el pool seleccionado,

- PanelInferior:Datos/Variables_de_proceso/Variables_de_Negocio
- pincha 2 veces en la variable pruebadatos
- en el diálogo que se abre. pincha en el "lápiz" a la derecha de Valor_prederteminado: initPuebadatos()

Se trata de un script en Groovy que da valor inicial a aquellos datos que hemos seleccionado en el contrato. Esos valores iniciales se almacenarán en la variable de probando nada más iniciar el proceso. En nuestro caso, algunos se introducen por formulario, pero otros hay que inicializarlos en este paso.

Sustituye ese texto por este otro —es el mismo pero añadidas algunas líneas más— y Aceptar

//necesitamos esta librería para la fecha

import java.time.LocalDateTime;

def probandoVar= new com.company.model.probando()

probandoVar.alegacion = pruebadatosInput?.alegacion

//accedemos a la API BonitaUsers para recuperar el id del iniciador

probandoVar.solicitanteID = BonitaUsers.getProcessInstanceInitiator(apiAccessor, processInstanceId).id

//esto sale de la clase LocalDate de Groovy, pone la fecha y hora del sistema

probandoVar.fecha = LocalDateTime.now();

//esto no haría falta pues respuesta lo actualizaremos después

//pero lo inicializamos a cadena vacía por cuestión de "buen hacer"

probandoVar.respuesta = ""

return probandoVar

- Vuelve a ejecutar el proceso

Volverá a abrirse el mismo formulario de instanciación pero, ahora, no nos dará error ninguno y pasaremos a Portal, el gestor web de procesos.

Vemos, a la izquierda, la tarea pendiente (Haciendo algo) que hemos de "tomar" para poder ejecutarla.

En la parte derecha, el formulario definido para la tarea preparado para introducir nuestra respuesta a la alegación. Fíjate que se muestra el identificadoren la base de datos de usuarios de Walter Bates (4), y la fecha en que se inició el proceso. También el dato que introdujimos en el formulario anterior.

Solo queda dar una respuesta y pinchar Submit.

Comprobar el resultado

Otra forma de ver los datos almacenados del proceso recién ejecutado es acceder a tareas realizadas

- pincha 2 veces en la variable pruebadatos
- en el diálogo que se abre. pincha en el "lápiz" a la derecha de Valor_prederteminado: initPuebadatos()

Nos vamos a Casos Archivados y examinamos "Contratos y formularios"

En algunos casos, como ocurre con este ejemplo, la cabecera de datos queda oculta, y no podemos saber con seguridad qué valores se corresponden con qué propiedades de la variable de negocio.

Los valores de variables de negocio se van almacenado en base de datos a medida que vamos ejecutando procesos. El servidor incluido en Bonita Studio es H2, una base de datos relacional de código abierto muy ligera, y que no se recomienda para entornos en producción.

Sí queremos, podemos consultar la consola de datos H2 en Menu:Desarrollo/Modelo_de_datos_de_negocio/Consultar los datots (consola H2)...

Estamos accediendo al gestor de base de datos H2 que acompaña a Bonita BPM. Seleccionando la tabla asociada a nuestro BDM, y ejecutando la consulta que aparece automáticamente, podemos ver las filas con las ejecuciones del proceso. En cualquier caso, se trata de ver que, gracias a la inicialización de la variable de negocio, hemos almacenado el id de Walter Bates (un número) y la fecha y hora en la que se instanció el proceso.

PP02C. Accediendo a datos de sesión

Resumen

1. puedo definir variables que acceden a las REST API proporcionadas por el producto
2. con ellas puedo ver y usar todo tipo de información de los objetos que gestiona Bonita BPM
3. la mayoría de los resultados, por no decir todos, tendrán formato JSON
4. el widget TEXT nos permite utilizar esas variables y HTML para mostrar, incluso, información de depuración que nos permita orientarnos mientras desarrollamos los formularios

Queremos mejorar nuestro formulario permitiendo que se vea información adicional.

Añadiendo datos a los formularios

En UI Designer, edita el formulario de la tarea Haciendo algo.

Vamos a modificar el formulario probandoF para añadir información adicional. Básicamente, vamos a actuar sobre las variables del formulario y utilizarlas para mostrar información en widgets (controles de formulario).

Fíjate en el formulario de la tarea, en la parte central inferior; ya tiene variables definidas automáticamente por el sistema. Las podemos utilizar o no, modificarlas o incluso eliminarlas si fuera necesario. Nosotros vamos a añadir nuevas variables.

Añade una variable con Crear una nueva variable

nombre: usuario

tipo: External API

API URL: ../API/system/session/1

- - Ten cuidado con los puntos iniciales, son necesarios

Añade un widget TEXT y, en el panel de la derecha, modifica el atributo Texto con lo siguiente:

<pre>usuario

{{usuario | json}}</pre>

Añade un widget INPUT y, en el panel de la derecha, modifica estos atributos:

Etiqueta: Usuario

Solo lectura: sí

Valor: usuario.user_name

Guarda el formulario

Ejecuta y comprueba que aparece el nombre de usuario "walter.bates" en el INPUT y la información completa de del usuario autenticado en el TEXT —en formato JSON—.

Hemos de diferenciar lo que se maneja con la variable de negocio, y que puede utilizarse en los formularios, y las variables propias del formulario. Las que añade Bonita automáticamente son necesarias para trasvasar los valores introducidos a la variable de negocio. Nosotros podemos añadir otras según necesitemos que el formulario se comporte de una manera u otra.

En este caso, haciendo uso de la API que nos proporciona el producto, hemos añadido información para el usuario del formulario: el nombre de usuario asociado al ID y, además, toda la información principal almacenada sobre él. Evidentemente, el cómo mostrar esa información, con más o menos decoraciones, y el uso de la misma, dependen de cada proceso y desarrollador.

PP02D. Accediendo a los valores de negocio

Resumen

1. la información de contexto contiene los datos necesarios para recuperar, entre otros, los datos de negocio; concretamente nombrevar_ref.link
2. Bonita Studio crea una variable en cada uno de sus formularios: context (../API/bpm/userTask/{{taskId}}/context) de tipo External API

Al definir un formulario con UI Designer, Bonita Studio añade ciertas variables que le permiten, entre otras cosas, capturar los datos a introducir en el formulario y mostrar información de la variable de negocio. En concreto, la variable context almacena todo el contexto de ejecución del proceso, esto es, todo los valores que se están manejando en él.

En el contrato de la tarea solo estamos utilizando un atributo de la variable de negocio cuyo propósito es recoger la respuesta a la solicitud y actualizar el atributo respuesta de la instancia del BDM. Además, Bonita Studio añade el resto de datos, concretamente, "solicitanteID", "fecha" y "alegacion". Lo hace mediante otra variable, en nuestro caso pruebadatos que, si nos fijamos, es una propiedad de context.

Muchos desarrolladores muestran esta variable en todo momento, con la intención de detectar posibles fallos en el diseño y la ejecución.

comprobar de dónde sale la información

En el widget TEXT ya creado para la información de usuario añade

<pre>contexto

{{context | json}}</pre>

Guarda el formulario

ejecuta

Comprueba que aparecen los datos esperados.

Hemos movido el widget de texto pero ahí puedes ver la informaciónd de contexto.

En definitiva, el contexto contiene una referencia a la variable de negocio junto con otros datos necesarios para recuperarla. En concreto pruebadatos_ref.link nos permite acceder a sus atributos, precisamente la definición de la otra variable en el formulario mencionada: pruebadatos.

Insistimos en que, aunque tengan el mismo nombre, esta variable solo es accesible en el formulario, no es la variable de negocio. Pruebadatos del formulario nos permite saber qué hay en la variable de negocio pruebadatos. De hecho, se podría cambiar el nombre de la primera siempre que mantengamos la coherencia en los distintos widgets en que se usa.

PP02E. Accediendo a datos de identidad

Resumen

1. Las REST API nos permiten acceder a los objetos de Bonita BPM que tienen relación directa o indirecta con el proceso en ejecución.
2. Del usuario queremos obtener otros datos aparte de su ID y su nombre de usuario: apellidos y nombre, por ejemplo.

Cada librería API (o REST) tiene un cometido. ../API/system nos proporciona información de sesión del usuario autenticado. Ahora vamos a utilizar otra API, ../API/identity, que nos permite acceder a la información de usuario y mostrarla en nuestro formulario.

Ten en cuenta que el proceso maneja únicamente el ID del usuario. Si queremos más datos, debemos usar ese dato para acceder a otras partes de la base de datos, en concreto a los usuarios de la organización.

recuperar la información adicional del solicitante —el iniciador del proceso—

En UIDesigner y el formulario de la tarea

- crea una variable

nombre: solicitante

tipo: External API

API URL: ../API/identity/user/{{pruebadatos.solicitanteID}}

mostrar los datos en el formulario

- En el widget de texto ya creado (con el contexto y los datos mínimos de usuario) añade al principio

<pre>del usuario

{{solicitante | json}}</pre>

Esto solo es para comprobar el contenido recuperado por la variable solicitante. Más utilidad tiene el mostrar el nombre completo del usuario con un cierto formato.

- añade un widget INPUT

Etiqueta: Solicitante

Solo lectura: sí

Valor: solicitante.firstname +" "+ solicitante.lastname

- - estamos concatenando cadenas de caracteres con el operador +

ejecuta

Comprueba que aparecen los datos esperados.

Al lanzar el proceso e instanciarlo, llegamos al formulario de la tarea Haciendo algo. No tomes la tarea ni envíes el formulario todavía, no pinches en submit.

Tengamos en cuenta lo siguiente:

"Usuario" y "fecha" son los datos de quien está ahora mismo examinando la tarea y se apresta a completarla.
Solicitante se deduce de la variable de negocio; esta contiene el identificador de usuario (4), almacenado desde el formulario de instanciación, y lo que hemos hecho nosotros —utilizando ese identificador— es, por decirlo así, acceder a la base de datos de usuarios (de la organización ACME) para recuperar su nombre y apellidos.
Da la casualidad de que el nombre de usuario, en esta organización de prueba, se compone de esos mismos datos (walter.bates), y hasta parece irrelevante lo que hemos hecho. Piensa en otra organización, con otros nombres de usuarios, con más apellidos...

La información completa a la que hemos accedido la podemos ver al final del formulario. Nosotros hemos utilizado usuario.firstname y usuario.lastname únicamente.

cambia de usuario

Bonita BPM Suite tiene una organización para el desarrollo de procesos con la que podemos probar si funcionan correctamente. Esta organización se llama ACME y tiene entre sus miembros a Walter Bates, el usuario por defecto para estas comprobaciones. Puesto que no se han asignado al proceso empleados o roles concretos —el actor es, simplemente, cualquiera de los empleados de ACME—, podemos probar con otro usuario.

cierra sesión
identifícate como helen.kelly, y con contraseña bpm

La contraseña de todos los miembros de ACME es la misma.

Fíjate, en Portal, que los datos del formulario han cambiado.

Ahora, el usuario que está viendo la tarea pendiente es Helen Kelly. Pero con quien iniciamos este caso fue Walter Bates (ID 4), y es este valor —su identificador— el que se ha almacenado en la variable de negocio. Dicho más claramente, Walter lanza una solicitud y Helen responderá a ella lo que considere conveniente.

Ahora mismo no estamos haciendo nada con ese dato, que es, en definitiva, la persona que está respondiendo a la alegación de Walter Bates que, por lo general, efectivamente será otra persona.

Por supuesto, puedes personalizar los formularios tanto como desees. Es interesante que te familiarices con la herramienta, prueba todas las opciones que quieras y que te permite UI Designer.

Page updated

Report abuse