Grpc Api

El Gateway de Zeebe expone un servicio gRPC definido en gateway.proto que es el punto de entrada principal para todas las operaciones del engine. Cubre deployment de recursos, instanciación de procesos, gestión de jobs, correlación de mensajes, señales, modificación de instancias en runtime, y consulta de topología del cluster. La misma funcionalidad está disponible via REST API HTTP en /v2/.

Servicio Gateway¶

El servicio gRPC Gateway define todos los RPCs disponibles. El gateway actúa como proxy stateless que enruta cada request a la partición correcta del cluster Zeebe según la partition key del recurso.

RPCs de deployment¶

DeployResource¶

Deploya uno o más recursos (procesos BPMN, decisiones DMN, formularios) al cluster.

rpc DeployResource(DeployResourceRequest) returns (DeployResourceResponse);

Request: lista de Resource con name (filename) y content (bytes del archivo). Opcionalmente tenantId para multi-tenancy.
Response: deploymentKey único, lista de Deployment con metadata de cada recurso deployado:
Para procesos: bpmnProcessId, version, processDefinitionKey, resourceName, tenantId.
Para decisiones: dmnDecisionId, dmnDecisionName, version, decisionKey, dmnDecisionRequirementsId, decisionRequirementsKey.
Para formularios: formId, version, formKey, resourceName, tenantId.

Validación: el server parsea y valida cada recurso antes de aceptar el deployment. Si cualquier recurso es inválido, todo el deployment se rechaza atómicamente.

RPCs de process instances¶

CreateProcessInstance¶

Crea una nueva instancia de proceso de forma asíncrona (fire-and-forget).

rpc CreateProcessInstance(CreateProcessInstanceRequest) returns (CreateProcessInstanceResponse);

Request: identificación del proceso (processDefinitionKey O bpmnProcessId + opcionalmente version), variables (JSON string), tenantId, opcionalmente startInstructions (lista de ProcessInstanceCreationStartInstruction para iniciar en un elemento específico en vez del start event), operationReference (correlación con operaciones externas).
Response: processDefinitionKey, bpmnProcessId, version, processInstanceKey, tenantId.

CreateProcessInstanceWithResult¶

Crea una instancia y espera sincrónicamente a que complete, retornando las variables finales.

rpc CreateProcessInstanceWithResult(CreateProcessInstanceWithResultRequest) returns (CreateProcessInstanceWithResultResponse);

Request: mismos campos que CreateProcessInstance más requestTimeout (cuánto esperar antes de timeout) y fetchVariables (lista de nombres de variables a retornar; vacía = todas).
Response: misma metadata del proceso más variables (JSON string con las variables finales del proceso).

Uso típico: procesos cortos o request-reply patterns donde el caller necesita el resultado.

ModifyProcessInstance¶

Modifica una instancia de proceso en ejecución: mueve tokens, agrega/elimina elementos activos.

rpc ModifyProcessInstance(ModifyProcessInstanceRequest) returns (ModifyProcessInstanceResponse);

Request: processInstanceKey, lista de activateInstructions (elementos a activar, con variables y ancestor scope key opcionales), lista de terminateInstructions (element instances a terminar por key), operationReference.
Response: vacío (success/failure indicado por status gRPC).

Caso de uso: reparación manual de instancias bloqueadas, testing, migración de procesos.

MigrateProcessInstance¶

Migra una instancia de proceso de una versión de la definición a otra.

rpc MigrateProcessInstance(MigrateProcessInstanceRequest) returns (MigrateProcessInstanceResponse);

Request: processInstanceKey, migrationPlan con targetProcessDefinitionKey y lista de MappingInstruction (mapeo de sourceElementId → targetElementId).
Response: vacío.

Restricciones: solo se pueden migrar elementos que existen en ambas versiones. Los element instances activos deben tener un mapping correspondiente.

CancelProcessInstance¶

Cancela una instancia de proceso en ejecución, terminando todos los element instances activos.

rpc CancelProcessInstance(CancelProcessInstanceRequest) returns (CancelProcessInstanceResponse);

RPCs de jobs¶

ActivateJobs¶

Activa jobs disponibles para un worker (modelo pull/polling).

rpc ActivateJobs(ActivateJobsRequest) returns (stream ActivateJobsResponse);

Request: type (tipo de job a activar), worker (nombre del worker), timeout (ms hasta que el job vuelve a ser activable), maxJobsToActivate, fetchVariable (lista de variables a incluir), requestTimeout (long polling: el server mantiene la conexión abierta hasta que hay jobs o se cumple el timeout), tenantIds (filtro multi-tenancy).
Response (stream): cada mensaje contiene una lista de ActivatedJob.

StreamActivatedJobs¶

Conexión streaming persistente para recibir jobs a medida que se crean (modelo push).

rpc StreamActivatedJobs(StreamActivatedJobsRequest) returns (stream ActivatedJob);

Request: type, worker, timeout, fetchVariable, tenantIds.
Response: stream continuo de ActivatedJob individuales.

Ventaja sobre ActivateJobs: menor latencia (no hay polling interval), menor overhead de red. El server pushea jobs al worker inmediatamente cuando se crean.

CompleteJob¶

Marca un job como completado exitosamente.

rpc CompleteJob(CompleteJobRequest) returns (CompleteJobResponse);

Request: jobKey, variables (JSON con variables de resultado), opcionalmente result (JobResult con denied: bool, corrections, statusCode).
Response: vacío.

El campo result con JobResult permite al worker indicar que el job fue denegado (por ejemplo, un user task que no cumple condiciones) o proveer correcciones, sin fallar el job.

FailJob¶

Marca un job como fallido con posibilidad de retry.

rpc FailJob(FailJobRequest) returns (FailJobResponse);

Request: jobKey, retries (retries restantes; 0 = crear incidente), errorMessage, retryBackOff (ms antes del próximo retry), variables (actualizar variables para el retry).
Response: vacío.

ThrowError¶

Lanza un error BPMN desde un job, activando error boundary events.

rpc ThrowError(ThrowErrorRequest) returns (ThrowErrorResponse);

Request: jobKey, errorCode (matchea con el errorCode del boundary event), errorMessage, variables.
Response: vacío.

UpdateJobTimeout / UpdateJobRetries¶

Actualizan el timeout o retries de un job activo sin completarlo o fallarlo.

RPCs de mensajes y señales¶

PublishMessage¶

Publica un mensaje para correlación con message catch events o message start events.

rpc PublishMessage(PublishMessageRequest) returns (PublishMessageResponse);

Request: name (nombre del mensaje, matchea con la message definition), correlationKey (para correlacionar con la instancia correcta — usado como partition key), timeToLive (ms), messageId (idempotency key), variables, tenantId.
Response: key, tenantId.

Correlación: el engine busca suscripciones activas que matcheen (name, correlationKey). Si encuentra una, entrega el mensaje. Si no, el mensaje se almacena en un buffer por el TTL esperando una suscripción futura.

CorrelateMessage¶

Versión síncrona de correlación que retorna el resultado inmediatamente.

rpc CorrelateMessage(CorrelateMessageRequest) returns (CorrelateMessageResponse);

Response incluye processInstanceKey y tenantId si el mensaje fue correlacionado.

BroadcastSignal¶

Emite una señal que activa todos los signal catch events y signal start events suscritos.

rpc BroadcastSignal(BroadcastSignalRequest) returns (BroadcastSignalResponse);

Request: signalName, variables, tenantId.
Response: key, tenantId.

Diferencia con mensajes: las señales son broadcast (1:N), no tienen correlation key. Todos los catch events suscritos a esa señal se activan.

RPCs de decisiones¶

EvaluateDecision¶

Evalúa una decisión DMN directamente, sin necesidad de un proceso.

rpc EvaluateDecision(EvaluateDecisionRequest) returns (EvaluateDecisionResponse);

Request: decisionKey O decisionId, variables (input para la decisión), tenantId.
Response: decisionKey, decisionId, decisionName, decisionVersion, decisionRequirementsId, decisionRequirementsKey, output (JSON con el resultado), evaluatedDecisions (lista de todas las decisiones evaluadas en la cadena DRG), failedDecisionId, failureMessage, tenantId.

RPCs de variables¶

SetVariables¶

Actualiza variables en el scope de un element instance.

rpc SetVariables(SetVariablesRequest) returns (SetVariablesResponse);

Request: elementInstanceKey (scope donde escribir), variables (JSON), local (si true, escribe solo en el scope local; si false, propaga al scope más cercano que ya tiene la variable), operationReference.
Response: key.

RPCs de topología¶

Topology¶

Consulta la topología actual del cluster.

rpc Topology(TopologyRequest) returns (TopologyResponse);

Response: brokers (lista con nodeId, host, port, partitions con partitionId, role LEADER/FOLLOWER/INACTIVE, health), clusterSize, partitionsCount, replicationFactor, gatewayVersion.

Tipo de dato ActivatedJob¶

Estructura central retornada por ActivateJobs y StreamActivatedJobs:

Campo	Tipo	Descripción
`key`	int64	Key único del job
`type`	string	Tipo de job (matchea con la task definition)
`processInstanceKey`	int64	Key de la instancia de proceso
`bpmnProcessId`	string	ID del proceso BPMN
`processDefinitionVersion`	int32	Versión de la definición
`processDefinitionKey`	int64	Key de la definición
`elementId`	string	ID del elemento BPMN que creó el job
`elementInstanceKey`	int64	Key del element instance
`customHeaders`	string	JSON con custom headers del task definition
`worker`	string	Nombre del worker que activó el job
`retries`	int32	Retries restantes
`deadline`	int64	Timestamp Unix (ms) del deadline de este job
`variables`	string	JSON con las variables del scope
`tenantId`	string	Tenant del proceso
`jobKind`	JobKind enum	Tipo de job
`listenerEventType`	ListenerEventType enum	Tipo de evento listener (si aplica)

JobKind enum¶

Valor	Significado
`BPMN_ELEMENT`	Job creado por un elemento BPMN estándar (service task, send task, etc.)
`EXECUTION_LISTENER`	Job para un execution listener configurado en un elemento
`TASK_LISTENER`	Job para un task listener (en user tasks)
`AD_HOC_SUB_PROCESS`	Job creado por actividades dentro de un ad-hoc sub-process

ListenerEventType enum¶

Valor	Significado
`START`	Listener de inicio del elemento
`END`	Listener de fin del elemento
`COMPLETING`	Listener durante la fase de completación
`CREATING`	Listener durante la fase de creación
`CANCELING`	Listener durante la fase de cancelación
`ASSIGNING`	Listener de asignación (user tasks)
`UPDATING`	Listener de actualización (user tasks)

Multi-tenancy¶

El soporte de multi-tenancy permea toda la API:

Todos los requests de creación aceptan tenantId para asignar un recurso a un tenant.
Los requests de consulta (ActivateJobs, StreamActivatedJobs) aceptan tenantIds (lista) para filtrar.
TenantFilter enum: PROVIDED (filtrar por los tenant IDs proporcionados) o ASSIGNED (todos los tenants asignados al caller autenticado).
El tenant ID se propaga a todos los records derivados (process instances, jobs, variables, etc.).

REST API (`/v2/`)¶

La misma funcionalidad de la API gRPC está disponible via HTTP REST en el path base /v2/. El mapeo es directo:

gRPC RPC	REST Endpoint	Método HTTP
`CreateProcessInstance`	`/v2/process-instances`	POST
`CreateProcessInstanceWithResult`	`/v2/process-instances` (con header)	POST
`CancelProcessInstance`	`/v2/process-instances/{key}`	DELETE
`DeployResource`	`/v2/deployments`	POST (multipart)
`ActivateJobs`	`/v2/jobs/activation`	POST
`CompleteJob`	`/v2/jobs/{key}/completion`	POST
`FailJob`	`/v2/jobs/{key}/failure`	POST
`PublishMessage`	`/v2/messages`	POST
`BroadcastSignal`	`/v2/signals/broadcast`	POST
`Topology`	`/v2/topology`	GET

El REST API usa JSON en vez de Protobuf, facilitando integración con lenguajes/frameworks sin soporte gRPC nativo. Internamente, el gateway traduce entre REST y gRPC.