vk-gramatvediba/tools/register-transcoder

register-transcoder

Transcodes a published Valsts Kase accounting-process register (.xlsx / .xlsm) into BPMN process skeletons — one deterministic step in the vk-gramatvediba transcription pipeline.

The Valsts Kase / VPC Grāmatvedības uzskaites procesu apraksts is published as a set of function-group spreadsheets (FG1–FG6). Each row of a register is a process step with explicit predecessor and successor step references, a RACI split across the responsible actors, the IT system used, an SLA, and the data the step produces. That structure is already a process graph; this tool reads it and emits the corresponding BPMN.

What it produces

For a given sub-process the tool emits one .bpmn file containing a single bpmn:process with isExecutable="false":

• one bpmn:userTask per register step, named from the register and carrying the step's description, system, SLA, RACI and cross-references in bpmn:documentation;
• bpmn:lanes derived from the RACI columns — a step is placed in the lane of its Responsible actor (Nodarbinātais / Iestāde / VPC);
• bpmn:sequenceFlows reconstructed from the register's own No procesa darbības soļa (predecessor) and Uz procesa darbības soli (successor) columns, restricted to links whose endpoints are both inside the emitted sub-process;
• synthesised bpmn:startEvent / bpmn:endEvent nodes — one per entry step (no in-group predecessor) and one per exit step (no in-group successor) — so the fragment's real boundary is visible rather than hidden.

Register format expected

The parser locates the worksheet and header row by content, not by position, so it tolerates the leading title rows the registers carry. It expects a header row containing Nr.p.k. and the columns No procesa darbības soļa (predecessor, with the FG-group and step-number in adjacent cells), Process, apakšprocess, Atbildības sadalījums (RACI) (a three-column block for Nodarbinātais / Iestāde / VPC), Darbību apraksts, Izmantotā IS, Izpildes termiņš, Sagatavotie dati and Uz procesa darbības soli (successor). Rows that carry a number and a name but no description and no RACI are treated as sub-process headers; rows with a description or any RACI entry are treated as steps. Steps are grouped under the most recent header.

Usage

transcode.py list <register.xlsx>
transcode.py emit <register.xlsx> <subprocess> [-o <output.bpmn>]

list reports the sub-processes that contain steps, with step counts. emit writes (or, without -o, prints) the BPMN skeleton for one sub-process.

python3 transcode.py list fg3_process.xlsm
python3 transcode.py emit fg3_process.xlsm 3.5.2 -o 3.5.2.skeleton.bpmn

The only dependency is openpyxl.

Limitations — a skeleton, not an executable

The output is deliberately a faithful mechanical transcription, not a finished package. It does not:

• detect decisions — every step becomes a userTask; branching points are not promoted to exclusiveGateways and no DMN is extracted;
• repair the register — where the register's predecessor and successor columns disagree, the skeleton reproduces the result as-is (this can surface as a reciprocal edge / short cycle, or as a step that reaches the rest of its sub-process only through a cross-FG excursion);
• carry BPMN diagram interchange (bpmndi) — the output is a logical model, laid out by an editor on import;
• emit a UAPF package — there is no uapf.yaml, no resources and no metadata.

The RACI-to-lane rule is a heuristic: the lane is the first actor whose RACI cell contains R. The full RACI is preserved verbatim in each task's documentation so the heuristic can be checked and corrected.

Position in the pipeline

A skeleton is the deterministic first pass. Refining one into a Level 4 executable — introducing explicit gateways, extracting decision logic into DMN, writing resource roles/agents/mappings and the package manifest — is the human / AI-assisted second pass. The curated processes/fg3-1, fg3-4 and fg3-5 packages are what that second pass yields; docs/methodology.md discusses the transcoder skeleton against the curated executable for the same sub-process.

sample-output/ holds skeletons emitted from the FG3 register for sub-processes 3.5.2 (Saimnieciskie norēķini) and 3.5.3 (Komandējuma norēķini) — the two that have curated executable counterparts in this workspace.