Bproc de Webhook

GO
, ,
1

Bproc de Webhooks

¿Qué es?

Se trata de una nueva herramienta de desarrollo que permite integrar al Sistema GO con otra aplicación o servicios cuando ocurren eventos específicos. Esto ofrece beneficios significativos a una organización. Aquí hay algunos de los beneficios de su uso:

  • Ampliación de funcionalidad a través de la automatización de procesos de negocio
  • Ahorro de tiempo y recursos para implementar soluciones especiales o personalizadas, disponiendo de fácil acceso a datos del contexto y a servicios externos
  • Flexibilidad, adaptabilidad y escalabilidad

¿Cómo funciona?

Al ocurrir un determinado evento sobre un Maestro o Tipo de documento, se puede disponer de un Bproc del tipo Webhook para que ejecute automáticamente una operación determinada, a través del consumo de un API determinada.

El flujo del webhook funciona de la siguiente manera:

  1. Configuración del Webhook: se establece la aplicación receptora (el servicio que desea recibir la información), se configura una URL que estará a la espera de las solicitudes entrantes
  2. Evento Desencadenante: en la aplicación emisora se desencadenará el webhook, para que esto ocurra, se debe definir el o los eventos específicos que el sistema deben atender, como por ejemplo el alta de un nuevo cliente, la actualización de datos de un proveedor, el envío de un formulario, etc.
    Nota: inicialmente los eventos serán acotados.
  3. Disparo del Webhook: Cuando se produce el evento desencadenante, la aplicación emisora envía una solicitud HTTP POST a la URL del webhook configurado en la aplicación receptora.
  4. Procesamiento del Webhook: La aplicación receptora recibe la solicitud del webhook y procesa los datos enviados, realizando las acciones necesarias en función de la información proporcionada por la solicitud.
  5. Acuse de Recibo: La aplicación receptora devuelve de forma inmediata (lo más rápido posible), el acuse de recibo, en el correspondiente Response.
  6. Monitoréo: un usuario del sistema puede revisar el estado de ejecución de cada bproc, viendo si se ejecutó y si se tiene el acuse de recibo de la aplicación receptora

Consideraciones:

  • Solo aplica a Tipos de documentos y a Maestros del sistema
  • La ejecución de los procesos automáticos no afecta de ninguna forma a la transacción principal, esto incluye los tiempos de procesamiento
  • Inicialmente solo se incluyen los siguientes eventos:
    • Documentos: (Alta / Modificación / Anulación)
    • Maestros: (Alta / Modificación / Eliminación)
  • Un usuario desarrollador puede establecer por BProc cuales son los maestros o las categorías de los documentos soportados por la Aplicación Receptora
  • Un usuario configurador puede habilitar los Bprocs de documentos para tipos de documentos específicos, siempre y cuando pertenezcan a alguna de las categorías soportadas por la aplicación receptora

Configuración de un Bproc webhook

Maestros de BPROCS

Se extiende la funcionalidad del maestro de BPROCs para que soporte al tipo Webhooks

1332×750 45 KB

  • Nueva Solapa Configuración:
    Se habilita cuando se selecciona el tipo de Bproc “Webhook”
    • Se indicar la clase (Documento / Maestro)
    • En función de la clase indicada:
      • Documentos: se debe indicar qué categorías de comprobantes son soportadas por la aplicación receptora
      • Maestros: se debe indicar para con qué maestros funciona la aplicación receptora
    • Cuales son los eventos que aplican
    • La URL que permite a la aplicación emisora acceder a la aplicación receptora

1344×743 92.1 KB

Habilitación a tipos de documentos

Se agrega una funcionalidad que permite habilitar Webhooks a tipos de documentos (Facturas de venta / Pedidos / etc). La modificación consiste en el agregado de una nueva Solapa “Webhooks“ en el tipo de documento desde donde se permite habilitar y deshabilitar los distintos Webhooks.

Condiciones de habilitación:

  • El Bproc del tipo Webhook debe estar activo
  • El tipo de documento debe pertenecer a una de las categorías habilitadas (que funcionan) para el Webhook. Estas categorías son las configuradas en el Bproc correspondiente.

1041×960 117 KB

Registro de Transacciones de Webhooks

Se crea un registro de las ejecuciones de los Webhooks que permiten consultar el estado de todas las transacciones.

Dispone de la siguiente información por espacio de trabajo:

  • ID del Evento: identifica de forma unívoca cada una de las ejecuciones de Webhooks que ocurre. Es un número autoincremental de transacciones.
  • Empresa: Es el código de la empresa desde donde se ejecutó la transacción
  • Webhooks [1…n]: son los distintos Webhooks que deben atender a esta transacción.
    Por cada webhook se debe administrar la siguiente información
    • Código: es el código que identifica de forma unívoca al Webhook para el espacio de trabajo
    • Fecha y hora de última actualización del estado
    • Estado de ejecución: puede ser alguno de estas opciones:
      • 0 - Enviado: La transacción del sistema inserta los registros dejándolos en este estado inicial
      • 1 - Recibido ok: tras recibir el acuse de recibo “Ok” del receptor, el Emisor (1 hilo x Webhook) pone el registro en este estado
      • 4 - Finalizado error: a este estado se llega de la siguiente forma:
        • El Emisor (1 hilo x Webhook):
          • Registra este estado si no le llega el acuse de recibo luego de un tiempo prudencial (sale por timeout).
            Nota para diseño: Es importante que los micro servicios que se ejecuten manden el acuse de recibo inmediatamente, y no lo haga luego del procesamiento.
          • Cambia a este estado si recibe como respuesta del mensaje un error no controlado (Caída del servidor, Servidor inexistente, Problemas de certificados, Seguridad, micro servicio inexistente, etc)
    • Porcentaje de avance: puede tomar valores desde 0 a 100. Inicialmente es 0, es de uso opcional por los Webhooks
    • Observaciones: lo puede usar tanto el emisor para registrar errores.
  • timestamp: Es el momento exacto en que se genera el envío
  • user: El código del usuario que generó el evento.
  • objeto involucrado: es la instancia de maestro o transacción involucrada. Este debe contener los siguientes datos
    • Generales
      • Clase: se debe indicar si es un maestro, o un documento
      • Tipo de evento: debe ser uno de estos (Create, Update, Delete, Cancellation)
      • id: La identificación del objeto. Puede ser el código de un documento o bien el del maestro afectado por el evento.
      • Parámetros por tipo de servicio (en función del tipo de servicio de notificación), se debe indicar dados distintos que son requeridos para hacer efectiva la notificación)
    • Si es un maestro
      • Type: se debe indicar el VO (ProductoVO, ClienteVO, ProveedorVO, etc)
    • Si es una transacción
      • Type: se debe indicar el tipo de documento (FV, FC, etc)
      • Category: es la categoría de la transacción
      • Sucursal: La sucursal donde se guardó la transacción

Vista de transacciones del Webhook

Se debe crear una vista que permita consultar el estado de los Webhooks

Opción de menú de acceso: Menú izquierdo → Configuración → Diseño del Espacio de Trabajo → Actualizaciones → Monitor de Webhooks

Debe contar con los parámetros:

  • Fecha de ejecución desde y hasta, ambos de carga obligatoria.
    Por defecto ambos deben tener asignada la fecha del día.
  • El estado: selector múltiple, por defecto debe tener seleccionado los Finalizados con Errores.

Se deben mostrar a simple vista los siguientes datos:

  • El Id de la llamada
  • El Webhook (Código y Nombre)
  • El estado de ejecución
  • Observaciones

Datos ocultos:
El usuario puede optar luego por agregar a la vista el resto de los datos del registro que inicialmente se encuentran ocultos.

Ejecución del Webhooks

Cuando se ejecuta un webhook se realiza un llamado a una aplicación receptora para que ejecute el proceso correspondiente, para que pueda operar, el emisor le provee en el propio llamado de la siguiente información del contexto:

  • id del evento
  • código del Webhook
  • tipo de Webhook (Documento / Maestro)
  • usuario
  • timestamp
  • objeto (todos los datos del maestro y documentos)

Caso de Uso del negocio ejemplo

Libración de un pedido de venta por cancelación de deuda crediticia

Actualmente al dar de alta un nuevo pedido de venta, existe una bpm que valida el estado de la cuenta corriente del cliente, si la misma se encuentra dentro de los límites, entonces lo indica como Ok, caso contrario lo deja en estado “Pendiente de Firma”, esperando que un usuario firmante lo autorice.

El problema con este flujo, es cuando el firmante no autoriza el pedido por la deuda existente, pero luego pasado un tiempo, cuando el cliente cancela esta deuda, el firmante se demora un tiempo en monitorear el estado del cliente y aprobar los pedidos, frenando las ventas.

Solución propuesta:

Se crea el siguiente webhook “Aviso Pago para Liberación de PV”

  • Cuando se ejecuta: al realizar una cobranza sobre un cliente, cuando este último tiene al menos un pedido de venta en estado “Pendiente de firma” siempre que el estado de la cuenta corriente resultante del pago no siga siendo deudor.
  • Qué hace el webhook: se manda un aviso por email a los firmantes correspondientes, avisandoles de la cancelación de deuda, para que le liberen el/los pedidos. En el cuerpo se detallan algunos datos del cliente, el saldo de su CC, y el detalle de los pedidos de ventas que debe firmar.

Especificación técnica:

Bproc de webhook del tipo API

En el campo URL del BPROC, el desarrollador indica aquí la ubicación del recurso que representa la API, donde puede también, aplicar parámetros del tipo hardcodeado como en cualquier URL.
El sistema al ejecutar el BPROC, envía adicionalmente en el Post información en formato Json con los datos indicados anteriormente.

Es importante a la hora de desarrollar una API que esté preparada para recibir esta estructura de información y darle el debido tratamiento.

Ejemplo de formato JSON enviado:


{

"eventID":1046,

"webhook":"WS83S",

"webhookType":"Documento/Maestro",

"user":"jperez@finnegans.com.ar",

"timeStamp":"2022-11-14T13:25:26.625Z",

"object":{

"type":"documento:FV/maestro:ProductoVO",

"category":"FacturaVenta

"Code(externo)":"4587",

"event":"create/update/nullify/delete"

}

}

Ejemplo para un documento:

{

"eventID":1046,

"webhook":"WS83D",

"webhookType":"Documento",

"user":"jperez@finnegans.com.ar",

"timeStamp":"2022-11-14T13:25:26.625Z",

"object":{

"type":"FV”,

"category":"FacturaVenta”,

"Code(externo)":"4587",

"event":"create/update/nullify"

}

}

Ejemplo con un Maestro:

{

"eventID":1047,

"webhook":"WS83M",

"webhookType":"Maestro",

"user":"jperez@finnegans.com.ar",

"timeStamp":"2022-11-14T13:25:26.625Z",

"object":{

"type":"ProductoVO",

"category": "”,

"Code(externo)":"2345",

"event":"create/update/delete"

}

}