-
Notifications
You must be signed in to change notification settings - Fork 8
/
operations.html
250 lines (201 loc) · 18.8 KB
/
operations.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<!doctype html>
<!--
FHIR Drills
Copyright 2016 Australian Digital Health Agency. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License
-->
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="description" content="FHIR Tutorials by the Australian Digital Health Agency to help you understand FHIR and its spec! No technical experience required.">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<title>Operations | FHIR® tutorials</title>
<!-- Add to homescreen for Chrome on Android -->
<!-- <meta name="mobile-web-app-capable" content="yes">
<link rel="icon" sizes="192x192" href="images/android-desktop.png"> -->
<!-- Add to homescreen for Safari on iOS -->
<!-- <meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="apple-mobile-web-app-title" content="Material Design Lite">
<link rel="apple-touch-icon-precomposed" href="images/ios-desktop.png"> -->
<!-- Tile icon for Win8 (144x144 + tile color) -->
<!-- <meta name="msapplication-TileImage" content="images/touch/ms-touch-icon-144x144-precomposed.png">
<meta name="msapplication-TileColor" content="#3372DF"> -->
<link rel="shortcut icon" href="images/favicon.ico">
<!-- SEO: If your mobile URL is different from the desktop URL, add a canonical link to the desktop page https://developers.google.com/webmasters/smartphone-sites/feature-phones -->
<!--
<link rel="canonical" href="http://www.example.com/">
-->
<!-- CodeMirror -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.13.4/codemirror.min.css"></link>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:regular,bold,italic,thin,light,bolditalic,black,medium&lang=en">
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
<link rel="stylesheet" href="https://code.getmdl.io/1.1.3/material.deep_purple-pink.min.css">
<link rel="stylesheet" href="styles.css">
<style>
#view-source {
position: fixed;
display: block;
right: 0;
bottom: 0;
margin-right: 40px;
margin-bottom: 40px;
z-index: 900;
}
</style>
<link href="css/lightbox.min.css" rel="stylesheet">
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-80290058-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body class="mdl-demo mdl-color--grey-100 mdl-color-text--grey-700 mdl-base">
<!-- The drawer is always open in large screens. The header is always shown,
even in small screens. -->
<div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer
mdl-layout--fixed-header">
<header class="mdl-layout__header">
<div class="mdl-layout__header-row">
<div class="mdl-layout-spacer"></div>
<div class="mdl-textfield mdl-js-textfield mdl-textfield--expandable
mdl-textfield--floating-label mdl-textfield--align-right">
<label class="mdl-button mdl-js-button mdl-button--icon"
for="fixed-header-drawer-exp">
<i class="material-icons">search</i>
</label>
<div class="mdl-textfield__expandable-holder">
<input class="mdl-textfield__input" type="text" name="sample"
id="fixed-header-drawer-exp">
</div>
</div>
</div>
</header>
<div class="mdl-layout__drawer">
<span class="mdl-layout-title">FHIR<sup>®</sup> tutorials</span>
<nav class="mdl-navigation">
<a href="./index.html" class="mdl-navigation__link">Overview</a>
<a href="./simple-patient.html" id="simple-patient" class="mdl-navigation__link">Simple Patient</a>
<a href="./simple-search.html" id="simple-search" class="mdl-navigation__link">Simple Search</a>
<a href="./patient-with-references.html" id="patient-with-references" class="mdl-navigation__link">Patient with References</a>
<a href="./bundle.html" id="bundle" class="mdl-navigation__link">Bundle</a>
<a href="./operations.html" id="operations" class="mdl-navigation__link is-active-tab">Operations</a>
<a href="./ValueSet-And-CodeSystem.html" id="ValueSet-And-CodeSystem" class="mdl-navigation__link">ValueSet & CodeSystem</a>
<a href="./conceptmap.html" id="conceptmap" class="mdl-navigation__link">ConceptMap</a>
<a href="./fhir-api.html" id="conceptmap" class="mdl-navigation__link">FHIR APIs</a>
<a href="#" class="mdl-navigation__link"></a>
<a href="./exercises.html" class="mdl-navigation__link">FHIR exercises</a>
</nav>
</div>
<main class="mdl-layout__content">
<section class="section--center mdl-grid mdl-grid--no-spacing mdl-shadow--2dp">
<div class="mdl-card mdl-cell mdl-cell--12-col-desktop mdl-cell--6-col-tablet mdl-cell--4-col-phone">
<div class="mdl-card__supporting-text">
<h4>Operations</h4>
<p>This tutorial will give you an overview of <b>Operations</b> in the FHIR specification</p>
<ul class="toc">
<h4>Contents</h4>
<!-- pr prefix stands for 'patient references'-->
<a href="#op-step1">Step 1: What are Operations</a>
<a href="#op-step2">Step 2: Operations input parameters</a>
<a href="#op-step3">Step 3: Operations output parameters</a>
<a href="#op-step4">Step 4: Custom Operations</a>
</ul>
<h5 id="op-step1">Step 1: What are Operations</h5>
<p>In the <a href="simple-patient.html">Simple Patient</a> tutorial, we looked at interacting with the FHIR server using the CRUD actions (Create, Read, Update and Delete). <b>Operations</b> extend on these basic actions to provide unique functionality where required. For instance, the operation <b>$validate</b> can check that a provided resource is acceptable to the server before you attempt to upload it. <b>$translate</b> can map one code to another using a ConceptMap. You can find a full list of the operations defined by the FHIR specification here: <a href="http://hl7.org/fhir/STU3/operationslist.html">FHIR defined Operations</a> and for operations that are particular to a given FHIR resource, you will find an operation tab at the top of the given resource's page.</p>
<p><b><a href="http://hl7.org/fhir/STU3/patient-operations.html">Operation</a> tab as seen on the Patient resource page</b><img src="images/Operations-OperationTabFhirSpec.png"></p>
<p>Let's jump straight in and look at some operation syntax examples. The basic concept of operations is much like a function in programming. An operation has an 'Operation Name' (e.g. $meta, $everything) which are always prefixed with a dollar sign '$' and operations are run in one of three context, them being:</p>
<p><b>Against the entire FHIR server:</b><br>
<i>Give me the meta-data for the entire FHIR server</i><br>
<i>Syntax:</i>
<b><code>[Service Root URL]/[$Operation Name]</code></b><br>
<i>Example:</i>
<b><code>http://www.acmehealth/fhirapi/$meta</code></b>
</p>
<p><b>Against a type of resource:</b><br>
<i>Give me the meta-data for a given resource type (Patient)</i><br>
<i>Syntax:</i>
<b><code>[Service Root URL]/[Resource Type]/[$Operation Name]</code></b><br>
<i>Example:</i>
<b><code>http://www.acmehealth/fhirapi/Patient/$meta</code></b>
</p>
<p><b>Against a single resource instance:</b><br>
<i>Give me all resources (everything) for the Patient resource with the given resource id of (123456)</i><br>
<i>Syntax: </i>
<b><code> [Service Root URL]/[Resource Type]/[Resource Id]/[$Operation Name]</code></b><br>
<i>Example:</i>
<b><code> http://www.acmehealth/fhirapi/Patient/123456/$everything</code></b>
</p>
<p>Operations can also have any number of input and output parameters. We will look at input parameter next.</p>
<h5 id="op-step2">Step 2: Operations input parameters</h5>
<p>There are two different ways to pass input parameters to an operation on a FHIR server. Generally, the POST action is used and the parameters are given in the HTTP body as a <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource. Take a look at the <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource in the FHIR specification now to get a feel for its contents. In essence, it is a simple resource containing value pairs (key, value) where value may be a FHIR data type or a whole resource. The point to take home here is that the <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource allows you to pass in complex data types and whole resources as parameters.</p>
<p>The other way to pass input parameters into operations is by using an HTTP GET and putting the parameters in the GET URL string as seen in the following examples:</p>
<p><i>Syntax: </i><b><code>[Service Root URL]/[Resource Name]/[$OperationName]?[OpParameterName1=value]&[OpParameterName2=value]..etc.</code></b>
<br>
<br>
The <b>$match</b> operation can be given on a Patient resource type using a number of input parameters:<br>
<i>Give me all the Patient resources that match on the patient demographic parameters (family, given, birthdate)</i><br>
<i>Example: </i><b><code>http://www.acmehealth/fhirapi/Patient/$match?family=chalmers&given=peter&birthdate=1974-12-25</code></b></p>
<p><b>Activity:</b> Find in the FHIR specification documentation the <b>$match</b> operation and answer; what other input parameters can this operation take and what is its output?</p>
<P>So when do you use each - Parameters in the URL string or parameters in the body using the <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource?</P>
<p>For some operations, you can use either option as long as the server supports both, for instance, the <b>$lookup</b> operation on a CodeSystem resource can be performed using both methods. Yet sometimes you must use the <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource and HTTP POST rather than the parameters in the URL string and GET. One of the key reasons for this is due to the parameters you need to pass into the operation. If one of them is a whole Resource or a complex datatype then you must use the <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource as you are unable to place a whole resource or complex data type in an URL string. The other reason is that an operation must be 'Idempotent' to use a GET action.</p>
<p><i>What the; Idempotent?</i><br>
<b>Idempotent: </b>An Idempotent operation can be applied multiple times without changing the result beyond the initial application. For example, if I make a call to delete a resource the action is said to be 'Idempotent' because if I repeat the very same call many times, no further changes occur, the resource just remains deleted as it did on the first call.</p>
<h5 id="op-step3">Step 3: Operations output parameters</h5>
<p>The output of an operation is somewhat the same as the input. If the operation was successful a HTTP status code of 200 OK will be returned along with either a <a href="http://hl7.org/fhir/STU3/parameters.html">Parameters</a> resource or you may get a whole resource returned depending on the operation. If an error is encountered by the server you will receive an OperationOutcome resource and an HTTP status code of 4xx or 5xx. Not all operations are alike so browse the <a href="http://hl7.org/fhir/STU3/operationslist.html">full list</a> to get a feel for inputs and outputs of each.</p>
<h5 id="op-step4">Step 4: Custom Operations</h5>
<p>While the FHIR specification outlines a set of operations, there is no requirement that any given server support these operations. In order to work out which operations a server supports you will need to inspect the servers' own CapabilityStatement which is a resource that all servers must provide given the following call: <code>GET: [Service Root URL]/metadata</code>. Check this resource to see which OperationDefinition resources it lists as supported. These will be listed at the following path in the CapabilityStatement resource: <code>CapabilityStatement/rest/operation</code> Here you should see a reference to another resource named OperationDefinition which is used to define the operation in its entirety; what the operation does and the inputs and outputs it uses.</p>
<p>Servers are also allowed to offer their own custom operations. Each of these should be defined in that servers CapabilityStatement resource by an OperationDefinition resource, as described above. A server can even extend onto an existing operation with new input and output parameters, once again all of these need to be stated in the appropriate OperationDefinition and referenced in the servers' own CapabilityStatement .</p>
<p><b>Activity:</b> Using a post client GET your servers' CapabilityStatement resource and identify the operations it supports?<br>
<i><b>Tip</b> <code>GET: [Service Root URL]/metadata</code></i></p>
<note>All operations in FHIR are accessed using a dollar symbol e.g <code>GET: [Service Root URL]/$MyOperationName</code>. Yet, the metadata call to get the servers' CapabilityStatement does not use a dollar sign. This is a quirk of the early development of FHIR. The 'metadata' operation was the very first operation ever defined by FHIR and as it returns the information about what the server supports. It is a critical piece of infrastructure. The FHIR team thought changing this call to '$metadata' would be to much of a breaking change.</note>
</div>
</section>
<footer class="mdl-mega-footer">
<div class="mdl-mega-footer--middle-section">
<div class="mdl-mega-footer--drop-down-section">
<input class="mdl-mega-footer--heading-checkbox" type="checkbox" checked>
<h1 class="mdl-mega-footer--heading">The Agency</h1>
<ul class="mdl-mega-footer--link-list">
<li><a href="https://www.digitalhealth.gov.au/">digitalhealth.gov.au</a></li>
<li><a href="https://myhealthrecord.gov.au/internet/mhr/publishing.nsf/content/home" title="Australian national health record">My Health Record</a></li>
</ul>
</div>
<div class="mdl-mega-footer--drop-down-section">
<input class="mdl-mega-footer--heading-checkbox" type="checkbox" checked>
<h1 class="mdl-mega-footer--heading">FHIR</h1>
<ul class="mdl-mega-footer--link-list">
<li><a href="http://wiki.hl7.org/index.php?title=FHIR_Connectathon_15" title="Next FHIR get-together in Madrid in May 2017">Connectathon 15</a></li>
<li><a href="http://hl7.org/fhir/STU3" title="Latest release of FHIR, for use in Madrid Connectathon">FHIR STU3 Release</a></li>
<li><a href="http://build.fhir.org/" title="The latest FHIR as it is in development">FHIR Continuous Integration Build</a></li>
</ul>
</div>
</div>
</footer>
</main>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.13.4/codemirror.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.13.4/mode/xml/xml.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.14.2/mode/javascript/javascript.min.js"></script>
<script src="https://code.getmdl.io/1.1.3/material.min.js"></script>
<script src="js/lightbox-plus-jquery.min.js"></script>
<!-- lua.vm.js -->
<script src="js/lua.vm.js/dist/lua.vm.js"></script>
<!-- main javascript for this page-->
<script src="js/main.js"></script>
<!-- supporting javascript to actually do the uploading -->
<script src="js/post-resources.js"></script>
</body>
</html>