Studio: workflow list and canvas
The Studio's two main screens are the workflow list (/workflows, S2) and the canvas
(/workflows/<id>, S5). The shell, tokens and plug points are in Studio (web app);
this page is about what T34 adds and how later tickets plug into it.
What each screen does
| Screen | Where | What it shows |
|---|---|---|
| List | web/src/features/workflows/ |
name, alias → version (prod v3.1), documents of the last 30 days, accuracy and STP (— until a provider exists), cost per page, last run, owner; search by name, tag filter, archived filter; create, duplicate, archive, export and import (dx.workflow/v1) |
| Canvas | web/src/features/studio/ |
palette generated from GET /v1/node-types, typed ports, dynamic handles (branch: true/false, classify: one per category, split: one per rule), configuration panel generated from each config_schema, problems panel (the violations of POST :validate), sticky notes, undo and redo, copy and paste, autolayout, minimap, save with If-Match |
A published version opens read-only with a Crear borrador button (it restores the version as
a draft); so does a draft opened by a user without workflow:write.
Backend endpoints
| Endpoint | Notes |
|---|---|
GET /v1/node-types |
{data: [{type, label, group, inputs[{port,type}], outputs[{port,type}], carries[], terminal, branching, config_schema, default_config, plugin?}]}. Built from the node registry of T25 (workflows/catalog.py); plugins installed in the project (T30 manifests) are extra plugin entries |
GET /v1/workflows?q=&tag=&archived=&cursor=&limit= |
keyset on (name, id), q is a case-insensitive substring of the name (trigram index on lower(name)), tag an exact tag, archived=true only the archived ones; each row has aliases, owner and stats{docs_30d, last_run_at, cost_per_page_30d, accuracy_30d, stp_30d} |
GET /v1/workflows/{id}:export |
{format: "dx.workflow/v1", workflow, graph, schemas} of the draft (else the latest published version) or of ?version_id=; the schemas keep every x-dx.field_id |
POST /v1/workflows:import |
creates the workflow and a draft from an exported document (new_name renames it); topology violations are returned in version.report, a repeated field_id is 400 INVALID_SCHEMAS, a taken name 409 WORKFLOW_NAME_TAKEN |
POST /v1/workflows/{id}:duplicate |
copy of the draft (else the latest published version) as a new draft, field_id kept; {name?} |
POST /v1/workflows/{id}:archive |
same as DELETE /v1/workflows/{id}, with If-Match |
PUT /v1/workflow-versions/{id} |
accepts ui (the Studio sidecar {layout, viewport}, stored in its own column and never part of the graph hash); omit it to keep the stored one |
Statistics providers
stats come from WorkflowStatsProviders (workflows/stats.py). RunsStatsProvider (built in)
fills docs_30d (workflow runs of the last 30 days), last_run_at and cost_per_page_30d from the
durable runs. accuracy_30d and stp_30d stay null (the UI shows «—») until a provider supplies
them. To add one, either call register_stats_provider(MyProvider()) or declare an entry point:
[project.entry-points."extractit.workflow_stats"]
quality = "my_package.stats:QualityStatsProvider"
A provider has fields: ClassVar[frozenset[str]] and
stats(session, tenant_id, project_id, workflow_ids, *, now) -> {workflow_id: {key: value}}
(one query for the whole page). Later providers win for the keys they return non-null.
T40 registers MonitoringStatsProvider (quality/monitoring/stats_provider.py) in this group as
monitoring: it fills stp_30d and accuracy_30d with the definitions of
the monitoring formulas (production runs only) and leaves a key out when
it is undefined (no finished run, no reviewed field), so the list keeps showing «—».
Registering a new node type
The palette, the ports and the configuration form come from the registry; nothing in the web app names a node type.
- Add the configuration model and the node to
workflows/nodes.py(or tighten an existing configuration withregister_node_config(type, Model, schema_version=…)). - Declare its ports in
BUILTIN_PORTS(workflows/registry.py): what itaccepts,emitsandcarries, and whether it isterminal. - Give it a group and a default configuration in
workflows/catalog.py(GROUPS,DEFAULT_CONFIGS; a test checks that the default validates against the generated JSON Schema). - Optional UI polish: an icon in
web/src/features/studio/visuals.ts, labels instudio.nodeType.<type>ofes.json/en.json, and a one-line summary inNodeCard.summarize. - Regenerate the web fixture (
web/src/test/fixtures/node-types.json, a pytest compares it with the catalog) and the OpenAPI snapshot:
uv run python - <<'PY'
import json
from extractit.api.routers.node_types import NodeTypeList, node_type_out
from extractit.workflows.catalog import node_types
data = NodeTypeList(data=[node_type_out(e) for e in node_types()]).model_dump(mode="json")
open("web/src/test/fixtures/node-types.json", "w").write(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False) + "\n")
PY
A branching node (one output per label) needs a branching kind (branch, classify, split) in
catalog.BRANCHING and the matching handle rule in web/src/features/studio/model/handles.ts.
Widget slots (tipo.campo)
The configuration form is generated with RJSF 6 (web/src/components/schema-form/). The validator is
our own over @cfworker/json-schema: the default one (ajv) compiles schemas with new Function, which
the CSP (no unsafe-eval) forbids.
A field can be edited by a custom widget instead of the generated one. The slot is
<node type>.<top-level config field>:
| Slot | Edits | Until a ticket registers it |
|---|---|---|
branch.condition |
the Check of a branch node |
JSON editor |
validate.rules |
the rules of a validate node | JSON editor |
extract.schema |
the extraction schema schemas[config.schema_id] |
JSON editor |
// web/src/features/schema-editor/studio/register.ts (loaded by import.meta.glob, T35)
import { registerWidget, type SlotWidgetProps } from "../../../components/schema-form";
function SchemaEditor({ value, onChange, readOnly, schemas }: SlotWidgetProps) { /* … */ }
registerWidget("extract.schema", SchemaEditor);
SlotWidgetProps is {slot, nodeId, nodeType, value, onChange, schema?, readOnly, schemas?}. For
extract.schema the value is the whole extraction schema and onChange(undefined) removes it. Any
features/<feature>/studio/register.ts is imported once, without the Studio knowing it. A field with
no widget whose JSON Schema RJSF cannot draw sensibly (a union of objects, a free object, a recursive
structure) falls back to a JSON editor automatically.
Document, history and conflicts
- The editor state (
features/studio/store/studioStore.ts) keepsgraphandschemasapart from the visual sidecarui(layout,viewport). Only the first two feed the validator, the hash and the compiled plan. - Undo and redo use immer patches with a stack of 100. A drag is one entry; edits of one config field within 500 ms merge into one.
Ctrl+Ssaves withIf-Match: "v<revision>". After a 412 the server's draft is read and a three-way merge (base, local, server) runs: what only one side changed is taken, and a node (note, schema) changed differently on both sides is settled node by node in the merge dialog.- Validation is live: 500 ms after an edit one
POST /v1/workflows/{id}:validateruns; the problems panel lists the server's violations verbatim (rule,node_ids) and a click focuses the node. The client-side port and cycle checks are advisory (they dim incompatible targets and refuse the connection); the server is the authority.
Keyboard
| Action | Keys |
|---|---|
| Add a node | focus its palette entry and press Enter |
| Connect without dragging | the Conectar con… button of a node (a dialog lists compatible targets) |
| Move the selected node | arrow keys (10 px), Shift+arrows (50 px) |
| Add a note | N |
| Save, undo, redo | Ctrl+S, Ctrl+Z, Ctrl+Shift+Z |
| Copy, paste, delete | Ctrl+C, Ctrl+V, Delete |