|
| 1 | +--- |
| 2 | +title: Executing the import by invoking $import operation on FHIR service in Azure Health Data Services |
| 3 | +description: This article describes how to import FHIR data using $import |
| 4 | +author: ginalee-dotcom |
| 5 | +ms.service: healthcare-apis |
| 6 | +ms.subservice: fhir |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 04/16/2022 |
| 9 | +ms.author: ranku |
| 10 | +--- |
| 11 | + |
| 12 | +# Bulk import FHIR data (Preview) |
| 13 | + |
| 14 | +The Bulk import feature enables importing FHIR data to the FHIR server at high throughput using the $import operation. This feature is suitable for initial data load into the FHIR server. |
| 15 | + |
| 16 | +## Current limitations |
| 17 | + |
| 18 | +* Conditional references in resources aren't supported. |
| 19 | +* If multiple resources share the same resource ID, then only one of those resources will be imported at random and an error will be logged corresponding to the remaining resources sharing the ID. |
| 20 | +* The data to be imported must be in the same Tenant as that of the FHIR service. |
| 21 | + |
| 22 | +## Using $import operation |
| 23 | + |
| 24 | +To use $import, you'll need to configure the FHIR server using the instructions in the [Configure bulk import settings](configure-import-data.md) article and set the **initialImportMode** to *true*. Doing so also suspends write operations (POST and PUT) on the FHIR server. You should set the **initialImportMode** to *false* to reenable write operations after you have finished importing your data. |
| 25 | + |
| 26 | +The FHIR data to be imported must be stored in resource specific files in FHIR NDJSON format on the Azure blob store. All the resources in a file must be of the same type. You may have multiple files per resource type. |
| 27 | + |
| 28 | +### Calling $import |
| 29 | + |
| 30 | +Make a ```POST``` call to ```<<FHIR service base URL>>/$import``` with the following required headers and body, which contains a FHIR [Parameters](http://hl7.org/fhir/parameters.html) resource. |
| 31 | + |
| 32 | +As `$import` is an async operation, a **callback** link will be returned in the `Content-location` header of the response together with ```202-Accepted``` status code. You can use this callback link to check import status. |
| 33 | + |
| 34 | +#### Request Header |
| 35 | + |
| 36 | +```http |
| 37 | +Prefer:respond-async |
| 38 | +Content-Type:application/fhir+json |
| 39 | +``` |
| 40 | + |
| 41 | +#### Body |
| 42 | + |
| 43 | +| Parameter Name | Description | Card. | Accepted values | |
| 44 | +| ----------- | ----------- | ----------- | ----------- | |
| 45 | +| inputFormat | String representing the name of the data source format. Currently only FHIR NDJSON files are supported. | 1..1 | ```application/fhir+ndjson``` | |
| 46 | +| mode | Import mode. Currently only initial load mode is supported. | 1..1 | ```InitialLoad``` | |
| 47 | +| input | Details of the input files. | 1..* | A JSON array with three parts described in the table below. | |
| 48 | + |
| 49 | +| Input part name | Description | Card. | Accepted values | |
| 50 | +| ----------- | ----------- | ----------- | ----------- | |
| 51 | +| type | Resource type of input file | 1..1 | A valid [FHIR resource type](https://www.hl7.org/fhir/resourcelist.html) that match the input file. | |
| 52 | +|URL | Azure storage url of input file | 1..1 | URL value of the input file that can't be modified. | |
| 53 | +| etag | Etag of the input file on Azure storage used to verify the file content hasn't changed. | 0..1 | Etag value of the input file that can't be modified. | |
| 54 | + |
| 55 | +**Sample body:** |
| 56 | + |
| 57 | +```json |
| 58 | +{ |
| 59 | + "resourceType": "Parameters", |
| 60 | + "parameter": [ |
| 61 | + { |
| 62 | + "name": "inputFormat", |
| 63 | + "valueString": "application/fhir+ndjson" |
| 64 | + }, |
| 65 | + { |
| 66 | + "name": "mode", |
| 67 | + "valueString": "InitialLoad" |
| 68 | + }, |
| 69 | + { |
| 70 | + "name": "input", |
| 71 | + "part": [ |
| 72 | + { |
| 73 | + "name": "type", |
| 74 | + "valueString": "Patient" |
| 75 | + }, |
| 76 | + { |
| 77 | + "name": "url", |
| 78 | + "valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson" |
| 79 | + }, |
| 80 | + { |
| 81 | + "name": "etag", |
| 82 | + "valueUri": "0x8D92A7342657F4F" |
| 83 | + } |
| 84 | + ] |
| 85 | + }, |
| 86 | + { |
| 87 | + "name": "input", |
| 88 | + "part": [ |
| 89 | + { |
| 90 | + "name": "type", |
| 91 | + "valueString": "CarePlan" |
| 92 | + }, |
| 93 | + { |
| 94 | + "name": "url", |
| 95 | + "valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson" |
| 96 | + } |
| 97 | + ] |
| 98 | + } |
| 99 | + ] |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +### Checking import status |
| 104 | + |
| 105 | +Make the REST call with the ```GET``` method to the **callback** link returned in the previous step. You can interpret the response using the following table: |
| 106 | + |
| 107 | +| Response code | Response body |Description | |
| 108 | +| ----------- | ----------- |----------- | |
| 109 | +| 202 Accepted | |The operation is still running.| |
| 110 | +| 200 OK |The response body doesn't contain any error.url entry|All resources were imported successfully.| |
| 111 | +| 200 OK |The response body contains some error.url entry|Error occurred while importing some of the resources. See the files located at error.url for the details. Rest of the resources were imported successfully.| |
| 112 | +| Other||A fatal error occurred and the operation has stopped. Successfully imported resources haven't been rolled back.| |
| 113 | + |
| 114 | +Below are some of the important fields in the response body: |
| 115 | + |
| 116 | +| Field | Description | |
| 117 | +| ----------- | ----------- | |
| 118 | +|transactionTime|Start time of the bulk import operation.| |
| 119 | +|output.count|Count of resources that were successfully imported| |
| 120 | +|error.count|Count of resources that weren't imported due to some error| |
| 121 | +|error.url|URL of the file containing details of the error. Each error.url is unique to an input URL. | |
| 122 | + |
| 123 | +**Sample response:** |
| 124 | + |
| 125 | +```json |
| 126 | +{ |
| 127 | + "transactionTime": "2021-07-16T06:46:52.3873388+00:00", |
| 128 | + "request": "https://importperf.azurewebsites.net/$Import", |
| 129 | + "output": [ |
| 130 | + { |
| 131 | + "type": "Patient", |
| 132 | + "count": 10000, |
| 133 | + "inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson" |
| 134 | + }, |
| 135 | + { |
| 136 | + "type": "CarePlan", |
| 137 | + "count": 199949, |
| 138 | + "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson" |
| 139 | + } |
| 140 | + ], |
| 141 | + "error": [ |
| 142 | + { |
| 143 | + "type": "OperationOutcome", |
| 144 | + "count": 51, |
| 145 | + "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson", |
| 146 | + "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson" |
| 147 | + } |
| 148 | + ] |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +## Next steps |
| 153 | + |
| 154 | +In this article, you've learned about how the Bulk import feature enables importing FHIR data to the FHIR server at high throughput using the $import operation. For more information about converting data to FHIR, exporting settings to set up a storage account, and moving data to Azure Synapse, see |
| 155 | + |
| 156 | + |
| 157 | +>[!div class="nextstepaction"] |
| 158 | +>[Converting your data to FHIR](convert-data.md) |
| 159 | +
|
| 160 | +>[!div class="nextstepaction"] |
| 161 | +>[Configure export settings and set up a storage account](configure-export-data.md) |
| 162 | +
|
| 163 | +>[!div class="nextstepaction"] |
| 164 | +>[Copy data from Azure API for FHIR to Azure Synapse Analytics](copy-to-synapse.md) |
0 commit comments