Jobs (ejecuciones)

Un job es una ejecución concreta de un proceso sobre una máquina. Cuando lanzas un proceso, NORA crea un job, lo encola y una máquina con el agente conectado lo recoge, ejecuta el robot y reporta el resultado. Cada job guarda su estado, sus logs, los datos de entrada/salida y, si falla, el mensaje de error.

Anatomía de un job

Un job referencia siempre un proceso y una máquina, y lleva estos campos principales (ver respuesta de la API más abajo):

Campo	Descripción
id	Identificador único del job (UUID).
process_id / machine_id	Proceso ejecutado y máquina asignada.
status	Estado actual (ver Estados).
priority	Prioridad de encolado: 1 baja, 3 normal, 5 urgente (rango 1–5).
input_data	Datos de entrada para el robot (objeto JSON, máx. 1 MB).
output_data	Datos devueltos por el robot al finalizar.
logs	Flujo de logs acumulado.
error_message	Mensaje de error si el job falló.
started_at / finished_at	Marcas de inicio y fin de ejecución.
progress_percent / progress_message	Progreso reportado por el robot.
retry_count	Número de reintento (0 = ejecución original).

Nota

Las prioridades disponibles dependen de tu plan. Si solicitas una prioridad no permitida para tu plan, la API responde con un error priority_not_allowed.

Cómo se lanza un job

Desde la interfaz

En el panel de NORA, abre un proceso y pulsa Ejecutar. Selecciona la máquina destino (debe estar activa y en línea), ajusta la prioridad y, si el proceso espera datos, completa el input_data. NORA crea el job en estado pending y lo asigna a la máquina cuando esta tenga capacidad libre.

Para crear un job desde la UI necesitas rol admin u operator. El rol viewer solo puede consultar jobs.

Por API

Los clientes externos lanzan jobs con una clave de API (X-API-Key: nora_ak_...). El endpoint y el payload exactos se documentan en Disparar jobs. En resumen:

curl -X POST https://nora-api.valisoftconsulting.com/api/v1/jobs/trigger \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "f1e2d3c4-0000-0000-0000-000000000000",
    "input_data": {"cliente": "ACME"},
    "priority": 3
  }'

machine_id es opcional en la API por clave: si lo omites, NORA elige automáticamente una máquina activa y en línea del tenant. La respuesta va envuelta en {"success": true, "data": {...}}:

{
  "success": true,
  "data": {
    "id": "9a8b7c6d-0000-0000-0000-000000000000",
    "process_id": "f1e2d3c4-0000-0000-0000-000000000000",
    "machine_id": "1234abcd-0000-0000-0000-000000000000",
    "status": "pending",
    "priority": 3,
    "input_data": {"cliente": "ACME"},
    "output_data": null,
    "logs": null,
    "error_message": null,
    "started_at": null,
    "finished_at": null,
    "retry_count": 0,
    "stop_requested": false,
    "process_name": "Facturación diaria",
    "machine_name": "VM-PROD-01"
  }
}

Crear un job por API requiere una clave con scope jobs:write. El endpoint está limitado a 30 solicitudes por minuto. Consulta autenticación para los scopes.

Estados

El status de un job evoluciona según estas transiciones válidas (definidas en el backend):

flowchart TD
    pending["pending<br/>(en cola)"]
    assigned["assigned<br/>(asignado a máquina)"]
    running["running<br/>(en ejecución)"]
    completed["completed"]
    failed["failed"]
    cancelled["cancelled"]

    pending -->|máquina lo recoge| assigned
    assigned -->|robot inicia| running
    running -->|éxito| completed
    running -->|error| failed
    pending -->|cancelar| cancelled
    assigned -->|cancelar| cancelled
    running -->|cancelar| cancelled

Estado	Significado
pending	Job creado y en cola, a la espera de que una máquina con capacidad lo recoja.
assigned	Una máquina lo tomó de la cola; el robot aún no ha comenzado.
running	El robot está ejecutándose. Se fija started_at.
completed	Terminó correctamente. Se fija finished_at y se guarda output_data.
failed	Terminó con error. Se fija finished_at y se guarda error_message.
cancelled	Cancelado antes de completar.

Nota

completed, failed y cancelled son estados terminales. Solo un job en uno de estos estados puede re-ejecutarse (rerun), lo que crea un nuevo job a partir del original. Si una máquina deja de enviar latido, sus jobs running/assigned pasan a failed automáticamente.

Logs

Mientras el job se ejecuta, el robot envía sus logs y NORA los anexa al campo logs del job, visible en tiempo casi real en la interfaz. El SDK produce cada línea con este formato:

[2026-06-19T14:03:11Z] [INFO] Procesando factura 0042
[2026-06-19T14:03:12Z] [ERROR] Timeout al abrir el portal | {"intento": 3}

Es decir: marca de tiempo UTC ISO‑8601 entre corchetes, nivel en mayúsculas (INFO, WARNING, ERROR, DEBUG) y el mensaje. Si pasas datos estructurados, se añaden tras una barra | como JSON. La función log() del SDK genera estas líneas; ver SDK de robots para los detalles.

Los logs antiguos pueden archivarse según la política de retención. Si un job tiene logs archivados, se recuperan por separado a través de su endpoint de logs archivados.

Cómo detener un job

Detener (stop) solicita una parada ordenada de un job en ejecución. NORA marca stop_requested = true; el agente lee esa señal y termina el robot de forma controlada. Solo se puede detener un job en estado running.

Por API, con una clave de scope jobs:stop:

curl -X POST https://nora-api.valisoftconsulting.com/api/v1/jobs/{job_id}/stop \
  -H "X-API-Key: nora_ak_xxxxxxxxxxxxxxxxxxxx"

Stop frente a cancel

Stop solo aplica a jobs running y pide una parada ordenada. Cancel aplica a jobs pending, assigned o running y los mueve directamente a cancelled. Un job ya cancelado hace que el agente reciba la señal kill para abortar el proceso si seguía vivo.

La respuesta de stop devuelve el job actualizado, envuelto en {"success": true, "data": {...}}.