FINORA Plataforma · Guía

Publica un proceso que reacciona a un evento del core

ImplementadoImplementadoAvanzado40 min

Lee antes Orquestación de procesos con BPMN 2.0.

Lo que necesitas

Qué	Rol en el orquestador	Para qué
Tu cliente de diseño	`ORQ_ADMIN`	Subir, enviar y activar la definición
El cliente de otra persona	`ORQ_APPROVER`	Aprobarla; si además está en el grupo `contabilidad`, completar la tarea
Un destino `finora-core` aprobado hacia `https://<su-gateway>`	—	Las llamadas del proceso al core
Un cliente del core o del gateway con el alcance `webhook:write`	—	Suscribir el webhook

En los ejemplos, O=https://<su-orquestador> y cada cliente se autentica con -u <cliente>:<secreto>. También puedes pedir un token con POST $O/api/v1/oauth/token (grant_type=client_credentials) y usar Authorization: Bearer.

Diseña el proceso

Este proceso inicia cuando llega el mensaje finora_evento_core, consulta el plan de cuentas por el gateway y deja una tarea de revisión al grupo contabilidad:

flowchart LR
  I((Mensaje<br/>finora_evento_core)) --> C["Consultar el plan de cuentas<br/>callDestination · GET /v1/glaccounts"]
  C --> R[Revisar el asiento<br/>grupo contabilidad]
  R --> F((Fin))

Guárdalo como revision-asiento-core.bpmn20.xml:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             xmlns:flowable="http://flowable.org/bpmn"
             xmlns:finora="http://finoracore.com/bpmn"
             targetNamespace="http://finoracore.com/procesos">
  <message id="mEventoCore" name="finora_evento_core"/>
  <process id="revisionAsientoCore" name="Revisión de asientos del core" isExecutable="true">
    <startEvent id="inicio"><messageEventDefinition messageRef="mEventoCore"/></startEvent>
    <sequenceFlow id="f1" sourceRef="inicio" targetRef="consultarPlan"/>
    <serviceTask id="consultarPlan" name="Consultar el plan de cuentas" flowable:async="true"
                 flowable:delegateExpression="${callDestination}"
                 finora:destination="finora-core" finora:method="GET" finora:path="/v1/glaccounts"
                 finora:statusVariable="estadoHttp">
      <extensionElements>
        <flowable:failedJobRetryTimeCycle>R3/PT30S</flowable:failedJobRetryTimeCycle>
      </extensionElements>
    </serviceTask>
    <sequenceFlow id="f2" sourceRef="consultarPlan" targetRef="revisar"/>
    <userTask id="revisar" name="Revisar el asiento" flowable:candidateGroups="contabilidad"/>
    <sequenceFlow id="f3" sourceRef="revisar" targetRef="fin"/>
    <endEvent id="fin"/>
  </process>
</definitions>

Fíjate en tres cosas: la tarea automática solo usa ${callDestination} (cualquier otra implementación se rechaza); flowable:async con failedJobRetryTimeCycle hace que un fallo de red se reintente tres veces cada 30 segundos antes de quedar en incidente; y el id del proceso (revisionAsientoCore) es su clave.

Publícalo con maker-checker

Súbelo. Con tu cliente de diseño:
Ventana de terminal
```
curl -s "$O/api/v1/process-definitions" -u <diseñador>:<secreto> \
  -H 'Content-Type: application/xml' --data-binary @revision-asiento-core.bpmn20.xml
```
La respuesta trae el id de la definición y el estado DRAFT. Si el BPMN viola la política de seguridad, la respuesta es 422 con el motivo y nada se guarda.

Envíalo a aprobación.

curl -s -X POST "$O/api/v1/process-definitions/<id>:submit" -u <diseñador>:<secreto>

Estado: PENDING_APPROVAL.

Que lo apruebe otra persona. Si intentas aprobarlo tú, la respuesta es 403 MAKER_CHECKER. Lo aprueba el cliente de otra persona con el rol ORQ_APPROVER:
Ventana de terminal
```
curl -s -X POST "$O/api/v1/process-definitions/<id>:approve" -u <aprobador>:<secreto>
```
Estado: APPROVED. Si lo rechaza, usa :reject con {"reason": "…"} y el estado pasa a REJECTED.
Actívalo.
Ventana de terminal
```
curl -s -X POST "$O/api/v1/process-definitions/<id>:activate" -u <diseñador>:<secreto>
```
Estado: CURRENT. Desde ahora el motor escucha el mensaje finora_evento_core. Si el destino finora-core no existe o no está aprobado, la activación responde 422 DESTINO_INEXISTENTE. Solo un proceso puede escuchar un mismo mensaje de inicio.

Suscribe el webhook en el core

Crea la suscripción en el core del sandbox, con el alcance webhook:write. Por el gateway es POST https://<su-gateway>/v1/webhooks; en el core, POST https://<su-core>/api/v1/ext/webhooks; también puedes hacerlo en la consola del core, en Webhooks.
```
{
  "name": "orquestador-revision-asientos",
  "url": "https://<su-orquestador>/api/v1/webhooks/finora-core/finora_evento_core",
  "eventTypes": ["AccEntryPosted"],
  "method": "POST"
}
```
El último segmento de la URL es el nombre del mensaje que escucha tu proceso. La URL debe ser HTTPS.
Guarda el secreto. La respuesta trae el secreto de firma una sola vez. Entrégalo por el canal seguro a quien administra el orquestador, que lo agrega a su configuración de secretos de webhooks del core (ORQ_CORE_WEBHOOK_SECRETS, con la forma fuente|secreto) y reinicia el orquestador. Sin ningún secreto configurado, el receptor responde 503.
Comprueba que el core esté publicando. El core solo entrega webhooks con su bandeja de eventos y su despachador de webhooks encendidos; pregunta al administrador de la plataforma si dudas.

Verifica el caso

Provoca un evento en el sandbox: registra un asiento de práctica, por ejemplo con Sigue un asiento de punta a punta en datos ficticios.
Mira la entrega en el core. Busca las entregas de tu suscripción (POST /api/v1/ext/webhooks/deliveries:search en el core, o la pantalla Webhooks). Debe aparecer DELIVERED, AccEntryPosted, HTTP 201 en el intento 1.
Encuentra el caso. El receptor abre el caso con la clave de negocio wh-<X-Finora-Webhook-Id>. Busca su tarea:
Ventana de terminal
```
curl -s "$O/api/v1/tasks?candidateGroup=contabilidad" -u <aprobador>:<secreto>
```
Con el processInstanceId de la tarea, consulta el caso:
Ventana de terminal
```
curl -s "$O/api/v1/process-instances/<processInstanceId>" -u <diseñador>:<secreto>
```
Verás el estado ACTIVE, la actividad revisar pendiente y las variables evento, eventType (AccEntryPosted), webhookId, fuenteWebhook y estadoHttp (200).

Completa la revisión con el cliente del grupo contabilidad:

curl -s -X POST "$O/api/v1/tasks/<taskId>:complete" -u <aprobador>:<secreto> \
  -H 'Content-Type: application/json' -d '{"variables": {"revisado": true}}'

El caso pasa a COMPLETED.

Prueba la idempotencia. Reenvía la misma entrega desde el core (:resend). El receptor responde 200 con Idempotent-Replayed: true y el mismo caso: no se abre otro.

Errores frecuentes

Qué pasa	Por qué	Qué hacer
`403` `MAKER_CHECKER` al aprobar	Quien aprueba es quien creó o envió la definición	Pide la aprobación a otra persona
`422` al subir	El BPMN usa algo fuera de la política (una clase, un script, una tarea HTTP directa)	Reemplázalo por `callDestination` hacia un destino aprobado
`422` `DESTINO_INEXISTENTE` al activar	El destino no existe o tiene un alta sin aprobar	Pide que lo aprueben en el orquestador
La entrega del core falla con `401`	El secreto del orquestador no es el de la suscripción, o el reloj de un lado está desfasado más de 300 s	Configura el secreto correcto y revisa la hora
La entrega falla con `404`	Ninguna versión vigente escucha ese mensaje	Revisa que la definición esté `CURRENT` y que la URL termine en el nombre del mensaje
El caso queda en `INCIDENT`	La llamada al gateway falló tras los tres reintentos	Corrige la causa y reintenta con `POST $O/api/v1/process-instances/<id>/incidents:retry-all`; el reintento repite su clave de idempotencia y no duplica nada