Introducción

En este tutorial, vas a ver un ejemplo de cómo orquestar varias llamadas a APIs para definir un comportamiento más complejo controlado.

Como ejemplo, vas a realizar un flujo que controla todo el proceso de validación de un "carro de la compra" para una tienda online. También tendrás disponibles siete APIs con las siguientes operaciones:

Módulos de gestión:
- API - Usuarios
  - Operación - Obtener usuario por ID
- API - Envío de pedidos
  - Operación - Validación de dirección de envío
- API - Pagos
  - Operación - Validar pago
  - Operación - Cancelar pago
- API - Inventario
  - Operación - Comprobar lista de items
  - Operación - Cancelar pedido
- API - Pedidos
  - Operación - Crear pedido
Herramientas internas
- API - Envío de correos
  - Operación - Enviar correo de error
  - Operación - Enviar correo de confirmación
- API - Backoffice
  - Operación - Dar de alta incidencia

Flujo de este ejemplo

Mediante la orquestación de las operaciones de las distintas APIs, podrás crear el flujo propuesto como ejemplo.

El flujo que seguirás será:

Validar Usuario.
Validar dirección de envío.
Validar el pago.
Comprobar la lista de items.
Crear el pedido.
Enviar correo de confirmación al usuario.

También verás cómo controlar los errores en caso de que las operaciones fallen por el motivo que sea. Si esto ocurriera, se deshará el proceso recorrido y se avisará al usuario. En caso de error grave, crearás una incidencia en el sistema para que quede constancia y el equipo de soporte pueda actuar.

Proceso

Para ello, sigue los siguientes pasos:

Selecciona la opción "FlowEngine Management" del menú Desarrollo:
Selecciona el dominio perteneciente a tu usuario:
Una vez estés dentro del dominio, define el mensaje que recibirá tu flujo. Crea un nodo "inject" para lanzar manualmente el flujo, y otro "function" con el contenido del carro de la compra:

El contenido del nodo "Function" será:
Una vez tienes definida tu información de entrada, valida el usuario llamando a la operación "Get User By ID" de la API "Users -V1". Para ello, arrastra un nodo de tipo "OnesaitPlatform Rest API invoker":

Haciendo doble click sobre el nodo añadido, rellena los campos requeridos seleccionando la API y operación comentadas anteriormente. Primero, selecciona la API del listado disponible:

Y una vez tengas la API fijada, podrás ver el listado de operaciones:

Una vez tengas la operación seleccionada, aparecerán los campos requeridos por la operación. En este caso, tienes que indicar cuál es el id. Dado que el ID del usuario está en el mensaje de entrada al flujo (msg.checkout.user), así lo indicaremos en el nodo:

Si das a "Done", verás que el nodo ahora tiene más salidas. Cada salida representa un statusCode de la llamada a la operación de la API. Puedes ver dicho valor situando el ratón encima de las salidas:

La cantidad de salidas (y el valor del statusCode) dependerá de lo que se haya definido en la operación. Para el resto del ejemplo, en todas las invocaciones a APIs, la patilla superior será siempre la salida de ejecución correcta (200). El resto representan distintos errores como "elemento no encontrado" (404), "error del servidor" (500), etc.

En el caso de esta operación, se devolverá toda la información de usuario (dirección, correo, teléfono, ...) en el payload del mensaje saliente.
Ya tienes el usuario validado. Ahora vas a validar su dirección. Antes de crear el siguiente nodo de invocación, vas a almacenar la información completa del usuario en otro campo del mensaje distinto a payload, para que no sea sobrescrita. Para ello, almacénala en "msg.user" en un nodo "Function":

Siguiendo los mismos pasos que en el punto anterior, crea la llamada a la operación de validación de dirección:

Como puedes ver en la imagen anterior, la operación (al ser POST) requiere del campo BODY, en el que le indicarás de dónde obtener la dirección. La información de usuario es justo la que devolvió la invocación anterior en el msg.payload. La API de usuarios gestiona los datos mediante una ontología y el resultado del msg.payload es:

Según esto, en el parámetro de entrada "body", indica en qué parte del mensaje se encuentra la dirección, es decir: msg.payload.StoreUsers.address
Una vez validada la dirección de envío, valida el pago, pasando como parámetro la información de pago que habías almacenado en msg.checkout.payment.
A continuación, llama a la API de Inventario para validar los elementos de la compra. La información del pedido se encuentra en msg.checkout.order:
Tras validar los elementos del pedido, invoca la API de Pedidos para generar el pedido en el sistema. Esta operación requiere dos parámetros: usuario y body (elementos del pedido):
Tras crear el pedido, aún tienes que mandar el correo de confirmación al usuario. La operación de notificación por correo requiere que en el body le pases un JSON con los campos "user" que contendrá la información completa del usuario, y el campo "order", que será una lista de los elementos comprados. Primero prepara el msg.payload para que contenga dicha información:

e invoca a la API de notificación por correo:

Con lo hecho hasta ahora, tendrías toda la secuencia de invocaciones a las APIs, suponiendo que ninguna operación falle. Recuerda que el resto de salidas de los nodos invocadores que no están siendo usadas representan (en este caso) errores al llamar a la operación.

Siguiendo los mismos pasos que has realizado anteriormente, puedes completar el flujo, capturando las salidas de error de la siguiente manera:

Dentro del flujo completo, puedes añadir tres secciones:

Rollback en caso de error, que corresponde a esta sección:
En caso de que alguna operación del rollback falle, considera que es una incidencia para el equipo de soporte, así que debes invocar a la API que da de alta las incidencias en el sistema:
En cualquiera de los casos, se avisa al usuario del error:

Cómo orquestar APIs desde el FlowEngine (Ejemplo del Carro de la Compra)

Introducción

Flujo de este ejemplo

Proceso