Skip to content

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.

  1. Add the configuration model and the node to workflows/nodes.py (or tighten an existing configuration with register_node_config(type, Model, schema_version=…)).
  2. Declare its ports in BUILTIN_PORTS (workflows/registry.py): what it accepts, emits and carries, and whether it is terminal.
  3. 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).
  4. Optional UI polish: an icon in web/src/features/studio/visuals.ts, labels in studio.nodeType.<type> of es.json/en.json, and a one-line summary in NodeCard.summarize.
  5. 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) keeps graph and schemas apart from the visual sidecar ui (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+S saves with If-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}:validate runs; 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