National Healthcare Directory Attestation and Verification, published by HL7 Patient Administration Working Group. This is not an authorized publication; it is the continuous build for version 1.0.0-ballot). This version is based on the current content of https://github.com/HL7/fhir-directory-attestation/ and changes regularly. See the Directory of published versions

Usecases

Cross-Track Scenario Notes

Directory Look Up

Use Case

St. James is a hospital network in Connecticut. They are opening a new infirmary on 456 Main Street, and hiring Dr. Allison Camron to operate it. As part of setting up their facilities, they first check the directory to see if the facility is already registered, and whether Dr. Camron is licensed by Connecticut yet.

Scenario Workflow

# 1. Query Practitioner
# Practitioner - Dr. Han Solo
GET {directory}/Practitioner?name=Allison%Camron

# 2. Query Organization
# Organization - St. Jame’s Infirmary
GET {directory}/Organization?name=St.%20Jame%E2%80%99s%20Infirmary

# 3. Query Location
# Location - 456 Main Street, Anytown, CT, 00014
GET {directory}/Location?name=456%20Main%20Street%2C%20Anytown%2C%20CT%2C%2000014

# 4. Query Endpoint
# Endpoint - Acme of Connecticut
GET {directory}/Endpoint?organization=Organization/{organizationId}

# 5. Query HealthcareService
# HealthcareService - Emergency Medical Services
GET {directory}/HealthcareService?category=emerg

# 6. Query CodeSystem
# Code System - NatDir Consent
GET {directory}/CodeSystem/ConsentCS

Directory to Directory Subscriptions

Use Case

St. James network also operates the federated directory for the State of Conneticut, meaning they keep a full copy of the national directory on servers at the hospital, along with various Conneticut specific records. As part of configuring their federated directory, they set up subscriptions to updates and changes that happen on the national directory. This involves a POST (i.e. push) message from the federated directory to the national directory, which will then POST messages in response at regular intervals or upon specified events.

Scenario Workflow

# Practitioner 
POST /Subscription 
PUT  /Subscription/
POST /Practitioner 
GET  /AuditEvent?entity=Practitioner/{practitionerId} 

# Organization
POST /Subscription 
PUT  /Subscription/
POST /Organization 
GET  /AuditEvent?entity=Organization/{organizationId} 

# Location
POST /Subscription 
PUT  /Subscription/
POST /Location 
GET  /AuditEvent?entity=Location/{locationId} 

# Endpoint 
POST /Subscription 
PUT  /Subscription/
POST /Endpoint 
GET  /AuditEvent?entity=Endpoint/{endpointId} 

# HealthcareService 
POST /Subscription 
PUT  /Subscription/
POST /HealthcareService  
GET  /AuditEvent?entity=HealthcareService/{healthcareServiceId} 

Dynamic Registration

Use Case

Administrators at St. James decide that they wish to be able to submit updates to the National Directory, so they begin the process to register an account. This involves gathering server keys from both the National Directory and their own hospital network, and submiting a signed software statement and registration request to the national directory. The server will responsd with client IDs that can then be used during authorization and exchanged for an access token.

GET {nationalDirectory}/.well-known/udap
# result> NationalDirectoryPublicCert

# payload> software_s_tatement(national_d_irectory_p_ublic_cert, app_cert)
POST {nationalDirectory}/oauth/register
# result> client_id

# payload> client_id
POST {nationalDirectory}/oauth/authorize
# access_token (Bearer token)

The directory needs authentication/authorization to get to sensitive data. This use case relies on the simpler client credential code flow, meaning the access is specified on an organizational account or application level. Instead of logging in individual users, the public directory simply needs to know if you’re a user using a particular piece of software; with the assumption that anybody with access to that software also has access to the directory.

Please refer to UDAP ServerTest 20 - Client Credentials Flow for testing guidance.

To Write Directory Data

Seeing that the Infirmary is not present in their local federated copy of the national database, St. James administrators register a new Organization with the federated directory, along with associated Location, HealthcareService, and Endpoint. Seeing that Dr. Camron record does not reflect her recent licensure in the State of Conneticut either, they patch her Practitioner record also. After they send the attestion in (via a PATCh command), they re-query the directory to confirm that the update went through. After the local Federated Directory is updated and returning data as expected, they then send the changes as an attestation to the National Directory using the same API.

Attestation

PUT /Organization
PATCH /Organization/{organizationId}
GET /Organization/{organizationId}

PUT /Location
PATCH /Location/{locationId}
GET /Location/{locationId}

PUT /HealthcareService
PATCH /HealthcareService/{healthcareServiceId}
GET /HealthcareService/{healthcareServiceId}

PUT /Endpoint
PATCH /Endpoint/{endpointId}
GET /Endpoint/{endpointId}

PUT /Practitioner
PATCH /Practitioner/{practitionerId}
GET /Practitioner/{practitionerId}

After receiving an attestation from an external source, clerks operating the National Directory reach out to the Conneticut State Licensing Board to verify that Allison Camron is licensed to practice medicine in that state. Because interoperable systems use the same APIs, the National Directory sends a

Validation

# 1. State Licensing Board
GET {stateLicensingBoard}/Practitioner?name=Allison%Camron

# 2. Centers for Medicare Services
GET {cms}/Organization?name=St.%20Jame%E2%80%99s%20Infirmary
GET {cms}/HealthcareService?category=emerg

# 3. US Post Office
GET {postOffice}/Location?name=456%20Main%20Street%2C%20Anytown%2C%20CT%2C%2000014

Tiered oauth

# add the women's shelter and a restriction for it
PUT {directory}/Organization/{organizationId}
PUT {directory}/PractitionerRole
PUT {directory}/Restriction

# Authentication: None
GET /Organization/{organizationId}  # returns OperationOutcome(false)

# Authentication: Bearer Token (Authenticated User)
GET /Organization/{organizationId} 

Organization & Practitioner Match

using $match

# payload:  Organization2
POST {directory}/Organization/{organization1}/$match

# payload:  Practitioner2
POST {directory}/Practitioner/{practitioner1}/$match