HL7 New Zealand: FHIR for developers

© 2016 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.
HL7 FHIR for Developers
HL7 New Zealand
Auckland, June 2016
Brian Postlethwaite
David Hay
Peter Jordan

• HL7 New Zealand
Programme

• HL7 New Zealand
Optional afternoon sessions
• a) Exporting/publishing legacy content
• b) FHIR based Referrals – Demonstrations of the maturity
Questionnaire
• c) FHIR Provider Directories – The global position
• d) Integrating SMART on FHIR
• e) How clinFHIR integrates with FHIR
• f) streams for chat
• Anything else you might want…

• HL7 New Zealand
SNOMED CT Expo 2016
27-28 October
Te Papa Tongarewa
Wellington NZ
www.snomedexpo.org
@SnomedCT
International audience
Four presentation streams
Hackathon starts August

FHIR: a deep dive for developers

• HL7 New Zealand
Elevator speech
• FHIR is
– About clinical information exchange
– Resources to represent clinical ‘things’
– A well defined API supporting all paradigms
– An incredible community
– A platform for expansion
• Ecosystem
• Decision support
• Quality metrics
• Conversion
– Spreading like <insert pun here>
6

• HL7 New Zealand
Contents of this tutorial
• Agenda
– General Comments
– Resources
– Profiling
– Exchange
– Moving on
• Assumption
– You have basic familiarity with FHIR

• HL7 New Zealand
DSTU/STU?
• It’s a release/publication status
– Draft Standard For Trial Use – relabelled STU
• Current version is STU2
– This presentation is based on STU2
• Next version (unfinished) is STU3
– Ballot end of year
– Will describe main changes at end
• FHIR Maturity model

• HL7 New Zealand
Test Servers & tools
• Public test servers
– Varying capability
– HAPI CLI
• (http://jamesagnew.github.io/hapi-fhir/doc_cli.html)
– Invaluable to experiment and learn
• Libraries
– C#, Java, others
• Tools you need
– Modern web browser
– REST client
– XML/Json editor
– IDE of choice
10

• HL7 New Zealand
clinFHIR
• An educational tool
– Built to support Clinician Connectathon
• clinFHIR.com
– Resource Builder
– Simple Profile Builder
– Extension Definition
– ValueSet
11

• HL7 New Zealand
The community
• http://www.fhir.org/
• https://chat.fhir.org/
– NZ Stream
• http://community.fhir.org/
• fhir@lists.hl7.org
• http://wiki.hl7.org/index.php?title=FHIR
• http://wiki.hl7.org/index.php?title=FHIR_gForge_Tracker
12

• HL7 New Zealand
The specification is your friend: Hl7.org/fhir
13

• HL7 New Zealand
The core
• Content
– Resources
• Exchange - API
– FHIR supports 4 interoperability
paradigms
– Same resources for all
REST Documents
Messages Services

• HL7 New Zealand
Architectures
15
FHIR
Broker
v3
v2
PHR
FHIR
App
Comm.
Interface
DB
FHIR

• HL7 New Zealand
Repository model – NZ EHR
Vendor Neutral Repository
FHIRFHIRFHIR
GP Hospital Mobile
N
Notify
(Subscription)

• HL7 New Zealand
Resources
Technically, all resources defined in StructureDefinition
(also used for profiling)

• HL7 New Zealand
Resource Type Hierarchy
19

• HL7 New Zealand
Resource
Narrative
Elements
ExtensionsExtensions
Structure of a Domain Resource
Metadata

• HL7 New Zealand
Resource Example

• HL7 New Zealand
Specification
• Review in Spec
– Patient

• HL7 New Zealand
References between resources
Coded Properties
type
bodySuite
indication
performer.role
complication
relatedItem.type
Other Properties
identifier (Identifier)
outcome (String)
PROCEDURE
PATIENT
DIAGNOSTIC REPORTCONDITION
Subject
ReportRelatedItem
Encounter Performer
ENCOUNTER PRACTITIONER

• HL7 New Zealand
References

• HL7 New Zealand
Contained versus reference
• References to external
resources
– When can be identified
– Preferred
• More flexible
• Contained resources
– When can’t be identified
– Complete resource
• No text
– Only useable within parent
<Patient>
…
<managingOrganization>
<reference value="Organization/1"/>
</managingOrganization>
…
</Patient>
<Patient>
<contained>
<Organization>
<id value="org1"/>
</Organization>
</contained>
…
<managingOrganization>
<reference value="#org1"/>
</managingOrganization>
…
</Patient>

• HL7 New Zealand
XML & JSON
27 Interconversion requires structure knowledge

• HL7 New Zealand
A Resource’s identity
• In fact: an URL
– http://server.org/fhir/Patient/1
endpoint
resource type
id
Note: This URL resolves to the current version of a resource
on a given server

• HL7 New Zealand
“Business” identifiers

• HL7 New Zealand
Patient
MRN 22234
“Ewout Kramer”
30-11-1972
Amsterdam
Resource metadata
Metadata
…
<id value="4705149-patient"/>
<meta>
<versionId value="4"/>
<lastUpdated value="2016-08-10T16:18:46Z"/>
<profile value=… />
<security value=…/>
<tags value=…/>
</meta>
…

• HL7 New Zealand
The FHIR Elements
Resource
Narrative
Extensions
Metadata
Elements
Extensions
Primitives
(integer, boolean,
string, instant)
Derived
Primitives
(oid, uuid,
code, id)
Complex
Datatypes
(HumanName,
Quantity, Period,
Address, Identifier )
Constrained
Types
(Quantity:
Distance, Count,
Duration, Money)
use
use
use
http://www.hl7.org/implement/standards/fhir/datatypes.html

• HL7 New Zealand
Element Hierarchy
32

• HL7 New Zealand
Primitive data types
instant
decimal
integer
unsignedInt postiveInt code id
oid
markdown
base64Binary string url
boolean
dateTimetime date
Element

• HL7 New Zealand
Complex data types
Ratio
Timing
Coding
Age Distance SimpleQuantity Duration Count
AttachmentPeriod Range
Element
Identifier
Signature
CodeableConcept Quantity SampledData ContactPoint
HumanName
Annotation
Address
Money

• HL7 New Zealand
CodeableConcept

• HL7 New Zealand
“Choice” properties

• HL7 New Zealand
Narrative

• HL7 New Zealand
NamingSystem resource
• Define the ‘system’ element
– CodeableConcept / Coding
– Identifier
• Some systems defined in spec
– (No NamingSystem required)
• Governance
– Many should be national – eg for NHI, HPI

• HL7 New Zealand
Coded types
• code, Coding, CodeableConcept, (Quantity)
• Possible values defined in ValueSet resource
– Binding Strength
• Required (must come from set)
• Extensible (may use alternate if have to)
• Preferred (don’t have to, but should)
• Example (set isn’t specified)
– Profile can tighten

• HL7 New Zealand
Examples
• Code: "status" : "confirmed"
• Coding: {
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "C3214954",
"display": "cashew nut allergenic extract Injectable"
}
• CodeableConcept: {
"coding": [{
"system": "http://snomed.info/sct",
"code": "39579001",
"display": "Anaphylactic reaction“
}],
"text" : "Anaphylaxis"
}

• HL7 New Zealand
ValueSet resource
• Defines list of possible values for a particular context
• Can reference external Terminology/s
– Or define own sets
• Why?
– A common valueSet improves recording consistency
– Improves user experience (pick lists)
• Examples in New Zealand
– ED diagnoses (derived from SNOMED)
– NZ POCS (Pathology Observation Code Set) (derived from LOINC)
– List of NZ Iwi (defined in ValueSet)

• HL7 New Zealand
Terminology Sub-system
• SNOMED CT / LOINC / RxNORM
• HGVS, ICPC, MIMS + 100s more
• ICD-X+
• ANZSCO, METEOR
• A drug formulary
• A config table in an application
• A list of enums in a java class
• Australian state codes
Code System:
Defines a set
of concepts
with a
coherent
meaning
Code
Display
Definition

• HL7 New Zealand
Value Set:
A selection of a
set of codes for
use in a
particular
context
Code System:
Defines a set
of concepts
with a
coherent
meaning
Code
Display
Definition

• HL7 New Zealand
Code System:
Defines a set
of concepts
with a
coherent
meaning
Code
Display
Definition
Element
Definition:
Type and
Value set
reference
Value Set:
A selection of a
set of codes for
use in a
particular
context
Binds

• HL7 New Zealand
Code System:
Defines a set
of concepts
with a
coherent
meaning
Code
Display
Definition
Element
Definition:
Type and
Value set
reference
Value Set:
A selection of a
set of codes for
use in a
particular
context
Binds
Element:
code/
Coding/
CodeableConcept
Conforms

• HL7 New Zealand
ValueSet for condition.code
{
"resourceType": "ValueSet",
"id": "valueset-condition-code",
"meta": {
"versionId": "1",
"lastUpdated": "2015-05-08T16:18:23Z",
},
"text": {
"status": "generated",
"div": ”Condition.code sample ValueSet"
},
"url": "http://hl7.org/fhir/vs/condition-code",
"version": "0.5.0",
"name": "Condition/Problem/Diagnosis Codes",
"publisher": "FHIR Project team",
"contact": [
{
"telecom": [
{
"system": "url",
"value": "http://hl7.org/fhir"
}
]
}
],
"description": "Example value set for
Condition/Problem/Diagnosis codes",
"copyright": "This value set includes content
from SNOMED CT, which is copyright © 2002+
International Health Terminology Standards
Development Organisation (IHTSDO), and
distributed by agreement between IHTSDO and
HL7. Implementer use of SNOMED CT is not
covered by this agreement",
"status": "draft",
"experimental": true,
"compose": {
"include": [
{
"system": "http://snomed.info/sct",
"filter": [
{
"property": "concept",
"op": "is-a",
"value": "404684003"
}
]
}
]
}
}

• HL7 New Zealand
Terminology Server
• Provides ‘services’ for consumers to access terminology
– Hide the complex stuff from a consumer
• Uses Operations framework
– Get definition for a concept
– Find a concept
• Within a ValueSet
http://hl7.org/fhir/2015May/terminology-service.html
• Find Terms
• Get Term
Definition

• HL7 New Zealand
Profiling
• The basic resources are not enough
– Many different contexts in healthcare
• Specific implementations / Use Cases need to:
– Extend resources
– Constrain resources
– Specify code sets / terminologies
– Specify resources used
• Multiple supporting artifacts in FHIR
– ‘Conformance’ resources
• FHIR is a platform specification
– Profiles adapt it to specific purposes
– Doesn’t change wire format
• Discoverability / Manage expectations
• Profiling increasingly important
– Allows clinicians to express reqirements
– Tooling supports Clinicians and Analysts involvement
• Whole spec build on profiling infrastructure

• HL7 New Zealand
Claiming conformance
• Profiles are like a template
– Servers indicate what profiles they support
– Clients can interrogate servers
• Conformance resource lists supported profiles
• http://107.170.196.80/resourceCreator.html?conformance=ohConforman
ce&hideNav
• Resource instances can ‘claim conformance’ to 1 or more
profiles
– Libraries developed to test this
– Can be conformant without claiming
• Cannot set defaults
– Can state what a value should be

• HL7 New Zealand
Extensions
• Only most common elements in base resource
– Keeps the resources small
– (Adding everything was the problem with version 3)
• Extensions allow other elements to be defined
– Same capabilities (dataType) as core elements
• Including resource references and terminology bindings
– Can extend properties and datatypes as well as the resource
• Extensions are normal
– Expect all real implementations to use extensions
• ‘normal’ and modifierExtensions
– Normal extensions can be ignored by a recipient
– Unknown modifierExtensions cannot be ignored

• HL7 New Zealand
Modifier Extensions
• Also a core part of FHIR
– Needed because some extensions can’t be safely ignored
– Can’t compute on an element containing an unrecognized modifier
extension. However, can:
• Reject instance
• Remove element containing unrecognized modifier extension
• Just display narrative
• Retrieve definition & seek human review
55

• HL7 New Zealand
Extending a multiple birth
Key = location of formal definit
Value = value according to definition

• HL7 New Zealand
Complex extensions

• HL7 New Zealand
Profiling a resource
Specify that the identifier uses the
NHI – and is required
Limit names to just 1 (instead of 0..*)
Limit maritalStatus to different set of
codes (ValueSet)
Multiple Birth indicator only boolean
Indicate photo not supported
Add an extension to support
“Ethnicity”
Note: hardly any mandatory elements
in the core spec!

• HL7 New Zealand
Slicing
• Specifying repeating elements
– Eg Blood Pressure (Observation.component)
– Composition (document sections)
• Constraining datatypes
– Eg MedicationDispense.medication
59

• HL7 New Zealand
Forge
60

• HL7 New Zealand
‘Conformance’ resources
• StructureDefinition
– The resource that ‘defines’ a resource
• core and ‘profiled’
• also used for extensions
• describes binding to ValueSets
• ValueSet
– Options for coded elements
• NamingSystem
– Defines system for Coding, Identifier
– Some in spec - somenot
61
Canonical URL

• HL7 New Zealand
Relationships between conformance resources
62
URI vs URL
Canonical URL

• HL7 New Zealand
A profiled resource Instance
63
{
"resourceType": "AllergyIntolerance",
"meta": {
"profile": [
"http://fhir.hl7.org.nz/dstu2/StructureDefinition/ohAllergyIntolerance"
]
},
"extension": [
{
"url": http://fhir.hl7.org.nz/dstu2/StructureDefinition/al-certainty”,
"valueCodeableConcept": {
"text": "really sure"
}
}
],
"patient": {
"reference": "Patient/14317",
"display": "Eve E. Everywoman "
}
}

• HL7 New Zealand
Validating a conformance claim
• It’s only a claim…
• Tooling (java) that can check
– One resource can be conformant to multiple profiles
• For design, use $validate operation
– http://hl7.org/fhir/resource-operations.html#validate
– Or use XML schema / schematron
– Or java validator
64

• HL7 New Zealand
Implementation Guide:
Data Access Framework
65
http://hl7.org/fhir/daf/d
af.html

• HL7 New Zealand
Practical steps exposing FHIR data
• Gap analysis
– Extensions required
– Elements unsupported
• Find or Create extension definitions (StructureDefinition)
– Prefer re-use
– In Spec or Registry (simplifier)
– Create using forge/clinFHIR
• Local save – and/or to simplifier
• Any other ‘conformance’ resources
– NamingSystem (no tooling)
– ValueSet (clinFHIR for simple, NEHTA working on official tool)
• Build profile
– Forge at present (clinFHIR to come for simple)
• Update Conformance resource
• Create samples
– Can use clinFHIR

• HL7 New Zealand
Viewing Profiles: clinFHIR
• Select Profile
– Look at structure
– Build resource
• http://107.170.196.80/resourceCreator.html
67

• HL7 New Zealand
Naming things…
• All conformance resources need URL
– Note: ‘canonical’ URL – or URI
– What ‘base’ server?
• Currently HL7 NZ, but needs review
• ? National ‘governance’
– Is there a ‘naming convention’
– How will versioning work
• Server infrastructure
– Should NZ have its own registry?

• HL7 New Zealand
Paradigms
• FHIR supports 4 interoperability paradigms
REST Documents
Messages Services

• HL7 New Zealand
FHIR
Repository
Regardless of paradigm, the content is the same
Lab System
Receive a lab result in a message…
FHIR
Message
FHIR
Document
…Package it in a discharge summary docum
National
Exchange

• HL7 New Zealand
REST SERVICE INTERFACE
How FHIR uses RESTful principles to communicate Resources

• HL7 New Zealand
Possibly distributed…
FHIR server @ hospitalA.org
Practitioner
Practitioner/87
Organization
Organization/1
FHIR server @ lab.hospitalA.org
Diagnostic
Report
DiagnosticReport/4445
Observation
Observation/3ff27
FHIR server @ pat.registry.org
Patient
Patient/223
subject

• HL7 New Zealand
Just a quick GET
GET /fhir/Patient/1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/xml+fhir;charset=utf-8
Content-Length: 787
Content-Location:
http://fhir.furore.com/fhir/Patient/1/_history/1
Last-Modified: Tue, 29 May 2012 23:45:32 GMT
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir"><identifier><label>SSN</label><identifier><system>
http://hl7.org/fhir/sid/usssn</system><id>444222222</id></identifier></identifier><name><use>official
</use><family>Everywoman</family><given>Eve</given></name><telecom><system>phone</system><value>555-
555 2003</value><use>work</use></telecom><gender><system>http://hl7.org/fhir/sid/v2-0001</system>
<code>F</code></gender><birthDate>1973-05-31</birthDate><address><use>home</use><line>2222 Home
Street</line></address><text><status>generated</status><div
xmlns="http://www.w3.org/1999/xhtml">Everywoman, Eve. SSN:444222222</div></text></Patient>
UTF-8
encoded
HTTP Verb +
path

• HL7 New Zealand
Mapping to verbs
create 2.1.10
The create interaction creates a new resource in a server assigned location. The create interaction is performed
by an HTTP POST operation as shown:
POST [service-url]/[resourcetype] (?_format=mimeType)
read 2.1.6
The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET
operation as shown:
GET [service-url]/[resourcetype]/{id} (?_format=mimeType)
update 2.1.8
The update interaction creates a new current version for an existing resource or creates a new resource if no
resource already exists for the given id. The update interaction is performed by an HTTP PUT operation as
shown:
PUT [service-url]/[resourcetype]/{id} (?_format=mimeType)
delete 2.1.9
The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE operation
as shown:
DELETE [service-url]/[resourcetype]/{id}

• HL7 New Zealand
Versioning
• Optional for a server (per resource)
• Can get history by
– Server
– Type
– Instance
• Id is url with /_history/{version) appended
• Search:
– [host]/_history
– [host]/Patient/_history
– [host]/Patient/1/_history
• Instance
– [host]/Patient/1/_history/2

• HL7 New Zealand
Searching
• A big topic!
– Afternoon session
– Return Bundle
• In the spec
– Each resource has defined search parameters
– Types & qualifiers
• Custom search

• HL7 New Zealand
Conformance resource
• Which FHIR version?
• Who can I contact?
• What’s the name of the software?
• Which Resources?
• What search operations?
• What formats?
• History
http://www.hl7.org/fhir/conformance.htm

• HL7 New Zealand
OPERATIONS
80

• HL7 New Zealand
FHIR Operations
• When more complex server logic required than simple CRUD
– Midway between REST & SOAP
• Some defined in spec. e.g.:
– Get all data for a patient
• /Patient/{id}/$everything
– Expand/filter terminology
• /ValueSet/{id}/$expand?filter=
• Can define custom services
– Still using FHIR resources
– Resources to define / inputs

• HL7 New Zealand
SOA
• Using FHIR resources with SOA patterns
• More complex environments
• In the spec: http://hl7.org/fhir/services.html
82

• HL7 New Zealand
DOCUMENTS
http://hl7.org/fhir/documents.html
83

• HL7 New Zealand
Documents – are bundles
84
Observation
Resource
Composition Resource
Section
Device Resource
Condition Resource
List Resource
<Bundle>
<entry>
<Composition />
</entry>
<entry>
<Observation />
</entry>
<entry>
<Device />
</entry>
<entry>
<List/>
</entry>
<entry>
<Condition/>
</entry>
</Bundle>
AttesterMetadata Section
Section
Equivalent to CDA

• HL7 New Zealand
Storing documents
• You can store your document using REST
– /Bundle (whole thing) - search supported
– /Binary (whole thing) – no search
– /Composition – composition only
• Note defined operation to reassemble
– / (server root)
• Process as individual – but ‘reassembly’ should be possible

• HL7 New Zealand
MESSAGES
http://hl7.org/fhir/messaging.html
86

• HL7 New Zealand
Messages – are bundles
87
Observation
Resource
MessageHeader Resource
source destination
Device Resource
Patient Resource
<Bundle>
<entry>
<MessageHeader />
</entry>
<entry>
<Observation />
</entry>
<entry>
<Patient />
</entry>
<entry>
<Device />
</entry>
</Bundle>
event
Equivalent to v2

• HL7 New Zealand
Sending messages
• Again, REST not necessary, but…
• There is an explicit REST operation:
– [base]/$process-message
– No storage implied. Might be a router, converted to v2, etc. etc.
• The server can process them based on the event code and
return the response as another message (again a bundle).

• HL7 New Zealand
MOVING ON…

• HL7 New Zealand
In FHIR
• Implementation Guides
• Workflow
• FluentPath
– https://github.com/ewoutkramer/fhirpath
• FHIR Mapping Language
– http://hl7.org/fhir/2016May/mapping-language.html
• CDS Hooks
90

• HL7 New Zealand
SMART

• HL7 New Zealand
Security
• FHIR is not a security standard
– Leverages existing standards
• Security tags
• Specialized resources
– Provenance, AuditEvent
• http://hl7.org/fhir/security.html
92

• HL7 New Zealand
STU3
• Expected end of this year
• Main Changes (from https://onfhir.hl7.org/)
– formats: no change to XML & JSON formats, but we will generate JSON
schema. Introduction of RDF, tied to an ontological base
– RESTful API: no change to existing API, bar some clarifications around
transactions. Maybe add Patch?
– Conformance – split out CodeSystem from Value set and minor changes to
other resources, including the use of FluentPath instead of XPath
– Core Clinical, Administrative & Financial resources – ongoing minor
changes in response to trial use and improved quality
– Continuing improvements to the Clinical Decision Support / Quality
Measure framework
– A new framework for workflow / task management
– Draft mapping framework and CCDA/FHIR mapping guides

• HL7 New Zealand
National Infrastructure / ecosystem
• FHIR interfaces to
– NHI (Patient)
– HPI (Practitioner)
• ‘Conformance’ registries
– Profiles
– ValueSet
– NamingSystem
• Common services
– Terminology
– Audit
• Security / Privacy
– OAuth2
– Relationships

• HL7 New Zealand
THANK YOU - QUESTIONS?

• HL7 New Zealand
ADVANCED SEARCH
http://hl7.org/fhir/2016May/search.html

• HL7 New Zealand
Searching
• In the spec
– Relationship to path (in resource)
– Describe filters on each type
• Custom
– SearchParameter resource
– Reference in Conformance
• Servers
– Declare which searches they support
– Can be really hard!
• Use the test servers!
– clinFHIR to create demo data

• HL7 New Zealand
Combining parameters
• Can search by GET & POST
• Always return a bundle
• Multiple parameters
– Specifying multiple parameters finds resources matching all params 
“AND”
• http://fhirtest.uhn.ca/baseDstu3/Patient?name=jones&gender=fe
male
– Parameters may list multiple values  “OR”
• http://fhirtest.uhn.ca/baseDstu3/Patient?name=patel,jones

• HL7 New Zealand
Example: Patient

• HL7 New Zealand
SearchParameter resource

• HL7 New Zealand
SearchParameter example
http://fhir3.healthintersections.com.au/open/SearchParameter/Patient-Name

• HL7 New Zealand
Advanced search
• Common Parameters
– _id
– _lastUpdated
– _tag
– _profile
– _security
– _text
– _content
– _list
– _type
– _query
105
• Search Result
Parameters
– sort
– count
– include
– revinclude
– summary
– elements
– contained
– containedType

• HL7 New Zealand
Common parameters - I
• _id
– Query by Id (string)
• _lastUpdated
– When the resource was last updated (date)
• _tag
– From the appropriate meta element (token)
• _profile
– From the appropriate meta element (url)
• _security
– From the appropriate meta element (token)
106

• HL7 New Zealand
Common parameters - II
• _text
– Search in text element (string)
• _content
– Search for text across the entire resource (string)
• _list
– Return resources referenced by a List resource
– Can use ‘current lists’ and other query
• http://hl7.org/fhir/lifecycle.html#current
• _query
– Custom named query
– Use OperationDefinition to define
107

• HL7 New Zealand
Search Result Parameters - I
• _sort
– The order of returned results (format changing in STU-3)
• _count
– Specify a number of resources to include
• _include
– Include other resources (more detail soon)
• _revinclude
– Include resources that reference this one
• Eg provenance

• HL7 New Zealand
Search Result Parameters - II
• _summary
– Return a subset
– true, false, text, data, count
– Resources marked as ‘SUBSETTED’
• _elements
– Specify elements to return (+mandatory)
– Resources marked as ‘SUBSETTED’
• _contained
– Whether search should include contained resources
– False (default), true, both
• _containedType
– With _contained – whether to return the container

• HL7 New Zealand
Chained searches
• Search ‘within’ a resource
– Patient has a search for “name” and “identifier”.
– Observation has a search for “subject” (the id of the Patient, Group or
Device)
• [host]/Observation?subject.name={x}
• [host]/Observation?subject.identifier={y}
• But note: this still only works on the predefined search
parameters. You cannot just use any property of the
resource.
http://fhirtest.uhn.ca/baseDstu3/Observation?subject.name=patel

• HL7 New Zealand
_Include
• Include related resources in the response
• Based on search parameters
• Server declares in conformance
• Format
– [host]/{type}?_include={source type}:{search parameter}:{target type}
• Eg
– [host]/MedicationOrder?_include=MedicationOrder:patient&criteria...
http://fhirtest.uhn.ca/baseDstu3/Observation?_id=99267&_include=Observation:encounter

• HL7 New Zealand
Compartment
• Syntactic sugar for queries
• Resources that share common property
– Eg patient
• Purpose:
– Access mechanism for finding a set of related resources quickly
– Provide a definitional basis for applying access control to resources
quickly
• http://hl7.org/fhir/compartments.html
112

• HL7 New Zealand
Meta tag

• HL7 New Zealand
REST STUFF
And finally, the last REST operation (for now):

• HL7 New Zealand
A Resource’s REST identity
• In fact: an URL
– http://server.org/fhir/Patient/1
endpoint
resource type
id
Note: This URL resolves to the current version of a resource

• HL7 New Zealand
One more look at the header
HTTP/1.1 200 OK
Content-Type: application/xml+fhir;charset=utf-8
Content-Length: 787
Content-Location:
http://fhir.furore.com/fhir/Patient/1/_history/12
Last-Modified: Tue, 29 May 2012 23:45:32 GMT

• HL7 New Zealand
For a specific version…
• We have the version-specific URL
http://server.org/fhir/ (continued)
Patient/1/_history/4
base path
resource type
identifier version id

• HL7 New Zealand
REST “representations”
GET /fhir/Patient/1?_format=json HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json+fhir;charset=utf-8
Content-Length: 787
Accept: application/json+fhir
HTTP/1.1 200 OK
Content-Type: application/json+fhir;charset=utf-8
Content-Length: 787

• HL7 New Zealand
To create a resource
• You POST the contents to an url which indicates the resource
type:
– E.g. http://server.org/fhir/Patient
• Supply body’s format in Content-Type header
• Server returns 201 (Created).
• Returns only the newly assigned version id URL in the
Location header.

• HL7 New Zealand
To update a resource
• Use PUT on the resource’s URL, with the new contents in the
body
• Tell server the body’s format (xml/json) in the Content-Type
header
• Server returns 200 and the URL to new version in the
Content-Location header.

• HL7 New Zealand
Using PUT to create
• Server might/might not allow you to PUT to an id that does
not yet exist.
• If it does: Server returns 201 and resource gets created at
that location
 client determines resource’s id!
• If it does not: server returns 405 (Method not allowed)

• HL7 New Zealand
Version-aware updates
• Use eTag & ‘if-match’ header
– Server requires client to send ‘if-match’ header with current
eTag
– Server uses this to check whether you are updating the latest
version.
– Server will then return 409 (Conflict) if it has been updated
by someone else in the meantime
• http://hl7.org/fhir/http.html#versionaware

• HL7 New Zealand
Conditional operations
• Eg create if not exist
– Search query in ‘if-none-exist’ header
• Especially useful in transactions, messages
• Create / Update / Delete
126
http://hl7.org/fhir/http.html

• HL7 New Zealand
What’s a ‘deleted’ Resource?
• DELETE method
• Trying read operations will return in a 410 (Gone) result
instead of 404 (Not Found)
• The resource will not be returned by the search operation
• You can “undelete” by doing an update with fresh content
• Just a “marker” in a resource’s history

• HL7 New Zealand
Version history - deletions
33, v12 – 2012-12-04
33, v13 – 2012-12-05
33, v14 – 2012-12-08
/server.org/fhir/Patient/33/_history/12
/server.org/fhir/Patient/33
33, v15 – 2012-12-09
33, v16 – 2012-12-10
DELETION

• HL7 New Zealand
Version history - revival
33, v13 – 2012-12-05
33, v14 – 2012-12-08
/server.org/fhir/Patient/33
33, v15 – 2012-12-09
33, v16 – 2012-12-10
33, v17 – 2012-12-11

• HL7 New Zealand
Operation Outcome
• When something goes wrong….return the
OperationOutcome Resource!

• HL7 New Zealand
Lists of things
• Current Allergies, Medications, Conditions
• Use the List resource
• Can query through _current
• http://hl7.org/fhir/lifecycle.html#current
131
GET [base]/AllergyIntolerance?patient=42&_list=$current-alle

• HL7 New Zealand
The Binary Endpoint
• Accepts any kind of content
• Stores the content as is, along with the content type
provided by the HTTP headers.
• Acts just like the normal Resource endpoints (but there is no
search)
• http://server.org/fhir/Binary/

• HL7 New Zealand
Useful for Attachments
/Binary/23344

• HL7 New Zealand
BUNDLES

• HL7 New Zealand
Communicating lists
• We need to communicate lists of Resources
– Search result
– History
– Documents or messages
– Multiple-resource inserts (batches or transactions)
• Descend from Resource (not DomainResource)
– No text, extensions, contained

• HL7 New Zealand
Query response

• HL7 New Zealand
Example: Keeping in sync
• History of all resources on server
– http://server.org/fhir/_history
• History of all patient resources on server
– http://server.org/fhir/Patient/_history
• History of specific patient on server
– http://server.org/fhir/Patient/1/_history
• A history of all changes: updates and deletions, ordered by
newest first
• Limit with _since and _count

• HL7 New Zealand
Transactions / Batches
• Multiple operations at once
– Transaction
• Related resources - Referential integrity
– Batch
• Unrelated
• Return bundle with outcomes
138

• HL7 New Zealand
Bundles in a Library
• C# hides the processing of bundle
Bundle result = new Bundle() { Title = "Demo bundle" };
result.Entries.Add(new ResourceEntry<Patient>()
{ LastUpdated=DateTimeOffset.Now, Content = new Patient() });
result.Entries.Add(new DeletedEntry()
{ Id = new Uri("http://..."), When = DateTime.Now });
var bundleXml = FhirSerializer.SerializeBundleToXml(result);

HL7 New Zealand: FHIR for developers

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to HL7 New Zealand: FHIR for developers

Similar to HL7 New Zealand: FHIR for developers (20)

More from David Hay

More from David Hay (7)

Recently uploaded

Recently uploaded (20)

HL7 New Zealand: FHIR for developers