Skip to main content

Creating a document

:::info Status Outline — expand with a full worked example (e.g. adding a new line-bearing Document from scratch, including its register writes and generated UI). :::

:::tip Use the shipped skill Prefer the create-document skill (in your scaffolded repo's .claude/skills/) over hand-rolling this. If the document also posts to the chart of accounts, follow it with post-to-accounting. :::

A Document is a transactional record: it posts/submits, can write registers and chart-of-accounts postings, and typically has tabular sections (line items).

The four pieces, document-specific parts​

  1. *Base : DocumentBase, [KandraDocumentEntity]. Redeclares Code/DateTime as override. Implement IEntityWithRows if it has tabular sections (needed even for a document with no lines, if it should appear in the register-transactions viewer).
  2. *Dto, [KandraDocumentForm(ValidatorType=...)].
  3. *Behavior — the full hook set including OnSubmitAsync/OnUnsubmitAsync. Register writes and postings happen only inside these two, via the ISubmitScope parameter.
  4. *Validator.

Submit-time flow​

See Overall architecture for the full request-to-register-write path. The short version: OnSubmitAsync(ISubmitScope scope, ...) calls scope.GetWriter<TWriter>() for each register it touches, and/or IPostingService if it posts to the chart of accounts.

What ships generated, per document​

Controller, client DI, EF config, DI registration, and — since the Document UI generator (DocumentUiEmitter) is real and covers all document kinds — the Blazor list/create/edit/view pages themselves, including the register-transactions viewer's per-document tab if [RegisterTransactions]/[RegisterCaption] are set.

Gotchas worth knowing before you start​

  • OnDelete hooks fire before entity removal (OnBeforeDeleteAsync), not after.
  • A Document without [SupportedPrintForm] must get onPrint: null in the generated UI wiring, not a PrintRecord reference — otherwise the Print button silently 404s.
  • If this document should link to/from another (e.g. an Invoice that can spawn a Waybill), see Document links — [SourceFor] plus IDocumentLinkService.

See also​