Complete Execution History

"Did yesterday's screening finish? How many failed? Who started it?" — without a durable history, answering means digging through technical records. DATTA consolidates every background task (uploads, rules, ETL, streams, screening) into a single live tracking panel and into a permanent history with period filtering that survives platform restarts and upgrades. You audit what already ran, when, by whom and with what outcome — in seconds.

This guide complements the background executions panel, which describes the side panel and the "Histórico (últimas 10)" section from the end user's point of view. Here the focus is the durable layer, the period filter and day-to-day operation through the interface itself.

Two levels of history

The "Execuções em segundo plano" panel mixes data of two distinct natures, and understanding the difference avoids surprises:

The panel's "Histórico (últimas 10)" section is just the most recent window of the durable history. The complete history with period filtering lives on the dedicated page (screens/historico-execucoes.html), reachable from the panel itself, through the link that opens the complete history next to "Histórico (últimas 10)".

What each record holds

Each terminal execution becomes a document in the datta_bg_executions system index — re-recording the same execution updates the record instead of duplicating it, because the key is the id field.

Today the producer already integrated is batch case screening, which writes the record when it completes, fails or is canceled — best-effort, with an 8 s limit, so that a failure to write the history never brings down the screening itself. The other types (uploads, rules, ETL, embeddings) join the same contract as they are integrated.

Writing is reserved for the platform's internal services and authenticated server-to-server: the regular user never writes to the history directly, only reads it. Both operations (writing a terminal record and reading the history) are in the API reference, with the SEARCH_EXECUTE (write) and SEARCH_VIEW (read) permissions.

Period filter

Reading the history accepts three parameters: the start of the interval, the end of the interval (both in epoch ms, compared against finalizadoEm) and a record limit — 10 by default, capped at 1000.

• Without an interval: returns the latest executions, up to the requested limit.
• With a start and/or an end: applies the range over finalizadoEm.
• The ordering is always most recent first.

The history page translates the dates chosen in the picker (yyyy-mm-dd) into epoch ms — the start at the first instant of the day (00:00:00) and the end at the last one (23:59:59.999) — and queries with a limit of 500 records.

The complete history page

The dedicated page (screens/historico-execucoes.html) follows the platform's design system: theme variables, dark/light and a responsive layout from 768px. In the telemetry it shows up under the datta-fe-historico-execucoes service name.

• Filters: two labeled date fields — Data início and Data fim — plus the Limpar, refresh and Aplicar filtro buttons.
• Table: Status (Concluída, Falhou or Cancelada badge), Type, Execution (title + context), When, Total, OK, Errors and Detail (message).
• While loading: a spinner fills the table area — never a blank screen.
• No data: "Nenhuma execução encontrada" ("No execution found"), with the "no período selecionado" ("in the selected period") suffix when a filter is active.
• Handled error: if the query fails, you see "Não foi possível carregar o histórico." ("Could not load the history.") with the Tentar novamente button — never a raw error code or a technical detail.
• Navigation trail: DATTA › Execuções em segundo plano, with the last link non-clickable.

The datta_bg_executions index is created lazily, on the first write. While no terminal execution has been recorded, the query treats the missing index as empty history — not as an error. The panel and the page show the empty state, not a failure message.

Hands-on example — auditing the week's screenings

1. Open the "Execuções em segundo plano" panel and go into the complete history.
2. Fill Data início with Monday and Data fim with Friday of the week you want.
3. Click Aplicar filtro.
4. The table lists each screening in the period with status, counts and message — for example, a Concluída · triagem · "Triagem em lote — Processos" · 120 total · 118 OK · 2 errors row.
5. Use the row shortcut to reopen the execution's screen and inspect the errors.

Orphaned tasks resolve themselves

The live state of ingestions and uploads (the panel's "Ingestões e uploads" section) lives in the task hub, but the actual processing runs in memory of the documents module. If that module restarts in the middle of a batch (an upgrade, running out of memory, a machine going down), the record stays RUNNING in the hub while the work is already dead — an orphaned task: the panel shows "Executando", but nothing is happening.

DATTA communicates that death at restart time, without waiting for staleness or the 24 h expiry. There are two complementary paths:

1. Controlled shutdown (a normal upgrade): on receiving the shutdown signal, the module walks the in-flight batches, marks each one as failed and cancels the processing, within the grace period — best-effort, with a 3 s limit per batch. The recorded message is "Interrompida: serviço reiniciado durante o processamento." ("Interrupted: service restarted during processing.")
2. Abrupt deaths (out of memory, forced termination, machine loss): when it comes back up, the platform sweeps the tasks listed as active, marks every task still RUNNING/QUEUED as Falhou and removes it from the active list. This covers the cases where the controlled shutdown never got to run.

Controlled shutdown              Out of memory / machine loss
        │                                   │
        ▼                                   ▼
in-flight batches marked            (does not run)
as failed, still up                         │
        │                                   ▼
        └──────────────► restart ──► sweep on startup
                                     marks the orphans as Falhou
                                     and drops them from the active list

The upshot: a task stuck on "Executando" resolves itself on the next restart — resend the batch and move on.

Why this is safe

The startup sweep assumes that any active task on a freshly started instance is provably orphaned. That holds because the documents module:

• runs as a single instance, with no overlap — the old instance is shut down before the new one comes up; and
• is the only producer of the task hub (every background ingestion task is born there).

Operational warning: if some day the documents module starts running on several simultaneous instances, adopts an overlapping upgrade, or another service starts writing tasks into the same hub, the startup sweep stops being safe — it would kill the task of a coexisting instance. In that scenario, the sweep must be scoped by owner/instance before marking anything as orphaned. Treat this as a blocking prerequisite for any change to that execution profile.

Hub read robustness

Reading the hub is defensive end to end: it ignores auxiliary keys (task:cancel:*), tolerates corrupted records (an invalid record is discarded instead of bringing down the query) and sorts in a way that tolerates missing fields. A single odd record cannot hide the entire upload history from the panel.

Operating through the interface

Routine operation of the history requires no command line and no access to the infrastructure:

• See what is running: the "Execuções em segundo plano" panel, which receives the live state in real time (refreshed every 5 s).
• See the recent history: the panel's "Histórico (últimas 10)" section.
• Audit by period: the complete history page, with the date filter.
• Task stuck on "Executando": manual intervention is NOT needed — the next restart of the documents module reconciles the orphan as Falhou, through the two paths described above.

Diagnostics

Quick check: a history query asking for 1 record that comes back empty indicates an empty or not-yet-created index; if it comes back with documents, the history is active. datta_bg_executions is a system index — it holds execution metadata, not context data — and it is registered in the Knowledge Catalog as such.

Cross-references

• Background executions panel — the end user's perspective.
• Roles and permissions — permission catalog and role mapping (SEARCH_EXECUTE, SEARCH_VIEW).
• API reference — reading and writing the history for audit integrations.