Como utilizar el Engine API de BonitaSoft con Spring Boot

En este artículo vamos a desarrollar un servicio restful con Spring Boot y el Engine API de Bonitasoft, este servicio nos va a retornar un listado de usuarios que están dentro de la organización que tenemos por defecto en Bonita Studio 7.11.

Si no sabes como usar Spring Boot puedes ver este tutorial en donde creamos un API Restful con las operaciones básicas de CRUD.

Recursos

Para desarrollar este servicio vamos a utilizar 3 herramientas:

Desarrollo

Vamos a dividir el desarrollo en 3 secciones:

1. Creación y carga del proyecto en Spring Initializr

Debemos ir a Spring Initializr y crear un proyecto con la dependencia Spring Web, esta dependencia nos va a ayudar con todo el tema de restful y luego hacemos clic en el botón «GENERATE»:

Esto nos descargara un archivo .zip, lo buscamos en el finder/explorador y lo descomprimimos:

Abrimos nuestro IDE y cargamos el proyecto, en mi caso estoy utilizando IntelliJ Idea:

Buscamos el proyecto y lo abrimos:

Luego de cargar el proyecto deberíamos tener algo similar a esto:

2. Creación de los servicios integrados con el Engine API de Bonitasoft

Antes de iniciar con el desarrollo debemos abrir el Bonita Studio para que levante el motor de bonita y podamos conectarnos posteriormente, vamos a ver que por defecto vamos a tener una organización creada y ahí se encuentran los usuarios que vamos a retornar desde nuestro servicio:

Nuevamente vamos a nuestro IDE y vamos a abrir el archivo Pom.xml para añadir las siguientes dependencias:

<!-- Bonita 7.11 -->
<dependency>
	<groupId>org.bonitasoft.engine</groupId>
	<artifactId>bonita-client</artifactId>
	<version>${bonita.bpm.version}</version>
</dependency>

También debemos agregar la siguiente propiedad:

<bonita.bpm.version>7.11.0</bonita.bpm.version>

Lo anterior lo debemos colocar en las siguientes secciones:

Ahora vamos a ir nuestro paquete principal que esta dentro de src > main > java y vamos a crear 2 paquetes dentro de com.example.demo, estos paquetes van a ser:

  • Service: aca crearemos el servicio con toda la lógica para conectarnos al motor de Bonita y obtendremos el listado de usuarios.
  • Controller: Aca crearemos nuestro @RestController donde expondremos los servicios del paquete service y crearemos un endpoint funcional.

Dentro del paquete service vamos a crear la clase EngineService, dentro de esta clase vamos a crear nuestro servicio y vamos a conectarnos al motor de bonita y obtendremos el listado de usuarios:

package com.example.demo.service;

import org.bonitasoft.engine.api.ApiAccessType;
import org.bonitasoft.engine.api.IdentityAPI;
import org.bonitasoft.engine.api.LoginAPI;
import org.bonitasoft.engine.api.TenantAPIAccessor;
import org.bonitasoft.engine.identity.User;
import org.bonitasoft.engine.identity.UserCriterion;
import org.bonitasoft.engine.session.APISession;
import org.bonitasoft.engine.util.APITypeManager;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Service
public class EngineService {

    public List<User> getUsers(){
        try {

            Map<String, String> map = new HashMap<String, String>();
            map.put("server.url", "http://localhost:8080");
            map.put("application.name", "bonita");
            APITypeManager.setAPITypeAndParams(ApiAccessType.HTTP, map);

            String username = "walter.bates";
            String password = "bpm";
            LoginAPI loginAPI = TenantAPIAccessor.getLoginAPI();
            APISession apiSession = loginAPI.login(username, password);

            IdentityAPI identityAPI = TenantAPIAccessor.getIdentityAPI(apiSession);
            List<User> users = identityAPI.getUsers(0,50, UserCriterion.USER_NAME_ASC);

            return users;

        } catch(Exception e) {
            e.printStackTrace();
            return null;
        }
    }

}

Vamos a explicar el codigo linea por linea. Lo primero que hacemos es agregar la directiva @Service para indicarle a Spring que estamos creando un servicio. Luego vamos a crear un método que nos va a retornar un List<User> (Acá es importante que el tipo User viene de org.bonitasoft.engine.identity.User), no olvidar que debemos agregar toda la lógica dentro del try-catch para capturar cualquier excepción que se presente. El código para obtener este listado de usuarios lo podemos dividir en 3 bloques:

Bloque #1 – Definición de server.url, application.name y metodo de conexión HTTP

Debemos crear un Map<String, String> en donde agregaremos la url y el puerto del servidor de donde se está ejecutando el motor de bonita (en nuestro caso es por localhost y el puerto 8080) y el nombre de la aplicación, esté map lo vamos a enviar dentro de un APITypeManager para indicar que nos vamos a conectar por HTTP a la url y aplicación indicada en el mismo map.

Bloque #2 – Autenticación

En esta segunda parte debemos crear las variables para almacenar el Username y el Password del usuario con el cual nos vamos a autenticar en Bonita, para este ejemplo vamos a utilizar el usuario «walter.bates» y la contraseña es «bpm». Luego vamos a obtener el LoginAPI que nos va a permitir posteriormente a crear un APISession que será utilizada en el bloque 3.

Bloque #3 – Vamos a obtener los usuarios

Con la sesión creada en el bloque 2 vamos a obtener el IdentityAPI, esta API nos permite administrar temas que tengan que ver la organización de Bonita es por eso que la utilizamos para obtener un listado de usuarios con el metodo getUsers() y por ultimo retornamos este listado.

Ahora vamos a pasar al paquete controller en donde crearemos la clase EngineController:

package com.example.demo.controller;

import com.example.demo.service.EngineService;
import org.bonitasoft.engine.identity.User;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/demo")
public class EngineController {
    private EngineService engineService;

    public EngineController(EngineService engineService){
        this.engineService = engineService;
    }

    @GetMapping
    public ResponseEntity<List<User>> getUsers(){
        return new ResponseEntity<List<User>>(this.engineService.getUsers(), HttpStatus.OK);
    }
}

En esta clase vamos a indicarle a Spring que va a ser nuestro @RestController, luego definimos nuestro path en «/demo» con @RequestMapping. Exponemos el servicio creado anteriormente y creamos un método que responderá por un method Get y lo vamos a llamar igualmente getUsers() que nos va a retornar el listado de usuarios por medio de un ResponseEntity con un status 200 OK.

Ya con esto tenemos nuestro servicio restful construido al 100%, ahora vamos a indicarle porque puerto queremos que se ejecute nuestro proyecto ya que por defecto se intentara ejecutar por el 8080 pero este ya lo está utilizando Bonita Studio y nos aparecerá un error. Dentro de la carpeta src > main > resources cree el archivo application.yaml para configurar el puerto:

server:
  port: 8081

Igualmente lo puedes configurar dentro del archivo application.properties que trae por defecto:

#Server Port
server.port=8081

3. Ejecución y consumo del servicio

Para ejecutar nuestro proyecto voy a agregar una configuración en nuestro IDE:

Luego de esto hacemos clic en Apply y luego en OK. Solo nos falta ejecutar el proyecto:

Esperamos a que se ejecute y levante nuestro servicio correctamente:

Por último vamos a consumir nuestro servicio enviando un request desde Postman:

El servicio funciona correctamente, nos retorna el listado de usuarios que le indicamos sin problemas. El codigo fuente de este proyecto lo puedes conseguir aqui: https://github.com/JesusHenriquez/demo-engineapi-bonitasoft

También te dejo el video de todo este procedimiento:

Te invito a que me cuentes en los comentarios qué te pareció este tutorial y que otro ejemplo de Spring Boot o del Engine API de Bonitasoft te gustaría ver.

La importancia del Readme.md y como construirlo

Muchos desarrolladores suelen tener muchos proyectos en repositorios de git en servicios como GitHub, Bitbucket o GitLab. Es normal ver que en la gran mayoría de estos proyectos que existe un archivo Readme.md en blanco o hasta es inexistente, es por eso que te voy a hablar un poco sobre su importancia y como puedes construir tu primer Readme.md.

¿Que es el archivo Readme.md?

Este archivo es donde se coloca información pertinente sobre tu proyecto, versión en la que se encuentra actualmente, como debe desplegarse, como contribuir, que requisitos debes complicar para su uso, entre otras cosas.

Importancia

Siempre es recomendable que tengas una buena documentación en tus proyectos y este fichero no es una excepción, te recomiendo que vayas actualizando tu readme a medida que tu proyecto avanza y detalles la información necesaria para su uso.

Si es un proyecto open source es casi obligatorio esta documentación ya que sera la puerta de entrada para futuros contribuyentes y hacer crecer la comunidad que necesitas para que tu proyecto prospere.

Ejemplo de un Readme.md

Podemos observar en proyectos muy populares en las diferentes comunidades de desarrolladores que cuentan con un buen readme, por ejemplo el repositorio de React.js de Facebook:

Imagen de Github/Facebook

Markdown = .md

Markdown es un lenguaje de marcado ligero con el cual se puede construir una estructura html enriquecida dándole una visual más agradable, es por eso que se utiliza este formato en los proyectos git.

Para utilizar el formato Markdown aquí te dejo la sintaxis para que puedas empezar:

Información sacada de Packetlife.net

Plantilla Readme.me

Les dejo una plantilla para que la reutilicen en sus proyectos, de esta forma añaden un plus que sera de mucha ayuda cuando trabajen en equipo:

Recomendaciónes

Para finalizar te recomiendo lo siguiente:

  • Si no haz creado un reame te recomiendo que empieces de una vez y crees tu primer readme en algún proyecto que tengas en git. Si quieres utiliza la plantilla que te compartí y adaptala con la información de tu proyecto.
  • Personaliza y añade mas secciones a tu reame para que sea increíble.
  • Puedes basarte en proyecto populares como el que mencione en este post.

Si tienes alguna pregunta o sugerencia no dudes en dejarlo en los comentarios y lo tomaremos en cuenta.

Creación de API Restful con Spring Boot, Lombok y Swagger

Hace un tiempo compartí una guía en youtube sobre como crear un API Restfull con Spring Boot, Project Lombok y Swagger. Les dejo por acá la guía para que puedan disfrutarla y colocar en los comentarios cualquier duda que tengan.

La guía consta de 3 partes en las cuales vamos desde la creación del proyecto desde Spring Initializr hasta la implementación y construcción de la interfaz gráfica con Swagger y Swagger UI. El producto final sera crear los servicios restfull para realizar un CRUD básico a la entidad de usuario.

Recursos y herramientas a utilizar

Guia

Código fuente del proyecto

Pueden conseguir el proyecto en mi perfil de github o en el siguiente link: https://github.com/JesusHenriquez/crud-restfull-springboot

Si tienes alguna pregunta o sugerencia no dudes en dejarlo en los comentarios y lo tomaremos en cuenta.

es_ESEspañol
en_USEnglish es_ESEspañol