> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# HMIS configuration

> Configure radiology services, PACS endpoints, tokens, and the normalized APIs.

## Map a radiology service

Each radiology service should define the defaults that HMIS copies to a new examination:

| Field        | Example          | Purpose                             |
| ------------ | ---------------- | ----------------------------------- |
| Service code | `CXR`            | Stable clinical procedure code      |
| Modality     | `DX`             | DICOM modality used in the worklist |
| Body part    | `Chest`          | Requested anatomy                   |
| Laterality   | `not_applicable` | Side where relevant                 |
| Contrast     | `none`           | Contrast requirement                |
| Priority     | `routine`        | Default scheduling priority         |

Users may confirm or adjust the examination details when appropriate. Do not make operators re-enter values that are already defined by the service mapping.

## PACS endpoint

The demo endpoint is seeded with these non-secret values:

| Setting                | Demo value                                                            |
| ---------------------- | --------------------------------------------------------------------- |
| Code                   | `HMIS-PACS`                                                           |
| Name                   | `HMIS PACS`                                                           |
| Viewer URL template    | `http://localhost:3000/viewer?StudyInstanceUIDs={study_instance_uid}` |
| OIE channel identifier | `hmis-pacs-study-events`                                              |
| Active                 | Yes                                                                   |

The endpoint code is an HMIS integration identifier. It is not a DICOM AE Title. Use a distinct immutable code for every separately managed PACS endpoint.

## Environment

HMIS publishes new accessions to OIE using:

```dotenv theme={null}
OIE_RADIOLOGY_WORKLIST_URL=http://oie:6670/radiology/worklist/
OIE_RADIOLOGY_PACS_CODE=HMIS-PACS
```

Keep the trailing slash on the OIE listener URL.

## Integration tokens

Generate two separate tokens from the super-admin **Integration API tokens** page:

| Token               | Exact ability              | Used by                     |
| ------------------- | -------------------------- | --------------------------- |
| Worklist read token | `radiology:worklists:read` | OIE worklist lookup channel |
| Study write token   | `radiology:studies:write`  | OIE study events relay      |

Copy a token when it is generated because Sanctum stores only its hash. Never put a real token in documentation, screenshots, channel exports, or source control.

## Worklist API

```http theme={null}
GET /api/v1/radiology/integration/worklist?pacs_code=HMIS-PACS&accession_number=ACC000123
Authorization: Bearer {{RADIOLOGY_WORKLIST_READ_TOKEN}}
Accept: application/json
```

An available response has this normalized shape:

```json theme={null}
{
  "status": "available",
  "worklist": {
    "pacs_code": "HMIS-PACS",
    "accession_number": "ACC000123",
    "requisition_number": "DX000123",
    "patient": {
      "identifier": "PT000123",
      "name": "Sample Patient",
      "sex": "female",
      "date_of_birth": "1990-01-01"
    },
    "visit": { "number": "OP000123" },
    "location": {
      "branch_code": "MAIN",
      "branch_name": "Main Branch"
    },
    "procedure": {
      "service_code": "CXR",
      "service_name": "Chest X-Ray",
      "modality": "DX",
      "body_part": "Chest",
      "laterality": "not_applicable",
      "contrast": "none",
      "priority": "routine",
      "clinical_indication": "Cough"
    }
  }
}
```

Only an active PACS and an `open` radiology requisition are returned. Every lookup and response is audited.

## Study-ingestion API

```http theme={null}
POST /api/v1/radiology/integration/studies
Authorization: Bearer {{RADIOLOGY_STUDIES_WRITE_TOKEN}}
Content-Type: application/json
Accept: application/json
```

```json theme={null}
{
  "message_id": "pacs-study-123-change-456",
  "pacs_code": "HMIS-PACS",
  "external_study_id": "pacs-internal-study-123",
  "study_instance_uid": "1.2.826.0.1.3680043.10.123.1",
  "accession_number": "ACC000123",
  "modality": "DX",
  "study_date": "2026-07-19",
  "received_at": "2026-07-19T10:00:00Z",
  "metadata": {
    "source": "pacs-stable-study",
    "study_description": "Chest X-Ray"
  }
}
```

HMIS enforces idempotency using `pacs_code + message_id`. An identical replay returns `duplicate`; reusing the identity with a different payload returns a conflict. Unknown PACS codes, accessions, invalid workflow states, and conflicting study links are quarantined and audited.