# 1177.pdhc — User manual

1177.pdhc is the platform's **patient-facing form host** — the place where
clinical questionnaires are rendered in a **1177 Vårdguiden style**, filled in
by (or on behalf of) a patient, and turned into structured answers that flow
back into the platform.

It is not a static form library: it receives a specific questionnaire for a
specific patient, presents it, collects the answers, and returns them as
structured FHIR data. Live at **https://1177.pdhc.se** (internal branding:
"1177 Forms").

---

## 1. Where it sits in the platform

Four services cooperate to turn a clinical idea into collected patient data:

```
plan.pdhc      designs the form (concepts → FHIR Questionnaire)
   │
request.pdhc   packages + delivers it to the provider
   │  (push)
1177.pdhc      hosts, renders, collects the answers      ← this service
   │  (dispatch)
gateway.pdhc   receives the completed response for analysis
```

- **In:** `request.pdhc` pushes an order (a FHIR Bundle containing the patient
  and one or more questionnaires).
- **The work:** 1177 creates one **assignment** per questionnaire, renders it,
  and collects answers.
- **Out:** on submit, it produces a FHIR **QuestionnaireResponse**, keeps a
  local copy, and dispatches it to `gateway.pdhc`.

---

## 2. What an operator does

Log in at `https://1177.pdhc.se/login` (username + access key). The portal:

- **Dashboard** — counts of assignments by state (pending / opened /
  completed) and total responses collected.
- **Assignments** — the list of forms waiting to be filled. Open one to see
  the rendered questionnaire. First open moves it `pending → opened`.
- **Fill & submit** — the form renders type-aware widgets automatically:
  radio buttons and checkboxes for choices, Ja/Nej for yes/no, text areas,
  **sliders** with anchor labels and a live value, number fields with the
  unit and allowed range, and native date/time pickers. Required fields are
  marked; the form won't submit until they're answered.
- **After submit** — the assignment becomes `completed`, the answers are sent
  to the gateway, and the form re-renders read-only (with a collapsible view
  of the raw FHIR if you need it).
- **Archive** — tidy the list by archiving old assignments (hidden by
  default; toggle "show all" to see them).
- **Settings** — manage API keys; **Cleanup** — bulk-delete assignments or
  responses (guarded — you must type `DELETE` to confirm).

**Assignment lifecycle:** `pending → opened → completed`
(or `expired` / `cancelled`).

---

## 3. Using the API (integrators)

Service and integration calls use the `X-API-Key` header. The essentials
(base paths `/api/assignments`, `/api/webhook`):

| Do this | Call |
|---|---|
| Check health (no auth) | `GET /api/health` → `{status, database}` |
| List a patient's assignments | `GET /api/assignments?patient_guid=<guid>` |
| Read one assignment | `GET /api/assignments/<assignment_guid>` |
| **Submit answers** | `POST /api/assignments/<assignment_guid>/submit` |
| Cancel an assignment | `POST /api/assignments/<assignment_guid>/cancel` |

Submitting answers produces the same FHIR QuestionnaireResponse and triggers
the same gateway dispatch as the web UI — the two paths are interchangeable.
`request.pdhc` delivers new forms by pushing a FHIR Bundle to
`POST /api/webhook/inbound` (also `X-API-Key`).

---

## 4. Access

- **People** log into the portal with a **username + access key** (the shared
  key-based login; the first admin is bootstrapped at deploy). Roles, per-user
  keys, and a patient-data access log are built in.
- **Services / integrators** authenticate with an **`X-API-Key`** (create and
  revoke keys under *Settings → API keys*).

*(Note: this service uses key/password login, not the platform SSO — every
access to patient data is written to the keyauth access log.)*

---

## 5. Good to know

- **One questionnaire = one assignment.** A single order carrying three
  questionnaires becomes three assignments for the patient.
- The form the patient sees is exactly the Questionnaire that `plan.pdhc`
  authored — `request.pdhc` must resolve and include it before delivering, so
  1177 always renders a complete, self-contained form.
- **Dispatch is fire-and-forget:** if the gateway is briefly unreachable, the
  completed response is still saved locally — it is never lost.
- Answers are typed correctly in FHIR automatically (choice → coding,
  number → integer/decimal, yes/no → boolean, dates → date/dateTime); empty
  optional questions are simply omitted.
- For the endpoints, the FHIR shapes, the data model, and deployment, see the
  **technical manual** (link at the top of this page — with a **Download
  (Markdown)** button).