HMIS configuration

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:

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

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:

{
  "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

POST /api/v1/radiology/integration/studies
Authorization: Bearer {{RADIOLOGY_STUDIES_WRITE_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "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.

Foundation

Implementation

Operations

Map a radiology service

PACS endpoint

Environment

Integration tokens

Worklist API

Study-ingestion API

​Map a radiology service

​PACS endpoint

​Environment

​Integration tokens

​Worklist API

​Study-ingestion API

Map a radiology service

PACS endpoint

Environment

Integration tokens

Worklist API

Study-ingestion API