# Going paperless on day one

  A discharge summary is a view of clinical data that has already been recorded, not something a
  person has to sit down and write. Record the data and the document comes free.

## The reason paperless usually fails

Claims require documents: a discharge summary, a claim form, a treatment sheet, a signed
consent. Most systems meet that requirement by asking a person to write the document, into a
word processor or into a form that produces a PDF, and then to attach it.

That is the paper workflow with the paper taken out. It still costs a person per claim, it still
happens at the end when everyone is in a hurry, and the documents it produces still disagree
with the clinical record they were transcribed from.

The alternative is to render documents rather than author them. Every field a discharge summary
contains, the diagnosis, the encounter dates, the medications, the results and the clinician, is
already recorded at [05 · Treat](/rail/stops/Treat). The document is a projection of that
record.

<Wire
  rows={[
    { call: "You record clinical facts", does: "Diagnoses, observations, orders, results and prescriptions, coded as the encounter runs. This is the work, and you were doing it anyway.", keep: "the record" },
    { call: "The rail renders documents", does: "It knows which documents this claim requires, and it holds the data each of them is made of. Ask for them and it produces them.", keep: "document_id" },
    { call: "Nobody types a summary", does: "A new HMIS on the rail is paperless the day it connects, without building a document editor, a template engine or a PDF pipeline.", keep: "the capability, for free" },
  ]}
/>

## Generate what the claim requires

  No document routes exist under a visit, so the two calls on this page answer 404 today. What is
  live sits at a different address and is scoped differently: `POST /api/v1/clinical/html-to-pdf`
  converts HTML you supply, and `GET /api/v1/clinical/document-bundles/{id}/render` and
  `POST /api/v1/clinical/document-bundles/{id}/pdf` render a bundle.

  So a facility that needs a PDF today can have one. What it cannot do yet is ask the rail to
  assemble the required document set from the clinical data already recorded, which is the part
  this guide is about.

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/documents/generate" to="/rail-api/05-treat">
  Generate the documents this visit's items require, from the clinical data already recorded.
</ApiRef>

The response is per document, and the one worth reading is the document that could not be built.

```json
{
  "documents": [
    { "document_type": "DISCHARGE_SUMMARY", "status": "generated", "attached_to_visit": true, "missing": [] },
    { "document_type": "CLAIM_FORM", "status": "incomplete", "missing": ["encounter.period.end", "diagnosis.primary"] }
  ]
}
```

`missing[]` names clinical elements rather than form fields. The fix is to record the fact, so
close the encounter or rank the primary diagnosis instead of typing anything into a document.
A system that treats `missing[]` as a validation error on a form has rebuilt the thing this
replaces.

  Which documents a claim needs comes from the interventions billed on it, read at
  [02 · Verify cover](/rail/stops/Entitle) and checked again at
  [08 · Submit](/rail/stops/Submit). Generate against that list rather than a fixed set, or you
  will produce three documents where one was required, and miss the one that was.

## Render on demand

<ApiRef method="GET" path="/api/v1/visits/{visit_id}/documents/{document_type}/render?format=html" to="/rail-api/05-treat">
  Render a document to show on screen, or as a PDF to hand over and sign.
</ApiRef>

<Wire
  rows={[
    { call: "HTML", does: "For display inside your own UI, in a clinician's review screen, in a patient portal. It is styled to be embedded rather than printed.", keep: "the markup" },
    { call: "PDF", does: "For the cases where a physical artefact is genuinely required, such as a signature, a hand-over, or a regulator who asks for one.", keep: "the file" },
    { call: "Deterministic from the record", does: "Render the same visit twice and you get the same document. You never have to store a snapshot, because you can ask for the view again.", keep: "nothing" },
  ]}
/>

Do not cache the rendered artefact as your source of truth. The record is the truth and the
document is derived from it, so a stored PDF goes stale the moment a result is amended. Store the
`document_id` that was attached to the claim, since that is the version the payer assessed, and
render fresh for everything else.

## What this gives an HMIS that has never had it

<BuildSequence
  steps={[
    {
      do: "A small clinic connects and is paperless",
      detail:
        "It needs no document editor, no template library and no PDF service. It records clinically, asks for documents, and attaches what comes back.",
    },
    {
      do: "The documents always match the record",
      detail:
        "Nothing is transcribed between the two, so what was billed, what was recorded and what the payer reads cannot drift apart.",
    },
    {
      do: "Attachment failures move upstream",
      detail:
        "MISSING_DOCUMENTS at submission becomes DOCUMENT_DATA_INCOMPLETE while the encounter is still open, naming the clinical gap while somebody can still close it.",
    },
    {
      do: "The same data serves four purposes",
      detail:
        "One recording becomes the claim's evidence, the shared health record, the referral's payload, and the document set. You capture it once, at the point it was true.",
    },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Submit",
      symptom: "\"Generation says incomplete and we cannot see why\"",
      cause: "Read missing[]. It names clinical elements, so record the fact rather than looking for a form field to fill.",
    },
    {
      where: "Submit",
      symptom: "\"We attached a summary we wrote and it was queried\"",
      cause: "A hand-written document disagrees with the coded record behind the claim. Generate it instead; the assessor is reading both.",
    },
    {
      where: "Treat",
      symptom: "\"The PDF we stored is out of date\"",
      cause: "A rendered document is a view rather than a record. Keep the document_id that was attached and re-render everything else.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 422 | `DOCUMENT_DATA_INCOMPLETE` | The clinical data the document renders from is missing elements. |
| 422 | `MISSING_DOCUMENTS` | A required document was never attached. Checked at [08 · Submit](/rail/stops/Submit). |

  Back to the stop that records the data all of this is generated from.